polkadot-cli 1.15.1 → 1.17.0

package/dist/cli.mjs

@@ -16,7 +16,31 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // src/utils/errors.ts
-var CliError, ConnectionError, MetadataError;
+function isLikelyStaleMetadataError(err) {
+  const msg = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  if (!msg)
+    return false;
+  return STALE_METADATA_PATTERNS.some((re) => re.test(msg));
+}
+function formatRuntimeError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (/wasm trap|wasm `?unreachable`? instruction|Execution aborted due to trap/i.test(msg)) {
+    const frames = Array.from(msg.matchAll(/\.wasm!([A-Za-z_]\w+)/g)).map((m) => m[1]);
+    const fn = [...frames].reverse().find((name) => !/^(?:__rustc|core::panicking|rust_begin_unwind|panic_fmt)/.test(name));
+    const where = fn?.includes("validate_transaction") ? "the runtime's validate_transaction step" : fn ? `runtime function ${fn}` : "the runtime";
+    return [
+      `The runtime rejected this transaction in ${where}.`,
+      "  Cause: a runtime invariant failed — typically the call's arguments are out of range, reference an unknown id, or violate a precondition.",
+      "  Tip:   re-check the arguments and the signing account's permissions; --dry-run will surface the same error before signing."
+    ].join(`
+`);
+  }
+  if (/Invalid Transaction/i.test(msg)) {
+    return `Transaction rejected as invalid by the runtime: ${msg}`;
+  }
+  return msg;
+}
+var CliError, ConnectionError, MetadataError, STALE_METADATA_PATTERNS;
 var init_errors = __esm(() => {
   CliError = class CliError extends Error {
     constructor(message) {
@@ -36,8 +60,28 @@ var init_errors = __esm(() => {
       this.name = "MetadataError";
     }
   };
+  STALE_METADATA_PATTERNS = [
+    /wasm trap/i,
+    /wasm `?unreachable`? instruction/i,
+    /Execution aborted due to trap/i,
+    /codec/i,
+    /decod(e|ing)/i,
+    /Lookup failed/i,
+    /metadata.*mismatch/i
+  ];
 });
 
+// src/utils/runtime-fingerprint.ts
+function fingerprintsMatch(a, b) {
+  return a.codeHash === b.codeHash && a.specVersion === b.specVersion && a.transactionVersion === b.transactionVersion;
+}
+function isRuntimeFingerprint(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const v = value;
+  return typeof v.specName === "string" && typeof v.specVersion === "number" && typeof v.transactionVersion === "number" && typeof v.implName === "string" && typeof v.implVersion === "number" && typeof v.authoringVersion === "number" && typeof v.codeHash === "string" && typeof v.fetchedAt === "string";
+}
+
 // src/config/types.ts
 function primaryRpc(rpc) {
   return Array.isArray(rpc) ? rpc[0] : rpc;
@@ -193,6 +237,9 @@ function getChainDir(chainName) {
 function getMetadataPath(chainName) {
   return join(getChainDir(chainName), "metadata.bin");
 }
+function getMetadataFingerprintPath(chainName) {
+  return join(getChainDir(chainName), "metadata.fingerprint.json");
+}
 function getConfigPath() {
   return join(getConfigDir(), "config.json");
 }
@@ -238,10 +285,25 @@ async function loadMetadata(chainName) {
   }
   return null;
 }
-async function saveMetadata(chainName, data) {
+async function saveMetadata(chainName, data, fingerprint) {
   const dir = getChainDir(chainName);
   await ensureDir(dir);
   await writeFile(getMetadataPath(chainName), data);
+  if (fingerprint) {
+    await writeFile(getMetadataFingerprintPath(chainName), `${JSON.stringify(fingerprint, null, 2)}
+`);
+  }
+}
+async function loadMetadataFingerprint(chainName) {
+  const path = getMetadataFingerprintPath(chainName);
+  if (!await fileExists(path))
+    return null;
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf-8"));
+    return isRuntimeFingerprint(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
 }
 async function removeChainData(chainName) {
   const dir = getChainDir(chainName);
@@ -612,6 +674,11 @@ function printResult(data, format = "pretty") {
 function isJsonOutput(opts) {
   return opts.json === true || opts.output === "json";
 }
+function writeStdout(text) {
+  return new Promise((resolve) => {
+    process.stdout.write(text, () => resolve());
+  });
+}
 function printJsonLine(data) {
   console.log(JSON.stringify(data, replacer));
 }
@@ -791,6 +858,324 @@ var init_client = __esm(() => {
   init_errors();
 });
 
+// src/core/pretty-type.ts
+function visualWidth(s) {
+  return s.replace(ANSI_RE, "").length;
+}
+function paint(color, code, text) {
+  return color ? `${code}${text}${RESET2}` : text;
+}
+function defaultWidth() {
+  return process.stdout.columns ?? 80;
+}
+function resolveOpts(opts) {
+  return {
+    indent: opts.indent ?? 0,
+    prefix: opts.prefix ?? 0,
+    width: opts.width ?? defaultWidth(),
+    color: opts.color ?? isTTY
+  };
+}
+function compactEntry(entry, color) {
+  if (!entry)
+    return "";
+  switch (entry.type) {
+    case "primitive":
+      return paint(color, YELLOW2, entry.value);
+    case "compact": {
+      const inner = entry.isBig ? "u128" : "u64";
+      return `${paint(color, MAGENTA2, "Compact")}<${paint(color, YELLOW2, inner)}>`;
+    }
+    case "AccountId32":
+      return paint(color, GREEN2, "AccountId32");
+    case "bitSequence":
+      return paint(color, MAGENTA2, "BitSequence");
+    case "sequence":
+      return `${paint(color, MAGENTA2, "Vec")}<${compactEntry(entry.value, color)}>`;
+    case "array":
+      return `[${compactEntry(entry.value, color)}; ${entry.len}]`;
+    case "tuple":
+      return `(${entry.value.map((v) => compactEntry(v, color)).join(", ")})`;
+    case "struct": {
+      const fields = Object.entries(entry.value);
+      if (fields.length === 0)
+        return "{}";
+      const inner = fields.map(([k, v]) => `${paint(color, CYAN2, k)}: ${compactEntry(v, color)}`).join(", ");
+      return `{ ${inner} }`;
+    }
+    case "option":
+      return `${paint(color, MAGENTA2, "Option")}<${compactEntry(entry.value, color)}>`;
+    case "result":
+      return `${paint(color, MAGENTA2, "Result")}<${compactEntry(entry.value.ok, color)}, ${compactEntry(entry.value.ko, color)}>`;
+    case "enum": {
+      const variants = Object.keys(entry.value);
+      if (variants.length > ENUM_COMPACT_LIMIT) {
+        return `enum(${variants.length} variants)`;
+      }
+      return variants.map((v) => paint(color, GREEN2, v)).join(" | ");
+    }
+    case "void":
+      return "()";
+    case "lookupEntry":
+      return compactEntry(entry.value, color);
+    default:
+      return "unknown";
+  }
+}
+function expandEntry(entry, indent, width, color, prefix = 0) {
+  const compact = compactEntry(entry, color);
+  if (visualWidth(compact) + indent + prefix <= width)
+    return compact;
+  switch (entry.type) {
+    case "struct":
+      return expandStruct(entry.value, indent, width, color);
+    case "tuple":
+      return expandTuple(entry.value, indent, width, color);
+    case "sequence":
+      return wrapMultiline("Vec", "<", ">", entry.value, indent, width, color);
+    case "array": {
+      const inner = expandEntry(entry.value, indent + 1, width, color);
+      return `[${inner}; ${entry.len}]`;
+    }
+    case "option":
+      return wrapMultiline("Option", "<", ">", entry.value, indent, width, color);
+    case "result": {
+      const innerIndent = indent + 2;
+      const padding = " ".repeat(innerIndent);
+      const closePadding = " ".repeat(indent);
+      const ok = expandEntry(entry.value.ok, innerIndent, width, color);
+      const ko = expandEntry(entry.value.ko, innerIndent, width, color);
+      return `${paint(color, MAGENTA2, "Result")}<
+${padding}${ok},
+${padding}${ko}
+${closePadding}>`;
+    }
+    case "enum": {
+      const variants = Object.keys(entry.value);
+      if (variants.length > ENUM_COMPACT_LIMIT)
+        return `enum(${variants.length} variants)`;
+      return expandEnum(variants, indent, color);
+    }
+    case "lookupEntry":
+      return expandEntry(entry.value, indent, width, color);
+    default:
+      return compact;
+  }
+}
+function expandStruct(fields, indent, width, color) {
+  const entries = Object.entries(fields);
+  if (entries.length === 0)
+    return "{}";
+  return renderFieldList(entries, "{", "}", indent, width, color);
+}
+function expandTuple(items, indent, width, color) {
+  if (items.length === 0)
+    return "()";
+  const inner = " ".repeat(indent + 2);
+  const close = " ".repeat(indent);
+  const lines = items.map((v) => `${inner}${expandEntry(v, indent + 2, width, color)}`);
+  return `(
+${lines.join(`,
+`)},
+${close})`;
+}
+function wrapMultiline(name, open, close, inner, indent, width, color) {
+  const innerIndent = indent + 2;
+  const padding = " ".repeat(innerIndent);
+  const closePadding = " ".repeat(indent);
+  const innerStr = expandEntry(inner, innerIndent, width, color);
+  return `${paint(color, MAGENTA2, name)}${open}
+${padding}${innerStr}
+${closePadding}${close}`;
+}
+function expandEnum(variants, indent, color) {
+  const prefix = `
+${" ".repeat(indent)}| `;
+  const [first, ...rest] = variants;
+  const head = paint(color, GREEN2, first ?? "");
+  if (rest.length === 0)
+    return head;
+  const tail = rest.map((v) => paint(color, GREEN2, v)).join(prefix);
+  return `${head}${prefix}${tail}`;
+}
+function renderFieldList(fields, open, close, indent, width, color) {
+  const innerIndent = indent + 2;
+  const maxNameLen = Math.max(...fields.map(([k]) => k.length));
+  const align = maxNameLen <= ALIGN_PADDING_LIMIT;
+  const padTo = align ? maxNameLen : 0;
+  const padding = " ".repeat(innerIndent);
+  const closePadding = " ".repeat(indent);
+  const lines = fields.map(([k, v]) => {
+    const paddedName = align ? k.padEnd(padTo) : k;
+    const fieldPrefix = (align ? padTo : k.length) + 2;
+    const value = expandEntry(v, innerIndent, width, color, fieldPrefix);
+    return `${padding}${paint(color, CYAN2, paddedName)}: ${value}`;
+  });
+  return `${open}
+${lines.join(`,
+`)},
+${closePadding}${close}`;
+}
+function prettyType(entry, opts = {}) {
+  const { indent, prefix, width, color } = resolveOpts(opts);
+  const compact = compactEntry(entry, color);
+  if (visualWidth(compact) + indent + prefix <= width)
+    return compact;
+  return expandEntry(entry, indent, width, color);
+}
+function prettyTypeById(lookup, typeId, opts = {}) {
+  try {
+    const entry = lookup(typeId);
+    if (!entry || typeof entry.type !== "string")
+      return `type(${typeId})`;
+    return prettyType(entry, opts);
+  } catch {
+    return `type(${typeId})`;
+  }
+}
+function prettyCallArgs(meta, palletName, callName, opts = {}) {
+  const fields = getCallFields(meta, palletName, callName);
+  if (fields === null)
+    return "";
+  return renderArgsFromFields(fields, opts);
+}
+function prettyEventFields(meta, palletName, eventName, opts = {}) {
+  const fields = getEventFields(meta, palletName, eventName);
+  if (fields === null)
+    return "";
+  return renderArgsFromFields(fields, opts);
+}
+function prettyRuntimeApiArgs(lookup, inputs, opts = {}) {
+  if (inputs.length === 0)
+    return "()";
+  const namedFields = inputs.map((i) => {
+    let entry;
+    try {
+      entry = lookup(i.type);
+      if (!entry || typeof entry.type !== "string")
+        entry = { type: "unknown" };
+    } catch {
+      entry = { type: "unknown" };
+    }
+    return [i.name, entry];
+  });
+  return renderArgsFromFields({ kind: "named", fields: namedFields }, opts);
+}
+function unwrapVariant(variant) {
+  if (!variant)
+    return null;
+  if (variant.type === "void")
+    return { kind: "void" };
+  if (variant.type === "struct") {
+    return {
+      kind: "named",
+      fields: Object.entries(variant.value)
+    };
+  }
+  if (variant.type === "tuple") {
+    return { kind: "positional", types: variant.value };
+  }
+  if (variant.type === "lookupEntry") {
+    const inner = variant.value;
+    if (inner.type === "void")
+      return { kind: "void" };
+    if (inner.type === "struct") {
+      return {
+        kind: "named",
+        fields: Object.entries(inner.value)
+      };
+    }
+    return { kind: "single", type: inner };
+  }
+  return null;
+}
+function getCallFields(meta, palletName, callName) {
+  try {
+    const palletMeta = meta.unified.pallets.find((p) => p.name === palletName);
+    if (!palletMeta?.calls)
+      return null;
+    const callsEntry = meta.lookup(palletMeta.calls.type);
+    if (callsEntry.type !== "enum")
+      return null;
+    const variant = callsEntry.value[callName];
+    return unwrapVariant(variant);
+  } catch {
+    return null;
+  }
+}
+function getEventFields(meta, palletName, eventName) {
+  try {
+    const palletMeta = meta.unified.pallets.find((p) => p.name === palletName);
+    if (!palletMeta?.events)
+      return null;
+    const eventsEntry = meta.lookup(palletMeta.events.type);
+    if (eventsEntry.type !== "enum")
+      return null;
+    const variant = eventsEntry.value[eventName];
+    return unwrapVariant(variant);
+  } catch {
+    return null;
+  }
+}
+function renderArgsFromFields(fields, opts) {
+  const { indent, prefix, width, color } = resolveOpts(opts);
+  const lead = indent + prefix;
+  switch (fields.kind) {
+    case "void":
+      return "()";
+    case "named": {
+      const compact = `(${fields.fields.map(([k, v]) => `${paint(color, CYAN2, k)}: ${compactEntry(v, color)}`).join(", ")})`;
+      if (visualWidth(compact) + lead <= width)
+        return compact;
+      return renderFieldList(fields.fields, "(", ")", indent, width, color);
+    }
+    case "positional": {
+      const compact = `(${fields.types.map((t) => compactEntry(t, color)).join(", ")})`;
+      if (visualWidth(compact) + lead <= width)
+        return compact;
+      const innerIndent = indent + 2;
+      const padding = " ".repeat(innerIndent);
+      const closePadding = " ".repeat(indent);
+      const lines = fields.types.map((t) => `${padding}${expandEntry(t, innerIndent, width, color)}`);
+      return `(
+${lines.join(`,
+`)},
+${closePadding})`;
+    }
+    case "single": {
+      const compact = `(${compactEntry(fields.type, color)})`;
+      if (visualWidth(compact) + lead <= width)
+        return compact;
+      const inner = expandEntry(fields.type, indent + 2, width, color);
+      return `(
+${" ".repeat(indent + 2)}${inner},
+${" ".repeat(indent)})`;
+    }
+  }
+}
+function compactTypeString(entry) {
+  return compactEntry(entry, false);
+}
+function compactArgsString(fields) {
+  if (fields === null)
+    return "";
+  switch (fields.kind) {
+    case "void":
+      return "()";
+    case "named":
+      return `(${fields.fields.map(([k, v]) => `${k}: ${compactEntry(v, false)}`).join(", ")})`;
+    case "positional":
+      return `(${fields.types.map((t) => compactEntry(t, false)).join(", ")})`;
+    case "single":
+      return `(${compactEntry(fields.type, false)})`;
+  }
+}
+var RESET2 = "\x1B[0m", CYAN2 = "\x1B[36m", GREEN2 = "\x1B[32m", YELLOW2 = "\x1B[33m", MAGENTA2 = "\x1B[35m", ANSI_RE, ENUM_COMPACT_LIMIT = 24, ALIGN_PADDING_LIMIT = 16;
+var init_pretty_type = __esm(() => {
+  init_output();
+  ANSI_RE = /\x1b\[[0-9;]*m/g;
+});
+
 // src/core/metadata.ts
 import { getDynamicBuilder, getLookupFn } from "@polkadot-api/metadata-builders";
 import {
@@ -809,28 +1194,52 @@ function parseMetadata(raw) {
   const builder = getDynamicBuilder(lookup);
   return { unified, lookup, builder, version: version2 };
 }
+async function getRuntimeFingerprint(clientHandle, chainName) {
+  const { client } = clientHandle;
+  const [version2, codeHash] = await Promise.all([
+    withTimeout(client._request("state_getRuntimeVersion", []), chainName),
+    withTimeout(client._request("state_getStorageHash", ["0x3a636f6465"]), chainName)
+  ]);
+  return {
+    specName: version2.specName,
+    specVersion: version2.specVersion,
+    transactionVersion: version2.transactionVersion,
+    implName: version2.implName,
+    implVersion: version2.implVersion,
+    authoringVersion: version2.authoringVersion,
+    codeHash,
+    fetchedAt: new Date().toISOString()
+  };
+}
 async function fetchMetadataFromChain(clientHandle, chainName) {
   const { client } = clientHandle;
+  let bytes;
   try {
     const hex = await withTimeout(client._request("state_call", ["Metadata_metadata_at_version", v15Arg]), chainName);
     const raw = hexToBytes(hex);
     const decoded = optionalOpaqueBytes.dec(raw);
     if (decoded !== undefined) {
-      const bytes = new Uint8Array(decoded);
-      await saveMetadata(chainName, bytes);
-      return bytes;
+      bytes = new Uint8Array(decoded);
     }
   } catch {}
+  if (!bytes) {
+    try {
+      const hex = await withTimeout(client._request("state_getMetadata", []), chainName);
+      bytes = hexToBytes(hex);
+    } catch (err) {
+      if (err instanceof ConnectionError)
+        throw err;
+      throw new ConnectionError(`Failed to fetch metadata for "${chainName}": ${err instanceof Error ? err.message : err}. ` + "Check that the RPC endpoint is correct and reachable.");
+    }
+  }
+  let fingerprint;
   try {
-    const hex = await withTimeout(client._request("state_getMetadata", []), chainName);
-    const bytes = hexToBytes(hex);
-    await saveMetadata(chainName, bytes);
-    return bytes;
-  } catch (err) {
-    if (err instanceof ConnectionError)
-      throw err;
-    throw new ConnectionError(`Failed to fetch metadata for "${chainName}": ${err instanceof Error ? err.message : err}. ` + "Check that the RPC endpoint is correct and reachable.");
+    fingerprint = await getRuntimeFingerprint(clientHandle, chainName);
+  } catch {
+    fingerprint = undefined;
   }
+  await saveMetadata(chainName, bytes, fingerprint);
+  return bytes;
 }
 function withTimeout(promise, chainName) {
   return Promise.race([
@@ -838,6 +1247,33 @@ function withTimeout(promise, chainName) {
     new Promise((_, reject) => setTimeout(() => reject(new ConnectionError(`Timed out fetching metadata for "${chainName}" after ${METADATA_TIMEOUT_MS / 1000}s. ` + "Check that the RPC endpoint is correct and reachable.")), METADATA_TIMEOUT_MS))
   ]);
 }
+async function withStalenessSuggestion(chainName, clientHandle, task) {
+  try {
+    return await task();
+  } catch (err) {
+    if (process.env.DOT_TRUST_CACHED_METADATA === "1")
+      throw err;
+    if (!isLikelyStaleMetadataError(err))
+      throw err;
+    let live;
+    try {
+      live = await getRuntimeFingerprint(clientHandle, chainName);
+    } catch {
+      throw err;
+    }
+    const cached = await loadMetadataFingerprint(chainName);
+    if (!cached)
+      throw err;
+    if (fingerprintsMatch(cached, live))
+      throw err;
+    const original = err instanceof Error ? formatRuntimeError(err) : String(err);
+    const versionNote = cached.specVersion !== live.specVersion ? `spec ${cached.specVersion} → ${live.specVersion}` : `runtime code hash changed (same spec ${live.specVersion}; likely a node restart with new wasm)`;
+    throw new CliError(`${original}
+
+` + `⚠ Local metadata for "${chainName}" is out of date (${versionNote}).
+` + `   Run: dot chain update ${chainName}`);
+  }
+}
 async function getOrFetchMetadata(chainName, clientHandle) {
   let raw = await loadMetadata(chainName);
   if (!raw) {
@@ -954,114 +1390,18 @@ function describeRuntimeApiMethodArgs(meta, method) {
 function describeType(lookup, typeId) {
   try {
     const entry = lookup(typeId);
-    return formatLookupEntry(entry);
+    if (!entry || typeof entry.type !== "string")
+      return `type(${typeId})`;
+    return compactTypeString(entry);
   } catch {
     return `type(${typeId})`;
   }
 }
-function formatLookupEntry(entry) {
-  switch (entry.type) {
-    case "primitive":
-      return entry.value;
-    case "compact":
-      return `Compact<${formatLookupEntry(entry.isBig ? { type: "primitive", value: "u128" } : { type: "primitive", value: "u64" })}>`;
-    case "AccountId32":
-      return "AccountId32";
-    case "bitSequence":
-      return "BitSequence";
-    case "sequence":
-      return `Vec<${formatLookupEntry(entry.value)}>`;
-    case "array":
-      return `[${formatLookupEntry(entry.value)}; ${entry.len}]`;
-    case "tuple":
-      return `(${entry.value.map(formatLookupEntry).join(", ")})`;
-    case "struct":
-      return `{ ${Object.entries(entry.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ")} }`;
-    case "option":
-      return `Option<${formatLookupEntry(entry.value)}>`;
-    case "result":
-      return `Result<${formatLookupEntry(entry.value.ok)}, ${formatLookupEntry(entry.value.ko)}>`;
-    case "enum": {
-      const variants = Object.keys(entry.value);
-      if (variants.length <= 4)
-        return variants.join(" | ");
-      return `enum(${variants.length} variants)`;
-    }
-    default:
-      return "unknown";
-  }
-}
 function describeCallArgs(meta, palletName, callName) {
-  try {
-    const palletMeta = meta.unified.pallets.find((p) => p.name === palletName);
-    if (!palletMeta?.calls)
-      return "";
-    const callsEntry = meta.lookup(palletMeta.calls.type);
-    if (callsEntry.type !== "enum")
-      return "";
-    const variant = callsEntry.value[callName];
-    if (!variant)
-      return "";
-    if (variant.type === "void")
-      return "()";
-    if (variant.type === "struct") {
-      const fields = Object.entries(variant.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
-      return `(${fields})`;
-    }
-    if (variant.type === "lookupEntry") {
-      const inner = variant.value;
-      if (inner.type === "void")
-        return "()";
-      if (inner.type === "struct") {
-        const fields = Object.entries(inner.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
-        return `(${fields})`;
-      }
-      return `(${formatLookupEntry(inner)})`;
-    }
-    if (variant.type === "tuple") {
-      const types = variant.value.map(formatLookupEntry).join(", ");
-      return `(${types})`;
-    }
-    return "";
-  } catch {
-    return "";
-  }
+  return compactArgsString(getCallFields(meta, palletName, callName));
 }
 function describeEventFields(meta, palletName, eventName) {
-  try {
-    const palletMeta = meta.unified.pallets.find((p) => p.name === palletName);
-    if (!palletMeta?.events)
-      return "";
-    const eventsEntry = meta.lookup(palletMeta.events.type);
-    if (eventsEntry.type !== "enum")
-      return "";
-    const variant = eventsEntry.value[eventName];
-    if (!variant)
-      return "";
-    if (variant.type === "void")
-      return "()";
-    if (variant.type === "struct") {
-      const fields = Object.entries(variant.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
-      return `(${fields})`;
-    }
-    if (variant.type === "lookupEntry") {
-      const inner = variant.value;
-      if (inner.type === "void")
-        return "()";
-      if (inner.type === "struct") {
-        const fields = Object.entries(inner.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
-        return `(${fields})`;
-      }
-      return `(${formatLookupEntry(inner)})`;
-    }
-    if (variant.type === "tuple") {
-      const types = variant.value.map(formatLookupEntry).join(", ");
-      return `(${types})`;
-    }
-    return "";
-  } catch {
-    return "";
-  }
+  return compactArgsString(getEventFields(meta, palletName, eventName));
 }
 function hexToBytes(hex) {
   const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
@@ -1075,6 +1415,7 @@ var METADATA_TIMEOUT_MS = 15000, optionalOpaqueBytes, v15Arg, PAPI_BUILTIN_EXTEN
 var init_metadata = __esm(() => {
   init_store();
   init_errors();
+  init_pretty_type();
   optionalOpaqueBytes = Option(Bytes());
   v15Arg = toHex(u32.enc(15));
   PAPI_BUILTIN_EXTENSIONS = new Set([
@@ -1471,6 +1812,7 @@ var init_tx = __esm(() => {
   init_client();
   init_metadata();
   init_output();
+  init_pretty_type();
   init_resolve_address();
   init_binary_display();
   init_errors();
@@ -1686,8 +2028,11 @@ async function handleCalls(target, opts) {
     }
     printHeading(`${pallet.name} Calls`);
     for (const c of pallet.calls) {
-      const args2 = describeCallArgs(meta, pallet.name, c.name);
-      console.log(`  ${CYAN}${c.name}${RESET}${DIM}${args2}${RESET}`);
+      const args2 = prettyCallArgs(meta, pallet.name, c.name, {
+        indent: 2,
+        prefix: c.name.length
+      });
+      console.log(`  ${CYAN}${c.name}${RESET}${args2}`);
       const summary = firstSentence(c.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -1713,7 +2058,10 @@ async function handleCalls(target, opts) {
     return;
   }
   printHeading(`${pallet.name}.${callItem.name} (Call)`);
-  const args = describeCallArgs(meta, pallet.name, callItem.name);
+  const args = prettyCallArgs(meta, pallet.name, callItem.name, {
+    indent: 2,
+    prefix: 6
+  });
   console.log(`  ${BOLD}Args:${RESET} ${args}`);
   if (callItem.docs.length) {
     console.log();
@@ -1772,8 +2120,11 @@ async function handleEvents(target, opts) {
     }
     printHeading(`${pallet.name} Events`);
     for (const e of pallet.events) {
-      const fields2 = describeEventFields(meta, pallet.name, e.name);
-      console.log(`  ${CYAN}${e.name}${RESET}${DIM}${fields2}${RESET}`);
+      const fields2 = prettyEventFields(meta, pallet.name, e.name, {
+        indent: 2,
+        prefix: e.name.length
+      });
+      console.log(`  ${CYAN}${e.name}${RESET}${fields2}`);
       const summary = firstSentence(e.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -1799,7 +2150,10 @@ async function handleEvents(target, opts) {
     return;
   }
   printHeading(`${pallet.name}.${eventItem.name} (Event)`);
-  const fields = describeEventFields(meta, pallet.name, eventItem.name);
+  const fields = prettyEventFields(meta, pallet.name, eventItem.name, {
+    indent: 2,
+    prefix: 8
+  });
   console.log(`  ${BOLD}Fields:${RESET} ${fields}`);
   if (eventItem.docs.length) {
     console.log();
@@ -1926,24 +2280,30 @@ async function handleStorage(target, opts) {
         chain: chainName,
         pallet: pallet.name,
         storage: pallet.storage.map((s) => {
-          const valueType = describeType(meta.lookup, s.valueTypeId);
+          const valueType2 = describeType(meta.lookup, s.valueTypeId);
           const keyType = s.keyTypeId != null ? describeType(meta.lookup, s.keyTypeId) : undefined;
-          return { name: s.name, type: s.type, valueType, keyType, docs: firstSentence(s.docs) };
+          return { name: s.name, type: s.type, valueType: valueType2, keyType, docs: firstSentence(s.docs) };
         })
       }));
       return;
     }
     printHeading(`${pallet.name} Storage`);
     for (const s of pallet.storage) {
-      const valueType = describeType(meta.lookup, s.valueTypeId);
-      let typeSuffix;
-      if (s.keyTypeId != null) {
-        const keyType = describeType(meta.lookup, s.keyTypeId);
-        typeSuffix = `: ${keyType} → ${valueType}    [map]`;
-      } else {
-        typeSuffix = `: ${valueType}`;
+      const isMap = s.keyTypeId != null;
+      const tag = isMap ? `${DIM} [map]${RESET}` : "";
+      console.log(`  ${CYAN}${s.name}${RESET}${tag}`);
+      if (isMap) {
+        const keyType = prettyTypeById(meta.lookup, s.keyTypeId, {
+          indent: 4,
+          prefix: 5
+        });
+        console.log(`    ${DIM}Key:${RESET}   ${keyType}`);
       }
-      console.log(`  ${CYAN}${s.name}${RESET}${DIM}${typeSuffix}${RESET}`);
+      const valueType2 = prettyTypeById(meta.lookup, s.valueTypeId, {
+        indent: 4,
+        prefix: 7
+      });
+      console.log(`    ${DIM}Value:${RESET} ${valueType2}`);
       const summary = firstSentence(s.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -1958,7 +2318,7 @@ async function handleStorage(target, opts) {
     throw new Error(suggestMessage(`storage item in ${pallet.name}`, itemName, names));
   }
   if (isJsonOutput(opts)) {
-    const valueType = describeType(meta.lookup, storageItem.valueTypeId);
+    const valueType2 = describeType(meta.lookup, storageItem.valueTypeId);
     const keyType = storageItem.keyTypeId != null ? describeType(meta.lookup, storageItem.keyTypeId) : undefined;
     console.log(formatJson({
       chain: chainName,
@@ -1966,18 +2326,26 @@ async function handleStorage(target, opts) {
       item: storageItem.name,
       category: "storage",
       type: storageItem.type,
-      valueType,
+      valueType: valueType2,
       keyType,
       docs: storageItem.docs
     }));
     return;
   }
   printHeading(`${pallet.name}.${storageItem.name} (Storage)`);
-  console.log(`  ${BOLD}Type:${RESET} ${storageItem.type}`);
-  console.log(`  ${BOLD}Value:${RESET} ${describeType(meta.lookup, storageItem.valueTypeId)}`);
+  console.log(`  ${BOLD}Type:${RESET}  ${storageItem.type}`);
   if (storageItem.keyTypeId != null) {
-    console.log(`  ${BOLD}Key:${RESET} ${describeType(meta.lookup, storageItem.keyTypeId)}`);
+    const keyType = prettyTypeById(meta.lookup, storageItem.keyTypeId, {
+      indent: 2,
+      prefix: 7
+    });
+    console.log(`  ${BOLD}Key:${RESET}   ${keyType}`);
   }
+  const valueType = prettyTypeById(meta.lookup, storageItem.valueTypeId, {
+    indent: 2,
+    prefix: 7
+  });
+  console.log(`  ${BOLD}Value:${RESET} ${valueType}`);
   if (storageItem.docs.length) {
     console.log();
     printDocs(storageItem.docs);
@@ -2008,9 +2376,15 @@ async function showItemHelp(category, target, opts) {
       throw new Error(suggestMessage(`method in ${api.name}`, methodName, names));
     }
     printHeading(`${api.name}.${method.name} (Runtime API)`);
-    const argStr = describeRuntimeApiMethodArgs(meta, method);
-    const retStr = describeType(meta.lookup, method.output);
-    console.log(`  ${BOLD}Args:${RESET} ${argStr}`);
+    const argStr = prettyRuntimeApiArgs(meta.lookup, method.inputs, {
+      indent: 2,
+      prefix: 9
+    });
+    const retStr = prettyTypeById(meta.lookup, method.output, {
+      indent: 2,
+      prefix: 9
+    });
+    console.log(`  ${BOLD}Args:${RESET}    ${argStr}`);
     console.log(`  ${BOLD}Returns:${RESET} ${retStr}`);
     if (method.docs.length) {
       console.log();
@@ -2053,7 +2427,10 @@ async function showItemHelp(category, target, opts) {
         throw new Error(suggestMessage(`call in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${callItem.name} (Call)`);
-      const args = describeCallArgs(meta, pallet.name, callItem.name);
+      const args = prettyCallArgs(meta, pallet.name, callItem.name, {
+        indent: 2,
+        prefix: 6
+      });
       console.log(`  ${BOLD}Args:${RESET} ${args}`);
       if (callItem.docs.length) {
         console.log();
@@ -2080,11 +2457,19 @@ async function showItemHelp(category, target, opts) {
         throw new Error(suggestMessage(`storage item in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${storageItem.name} (Storage)`);
-      console.log(`  ${BOLD}Type:${RESET} ${storageItem.type}`);
-      console.log(`  ${BOLD}Value:${RESET} ${describeType(meta.lookup, storageItem.valueTypeId)}`);
+      console.log(`  ${BOLD}Type:${RESET}  ${storageItem.type}`);
       if (storageItem.keyTypeId != null) {
-        console.log(`  ${BOLD}Key:${RESET} ${describeType(meta.lookup, storageItem.keyTypeId)}`);
+        const keyType = prettyTypeById(meta.lookup, storageItem.keyTypeId, {
+          indent: 2,
+          prefix: 7
+        });
+        console.log(`  ${BOLD}Key:${RESET}   ${keyType}`);
       }
+      const valueType = prettyTypeById(meta.lookup, storageItem.valueTypeId, {
+        indent: 2,
+        prefix: 7
+      });
+      console.log(`  ${BOLD}Value:${RESET} ${valueType}`);
       if (storageItem.docs.length) {
         console.log();
         printDocs(storageItem.docs);
@@ -2111,7 +2496,11 @@ async function showItemHelp(category, target, opts) {
         throw new Error(suggestMessage(`constant in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${constItem.name} (Constant)`);
-      console.log(`  ${BOLD}Type:${RESET} ${describeType(meta.lookup, constItem.typeId)}`);
+      const constType = prettyTypeById(meta.lookup, constItem.typeId, {
+        indent: 2,
+        prefix: 6
+      });
+      console.log(`  ${BOLD}Type:${RESET} ${constType}`);
       if (constItem.docs.length) {
         console.log();
         printDocs(constItem.docs);
@@ -2129,7 +2518,10 @@ async function showItemHelp(category, target, opts) {
         throw new Error(suggestMessage(`event in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${eventItem.name} (Event)`);
-      const fields = describeEventFields(meta, pallet.name, eventItem.name);
+      const fields = prettyEventFields(meta, pallet.name, eventItem.name, {
+        indent: 2,
+        prefix: 8
+      });
       console.log(`  ${BOLD}Fields:${RESET} ${fields}`);
       if (eventItem.docs.length) {
         console.log();
@@ -2164,6 +2556,7 @@ var init_focused_inspect = __esm(() => {
   init_client();
   init_metadata();
   init_output();
+  init_pretty_type();
 });
 
 // src/core/hash.ts
@@ -2553,7 +2946,7 @@ var init_complete = __esm(() => {
     ext: "extensions"
   };
   NAMED_COMMANDS = ["chain", "account", "inspect", "hash", "sign", "parachain", "completions"];
-  CHAIN_SUBCOMMANDS = ["add", "remove", "update", "list"];
+  CHAIN_SUBCOMMANDS = ["add", "info", "list", "remove", "update"];
   ACCOUNT_SUBCOMMANDS = [
     "add",
     "create",
@@ -2584,7 +2977,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.15.1";
+var version = "1.17.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -3427,6 +3820,8 @@ ${BOLD}Usage:${RESET}
   $ dot chain update <name>             Re-fetch metadata for a chain
   $ dot chain update --all              Re-fetch metadata for all configured chains
   $ dot chain list                      List configured chains
+  $ dot chain info <name>               Show details for a single chain
+  $ dot chain <name>                    Shortcut for \`chain info <name>\`
   $ dot chain export [names...]         Export chain configuration to stdout
   $ dot chain import <file>             Import chain configuration from a file
 
@@ -3436,6 +3831,9 @@ ${BOLD}Examples:${RESET}
   $ dot chain add my-para --rpc wss://rpc.example.com --relay polkadot
   $ dot chain add my-para --rpc wss://rpc.example.com --relay polkadot --parachain-id 2000
   $ dot chain list
+  $ dot chains -v
+  $ dot chain info polkadot
+  $ dot chain polkadot
   $ dot chain update kusama
   $ dot chain update --all
   $ dot chain remove kusama
@@ -3448,7 +3846,7 @@ ${BOLD}Examples:${RESET}
   $ dot chain import my-chains.json --no-metadata
 `.trimStart();
 function registerChainCommands(cli) {
-  cli.command("chain [action] [...names]", "Manage chains (add, remove, update, list, export, import)").alias("chains").option("--all", "Update/export all configured chains").option("--relay <name>", "Parent relay chain for this parachain").option("--parachain-id <id>", "Parachain ID (auto-detected if omitted with --relay)").option("--file <path>", "Output/input file for export/import").option("--overwrite", "Overwrite existing chains on import").option("--dry-run", "Preview import without applying changes").option("--no-metadata", "Skip automatic metadata fetch after import").action(async (action, names, opts) => {
+  cli.command("chain [action] [...names]", "Manage chains (add, remove, update, list, export, import)").alias("chains").option("--all", "Update/export all configured chains").option("--relay <name>", "Parent relay chain for this parachain").option("--parachain-id <id>", "Parachain ID (auto-detected if omitted with --relay)").option("--file <path>", "Output/input file for export/import").option("--overwrite", "Overwrite existing chains on import").option("--dry-run", "Preview import without applying changes").option("--no-metadata", "Skip automatic metadata fetch after import").option("-v, --verbose", "Show RPC endpoints in `chains` list output").action(async (action, names, opts) => {
     if (!action) {
       if (process.argv[2] === "chains")
         return chainList(opts);
@@ -3462,17 +3860,24 @@ function registerChainCommands(cli) {
         return chainRemove(names[0], opts);
       case "list":
         return chainList(opts);
+      case "info":
+        return chainInfo(names[0], opts);
       case "update":
         return chainUpdate(names[0], opts);
       case "export":
         return chainExport(names, opts);
       case "import":
         return chainImport(names[0], opts);
-      default:
+      default: {
+        const config = await loadConfig();
+        if (findChainName(config, action)) {
+          return chainInfo(action, opts);
+        }
         console.error(`Unknown action "${action}".
 `);
         console.log(CHAIN_HELP);
         process.exit(1);
+      }
     }
   });
 }
@@ -3582,6 +3987,7 @@ async function chainList(opts = {}) {
     console.log(formatJson({ chains }));
     return;
   }
+  const verbose = opts.verbose === true;
   printHeading("Configured Chains");
   const parachainsByRelay = new Map;
   const standalone = [];
@@ -3603,7 +4009,7 @@ async function chainList(opts = {}) {
   for (const relayName of relayNames) {
     const relayConfig = config.chains[relayName];
     if (relayConfig) {
-      printChainLine("  ", relayName, relayConfig);
+      printChainLine("  ", relayName, relayConfig, "", verbose);
     }
     const paras = parachainsByRelay.get(relayName) ?? [];
     for (let i = 0;i < paras.length; i++) {
@@ -3611,17 +4017,21 @@ async function chainList(opts = {}) {
       const isLast = i === paras.length - 1;
       const prefix = isLast ? "  └─ " : "  ├─ ";
       const idSuffix = chainConfig.parachainId != null ? ` ${DIM}[${chainConfig.parachainId}]${RESET}` : "";
-      printChainLine(prefix, name, chainConfig, idSuffix);
+      printChainLine(prefix, name, chainConfig, idSuffix, verbose);
     }
     console.log();
   }
   for (const [name, chainConfig] of standalone) {
-    printChainLine("  ", name, chainConfig);
+    printChainLine("  ", name, chainConfig, "", verbose);
   }
   if (standalone.length > 0)
     console.log();
 }
-function printChainLine(prefix, name, chainConfig, suffix = "") {
+function printChainLine(prefix, name, chainConfig, suffix = "", verbose = false) {
+  if (!verbose) {
+    console.log(`${prefix}${CYAN}${name}${RESET}${suffix}`);
+    return;
+  }
   const rpcs = Array.isArray(chainConfig.rpc) ? chainConfig.rpc : [chainConfig.rpc];
   console.log(`${prefix}${CYAN}${name}${RESET}${suffix}  ${DIM}${rpcs[0]}${RESET}`);
   const indent = prefix.replace(/[^\s]/g, " ");
@@ -3629,6 +4039,56 @@ function printChainLine(prefix, name, chainConfig, suffix = "") {
     console.log(`${indent}  ${DIM}${rpcs[i]}${RESET}`);
   }
 }
+async function chainInfo(name, opts = {}) {
+  if (!name) {
+    console.error("Usage: dot chain info <name>");
+    process.exit(1);
+  }
+  const config = await loadConfig();
+  const { name: resolved, chain } = resolveChain(config, name);
+  const rpcs = Array.isArray(chain.rpc) ? chain.rpc : [chain.rpc];
+  const parachains = Object.entries(config.chains).filter(([, c]) => c.relay === resolved).map(([n, c]) => ({ name: n, parachainId: c.parachainId }));
+  const fingerprint = await loadMetadataFingerprint(resolved);
+  if (isJsonOutput(opts)) {
+    console.log(formatJson({
+      name: resolved,
+      rpc: rpcs,
+      ...chain.relay && { relay: chain.relay },
+      ...chain.parachainId != null && { parachainId: chain.parachainId },
+      ...parachains.length > 0 && { parachains },
+      metadata: fingerprint ? {
+        specName: fingerprint.specName,
+        specVersion: fingerprint.specVersion,
+        fetchedAt: fingerprint.fetchedAt
+      } : null
+    }));
+    return;
+  }
+  printHeading(resolved);
+  console.log(`  ${CYAN}rpc:${RESET}`);
+  for (const rpc of rpcs) {
+    console.log(`    ${DIM}${rpc}${RESET}`);
+  }
+  if (chain.relay) {
+    console.log(`  ${CYAN}relay:${RESET}        ${chain.relay}`);
+  }
+  if (chain.parachainId != null) {
+    console.log(`  ${CYAN}parachain id:${RESET} ${chain.parachainId}`);
+  }
+  if (parachains.length > 0) {
+    console.log(`  ${CYAN}parachains:${RESET}`);
+    for (const p of parachains) {
+      const idSuffix = p.parachainId != null ? ` ${DIM}[${p.parachainId}]${RESET}` : "";
+      console.log(`    ${p.name}${idSuffix}`);
+    }
+  }
+  console.log(`  ${CYAN}metadata:${RESET}`);
+  if (fingerprint) {
+    console.log(`    ${fingerprint.specName} v${fingerprint.specVersion} ${DIM}(cached ${fingerprint.fetchedAt})${RESET}`);
+  } else {
+    console.log(`    ${DIM}not cached — run \`dot chain update ${resolved}\`${RESET}`);
+  }
+}
 async function chainUpdate(name, opts) {
   const config = await loadConfig();
   if (opts.all) {
@@ -4005,6 +4465,7 @@ init_store();
 init_client();
 init_metadata();
 init_output();
+init_pretty_type();
 async function loadMeta2(chainName, chainConfig, rpcOverride) {
   if (rpcOverride) {
     process.stderr.write(`Fetching metadata from ${chainName}...
@@ -4089,8 +4550,11 @@ async function handleCalls2(target, opts) {
     }
     printHeading(`${pallet.name} Calls`);
     for (const c of pallet.calls) {
-      const args2 = describeCallArgs(meta, pallet.name, c.name);
-      console.log(`  ${CYAN}${c.name}${RESET}${DIM}${args2}${RESET}`);
+      const args2 = prettyCallArgs(meta, pallet.name, c.name, {
+        indent: 2,
+        prefix: c.name.length
+      });
+      console.log(`  ${CYAN}${c.name}${RESET}${args2}`);
       const summary = firstSentence(c.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -4116,7 +4580,10 @@ async function handleCalls2(target, opts) {
     return;
   }
   printHeading(`${pallet.name}.${callItem.name} (Call)`);
-  const args = describeCallArgs(meta, pallet.name, callItem.name);
+  const args = prettyCallArgs(meta, pallet.name, callItem.name, {
+    indent: 2,
+    prefix: 6
+  });
   console.log(`  ${BOLD}Args:${RESET} ${args}`);
   if (callItem.docs.length) {
     console.log();
@@ -4175,8 +4642,11 @@ async function handleEvents2(target, opts) {
     }
     printHeading(`${pallet.name} Events`);
     for (const e of pallet.events) {
-      const fields2 = describeEventFields(meta, pallet.name, e.name);
-      console.log(`  ${CYAN}${e.name}${RESET}${DIM}${fields2}${RESET}`);
+      const fields2 = prettyEventFields(meta, pallet.name, e.name, {
+        indent: 2,
+        prefix: e.name.length
+      });
+      console.log(`  ${CYAN}${e.name}${RESET}${fields2}`);
       const summary = firstSentence(e.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -4202,7 +4672,10 @@ async function handleEvents2(target, opts) {
     return;
   }
   printHeading(`${pallet.name}.${eventItem.name} (Event)`);
-  const fields = describeEventFields(meta, pallet.name, eventItem.name);
+  const fields = prettyEventFields(meta, pallet.name, eventItem.name, {
+    indent: 2,
+    prefix: 8
+  });
   console.log(`  ${BOLD}Fields:${RESET} ${fields}`);
   if (eventItem.docs.length) {
     console.log();
@@ -4329,24 +4802,30 @@ async function handleStorage2(target, opts) {
         chain: chainName,
         pallet: pallet.name,
         storage: pallet.storage.map((s) => {
-          const valueType = describeType(meta.lookup, s.valueTypeId);
+          const valueType2 = describeType(meta.lookup, s.valueTypeId);
           const keyType = s.keyTypeId != null ? describeType(meta.lookup, s.keyTypeId) : undefined;
-          return { name: s.name, type: s.type, valueType, keyType, docs: firstSentence(s.docs) };
+          return { name: s.name, type: s.type, valueType: valueType2, keyType, docs: firstSentence(s.docs) };
         })
       }));
       return;
     }
     printHeading(`${pallet.name} Storage`);
     for (const s of pallet.storage) {
-      const valueType = describeType(meta.lookup, s.valueTypeId);
-      let typeSuffix;
-      if (s.keyTypeId != null) {
-        const keyType = describeType(meta.lookup, s.keyTypeId);
-        typeSuffix = `: ${keyType} → ${valueType}    [map]`;
-      } else {
-        typeSuffix = `: ${valueType}`;
+      const isMap = s.keyTypeId != null;
+      const tag = isMap ? `${DIM} [map]${RESET}` : "";
+      console.log(`  ${CYAN}${s.name}${RESET}${tag}`);
+      if (isMap) {
+        const keyType = prettyTypeById(meta.lookup, s.keyTypeId, {
+          indent: 4,
+          prefix: 5
+        });
+        console.log(`    ${DIM}Key:${RESET}   ${keyType}`);
       }
-      console.log(`  ${CYAN}${s.name}${RESET}${DIM}${typeSuffix}${RESET}`);
+      const valueType2 = prettyTypeById(meta.lookup, s.valueTypeId, {
+        indent: 4,
+        prefix: 7
+      });
+      console.log(`    ${DIM}Value:${RESET} ${valueType2}`);
       const summary = firstSentence(s.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -4361,7 +4840,7 @@ async function handleStorage2(target, opts) {
     throw new Error(suggestMessage(`storage item in ${pallet.name}`, itemName, names));
   }
   if (isJsonOutput(opts)) {
-    const valueType = describeType(meta.lookup, storageItem.valueTypeId);
+    const valueType2 = describeType(meta.lookup, storageItem.valueTypeId);
     const keyType = storageItem.keyTypeId != null ? describeType(meta.lookup, storageItem.keyTypeId) : undefined;
     console.log(formatJson({
       chain: chainName,
@@ -4369,18 +4848,26 @@ async function handleStorage2(target, opts) {
       item: storageItem.name,
       category: "storage",
       type: storageItem.type,
-      valueType,
+      valueType: valueType2,
       keyType,
       docs: storageItem.docs
     }));
     return;
   }
   printHeading(`${pallet.name}.${storageItem.name} (Storage)`);
-  console.log(`  ${BOLD}Type:${RESET} ${storageItem.type}`);
-  console.log(`  ${BOLD}Value:${RESET} ${describeType(meta.lookup, storageItem.valueTypeId)}`);
+  console.log(`  ${BOLD}Type:${RESET}  ${storageItem.type}`);
   if (storageItem.keyTypeId != null) {
-    console.log(`  ${BOLD}Key:${RESET} ${describeType(meta.lookup, storageItem.keyTypeId)}`);
+    const keyType = prettyTypeById(meta.lookup, storageItem.keyTypeId, {
+      indent: 2,
+      prefix: 7
+    });
+    console.log(`  ${BOLD}Key:${RESET}   ${keyType}`);
   }
+  const valueType = prettyTypeById(meta.lookup, storageItem.valueTypeId, {
+    indent: 2,
+    prefix: 7
+  });
+  console.log(`  ${BOLD}Value:${RESET} ${valueType}`);
   if (storageItem.docs.length) {
     console.log();
     printDocs(storageItem.docs);
@@ -4411,9 +4898,15 @@ async function showItemHelp2(category, target, opts) {
       throw new Error(suggestMessage(`method in ${api.name}`, methodName, names));
     }
     printHeading(`${api.name}.${method.name} (Runtime API)`);
-    const argStr = describeRuntimeApiMethodArgs(meta, method);
-    const retStr = describeType(meta.lookup, method.output);
-    console.log(`  ${BOLD}Args:${RESET} ${argStr}`);
+    const argStr = prettyRuntimeApiArgs(meta.lookup, method.inputs, {
+      indent: 2,
+      prefix: 9
+    });
+    const retStr = prettyTypeById(meta.lookup, method.output, {
+      indent: 2,
+      prefix: 9
+    });
+    console.log(`  ${BOLD}Args:${RESET}    ${argStr}`);
     console.log(`  ${BOLD}Returns:${RESET} ${retStr}`);
     if (method.docs.length) {
       console.log();
@@ -4456,7 +4949,10 @@ async function showItemHelp2(category, target, opts) {
         throw new Error(suggestMessage(`call in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${callItem.name} (Call)`);
-      const args = describeCallArgs(meta, pallet.name, callItem.name);
+      const args = prettyCallArgs(meta, pallet.name, callItem.name, {
+        indent: 2,
+        prefix: 6
+      });
       console.log(`  ${BOLD}Args:${RESET} ${args}`);
       if (callItem.docs.length) {
         console.log();
@@ -4483,11 +4979,19 @@ async function showItemHelp2(category, target, opts) {
         throw new Error(suggestMessage(`storage item in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${storageItem.name} (Storage)`);
-      console.log(`  ${BOLD}Type:${RESET} ${storageItem.type}`);
-      console.log(`  ${BOLD}Value:${RESET} ${describeType(meta.lookup, storageItem.valueTypeId)}`);
+      console.log(`  ${BOLD}Type:${RESET}  ${storageItem.type}`);
       if (storageItem.keyTypeId != null) {
-        console.log(`  ${BOLD}Key:${RESET} ${describeType(meta.lookup, storageItem.keyTypeId)}`);
+        const keyType = prettyTypeById(meta.lookup, storageItem.keyTypeId, {
+          indent: 2,
+          prefix: 7
+        });
+        console.log(`  ${BOLD}Key:${RESET}   ${keyType}`);
       }
+      const valueType = prettyTypeById(meta.lookup, storageItem.valueTypeId, {
+        indent: 2,
+        prefix: 7
+      });
+      console.log(`  ${BOLD}Value:${RESET} ${valueType}`);
       if (storageItem.docs.length) {
         console.log();
         printDocs(storageItem.docs);
@@ -4514,7 +5018,11 @@ async function showItemHelp2(category, target, opts) {
         throw new Error(suggestMessage(`constant in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${constItem.name} (Constant)`);
-      console.log(`  ${BOLD}Type:${RESET} ${describeType(meta.lookup, constItem.typeId)}`);
+      const constType = prettyTypeById(meta.lookup, constItem.typeId, {
+        indent: 2,
+        prefix: 6
+      });
+      console.log(`  ${BOLD}Type:${RESET} ${constType}`);
       if (constItem.docs.length) {
         console.log();
         printDocs(constItem.docs);
@@ -4532,7 +5040,10 @@ async function showItemHelp2(category, target, opts) {
         throw new Error(suggestMessage(`event in ${pallet.name}`, itemName, names));
       }
       printHeading(`${pallet.name}.${eventItem.name} (Event)`);
-      const fields = describeEventFields(meta, pallet.name, eventItem.name);
+      const fields = prettyEventFields(meta, pallet.name, eventItem.name, {
+        indent: 2,
+        prefix: 8
+      });
       console.log(`  ${BOLD}Fields:${RESET} ${fields}`);
       if (eventItem.docs.length) {
         console.log();
@@ -4607,8 +5118,16 @@ async function handleExtensions(target, opts) {
     return;
   }
   printHeading(`${described.identifier} (Transaction Extension)`);
-  console.log(`  ${BOLD}Value type:${RESET}       ${described.valueType}`);
-  console.log(`  ${BOLD}AdditionalSigned:${RESET} ${described.additionalSignedType}`);
+  const valueType = prettyTypeById(meta.lookup, described.valueTypeId, {
+    indent: 2,
+    prefix: 18
+  });
+  const addSigType = prettyTypeById(meta.lookup, described.additionalSignedTypeId, {
+    indent: 2,
+    prefix: 18
+  });
+  console.log(`  ${BOLD}Value type:${RESET}       ${valueType}`);
+  console.log(`  ${BOLD}AdditionalSigned:${RESET} ${addSigType}`);
   console.log(`  ${BOLD}Handled by:${RESET}       ${described.isBuiltin ? "polkadot-api (builtin)" : "user (custom — provide via --ext)"}`);
   if (!described.isBuiltin) {
     console.log();
@@ -4692,6 +5211,7 @@ init_store();
 init_client();
 init_metadata();
 init_output();
+init_pretty_type();
 
 // src/utils/parse-target.ts
 function parseTarget(input, options) {
@@ -4868,15 +5388,21 @@ function registerInspectCommand(cli) {
       if (pallet2.storage.length) {
         console.log(`  ${BOLD}Storage Items:${RESET}`);
         for (const s of pallet2.storage) {
-          const valueType = describeType(meta.lookup, s.valueTypeId);
-          let typeSuffix;
-          if (s.keyTypeId != null) {
-            const keyType = describeType(meta.lookup, s.keyTypeId);
-            typeSuffix = `: ${keyType} → ${valueType}    [map]`;
-          } else {
-            typeSuffix = `: ${valueType}`;
+          const isMap = s.keyTypeId != null;
+          const tag = isMap ? `${DIM} [map]${RESET}` : "";
+          console.log(`    ${CYAN}${s.name}${RESET}${tag}`);
+          if (isMap) {
+            const keyType = prettyTypeById(meta.lookup, s.keyTypeId, {
+              indent: 6,
+              prefix: 7
+            });
+            console.log(`      ${DIM}Key:${RESET}   ${keyType}`);
           }
-          console.log(`    ${CYAN}${s.name}${RESET}${DIM}${typeSuffix}${RESET}`);
+          const valueType = prettyTypeById(meta.lookup, s.valueTypeId, {
+            indent: 6,
+            prefix: 7
+          });
+          console.log(`      ${DIM}Value:${RESET} ${valueType}`);
           const summary = firstSentence(s.docs);
           if (summary) {
             console.log(`        ${DIM}${summary}${RESET}`);
@@ -4887,8 +5413,11 @@ function registerInspectCommand(cli) {
       if (pallet2.constants.length) {
         console.log(`  ${BOLD}Constants:${RESET}`);
         for (const c of pallet2.constants) {
-          const typeStr = describeType(meta.lookup, c.typeId);
-          console.log(`    ${CYAN}${c.name}${RESET}${DIM}: ${typeStr}${RESET}`);
+          const typeStr = prettyTypeById(meta.lookup, c.typeId, {
+            indent: 4,
+            prefix: c.name.length + 2
+          });
+          console.log(`    ${CYAN}${c.name}${RESET}: ${typeStr}`);
           const summary = firstSentence(c.docs);
           if (summary) {
             console.log(`        ${DIM}${summary}${RESET}`);
@@ -4899,8 +5428,11 @@ function registerInspectCommand(cli) {
       if (pallet2.calls.length) {
         console.log(`  ${BOLD}Calls:${RESET}`);
         for (const c of pallet2.calls) {
-          const args = describeCallArgs(meta, pallet2.name, c.name);
-          console.log(`    ${CYAN}${c.name}${RESET}${DIM}${args}${RESET}`);
+          const args = prettyCallArgs(meta, pallet2.name, c.name, {
+            indent: 4,
+            prefix: c.name.length
+          });
+          console.log(`    ${CYAN}${c.name}${RESET}${args}`);
           const summary = firstSentence(c.docs);
           if (summary) {
             console.log(`        ${DIM}${summary}${RESET}`);
@@ -4911,8 +5443,11 @@ function registerInspectCommand(cli) {
       if (pallet2.events.length) {
         console.log(`  ${BOLD}Events:${RESET}`);
         for (const e of pallet2.events) {
-          const fields = describeEventFields(meta, pallet2.name, e.name);
-          console.log(`    ${CYAN}${e.name}${RESET}${DIM}${fields}${RESET}`);
+          const fields = prettyEventFields(meta, pallet2.name, e.name, {
+            indent: 4,
+            prefix: e.name.length
+          });
+          console.log(`    ${CYAN}${e.name}${RESET}${fields}`);
           const summary = firstSentence(e.docs);
           if (summary) {
             console.log(`        ${DIM}${summary}${RESET}`);
@@ -5014,11 +5549,19 @@ function registerInspectCommand(cli) {
     const storageItem = pallet.storage.find((s) => s.name.toLowerCase() === itemName.toLowerCase());
     if (storageItem) {
       printHeading(`${pallet.name}.${storageItem.name} (Storage)`);
-      console.log(`  ${BOLD}Type:${RESET} ${storageItem.type}`);
-      console.log(`  ${BOLD}Value:${RESET} ${describeType(meta.lookup, storageItem.valueTypeId)}`);
+      console.log(`  ${BOLD}Type:${RESET}  ${storageItem.type}`);
       if (storageItem.keyTypeId != null) {
-        console.log(`  ${BOLD}Key:${RESET} ${describeType(meta.lookup, storageItem.keyTypeId)}`);
+        const keyType = prettyTypeById(meta.lookup, storageItem.keyTypeId, {
+          indent: 2,
+          prefix: 7
+        });
+        console.log(`  ${BOLD}Key:${RESET}   ${keyType}`);
       }
+      const valueType = prettyTypeById(meta.lookup, storageItem.valueTypeId, {
+        indent: 2,
+        prefix: 7
+      });
+      console.log(`  ${BOLD}Value:${RESET} ${valueType}`);
       if (storageItem.docs.length) {
         console.log();
         printDocs(storageItem.docs);
@@ -5029,7 +5572,11 @@ function registerInspectCommand(cli) {
     const constantItem = pallet.constants.find((c) => c.name.toLowerCase() === itemName.toLowerCase());
     if (constantItem) {
       printHeading(`${pallet.name}.${constantItem.name} (Constant)`);
-      console.log(`  ${BOLD}Type:${RESET} ${describeType(meta.lookup, constantItem.typeId)}`);
+      const typeStr = prettyTypeById(meta.lookup, constantItem.typeId, {
+        indent: 2,
+        prefix: 6
+      });
+      console.log(`  ${BOLD}Type:${RESET} ${typeStr}`);
       if (constantItem.docs.length) {
         console.log();
         printDocs(constantItem.docs);
@@ -5040,7 +5587,10 @@ function registerInspectCommand(cli) {
     const callItem = pallet.calls.find((c) => c.name.toLowerCase() === itemName.toLowerCase());
     if (callItem) {
       printHeading(`${pallet.name}.${callItem.name} (Call)`);
-      const args = describeCallArgs(meta, pallet.name, callItem.name);
+      const args = prettyCallArgs(meta, pallet.name, callItem.name, {
+        indent: 2,
+        prefix: 6
+      });
       console.log(`  ${BOLD}Args:${RESET} ${args}`);
       if (callItem.docs.length) {
         console.log();
@@ -5052,7 +5602,10 @@ function registerInspectCommand(cli) {
     const eventItem = pallet.events.find((e) => e.name.toLowerCase() === itemName.toLowerCase());
     if (eventItem) {
       printHeading(`${pallet.name}.${eventItem.name} (Event)`);
-      const fields = describeEventFields(meta, pallet.name, eventItem.name);
+      const fields = prettyEventFields(meta, pallet.name, eventItem.name, {
+        indent: 2,
+        prefix: 8
+      });
       console.log(`  ${BOLD}Fields:${RESET} ${fields}`);
       if (eventItem.docs.length) {
         console.log();
@@ -5081,6 +5634,56 @@ function registerInspectCommand(cli) {
   });
 }
 
+// src/commands/metadata.ts
+init_store();
+init_client();
+init_metadata();
+init_output();
+init_errors();
+function buildMetadataPayload(chainName, meta, fingerprint) {
+  return {
+    chain: chainName,
+    runtime: { ...fingerprint ?? {}, metadataVersion: meta.version },
+    pallets: listPallets(meta),
+    runtimeApis: listRuntimeApis(meta),
+    transactionExtensions: getSignedExtensions(meta)
+  };
+}
+async function handleMetadata(chain, opts) {
+  const config = await loadConfig();
+  const { name: chainName, chain: chainConfig } = resolveChain(config, chain);
+  let rawBytes;
+  if (opts.cached) {
+    rawBytes = await loadMetadata(chainName);
+    if (!rawBytes) {
+      throw new CliError(`No cached metadata for "${chainName}". Run \`dot chain update ${chainName}\` first, or omit --cached to fetch fresh.`);
+    }
+  } else {
+    const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
+    try {
+      await fetchMetadataFromChain(clientHandle, chainName);
+    } finally {
+      clientHandle.destroy();
+    }
+    rawBytes = await loadMetadata(chainName);
+    if (!rawBytes) {
+      throw new CliError(`Failed to load metadata for "${chainName}" after fetch.`);
+    }
+  }
+  if (opts.raw) {
+    await writeStdout(`0x${Buffer.from(rawBytes).toString("hex")}
+`);
+    return;
+  }
+  const meta = parseMetadata(rawBytes);
+  const fingerprint = await loadMetadataFingerprint(chainName);
+  await writeStdout(`${formatJson(buildMetadataPayload(chainName, meta, fingerprint))}
+`);
+}
+function registerMetadataCommand(cli) {
+  cli.command("metadata <chain>", "Fetch chain metadata (decoded JSON; --raw for SCALE hex)").option("--raw", "Print SCALE-encoded metadata bytes as hex instead of decoded JSON").option("--cached", "Use cached metadata instead of fetching fresh from the chain").option("--rpc <url>", "Override RPC endpoint(s)").action((chain, opts) => handleMetadata(chain, opts));
+}
+
 // src/commands/parachain.ts
 init_accounts();
 init_output();
@@ -5176,6 +5779,7 @@ init_store();
 init_client();
 init_metadata();
 init_output();
+init_pretty_type();
 init_focused_inspect();
 init_tx();
 async function handleQuery(target, keys, opts) {
@@ -5186,10 +5790,11 @@ async function handleQuery(target, keys, opts) {
     const pallets = listPallets(meta);
     const withStorage = pallets.filter((p) => p.storage.length > 0);
     if (isJsonOutput(opts)) {
-      console.log(formatJson({
+      await writeStdout(`${formatJson({
         chain: chainName2,
         pallets: withStorage.map((p) => ({ name: p.name, storage: p.storage.length }))
-      }));
+      })}
+`);
       return;
     }
     printHeading(`Pallets with storage on ${chainName2} (${withStorage.length})`);
@@ -5207,14 +5812,15 @@ async function handleQuery(target, keys, opts) {
     const pallet2 = resolvePallet(meta, palletName(target));
     if (pallet2.storage.length === 0) {
       if (isJsonOutput(opts)) {
-        console.log(formatJson({ chain: chainName2, pallet: pallet2.name, storage: [] }));
+        await writeStdout(`${formatJson({ chain: chainName2, pallet: pallet2.name, storage: [] })}
+`);
       } else {
         console.log(`No storage items in ${pallet2.name}.`);
       }
       return;
     }
     if (isJsonOutput(opts)) {
-      console.log(formatJson({
+      await writeStdout(`${formatJson({
         chain: chainName2,
         pallet: pallet2.name,
         storage: pallet2.storage.map((s) => {
@@ -5222,20 +5828,27 @@ async function handleQuery(target, keys, opts) {
           const keyType = s.keyTypeId != null ? describeType(meta.lookup, s.keyTypeId) : undefined;
           return { name: s.name, type: s.type, valueType, keyType, docs: firstSentence(s.docs) };
         })
-      }));
+      })}
+`);
       return;
     }
     printHeading(`${pallet2.name} Storage`);
     for (const s of pallet2.storage) {
-      const valueType = describeType(meta.lookup, s.valueTypeId);
-      let typeSuffix;
-      if (s.keyTypeId != null) {
-        const keyType = describeType(meta.lookup, s.keyTypeId);
-        typeSuffix = `: ${keyType} → ${valueType}    [map]`;
-      } else {
-        typeSuffix = `: ${valueType}`;
+      const isMap = s.keyTypeId != null;
+      const tag = isMap ? `${DIM} [map]${RESET}` : "";
+      console.log(`  ${CYAN}${s.name}${RESET}${tag}`);
+      if (isMap) {
+        const keyType = prettyTypeById(meta.lookup, s.keyTypeId, {
+          indent: 4,
+          prefix: 5
+        });
+        console.log(`    ${DIM}Key:${RESET}   ${keyType}`);
       }
-      console.log(`  ${CYAN}${s.name}${RESET}${DIM}${typeSuffix}${RESET}`);
+      const valueType = prettyTypeById(meta.lookup, s.valueTypeId, {
+        indent: 4,
+        prefix: 7
+      });
+      console.log(`    ${DIM}Value:${RESET} ${valueType}`);
       const summary = firstSentence(s.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -5276,14 +5889,19 @@ async function handleQuery(target, keys, opts) {
         console.log(`${DIM}Hint: use --dump to fetch all entries${RESET}`);
         return;
       }
-      const entries = await storageApi.getEntries(...parsedKeys);
-      printResult(entries.map((e) => ({
+      const entries = await withStalenessSuggestion(chainName, clientHandle, () => storageApi.getEntries(...parsedKeys));
+      const rows = entries.map((e) => ({
         keys: e.keyArgs,
         value: e.value
-      })), format);
+      }));
+      const text = format === "json" ? formatJson(rows) : formatPretty(rows);
+      await writeStdout(`${text}
+`);
     } else {
-      const result = await storageApi.getValue(...parsedKeys);
-      printResult(result, format);
+      const result = await withStalenessSuggestion(chainName, clientHandle, () => storageApi.getValue(...parsedKeys));
+      const text = format === "json" ? formatJson(result) : formatPretty(result);
+      await writeStdout(`${text}
+`);
     }
   } finally {
     clientHandle.destroy();
@@ -5430,6 +6048,7 @@ init_accounts();
 init_client();
 init_metadata();
 init_output();
+init_pretty_type();
 init_resolve_address();
 init_binary_display();
 init_errors();
@@ -5562,8 +6181,11 @@ async function handleTx(target, args, opts) {
     }
     printHeading(`${pallet2.name} Calls`);
     for (const c of pallet2.calls) {
-      const callArgs = describeCallArgs(meta, pallet2.name, c.name);
-      console.log(`  ${CYAN}${c.name}${RESET}${DIM}${callArgs}${RESET}`);
+      const callArgs = prettyCallArgs(meta, pallet2.name, c.name, {
+        indent: 2,
+        prefix: c.name.length
+      });
+      console.log(`  ${CYAN}${c.name}${RESET}${callArgs}`);
       const summary = firstSentence(c.docs);
       if (summary) {
         console.log(`      ${DIM}${summary}${RESET}`);
@@ -5714,6 +6336,7 @@ async function handleTx(target, args, opts) {
       callHex = Binary3.toHex(encodedCall);
     }
     const decodedStr = decodeCall(meta, callHex);
+    const decodedObj = decodeCallObject(meta, callHex);
     if (opts.dryRun && opts.unsigned) {
       if (isJsonOutput(opts)) {
         console.log(formatJson({
@@ -5728,17 +6351,18 @@ async function handleTx(target, args, opts) {
       console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
       console.log(`  ${BOLD}Type:${RESET}   unsigned (bare)`);
       console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
-      console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
+      printDecodedCall(decodedObj, decodedStr);
       console.log(`  ${BOLD}Fees:${RESET}   ${DIM}N/A (unsigned transaction)${RESET}`);
       return;
     }
     if (opts.dryRun) {
       const signerAddress = toSs58(signer.publicKey);
       let estimatedFees;
+      let estimationError;
       try {
-        estimatedFees = String(await tx.getEstimatedFees(signer?.publicKey, txOptions));
-      } catch {
-        estimatedFees = undefined;
+        estimatedFees = String(await withStalenessSuggestion(chainName, clientHandle, () => tx.getEstimatedFees(signer?.publicKey, txOptions)));
+      } catch (err) {
+        estimationError = err instanceof Error ? err.message : String(err);
       }
       if (isJsonOutput(opts)) {
         const result2 = {
@@ -5748,6 +6372,8 @@ async function handleTx(target, args, opts) {
           decoded: decodedStr,
           estimatedFees
         };
+        if (estimationError !== undefined)
+          result2.estimationError = estimationError;
         if (nonce !== undefined)
           result2.nonce = nonce;
         if (tip !== undefined)
@@ -5764,7 +6390,7 @@ async function handleTx(target, args, opts) {
       console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
       console.log(`  ${BOLD}From:${RESET}   ${opts.from} (${signerAddress})`);
       console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
-      console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
+      printDecodedCall(decodedObj, decodedStr);
       if (nonce !== undefined)
         console.log(`  ${BOLD}Nonce:${RESET} ${nonce}`);
       if (tip !== undefined)
@@ -5779,6 +6405,12 @@ async function handleTx(target, args, opts) {
         console.log(`  ${BOLD}Estimated fees:${RESET} ${estimatedFees}`);
       } else {
         console.log(`  ${BOLD}Estimated fees:${RESET} ${YELLOW}unable to estimate${RESET}`);
+        if (estimationError) {
+          const formatted = formatRuntimeError(estimationError).replace(/\n/g, `
+  `);
+          console.log(`  ${YELLOW}⚠${RESET} ${formatted}`);
+          console.log(`  ${DIM}Submitting this transaction is likely to fail.${RESET}`);
+        }
       }
       return;
     }
@@ -5798,7 +6430,7 @@ async function handleTx(target, args, opts) {
       }
       const observable = clientHandle.client.submitAndWatch(generalTx, at);
       if (isJsonOutput(opts)) {
-        const result3 = await watchTransactionJson(observable, waitLevel, { unsigned: true });
+        const result3 = await withStalenessSuggestion(chainName, clientHandle, () => watchTransactionJson(observable, waitLevel, { unsigned: true }));
         const rpcUrl3 = primaryRpc(opts.rpc ?? chainConfig.rpc);
         if (result3.type === "broadcasted") {
           printJsonLine({ event: "broadcasted", txHash: result3.txHash });
@@ -5830,12 +6462,12 @@ async function handleTx(target, args, opts) {
         }
         return;
       }
-      const result2 = await watchTransaction(observable, waitLevel, { unsigned: true });
+      const result2 = await withStalenessSuggestion(chainName, clientHandle, () => watchTransaction(observable, waitLevel, { unsigned: true }));
       console.log();
       console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
       console.log(`  ${BOLD}Type:${RESET}   unsigned (bare)`);
       console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
-      console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
+      printDecodedCall(decodedObj, decodedStr);
       console.log(`  ${BOLD}Tx:${RESET}     ${result2.txHash}`);
       if (result2.type === "broadcasted") {
         console.log(`  ${BOLD}Status:${RESET} ${GREEN}broadcasted${RESET}`);
@@ -5879,7 +6511,7 @@ async function handleTx(target, args, opts) {
       return;
     }
     if (isJsonOutput(opts)) {
-      const result2 = await watchTransactionJson(tx.signSubmitAndWatch(signer, txOptions), waitLevel);
+      const result2 = await withStalenessSuggestion(chainName, clientHandle, () => watchTransactionJson(tx.signSubmitAndWatch(signer, txOptions), waitLevel));
       const rpcUrl2 = primaryRpc(opts.rpc ?? chainConfig.rpc);
       if (result2.type === "broadcasted") {
         printJsonLine({ event: "broadcasted", txHash: result2.txHash });
@@ -5910,11 +6542,11 @@ async function handleTx(target, args, opts) {
       }
       return;
     }
-    const result = await watchTransaction(tx.signSubmitAndWatch(signer, txOptions), waitLevel);
+    const result = await withStalenessSuggestion(chainName, clientHandle, () => watchTransaction(tx.signSubmitAndWatch(signer, txOptions), waitLevel));
     console.log();
     console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
     console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
-    console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
+    printDecodedCall(decodedObj, decodedStr);
     if (nonce !== undefined)
       console.log(`  ${BOLD}Nonce:${RESET} ${nonce}`);
     if (tip !== undefined)
@@ -6001,6 +6633,39 @@ function decodeCall(meta, callHex) {
     return "(unable to decode)";
   }
 }
+function decodeCallObject(meta, callHex) {
+  try {
+    const callTypeId = meta.lookup.call;
+    if (callTypeId == null)
+      return null;
+    const codec = meta.builder.buildDefinition(callTypeId);
+    const decoded = codec.dec(Binary3.fromHex(callHex));
+    return {
+      palletName: decoded.type,
+      callName: decoded.value.type,
+      args: sanitizeForSerialization(decoded.value.value)
+    };
+  } catch {
+    return null;
+  }
+}
+function printDecodedCall(obj, fallback) {
+  if (!obj) {
+    console.log(`  ${BOLD}Decode:${RESET} ${fallback}`);
+    return;
+  }
+  const header = `${CYAN}${obj.palletName}${RESET}.${CYAN}${obj.callName}${RESET}`;
+  const hasArgs = obj.args !== null && obj.args !== undefined && !(typeof obj.args === "object" && Object.keys(obj.args).length === 0);
+  if (!hasArgs) {
+    console.log(`  ${BOLD}Decode:${RESET} ${header}`);
+    return;
+  }
+  console.log(`  ${BOLD}Decode:${RESET} ${header}`);
+  const indented = formatPretty(obj.args).split(`
+`).map((l) => `    ${l}`).join(`
+`);
+  console.log(indented);
+}
 function decodeCallFallback(meta, callHex) {
   const callTypeId = meta.lookup.call;
   if (callTypeId == null)
@@ -7144,13 +7809,13 @@ 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 YELLOW3 = "\x1B[33m";
+  const GREEN3 = "\x1B[32m";
+  const CYAN3 = "\x1B[36m";
+  const RESET3 = "\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 line1 = `Update available! ${YELLOW3}${current}${RESET3} → ${GREEN3}${BOLD2}${latest}${RESET3}`;
+  const line2 = `Run ${CYAN3}npm i -g polkadot-cli${RESET3} 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;
@@ -7237,6 +7902,34 @@ class CliError2 extends Error {
     this.name = "CliError";
   }
 }
+var PAPI_CLEANUP_PATTERNS = [
+  /^Not connected$/,
+  /DisjointError/,
+  /ChainHead.*(aborted|stopped)/i
+];
+function isPapiCleanupError(err) {
+  if (!(err instanceof Error))
+    return false;
+  return PAPI_CLEANUP_PATTERNS.some((re) => re.test(err.message));
+}
+function formatRuntimeError2(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (/wasm trap|wasm `?unreachable`? instruction|Execution aborted due to trap/i.test(msg)) {
+    const frames = Array.from(msg.matchAll(/\.wasm!([A-Za-z_]\w+)/g)).map((m) => m[1]);
+    const fn = [...frames].reverse().find((name) => !/^(?:__rustc|core::panicking|rust_begin_unwind|panic_fmt)/.test(name));
+    const where = fn?.includes("validate_transaction") ? "the runtime's validate_transaction step" : fn ? `runtime function ${fn}` : "the runtime";
+    return [
+      `The runtime rejected this transaction in ${where}.`,
+      "  Cause: a runtime invariant failed — typically the call's arguments are out of range, reference an unknown id, or violate a precondition.",
+      "  Tip:   re-check the arguments and the signing account's permissions; --dry-run will surface the same error before signing."
+    ].join(`
+`);
+  }
+  if (/Invalid Transaction/i.test(msg)) {
+    return `Transaction rejected as invalid by the runtime: ${msg}`;
+  }
+  return msg;
+}
 
 // src/utils/parse-dot-path.ts
 var CATEGORY_ALIASES = {
@@ -7359,6 +8052,7 @@ if (process.argv[2] === "__complete") {
     console.log("  dot polkadot.const.Balances.ExistentialDeposit");
     console.log("  dot polkadot.events.Balances                        List events in Balances");
     console.log("  dot polkadot.apis.Core.version                      Call a runtime API");
+    console.log("  dot metadata polkadot                               Dump runtime metadata as JSON");
     console.log("  dot polkadot.extensions                             List transaction extensions");
     console.log("  dot polkadot.extensions.CheckMortality              Inspect one extension");
     console.log("  dot query.System.Number --chain polkadot            --chain flag form");
@@ -7369,6 +8063,7 @@ if (process.argv[2] === "__complete") {
     console.log();
     console.log("Commands:");
     console.log("  inspect [target]   Inspect chain metadata (alias: explore)");
+    console.log("  metadata <chain>   Dump runtime metadata as JSON (--raw for SCALE hex)");
     console.log("  chain              Manage chain configurations");
     console.log("  account            Manage accounts");
     console.log("  hash               Hash utilities");
@@ -7395,6 +8090,7 @@ if (process.argv[2] === "__complete") {
   cli.option("--json", "Output as JSON (shorthand for --output json)");
   registerChainCommands(cli);
   registerInspectCommand(cli);
+  registerMetadataCommand(cli);
   registerAccountCommands(cli);
   registerHashCommand(cli);
   registerSignCommand(cli);
@@ -7551,12 +8247,18 @@ if (process.argv[2] === "__complete") {
     if (err instanceof CliError2) {
       console.error(`Error: ${err.message}`);
     } else if (err instanceof Error) {
-      console.error(`Error: ${err.message}`);
+      console.error(`Error: ${formatRuntimeError2(err)}`);
     } else {
       console.error("An unexpected error occurred:", err);
     }
     return showUpdateAndExit(1);
   }
+  process.on("unhandledRejection", (reason) => {
+    if (isPapiCleanupError(reason))
+      return;
+    console.error(`Error: ${formatRuntimeError2(reason)}`);
+    process.exit(1);
+  });
   async function main() {
     try {
       cli.parse(process.argv, { run: false });