Skip to content
Back to search

polkadot-cli

MarketplaceWorks with Claude CodeGitHub

A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, submit extrinsics, and compute hashes — all from…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/paritytech--polkadot-cli/badge.svg)](/listings/paritytech--polkadot-cli)

HTML

<a href="/listings/paritytech--polkadot-cli"><img src="/api/listings/paritytech--polkadot-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g polkadot-cli@latest

This installs the `dot` command globally.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "polkadot-cli",
  3. "owner": {
  4. "name": "paritytech",
  5. "email": "philip.poloczek@parity.io"
  6. },
  7. "metadata": {
  8. "description": "Claude Code skill for the polkadot-cli (`dot`) CLI — query, tx, runtime APIs, and scripting patterns for Polkadot/Substrate chains.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "dot-cli",
  14. "description": "Guide for using the `dot` CLI to interact with Polkadot/Substrate chains — storage queries, extrinsic submission, runtime APIs, chain management, and bash scripting patterns.",
  15. "source": "./",
  16. "strict": false,
  17. "skills": ["./dot-cli"]
  18. }
  19. ]
  20. }
README.md · README · 2,421 lines · 20 findings marked
  1. [![npm version](https://img.shields.io/npm/v/polkadot-cli)](https://www.npmjs.com/package/polkadot-cli)
  2. [![codecov](https://codecov.io/gh/paritytech/polkadot-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/paritytech/polkadot-cli)
  3. # polkadot-cli
  4. A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, submit extrinsics, and compute hashes — all from your terminal.
  5. Ships with Polkadot and all system parachains preconfigured with multiple fallback RPC endpoints. Add any Substrate-based chain by pointing to its RPC endpoint(s).
  6. ![Querying Polkadot and Asset Hub with no endpoint or config](docs/static/vhs/hero.gif)
  7. ## Features
  8. - ✅ Same syntax as [polkadot-api](https://papi.how) (PAPI)
  9. - ✅ Chain name prefix — `dot polkadot.query.System.Number`
  10. - ✅ zsh, bash, and fish autocompletion
  11. - ✅ Exposes all on-chain metadata documentation
  12. - ✅ Encode, dry-run, and submit extrinsics
  13. - ✅ Support for custom signed extensions — and a `dot <chain>.extensions` inspector to discover them
  14. - ✅ Built with agent use in mind — structured JSON output on every command (`--json`)
  15. - ✅ Fuzzy matching with typo suggestions
  16. - ✅ Account management — BIP39 mnemonics, derivation paths, env-backed secrets, watch-only, dev accounts
  17. - ✅ Local workspaces — `dot init` creates a `.polkadot/` in any directory, auto-discovered git-style and fully isolated from your global `~/.polkadot`
  18. - ✅ Named address resolution across all commands
  19. - ✅ Runtime API calls — `dot polkadot.apis.Core.version`
  20. - ✅ Raw JSON-RPC calls — `dot polkadot.rpc.system_health`, with discovery via `rpc_methods` and tab-completion
  21. - ✅ Full-metadata dump — `dot metadata <chain>` emits one JSON blob with pallets, runtime APIs, and transaction extensions (or raw SCALE bytes via `--raw`)
  22. - ✅ Stale-metadata detection — when a tx or query fails because the runtime upgraded, the CLI tells you exactly which `dot chain update` to run
  23. - ✅ Chain topology — relay/parachain hierarchy with tree display and auto-detection
  24. - ✅ Batteries included — all system parachains and testnets already setup to be used
  25. - ✅ File-based commands — run any command from a YAML/JSON file with variable substitution
  26. - ✅ Sovereign accounts — store a parachain (child / sibling) or pallet (Treasury, Bounties, NominationPools, …) sovereign as a named watch-only account in one command
  27. - ✅ Message signing — sign arbitrary bytes with account keypairs for use as `MultiSignature` arguments
  28. - ✅ General (v5) transactions — submit governance-authorized calls without a signer (`--general`)
  29. - ✅ Non-native fee payment — pay tx fees in any asset the chain accepts via `--asset` (asset-hub-style chains)
  30. - ✅ Bandersnatch member keys — derive Ring VRF member keys from mnemonics for on-chain member sets
  31. - ✅ Export/import — portable chain and account configuration for backup, sharing, and CI bootstrapping
  32. - ✅ Agent skill — bundled `dot-cli` skill teaches coding agents (Claude Code, Codex) how to drive the CLI; install with `dot skill install --codex`/`--claude`
  33. ### Preconfigured chains
  34. | Network | Chain |
  35. |---------|-------|
  36. | Polkadot | `polkadot` (relay) |
  37. | | `polkadot-asset-hub` |
  38. | | `polkadot-bridge-hub` |
  39. | | `polkadot-collectives` |
  40. | | `polkadot-coretime` |
  41. | | `polkadot-people` |
  42. | | `polkadot-bulletin` |
  43. | Paseo (testnet) | `paseo` (relay) |
  44. | | `paseo-asset-hub` |
  45. | | `paseo-people` |
  46. | | `paseo-bulletin` |
  47. Each chain ships with multiple RPC endpoints from decentralized infrastructure providers (Parity, Dwellir, Gatotech, LuckyFriday, Stakeworld, and others). The CLI automatically falls back to the next endpoint if the primary is unreachable.
  48. ## Install
  49. ```bash
  50. npm install -g polkadot-cli@latest
  51. ```
  52. This installs the `dot` command globally.
  53. ## Agent skill (Claude Code & Codex)
  54. `dot` ships a skill that teaches coding agents how to drive the CLI — query patterns, tx encoding, runtime API calls, and bash scripting gotchas. The skill auto-triggers when you ask about `dot`, Substrate storage queries, extrinsic submission, runtime APIs, or XCM.
  55. The skill is bundled into the `dot` binary, so it's always version-matched to your install. Print it anywhere with:
  56. ```bash
  57. dot skill show # SKILL.md to stdout
  58. dot skill show --references # plus the bundled reference docs
  59. ```
  60. ### Codex CLI
  61. ```bash
  62. dot skill install --codex
  63. ```
  64. This writes the skill to `~/.agents/skills/dot-cli`, where Codex auto-discovers it (use `--local` to install into `./.agents/skills` for the current repo instead). Restart Codex if it doesn't pick the skill up immediately.
  65. ### Claude Code
  66. ```bash
  67. dot skill install --claude # -> ~/.claude/skills/dot-cli
  68. ```
  69. This registers the skill under the short name `dot-cli`, invokable with `/dot-cli`.
  70. Alternatively, install via the plugin marketplace (registers as the more verbose `dot-cli:dot-cli`):
  71. ```
  72. /plugin marketplace add paritytech/polkadot-cli
  73. /plugin install dot-cli@polkadot-cli
  74. ```
  75. Pick one method — installing both ways leaves Claude Code with two copies of the same skill. Marketplace installs update with `/plugin marketplace update polkadot-cli`.
  76. After upgrading `dot` (`npm install -g polkadot-cli@latest`), re-run `dot skill install --codex`/`--claude` to refresh the installed skill. Run `dot skill path` to see where each agent's copy lives. Installed copies carry the CLI version in their frontmatter (`version:`), so an agent can spot a stale skill by comparing it against `dot --version`.
  77. ## Plugins
  78. `dot` supports git/cargo-style external subcommands: any executable named `dot-<name>` on your PATH runs as `dot <name>`, with the remaining arguments forwarded verbatim, stdio inherited, and the plugin's exit code passed through.
  79. ```bash
  80. npm install -g dot-example # ships a `dot-example` binary
  81. dot example status --json # runs: dot-example status --json
  82. ```
  83. This is how domain-specific tooling extends `dot` without the CLI loading third-party code into its own process. Plugins are ordinary child processes — the intended pattern is that a plugin invokes `dot` itself for anything chain- or signing-related (e.g. `dot tx.… --from <account>`), so key handling stays inside `dot`.
  84. Plugins receive a `DOT_BIN` environment variable pointing at the entry script of the `dot` that dispatched them (the same convention as cargo's `CARGO`), so they can invoke the exact same installation rather than whatever `dot` is first on PATH.
  85. Notes:
  86. - Only a bare first token dispatches: `dot foo.bar` is always dot-path syntax, `./file.yaml` is always file input — neither will hit the plugin lookup.
  87. - Built-in commands and categories always win over a plugin of the same name.
  88. ## Usage
  89. ### Manage chains
  90. ![Listing the preconfigured chains, then adding one by RPC with its parachain ID detected](docs/static/vhs/chains.gif)
  91. ```bash
  92. # Show chain help
  93. dot chain # shows available actions
  94. dot chains # shorthand, same as above
  95. # Add a chain (single RPC)
  96. dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
  97. # Add a chain with fallback RPCs (repeat --rpc for each endpoint)
  98. dot chain add kusama --rpc wss://kusama-rpc.polkadot.io --rpc wss://kusama-rpc.dwellir.com
  99. # Add a parachain under a relay (auto-detects parachain ID)
  100. # Name parachains `{relay}-{parachain}` — see "Naming convention" below
  101. dot chain add local-relay-asset-hub --rpc ws://localhost:9945 --relay local-relay
  102. # Add a parachain with explicit parachain ID
  103. dot chain add my-para --rpc wss://rpc.example.com --relay polkadot --parachain-id 2000
  104. # List configured chains (shows relay/parachain hierarchy)
  105. dot chain list
  106. dot chains # shorthand
  107. dot chains -v # include RPC endpoints in the list
  108. # Inspect a single chain (rpc, parachains, metadata cache status)
  109. dot chain info polkadot
  110. dot chain polkadot # bare-noun shortcut, same as `chain info polkadot`
  111. # Re-fetch metadata after a runtime upgrade
  112. dot chain update polkadot # updates a specific chain
  113. dot chain update --all # updates all configured chains in parallel
  114. # Remove a chain (only user-added chains can be removed)
  115. dot chain remove kusama
  116. ```
  117. #### Naming convention
  118. Name chains `{relay}-{parachain}`: the parent relay's name, a hyphen, then the parachain's role. Every preconfigured chain already follows this pattern (`polkadot-asset-hub`, `polkadot-bridge-hub`, `paseo-people`, …), and reusing it for chains you add keeps the relay/parachain topology readable.
  119. | Chain kind | Recommended name | Examples |
  120. |------------|------------------|----------|
  121. | Relay chain | `{relay}` | `polkadot`, `kusama`, `paseo` |
  122. | Parachain | `{relay}-{parachain}` | `polkadot-asset-hub`, `kusama-bridge-hub`, `paseo-people` |
  123. The relay prefix is what keeps chains distinct: parachain IDs collide across relays (Asset Hub is `1000` on both Polkadot and Paseo), so the name — not the ID — is how you select a chain (`dot polkadot-asset-hub.query…`). A relay-prefixed name also mirrors the `dot chain list` tree, which groups parachains under their relay.
  124. ```bash
  125. # Recommended — relay-prefixed name
  126. dot chain add kusama-asset-hub --rpc wss://asset-hub-kusama-rpc.polkadot.io --relay kusama --parachain-id 1000
  127. ```
  128. Use lowercase, hyphen-separated names (chain names resolve case-insensitively).
  129. #### Chain topology
  130. `dot chain list` displays chains as a tree, grouping parachains under their parent relay:
  131. ```
  132. Configured Chains
  133. polkadot
  134. ├─ polkadot-asset-hub [1000]
  135. ├─ polkadot-bridge-hub [1002]
  136. ├─ polkadot-collectives [1001]
  137. ├─ polkadot-coretime [1005]
  138. └─ polkadot-people [1004]
  139. paseo
  140. ├─ paseo-asset-hub [1000]
  141. └─ paseo-people [1004]
  142. my-solo-chain
  143. ```
  144. The default list is intentionally compact — names + relay tree + parachain IDs. Pass `-v` / `--verbose` to also print every RPC endpoint inline (à la `git remote -v`):
  145. ```
  146. Configured Chains
  147. polkadot wss://polkadot-rpc.n.dwellir.com
  148. wss://polkadot.gatotech.network
  149. wss://rpc.polkadot.io
  150. ├─ polkadot-asset-hub [1000] wss://polkadot-asset-hub-rpc.polkadot.io
  151. ...
  152. ```
  153. For the full set of fields for one chain (RPCs, parent relay, child parachains, metadata cache status), use `dot chain info <name>`:
  154. ```
  155. dot chain info polkadot
  156. # polkadot
  157. #
  158. # rpc:
  159. # wss://polkadot-rpc.n.dwellir.com
  160. # wss://rpc.polkadot.io
  161. # ...
  162. # parachains:
  163. # polkadot-asset-hub [1000]
  164. # polkadot-bridge-hub [1002]
  165. # ...
  166. # metadata:
  167. # not cached — run `dot chain update polkadot`
  168. ```
  169. After a successful `dot chain update <name>`, the `metadata:` row shows the cached `specName`, `specVersion`, and `fetchedAt` timestamp instead of the `not cached` hint. `dot chain info <name> --json` emits the same data as a structured object (with `metadata: null` when no fingerprint is cached). Names resolve case-insensitively. The bare-noun form `dot chain <name>` is a shortcut for `dot chain info <name>` — known action verbs (`add`, `remove`, `update`, `list`, `export`, `import`, `info`) take precedence over chain names if there's ever a clash.
  170. All built-in system parachains are preconfigured with their relay chain and parachain ID. When adding a custom parachain with `--relay`, the CLI auto-detects the parachain ID from on-chain `ParachainInfo` storage. Use `--parachain-id` to set it explicitly if auto-detection is not available.
  171. Removing a relay chain that has parachains prints a warning listing the orphaned chains. The parachains remain in the config and can be re-associated later.
  172. #### Selecting a chain
  173. Every chain-consuming command must specify a chain explicitly. Prefer the dotpath chain prefix; the `--chain <name>` flag is equivalent. There is no hidden default; running a command without a chain errors out with a message listing the configured chains.
  174. ```bash
  175. # Recommended — dotpath chain prefix
  176. dot polkadot.query.System.Number
  177. # Output:
  178. # 31014744
  179. # Equivalent — --chain flag
  180. dot query.System.Number --chain polkadot
  181. # Output:
  182. # 31014744
  183. # Both at once errors
  184. dot polkadot.query.System.Number --chain polkadot # ✗ errors
  185. ```
  186. Chain names are case-insensitive (`Polkadot.query.System.Number` works the same).
  187. #### Export/import chain configuration
  188. Export and import chain configurations for backup, sharing across machines, or team collaboration.
  189. ```bash
  190. # Export custom chains to stdout (pipe-friendly JSON)
  191. dot chain export
  192. # Export all chains including built-ins
  193. dot chain export --all
  194. # Export specific chains
  195. dot chain export my-relay my-para
  196. # Export to a file
  197. dot chain export --all --file my-chains.json
  198. # Import from a file
  199. dot chain import my-chains.json
  200. # Preview without applying
  201. dot chain import my-chains.json --dry-run
  202. # Overwrite existing chains
  203. dot chain import my-chains.json --overwrite
  204. # Skip automatic metadata fetch (faster for offline/CI bootstrap)
  205. dot chain import my-chains.json --no-metadata
  206. # Pipe between machines
  207. ssh remote-dev "dot chain export" | dot chain import -
  208. ```
  209. By default, `export` only includes user-added chains and built-ins with modified RPCs. Use `--all` to include everything. Import skips existing chains unless `--overwrite` is passed, and validates relay references with warnings for missing relays.
  210. After a non-dry-run import, metadata is fetched automatically for each newly added or overwritten chain so tab completion and metadata-dependent commands work immediately. Pass `--no-metadata` to skip the fetch — you can always backfill later with `dot chain update --all`.
  211. Output shows one line per chain with a status glyph and a terse summary:
  212. ```
  213. ✓ preview
  214. ✓ preview-people
  215. ⟳ polkadot (overwritten)
  216. - paseo (skipped)
  217. 2 added, 1 overwritten, 1 skipped
  218. Updating metadata for 3 chain(s)...
  219. ✓ preview
  220. ✓ preview-people
  221. ✓ polkadot
  222. ```
  223. Running `dot chain import` with no file path prints the subcommand help instead of blocking on stdin.
  224. ### Manage accounts
  225. Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
  226. ![Creating a key, naming a watch-only address, deriving a child, and querying by name](docs/static/vhs/accounts.gif)
  227. > **Security warning:** Account secrets (mnemonics and seeds) are currently stored **unencrypted** in `~/.polkadot/accounts.json`. Do not use this for high-value accounts on mainnet. Encrypted storage is planned for a future release. Use `--env` to keep secrets off disk entirely.
  228. ```bash
  229. # Show account help
  230. dot account # shows available actions
  231. dot accounts # shorthand, same as above
  232. # List all accounts (dev + stored)
  233. dot account list
  234. # Add a watch-only address (no secret — for use as tx recipient or query target)
  235. dot account add treasury 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 333 on GitHub
  236. dot account add council 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
  237. # Create a new account (generates a mnemonic)
  238. dot account create my-validator
  239. # Create with a derivation path
  240. dot account create my-staking --path //staking
  241. # Add a keyed account from a BIP39 mnemonic
  242. dot account add treasury --secret "word1 word2 ... word12"
  243. # Add from a 32-byte hex seed or a 64-byte raw sr25519 private key
  244. dot account add seeded --secret 0x1111111111111111111111111111111111111111111111111111111111111111
  245. dot account add raw-key --secret 0x<128-hex-char expanded secret> # no --path
  246. # Add with a derivation path
  247. dot account add hot-wallet --secret "word1 word2 ... word12" --path //hot
  248. # Add an env-var-backed account (secret stays off disk)
  249. dot account add ci-signer --env MY_SECRET
  250. # Derive a child account from an existing one
  251. dot account derive treasury treasury-staking --path //staking
  252. # Use it — the env var is read at signing time
  253. MY_SECRET="word1 word2 ..." dot polkadot.tx.System.remark 0xdead --from ci-signer
  254. # Remove one or more accounts (delete and rm are aliases for remove)
  255. dot account remove my-validator
  256. dot account delete my-validator stale-key
  257. dot account rm my-validator stale-key
  258. # Export accounts (secrets redacted by default)
  259. dot account export
  260. dot account export --include-secrets --file backup.json
  261. dot account export --watch-only
  262. # Batch-import accounts from a file
  263. dot account import team-accounts.json
  264. dot account import accounts.json --dry-run
  265. dot account import accounts.json --overwrite
  266. # Inspect an account — show public key and SS58 address
  267. dot account inspect alice
  268. dot account alice # shorthand (same as inspect)
  269. dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 379 on GitHub
  270. dot account inspect 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
  271. dot account inspect alice --prefix 0 # Polkadot mainnet prefix
  272. dot account inspect alice --json # JSON output
  273. dot account inspect dave --show-secret # reveal mnemonic + sr25519 private key
  274. ```
  275. #### Watch-only accounts
  276. Add named addresses without secrets — useful for saving frequently-used recipients, multisig members, or query targets:
  277. ```bash
  278. dot account add treasury 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 391 on GitHub
  279. dot account add council 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
  280. ```
  281. Watch-only accounts appear in `dot account list` under a dedicated **Watch-only** section and can be inspected and removed like any other account. They cannot be used with `--from` (signing) or as a source for `derive`.
  282. The `add` subcommand is context-sensitive: bare `add <name> <address>` creates a watch-only entry, while `add --secret` or `add --env` imports a keyed account. `dot account import` is reserved for file-based batch import.
  283. #### Named address resolution
  284. Named accounts (both watch-only and keyed) resolve automatically everywhere an AccountId32 or MultiAddress is expected — in `dot tx` arguments and `dot query` keys:
  285. ```bash
  286. # Use a named account as transfer recipient
  287. dot polkadot.tx.Balances.transfer_keep_alive treasury 1000000000000 --from alice
  288. # Query by account name
  289. dot polkadot.query.System.Account treasury
  290. # Dev accounts also resolve
  291. dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000000 --from alice
  292. ```
  293. Resolution order: dev account name > stored account name > SS58 address > hex public key. If the input doesn't match any, the CLI shows an error listing all available account names alphabetically, one per line. When the input is close to an existing name, a "Did you mean?" suggestion is included:
  294. ```
  295. Error: Unknown account or address "people-sudo-signer".
  296. Did you mean: people-paseo-sudo?
  297. Available accounts:
  298. - alice
  299. - bob
  300. - charlie
  301. - people-paseo-sudo
  302. - ...
  303. ```
  304. #### Inspect accounts
  305. Convert between SS58 addresses, hex public keys, and account names. Accepts any of:
  306. - **Dev account name** (`alice`, `bob`, etc.) — resolves to public key and SS58
  307. - **Stored account name** — looks up the public key from the accounts file
  308. - **SS58 address** — decodes to the underlying public key
  309. - **Hex public key** (`0x` + 64 hex chars) — encodes to SS58
  310. - **`--pallet-id <id>`** — derives a pallet sovereign address without saving it (script-friendly; nothing persists)
  311. - **`--parachain <id> --parachain-type <child|sibling>`** — derives a parachain sovereign address without saving it
  312. ```bash
  313. dot account inspect alice
  314. dot account alice # shorthand — unknown subcommands fall through to inspect
  315. dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 442 on GitHub
  316. dot account inspect 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
  317. # pallet-revive H160 — the 20-byte address shape from EVM tooling. Same
  318. # input slot as SS58 / hex pubkey; resolved to the deterministic fallback
  319. # AccountId32 (`H160 || 0xEE * 12`).
  320. dot account inspect 0x9621DDe636dE098B43Efb0fA9b61fAcFE328F99D
  321. ```
  322. Use `--prefix` to encode the SS58 address with a specific network prefix (default: 42):
  323. ```bash
  324. dot account inspect alice --prefix 0 # Polkadot mainnet (prefix 0, starts with '1')
  325. dot account inspect alice --prefix 2 # Kusama (prefix 2)
  326. ```
  327. JSON output:
  328. ```bash
  329. dot account inspect alice --json
  330. # Output:
  331. # {
  332. # "publicKey": "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d",
  333. # "ss58": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 465 on GitHub
  334. # "h160": "0x9621DDe636dE098B43Efb0fA9b61fAcFE328F99D",
  335. # "prefix": 42,
  336. # "name": "Alice",
  337. # "kind": "dev"
  338. # }
  339. ```
  340. Plain text output:
  341. ```bash
  342. dot account inspect alice
  343. # Output:
  344. # Account Info
  345. #
  346. # Name: Alice
  347. # Kind: dev
  348. # Public Key: 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
  349. # SS58: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 483 on GitHub
  350. # H160: 0x9621DDe636dE098B43Efb0fA9b61fAcFE328F99D
  351. # Prefix: 42
  352. ```
  353. The `Kind:` line categorises the account: `dev` (built-in), `signer` (has a secret/env), `watch-only` (raw external address), `pallet sovereign` (derived from a `PalletId`), `parachain sovereign (child|sibling)` (derived from a parachain ID), or `revive H160 fallback` (a 20-byte input resolved to its deterministic Substrate AccountId32). For derived sovereigns, an extra `Source:` line shows what the address was derived from. For env-backed signers, an `Env:` line shows the variable; for derived child keys, `Derivation:` shows the path.
  354. ##### pallet-revive H160 address
  355. Every Substrate account has a corresponding 20-byte H160 address under [pallet-revive](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive) (the new EVM-compatible smart-contracts pallet on Polkadot Hub / Asset Hub). `dot account inspect` always shows it, EIP-55 checksummed, on the `H160:` line. The mapping is offline and prefix-independent:
  356. - **AccountId32 → H160:** if the last 12 bytes are `0xEE`, strip them (the account originated from an Eth address); otherwise `keccak256(accountId32)` and take the last 20 bytes.
  357. - **H160 → AccountId32:** deterministic fallback is `H160 || 0xEE * 12`. (The full mapping after a successful `pallet_revive.map_account` extrinsic lives in on-chain `AddressSuffix` storage and isn't recoverable offline — that's a chain-state lookup.)
  358. Pass a 20-byte hex value as the inspect input to resolve it back to its fallback Substrate account:
  359. ```bash
  360. dot account inspect 0x9621DDe636dE098B43Efb0fA9b61fAcFE328F99D
  361. # Output:
  362. # Account Info
  363. #
  364. # Kind: revive H160 fallback
  365. # Public Key: 0x9621dde636de098b43efb0fa9b61facfe328f99deeeeeeeeeeeeeeeeeeeeeeee
  366. # SS58: 5FTZ6n1wY3GBqEZ2DWEdspbTarvRnp8DM8x2YXbWubu7JN98
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 506 on GitHub
  367. # H160: 0x9621DDe636dE098B43Efb0fA9b61fAcFE328F99D
  368. # Prefix: 42
  369. # Script-friendly: just the H160 for a given account
  370. dot account inspect alice --json | jq -r .h160
  371. # 0x9621DDe636dE098B43Efb0fA9b61fAcFE328F99D
  372. ```
  373. Note: `dot` implements the current `pallet-revive` master variant (keccak fallback). Older `stable2412` runtimes used plain `accountId32[..20]` truncation; if you target one, compute it manually until a `--revive-truncate` flag lands.
  374. ##### Stateless sovereign derivation (script-friendly)
  375. Pass `--pallet-id` or `--parachain` / `--parachain-type` to compute a sovereign address **without persisting** anything to `~/.polkadot/accounts.json`. The output shape matches the stored case (same `Kind:` / `Source:` / SS58 / public key + same `--json` schema), but no `Name:` line and nothing in `dot account list` afterwards. Use this in scripts when you just need the address:
  376. ```bash
  377. # Polkadot Treasury — pallet sovereign on prefix 0
  378. dot account inspect --pallet-id py/trsry --prefix 0
  379. # Output:
  380. # Account Info
  381. #
  382. # Kind: pallet sovereign
  383. # Public Key: 0x6d6f646c70792f74727372790000000000000000000000000000000000000000
  384. # SS58: 13UVJyLnbVp9RBZYFwFGyDvVd1y27Tt8tkntv6Q7JVPhFsTB
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 529 on GitHub
  385. # Source: PalletId py/trsry (0x70792f7472737279)
  386. # Prefix: 0
  387. # Hex form works the same
  388. dot account inspect --pallet-id 0x70792f7472737279 --prefix 0
  389. # Parachain sovereigns (type is required — child = on relay, sibling = on another parachain)
  390. dot account inspect --parachain 1004 --parachain-type child
  391. # Pipeline: just the SS58
  392. SS58=$(dot account inspect --pallet-id py/trsry --prefix 0 --json | jq -r .ss58)
  393. # JSON shape includes a `source` object describing the derivation
  394. dot account inspect --pallet-id py/trsry --json
  395. # {
  396. # "publicKey": "0x6d6f646c70792f74727372790000000000000000000000000000000000000000",
  397. # "ss58": "5EYCAe5ijiYfyeZ2JJCGq56LmPyNRAKzpG4QkoQkkQNB5e6Z",
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 546 on GitHub
  398. # "prefix": 42,
  399. # "kind": "pallet sovereign",
  400. # "source": { "kind": "pallet", "palletId": "py/trsry", "palletIdHex": "0x70792f7472737279" }
  401. # }
  402. ```
  403. Constraints (will error): cannot combine a positional input with derivation flags; `--pallet-id` and `--parachain` are mutually exclusive; `--parachain` requires `--parachain-type child|sibling`; `--show-secret` doesn't apply (derived sovereigns have no key).
  404. #### Reveal the mnemonic and sr25519 private key
  405. For provisioning another signer (e.g. a server that expects a raw hex private key in an env var), add `--show-secret` to print the **64-byte sr25519 expanded secret** as `0x`-prefixed hex. It also reveals the **stored mnemonic** (or hex seed) so you can back it up:
  406. ```bash
  407. dot account inspect my-validator --show-secret
  408. # Mnemonic: word1 word2 ... word12 (only for accounts stored as a phrase)
  409. # Private Key: 0x<128 hex chars> (sr25519 expanded, 64 bytes — never share)
  410. ```
  411. Works for dev accounts (derived on-the-fly from the standard dev mnemonic) and for stored accounts that have a secret. Refuses on watch-only accounts, bare SS58 addresses, or hex public keys. The revealed line depends on how the account was stored: a phrase shows under `Mnemonic`, a 32-byte hex seed under `Seed`, and a raw private key shows only the `Private Key` (the stored secret already _is_ the expanded key). **Env-backed secrets are never resolved to disk output** — only the `$VAR` reference is shown. The expanded `Private Key` is the final secret after any derivation path is applied, so it can be fed directly to signers that don't accept a mnemonic+path (e.g. `@scure/sr25519`'s `sign`, or services like identity-backend that read a `PROXY_PRIVATE_KEY`). Combine with `--json` to include the values under the `mnemonic`/`seed` and `privateKey` fields.
  412. The revealed `Private Key` round-trips: you can re-import it as a usable account (see [Import a raw private key](#import-a-raw-private-key) below).
  413. > **Note:** if the account was stored with a derivation path, the revealed `Mnemonic`/`Seed` reproduces the original address **only when re-imported with the same `--path`** (shown on the `Derivation` line). The `Private Key` already bakes in the path, so it round-trips on its own.
  414. #### Env-var-backed accounts
  415. For CI/CD and security-conscious workflows, store a reference to an environment variable instead of the secret itself:
  416. ```bash
  417. dot account add ci-signer --env MY_SECRET
  418. ```
  419. `--secret` and `--env` are mutually exclusive. Use `dot account add` for single-account imports; `dot account import` is reserved for file-based batch import.
  420. The secret is never written to disk. At signing time, the CLI reads `$MY_SECRET` and derives the keypair. If the variable is not set, the CLI errors with a clear message. `account list` annotates env-backed signers with `env $MY_SECRET` in the metadata column and resolves the address live when the variable is available.
  421. #### Derivation paths
  422. Use `--path` with `create`, `add`, or the `derive` action to derive child keys from the same secret. Different paths produce different keypairs, enabling key separation (e.g. staking vs. governance) without managing multiple mnemonics.
  423. ```bash
  424. # Create with a derivation path
  425. dot account create my-staking --path //staking
  426. # Multi-segment path (hard + soft junctions)
  427. dot account create multi --path //polkadot//0/wallet
  428. # Add with a path
  429. dot account add hot --secret "word1 word2 ..." --path //hot
  430. # Derive a child from an existing account
  431. dot account derive treasury treasury-staking --path //staking
  432. ```
  433. `derive` copies the source account's secret and applies the given path. It requires both a source name, a new name, and `--path`. Works with env-backed accounts too — the derived account shares the same env var reference.
  434. `account list` shows derivation paths and env sources on tree-style continuation lines (label names mirror the `--flag` that sets them):
  435. ```
  436. Signers
  437. treasury-staking 5FHneW46...
  438. └─ path: //staking
  439. ci-signer 5EPCUjPx...
  440. ├─ path: //ci
  441. └─ env: $MY_SECRET
  442. ```
  443. **Supported secret formats for import:**
  444. | Format | Example | `--path`? |
  445. |--------|---------|-----------|
  446. | BIP39 mnemonic (12/24 words) | `"abandon abandon ... about"` | Yes |
  447. | Hex seed (`0x` + 64 hex chars = 32 bytes) | `0x1111...1111` | Yes |
  448. | Raw private key (`0x` + 128 hex chars = 64-byte sr25519 expanded secret) | `0x20e0...5568` | No (cannot be HD-derived) |
  449. All three formats work directly from the command line via `--secret` or via `--env`.
  450. #### Import a raw private key
  451. The 64-byte expanded secret that `--show-secret` prints can be re-imported as a fully usable, signing-capable account. This is the round-trip companion to `--show-secret` — handy when a key only exists in expanded form (e.g. exported from another tool or read from a `PROXY_PRIVATE_KEY` env var):
  452. ```bash
  453. # Round-trip: reveal dave's expanded secret, then import it under a new name
  454. SECRET=$(dot account inspect dave --show-secret --json | jq -r .privateKey)
  455. dot account add raw-dave --secret "$SECRET"
  456. # raw-dave now has the same address as dave and can sign
  457. # Or from an environment variable (secret stays off disk)
  458. dot account add server-signer --env PROXY_PRIVATE_KEY
  459. ```
  460. A raw private key cannot be HD-derived, so `--path` is rejected for this format. Imported expanded-secret accounts sign exactly like mnemonic-backed ones.
  461. #### Export/import accounts
  462. Export and import accounts for backup, sharing, or bootstrapping CI environments. Secrets are **redacted by default** — safe to share or commit.
  463. ```bash
  464. # Export accounts (secrets redacted by default)
  465. dot account export
  466. # Export specific accounts
  467. dot account export treasury my-validator
  468. # Include secrets (explicit opt-in, prints warning)
  469. dot account export --include-secrets --file backup.json
  470. # Export only watch-only accounts (always safe)
  471. dot account export --watch-only
  472. # Batch-import accounts from a file (positional path, like `dot chain import`)
  473. dot account import team-accounts.json
  474. # Preview without applying
  475. dot account import accounts.json --dry-run
  476. # Overwrite existing accounts
  477. dot account import accounts.json --overwrite
  478. # Pipe from another machine
  479. ssh remote-dev "dot account export --watch-only" | dot account import -
  480. ```
  481. Output mirrors `dot chain import` — one line per account with a status glyph (`✓` added, `⟳` overwritten, `-` skipped) and a terse count summary at the end. Running `dot account import` with no file path prints the subcommand help instead of blocking on stdin.
  482. `dot account import` is file-only. For a single-account import from a mnemonic or env variable, use `dot account add <name> --secret "..."` or `dot account add <name> --env VAR`.
  483. Security: default export replaces mnemonic/seed with `"<redacted>"`. `--include-secrets` is required for actual secrets. Env-backed accounts export the variable *name* (e.g. `{"env": "MY_SECRET"}`), never the value. Redacted accounts import as watch-only (public key preserved, no signing capability).
  484. ### Chain prefix
  485. Instead of the `--chain` flag, you can prefix the dot-path with the chain name. The prefix becomes the first segment of the dot-path:
  486. ```bash
  487. dot polkadot.query.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 681 on GitHub
  488. dot polkadot.const.Balances.ExistentialDeposit
  489. dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000 --from alice --dry-run
  490. dot inspect polkadot.System # for `inspect`, the prefix is the first arg
  491. dot inspect polkadot.System.Account
  492. ```
  493. Chain names are case-insensitive — `Polkadot.query.System.Account`, `POLKADOT.query.System.Account`, and `polkadot.query.System.Account` all resolve the same way. The same applies to `--chain Polkadot`.
  494. Every invocation must specify a chain explicitly: either via a dotpath prefix (as above) or via `--chain <name>`. If both are provided, the CLI errors.
  495. ### Space-separated syntax
  496. The `Pallet` and `Item` segments can be passed as separate arguments instead of dot-joined. These pairs are equivalent:
  497. ```bash
  498. # Dot notation vs fully space-separated — these are identical:
  499. dot polkadot.query.System # dot notation
  500. dot query System --chain polkadot # space-separated
  501. dot polkadot.events.Balances.Transfer
  502. dot events Balances Transfer --chain polkadot
  503. dot polkadot.apis.Core
  504. dot apis Core --chain polkadot
  505. ```
  506. This works for all categories (`query`, `tx`, `const`, `events`, `errors`, `apis`, `extensions`, `rpc`). When passing positional method arguments, keep `Pallet` and `Item` either fully dot-joined (`query.System.Account 5Grw...`) or fully space-separated (`query System Account 5Grw...`) — mixing the two (`query System.Account 5Grw...`) does not work because the second arg gets parsed as a pallet name.
  507. ### Query storage
  508. ```bash
  509. # Plain storage value
  510. dot polkadot.query.System.Number
  511. # Output:
  512. # 31014744
  513. # Map entry by key — Alice's account on Polkadot (free balance is u128 as a quoted string)
  514. dot polkadot.query.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 719 on GitHub
  515. # Output:
  516. # {
  517. # "nonce": 0,
  518. # "consumers": 0,
  519. # "providers": 0,
  520. # "sufficients": 0,
  521. # "data": {
  522. # "free": "0",
  523. # "reserved": "0",
  524. # "frozen": "0",
  525. # "flags": "170141183460469231731687303715884105728"
  526. # }
  527. # }
  528. # Map without key — shows help/usage (use --dump to fetch all entries)
  529. dot polkadot.query.System.Account
  530. # Dump all map entries (requires --dump)
  531. dot polkadot.query.System.Account --dump
  532. # Pipe-safe — stdout is clean data, progress messages go to stderr
  533. dot polkadot.query.System.Account --dump | jq '.[0].value.data.free'
  534. dot polkadot.query.System.Number --json | jq '.+1'
  535. # --chain flag is equivalent to the dotpath prefix
  536. dot query.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY --chain polkadot
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 745 on GitHub
  537. ```
  538. #### Partial key queries
  539. For storage maps with multiple keys (NMaps), you can provide fewer keys than
  540. expected to retrieve all entries matching that prefix. This uses the chain's
  541. prefix-based iteration and does not require `--dump`.
  542. ```bash
  543. # Full key — returns a single value
  544. dot polkadot.query.Staking.ErasStakers 100 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 756 on GitHub
  545. # Partial key — returns all entries matching the first key
  546. dot polkadot.query.Staking.ErasStakers 100
  547. # No keys — requires --dump (safety net for large maps)
  548. dot polkadot.query.Staking.ErasStakers --dump
  549. ```
  550. #### Output formatting
  551. Query results automatically convert on-chain types for readability:
  552. - **BigInt** values (e.g. balances) render as decimal strings
  553. - **Binary** fields (e.g. token `name`, `symbol`) render as text when the value contains only printable characters, or as `0x`-prefixed hex otherwise (values containing control characters, Private Use Area code points, or invalid UTF-8 sequences always fall back to hex)
  554. - **Uint8Array** values render as `0x`-prefixed hex
  555. ```bash
  556. # Token metadata — symbol and name display as text, not {}
  557. dot polkadot-asset-hub.query.Assets.Metadata 1984
  558. # Output:
  559. # {
  560. # "deposit": "2008200000",
  561. # "name": "Tether USD",
  562. # "symbol": "USDt",
  563. # "decimals": 6,
  564. # "is_frozen": false
  565. # }
  566. ```
  567. #### Historical reads — `--at <block>`
  568. Storage queries default to the latest finalized head. Pass `--at` to read
  569. state at a specific block hash, the chain head (`best`), or `finalized`
  570. (explicit). Accepted on both `query.*` and `apis.*` runtime calls.
  571. ```bash
  572. # Read at the current best (non-finalized) head — useful for low-latency reads
  573. dot polkadot.query.System.Number --at best
  574. # Read at the last finalized block — same as the default, but explicit
  575. dot polkadot.query.System.Number --at finalized
  576. # Pin a finalized hash and read multiple items at that exact block
  577. HASH=$(dot polkadot.rpc.chain_getFinalizedHead | tr -d '"')
  578. dot polkadot.query.System.Number --at "$HASH"
  579. dot polkadot.apis.Core.version --at "$HASH" --json | jq .spec_version
  580. ```
  581. `--at` accepts a 32-byte `0x…` block hash, `"best"`, or `"finalized"`.
  582. Anything else errors before any network call. Tx submission rejects `"best"`.
  583. > **Archive-only blocks**: papi v2 talks to the `chainHead_v1_*` JSON-RPC API,
  584. > which only serves *pinned* (recent) blocks. Querying a hash older than a
  585. > few minutes against a non-archive node fails with a clean error that
  586. > includes a copy-pasteable `--rpc wss://<archive-endpoint>` hint:
  587. >
  588. > ```
  589. > ⚠ 0x… is not available on the current RPC endpoint.
  590. > Public nodes serve only recent (pinned) blocks via chainHead_v1_*.
  591. > For deep historical reads, point --rpc at an archive endpoint, e.g.:
  592. > dot ... --at 0x… --rpc wss://<archive-endpoint>
  593. > ```
  594. ### Look up constants
  595. ```bash
  596. dot polkadot.const.Balances.ExistentialDeposit
  597. # Output:
  598. # "10000000000"
  599. dot polkadot.const.System.SS58Prefix
  600. # Output:
  601. # 0
  602. # --chain flag is equivalent
  603. dot const.Balances.ExistentialDeposit --chain polkadot
  604. # Pipe-safe — stdout is clean JSON, progress messages go to stderr
  605. dot polkadot.const.Balances.ExistentialDeposit --json | jq
  606. ```
  607. ### Inspect metadata
  608. Works offline from cached metadata after the first fetch. The chain is required. Prefer the chain-prefix-on-target form (`dot inspect polkadot.System`); `--chain` is equivalent. Note that `dot polkadot.inspect.X` does **not** parse — `inspect` is a top-level command, not a dotpath category.
  609. `inspect` is **forgiving**: it accepts the same dot-paths you use to invoke a call and degrades to discovery rather than erroring. A `kind` segment (`tx`/`query`/`const`/`events`/`errors`/…) is tolerated and ignored — so `dot inspect polkadot.tx.System.remark` describes the `System.remark` call just like `dot inspect polkadot.System.remark` does. Partial paths list rather than fail: `dot inspect polkadot.query.System` (and the bare `dot inspect System`) list the pallet's items.
  610. Output is **width-aware**: short type signatures stay on a single line, longer ones expand across multiple lines with field names aligned. Composite struct fields, enum variants, and call arguments are color-coded (cyan field names, yellow primitives, magenta container keywords like `Vec`/`Option`, green enum variants) when stdout is a TTY; piped output stays plain.
  611. ![Inspecting storage, calls, events and errors from cached metadata](docs/static/vhs/inspect.gif)
  612. ```bash
  613. # Pallet detail — list storage, constants, calls, events, and errors
  614. dot inspect polkadot.System
  615. # Output:
  616. # System Pallet
  617. #
  618. # Storage Items:
  619. # Account [map]
  620. # Key: AccountId32
  621. # Value: {
  622. # nonce : u32,
  623. # consumers : u32,
  624. # providers : u32,
  625. # sufficients: u32,
  626. # data : { free: u128, reserved: u128, frozen: u128, flags: u128 },
  627. # }
  628. # The full account information for a particular account ID.
  629. # ...
  630. # Storage item detail — full type and docs (each part on its own line)
  631. dot inspect polkadot.System.Account
  632. # Output:
  633. # System.Account (Storage)
  634. #
  635. # Type: map
  636. # Key: AccountId32
  637. # Value: {
  638. # nonce : u32,
  639. # consumers : u32,
  640. # providers : u32,
  641. # sufficients: u32,
  642. # data : { free: u128, reserved: u128, frozen: u128, flags: u128 },
  643. # }
  644. #
  645. # The full account information for a particular account ID.
  646. # Event detail — shows field signature and docs
  647. dot inspect polkadot.Balances.Transfer
  648. # Output:
  649. # Balances.Transfer (Event)
  650. #
  651. # Fields: (from: AccountId32, to: AccountId32, amount: u128)
  652. #
  653. # Transfer succeeded.
  654. # Error detail — shows docs
  655. dot inspect polkadot.Balances.InsufficientBalance
  656. # Output:
  657. # Balances.InsufficientBalance (Error)
  658. #
  659. # Balance too low to send value.
  660. # List all pallets — single positional is read as a pallet name, so use --chain here
  661. dot inspect --chain polkadot
  662. ```
  663. All listings — pallets, storage items, constants, calls, events, and errors — are sorted alphabetically, making it easy to find a specific item at a glance.
  664. The pallet listing view shows type information inline so you can understand item shapes at a glance:
  665. - **Storage**: name with optional `[map]` tag, followed by indented `Key:` / `Value:` lines (composite values expand to one field per line when wide)
  666. - **Constants**: the constant's type (e.g. `ExistentialDeposit: u128`)
  667. - **Calls**: argument signature inline if it fits, otherwise one argument per line with names aligned by colon
  668. - **Events**: field signature inline if it fits, otherwise one field per line
  669. - **Errors**: name and documentation (e.g. `InsufficientBalance`)
  670. Long call signatures expand automatically:
  671. ```bash
  672. dot inspect polkadot.Referenda
  673. # Output (excerpt):
  674. # cancel(index: u32)
  675. # Cancel an ongoing referendum.
  676. # ...
  677. # submit(
  678. # proposal_origin : system | Origins | ParachainsOrigin | XcmPallet,
  679. # proposal : Legacy | Inline | Lookup,
  680. # enactment_moment: At | After,
  681. # )
  682. # Propose a referendum on a privileged action.
  683. ```
  684. Enums up to 24 variants now render as `A | B | C | …` (previously variants were collapsed to `enum(N variants)` for >4); only enums with more than 24 variants are still summarized for readability. So a transaction extension's value type like `Option<AsPersonalAliasWithAccount | AsPersonalAliasWithProof | …>` now spells out the variants you actually need to construct.
  685. Documentation from the runtime metadata is shown on an indented line below each item. The detail view (`dot inspect Balances.transfer_allow_death`) shows the full argument signature and complete documentation text. Use call inspection to discover argument names, types, and docs before constructing `dot tx` commands.
  686. ### Dump full metadata
  687. `dot metadata <chain>` fetches the chain's runtime metadata and prints **everything** as one JSON blob — pallets (with calls, events, errors, storage, constants), runtime APIs, and transaction extensions, headed by a runtime fingerprint (`specVersion`, `transactionVersion`, `codeHash`, etc.). Useful for feeding LLM agents or pipelines that want a single source of truth instead of walking `dot inspect` piecemeal.
  688. ```bash
  689. # Decoded JSON — fetches fresh from the chain (top-level command; no chain prefix)
  690. dot metadata polkadot
  691. # SCALE-encoded metadata bytes as a single 0x… hex line (for tools that re-parse)
  692. dot metadata polkadot --raw
  693. # Skip the network round-trip and use cached metadata
  694. dot metadata polkadot --cached
  695. # Override the RPC endpoint
  696. dot metadata polkadot --rpc wss://rpc.example.com
  697. # Slice with jq — list call names in Balances
  698. dot metadata polkadot | jq -r '.pallets[] | select(.name=="Balances") | .calls[].name'
  699. # Output:
  700. # burn
  701. # force_adjust_total_issuance
  702. # force_set_balance
  703. # force_transfer
  704. # force_unreserve
  705. # transfer_all
  706. # transfer_allow_death
  707. # transfer_keep_alive
  708. # upgrade_accounts
  709. # All transaction extension identifiers
  710. dot metadata polkadot | jq -r '.transactionExtensions[].identifier'
  711. # Output:
  712. # AuthorizeCall
  713. # CheckNonZeroSender
  714. # CheckSpecVersion
  715. # CheckTxVersion
  716. # CheckGenesis
  717. # CheckMortality
  718. # CheckNonce
  719. # CheckWeight
  720. # ChargeTransactionPayment
  721. # PrevalidateAttests
  722. # CheckMetadataHash
  723. ```
  724. The decoded JSON is structured-only (no colorization), so it's safe to redirect to a file or pipe into other tools. The default fetches fresh from the RPC and atomically updates the local metadata cache and runtime-fingerprint sidecar — so subsequent commands benefit from the freshest possible metadata.
  725. ### Runtime APIs
  726. Browse and call Substrate runtime APIs. These are top-level APIs exposed by the runtime (e.g. `Core`, `AccountNonceApi`, `TransactionPaymentApi`), accessed as `dot <chain>.apis.ApiName.method`.
  727. ```bash
  728. # List all runtime APIs with method counts
  729. dot polkadot.apis
  730. # Output:
  731. # Runtime APIs on polkadot (24)
  732. #
  733. # AccountNonceApi 1 methods
  734. # AssetHubMigrationApi 2 methods
  735. # AuthorityDiscoveryApi 1 methods
  736. # BabeApi 6 methods
  737. # ...
  738. # List methods in a specific API (with signatures)
  739. dot polkadot.apis.Core
  740. # Output:
  741. # Core Methods
  742. #
  743. # execute_block(block: { header: { ... }, extrinsics: Vec<Vec<u8>> }) → unknown
  744. # Execute the given block.
  745. # initialize_block(header: { ... }) → AllExtrinsics | OnlyInherents
  746. # Initialize a block with the given header and return the runtime executive mode.
  747. # version() → { spec_name: str, impl_name: str, ... }
  748. # Returns the version of the runtime.
  749. # Call a runtime API method
  750. dot polkadot.apis.Core.version --json
  751. # Output:
  752. # {
  753. # "spec_name": "polkadot",
  754. # "impl_name": "parity-polkadot",
  755. # "spec_version": 2002001,
  756. # "transaction_version": 26,
  757. # ...
  758. # }
  759. # --chain flag is equivalent
  760. dot apis.Core.version --chain polkadot
  761. # Show method signature and docs (chain still required to load metadata)
  762. dot polkadot.apis.Core.version --help
  763. ```
  764. `api` is an alias for `apis`.
  765. Runtime API info requires v15+ metadata (the CLI negotiates the highest version the chain supports, currently up to v16). If `dot <chain>.apis` shows 0 APIs, update the cached metadata:
  766. ```bash
  767. dot chain update polkadot # specific chain
  768. dot chain update --all # all configured chains
  769. ```
  770. #### Argument formats
  771. Runtime API arguments accept the same shorthand as `dot tx` arguments:
  772. | Type | Pass as | Example |
  773. |------|---------|---------|
  774. | Integers (`u8` … `u32`, `i8` … `i32`) | decimal | `0`, `42` |
  775. | Big integers (`u64`, `u128`, `u256`, `i64` …) | decimal | `1000000000000` |
  776. | `bool` | `true` / `false` | `true` |
  777. | `AccountId32` | dev name, stored account, SS58, or `0x` + 64 hex pubkey | `alice`, `5GrwvaEF…` |
  778. | `Vec<u8>` (unsized bytes) | `0x…` hex or text | `0xdeadbeef`, `hello` |
  779. | `[u8; N]` (sized bytes, e.g. `H160`/`H256`/raw `AccountId`) | `0x` + exactly `2 * N` hex chars (recommended), or text | `0x970951a12f975e6762482aca81e57d5a2a4e73f4` |
  780. | `Option<T>` | `null` (recommended), `none`, `undefined` — or a `T` value for `Some(value)` | `null` |
  781. | `Vec<T>` (non-byte) | JSON array or comma-separated | `[1,2,3]`, `1,2,3` |
  782. | Structs / nested enums | JSON | `{"type":"X1","value":{…}}` |
  783. For sized byte arrays (`[u8; N]`) — common for Ethereum-style addresses (`H160`, `[u8; 20]`), 32-byte hashes (`H256`), and raw `AccountId32` bytes — pass a `0x`-prefixed hex string. Example: a contract call against the `pallet-revive` runtime API. Use `dot <chain>.apis.<ApiName>.<method> --help` to see the exact argument signature for any method.
  784. ```bash
  785. ORIGIN=alice
  786. CONTRACT=0x970951a12f975e6762482aca81e57d5a2a4e73f4 # H160, [u8; 20]
  787. CALLDATA=$(cast calldata "set(uint256)" 42)
  788. # Args: origin, dest, value, gas_limit (Option), storage_deposit (Option), input_data
  789. dot paseo-asset-hub.apis.ReviveApi.call \
  790. "$ORIGIN" "$CONTRACT" 0 null null "$CALLDATA"
  791. ```
  792. ##### Passing `Option<T>`
  793. Absent options (`None`) can be written three ways, all equivalent:
  794. ```bash
  795. # null (recommended), none, and undefined all mean None
  796. dot paseo-asset-hub.apis.ReviveApi.call "$ORIGIN" "$CONTRACT" 0 null null "$CALLDATA"
  797. dot paseo-asset-hub.apis.ReviveApi.call "$ORIGIN" "$CONTRACT" 0 none none "$CALLDATA"
  798. dot paseo-asset-hub.apis.ReviveApi.call "$ORIGIN" "$CONTRACT" 0 undefined undefined "$CALLDATA"
  799. ```
  800. `null` is the **recommended** form — it matches JSON / YAML semantics, so args read identically on the CLI and inside [file-based command](#file-based-commands) YAML/JSON inputs.
  801. A present option (`Some(value)`) is just the value itself — no wrapping:
  802. ```bash
  803. # gas_limit = Some({ ref_time: 1_000_000, proof_size: 100_000 })
  804. dot paseo-asset-hub.apis.ReviveApi.call "$ORIGIN" "$CONTRACT" 0 \
  805. '{"ref_time":1000000,"proof_size":100000}' \
  806. null \
  807. "$CALLDATA"
  808. ```
  809. Notes:
  810. - The `null` / `none` / `undefined` literals are case-sensitive (lowercase only).
  811. - There is no `Some(value)` prefix — bare values are already treated as `Some`.
  812. ### Focused metadata listings
  813. Each category supports partial dot-paths for browsing metadata. Category-only invocations list pallets (or APIs); pallet-level invocations list items; item-level invocations show detail. Singular and plural aliases work: `event` = `events`, `error` = `errors`, `api` = `apis`, `consts` = `constants` = `const`.
  814. ```bash
  815. # List pallets with calls (and the calls themselves)
  816. dot polkadot.tx # pallets with calls
  817. dot polkadot.tx.Balances # calls with arg signatures
  818. dot polkadot.tx.Balances.transfer_allow_death # call detail (or use --help)
  819. # Events
  820. dot polkadot.events # pallets with events
  821. dot polkadot.events.Balances # events with field signatures
  822. dot polkadot.events.Balances.Transfer # event detail
  823. # Errors
  824. dot polkadot.errors # pallets with errors
  825. dot polkadot.errors.Balances # errors with docs
  826. dot polkadot.errors.Balances.InsufficientBalance
  827. # Storage (via the query category)
  828. dot polkadot.query # pallets with storage items
  829. dot polkadot.query.System # storage items with types
  830. dot polkadot.query.System.Account # storage help (use --dump for all entries)
  831. # Constants
  832. dot polkadot.const # pallets with constants
  833. dot polkadot.const.Balances # list constants (offline)
  834. dot polkadot.const.Balances.ExistentialDeposit # look up value (connects to chain)
  835. # Runtime APIs
  836. dot polkadot.apis # all runtime APIs
  837. dot polkadot.apis.Core # methods in Core
  838. # Transaction extensions (flat — no pallet sub-level)
  839. dot polkadot.extensions # all transaction extensions
  840. dot polkadot.extensions.CheckMortality # extension detail
  841. ```
  842. `--chain <name>` works as an alternative to the prefix in every form (e.g. `dot tx.Balances --chain polkadot`). To browse pallets across all categories at once, use `dot inspect` (see [Inspect metadata](#inspect-metadata)).
  843. ### Transaction extensions
  844. List the transaction extensions (also known as signed extensions) a chain declares in its runtime, with types and a marker indicating whether `polkadot-api` handles the extension automatically or whether you need to provide a value via `--ext` when building a transaction (see [Submit extrinsics](#submit-extrinsics)).
  845. ```bash
  846. # List all transaction extensions on a chain
  847. dot polkadot.extensions
  848. # Output:
  849. # Transaction extensions on polkadot (11, extension version 0)
  850. #
  851. # AuthorizeCall unknown [custom]
  852. # ChargeTransactionPayment Compact<u128> [builtin]
  853. # CheckGenesis unknown [builtin]
  854. # CheckMetadataHash Disabled | Enabled [builtin]
  855. # CheckMortality enum(256 variants) [builtin]
  856. # CheckNonce Compact<u64> [builtin]
  857. # CheckNonZeroSender unknown [builtin]
  858. # CheckSpecVersion unknown [builtin]
  859. # CheckTxVersion unknown [builtin]
  860. # CheckWeight unknown [builtin]
  861. # PrevalidateAttests unknown [builtin]
  862. # Detail view for a single extension
  863. dot polkadot.extensions.CheckMortality
  864. # Output:
  865. # CheckMortality (Transaction Extension)
  866. #
  867. # Value type: enum(256 variants)
  868. # AdditionalSigned: [u8; 32]
  869. # Handled by: polkadot-api (builtin)
  870. # Structured output for scripts
  871. dot polkadot.extensions --json
  872. ```
  873. `extension` and `ext` are aliases for `extensions`. Shell completion suggests identifiers after `dot polkadot.extensions.<Tab>`.
  874. The list view tags each entry:
  875. - `[builtin]` — `polkadot-api` fills this in for you (e.g. `CheckMortality`, `CheckNonce`, `ChargeTransactionPayment`, `CheckMetadataHash`)
  876. - `[custom]` — you must provide a value with `--ext` when signing, for example `--ext '{"<Identifier>":{"value":<v>}}'`
  877. The detail view shows the extension's value type, its `additionalSigned` type, and a ready-to-adapt `--ext` snippet for custom extensions. Use this to discover what `--ext` payload a chain expects before submitting a `dot tx` command.
  878. ### Raw JSON-RPC
  879. Substrate nodes expose a JSON-RPC surface that lives outside runtime metadata: `system_*` (sync state, peers, version), `chain_*` (blocks, headers, finalized head), `state_*` (raw storage, key iteration, runtime version), `author_*` (mempool, key management), `payment_*` (fee estimation), consensus families (`babe_*`, `grandpa_*`, `mmr_*`, `beefy_*`), and the new spec families (`chainSpec_v1_*`, `archive_v1_*`, `rpc_methods`). The `rpc` category exposes them all.
  880. Methods are discovered per-chain via the standard `rpc_methods` JSON-RPC call and cached at `~/.polkadot/chains/<chain>/rpc-methods.json`. The set of available methods depends on the node, not the chain — an archive node adds `archive_v1_*`, validators may add `babe_epochAuthorship`, dev nodes add `dev_newBlock`, and `--rpc-methods safe` strips writes.
  881. ```bash
  882. # List all methods the node exposes, grouped by family
  883. dot polkadot.rpc
  884. # Output:
  885. # RPC methods on polkadot (129)
  886. #
  887. # system (20)
  888. # system_health Node sync state (peers, isSyncing, shouldHavePeers).
  889. # system_version Node software version string.
  890. # system_chain Chain name as reported by the node.
  891. # ...
  892. # chain (19)
  893. # chain_getBlock Full block (header + extrinsics) by hash.
  894. # chain_getFinalizedHead Hash of the latest finalized head.
  895. # ...
  896. # Call a method
  897. dot polkadot.rpc.system_health
  898. # Output:
  899. # {
  900. # "peers": 131,
  901. # "isSyncing": false,
  902. # "shouldHavePeers": true
  903. # }
  904. # Positional args (parsed by the same heuristic as tx args)
  905. dot polkadot.rpc.chain_getBlockHash 1000
  906. # Output:
  907. # "0xcf36a1e4a16fc579136137b8388f35490f09c5bdd7b9133835eba907a8b76c30"
  908. # Show curated info for a known method
  909. dot polkadot.rpc.author_insertKey --help
  910. # Output:
  911. # author_insertKey
  912. # ⚠️ WRITE / state-changing
  913. # Insert a key into the node keystore.
  914. #
  915. # Family: author
  916. # Args: <keyType: string> <suri: string> <publicKey: hex>
  917. # Refresh the cached method list (after a node upgrade)
  918. dot polkadot.rpc --refresh
  919. # JSON output works on any method
  920. dot polkadot.rpc.system_health --json
  921. ```
  922. `dot chain add` and `dot chain update` automatically populate the method cache, and `dot chain info <name>` shows a per-family breakdown. Tab completion sources from the cache, so methods on a custom chain start completing the moment you've added or updated it.
  923. About 50 well-known methods carry curated metadata (description, named args, `⚠️ WRITE` tag for state-changing calls). Any other method the node reports is callable via raw passthrough — args are forwarded as-is to the JSON-RPC `params` array.
  924. Subscription methods (`*_subscribe*`, `chainHead_v1_follow`, `transaction_v1_*`) appear in tab-completion but error out as one-shots — they need a long-running follow session that doesn't fit a single CLI invocation:
  925. ```bash
  926. dot polkadot.rpc.chain_subscribeAllHeads
  927. # Error: "chain_subscribeAllHeads" is a subscription method (requires a follow
  928. # session) and is not callable as a one-shot. Use a long-running client for
  929. # streaming RPC.
  930. ```
  931. The `rpc` category is **flat** — there's no pallet level. The form is `[chain.]rpc.<method_name>`, where `<method_name>` keeps its underscores in a single segment (e.g. `polkadot.rpc.chain_getBlock`).
  932. ### Submit extrinsics
  933. Build, sign, and submit transactions. Pass a `Pallet.Call` with arguments, or a raw SCALE-encoded call hex (e.g. from a multisig proposal or governance). Both forms display a decoded human-readable representation of the call.
  934. ![Dry-running then submitting a transfer on Paseo Asset Hub, with events and explorer links](docs/static/vhs/submit.gif)
  935. ```bash
  936. # Estimate fees without submitting (no broadcast). The Decode block shows
  937. # the call name on the header line and indented JSON below it.
  938. dot polkadot.tx.System.remark 0xdeadbeef --from alice --dry-run
  939. # Output:
  940. # Chain: polkadot
  941. # From: alice (5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY)
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 1,257 on GitHub
  942. # Call: 0x000010deadbeef
  943. # Decode: System.remark
  944. # {
  945. # "remark": "0xdeadbeef"
  946. # }
  947. # Estimated fees: 125598975
  948. # Transfer (amount in plancks). Method names are snake_case.
  949. dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000000 --from alice --dry-run
  950. # Submit (omit --dry-run)
  951. dot polkadot.tx.System.remark 0xdeadbeef --from alice
  952. # Force every tx to dry-run via the global DOT_DRY_RUN env var — a safety net
  953. # for scripts and demos. A hint is printed to stderr; the command behaves
  954. # exactly as if --dry-run had been passed.
  955. DOT_DRY_RUN=1 dot polkadot.tx.System.remark 0xdeadbeef --from alice
  956. # stderr: ⚠ DOT_DRY_RUN is set — extrinsics will be simulated, not submitted.
  957. # stdout: (the dry-run output above — no broadcast)
  958. # Submit a raw SCALE-encoded call (e.g. from a multisig proposal or another tool)
  959. dot polkadot.tx 0x000010deadbeef --from alice --dry-run
  960. # Batch multiple remarks with Utility.batch_all (comma-separated encoded calls).
  961. # Complex decoded calls remain readable because each level is indented.
  962. A=$(dot polkadot.tx.System.remark 0xdeadbeef --encode)
  963. B=$(dot polkadot.tx.System.remark 0xcafe --encode)
  964. dot polkadot.tx.Utility.batch_all "$A,$B" --from alice --dry-run
  965. # Output (excerpt — nested calls each get their own enum {type, value} envelope):
  966. # Chain: polkadot
  967. # From: alice (5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY)
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 1,288 on GitHub
  968. # Call: 0x1a0208000010deadbeef000008cafe
  969. # Decode: Utility.batch_all
  970. # {
  971. # "calls": [
  972. # {
  973. # "type": "System",
  974. # "value": {
  975. # "type": "remark",
  976. # "value": { "remark": "0xdeadbeef" }
  977. # }
  978. # },
  979. # ...
  980. # ]
  981. # }
  982. # Estimated fees: 133994995
  983. ```
  984. The `--chain` flag is equivalent to the chain prefix:
  985. ```bash
  986. dot polkadot.tx.System.remark 0xdeadbeef --from alice
  987. dot tx.System.remark 0xdeadbeef --from alice --chain polkadot
  988. ```
  989. #### Enum shorthand
  990. Enum arguments accept a concise `Variant(value)` syntax instead of verbose JSON:
  991. ```bash
  992. # Instead of: '{"type":"system","value":{"type":"Authorized"}}'
  993. dot polkadot.tx.Utility.dispatch_as 'system(Authorized)' $(dot polkadot.tx.System.remark 0xcafe --encode) --from alice --dry-run
  994. # Output:
  995. # Chain: polkadot
  996. # From: alice (5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY)
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 1,322 on GitHub
  997. # Call: 0x1a030003000008cafe
  998. # Decode: Utility.dispatch_as
  999. # {
  1000. # "as_origin": { "type": "system", "value": { "type": "Authorized" } },
  1001. # "call": { "type": "System", "value": { "type": "remark", "value": { "remark": "0xcafe" } } }
  1002. # }
  1003. # Estimated fees: 127644270
  1004. # Nested enums work too — Signed origin with an account
  1005. dot polkadot.tx.Utility.dispatch_as 'system(Signed(bob))' "$INNER_CALL" --from alice --dry-run
  1006. # Void variants — empty parens or just the name
  1007. dot polkadot.tx.Pallet.call 'Root()' ... --from alice
  1008. dot polkadot.tx.Pallet.call 'Root' ... --from alice
  1009. # JSON inside parens for struct values
  1010. dot polkadot.tx.Pallet.call 'AccountId32({"id":"0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d"})' ... --from alice
  1011. ```
  1012. Variant matching is case-insensitive (`system` resolves to `system`, `authorized` to `Authorized`). All existing formats (JSON objects, hex, SS58 addresses) continue to work unchanged.
  1013. #### Encode call data
  1014. Encode a call to hex without signing or submitting. Useful for preparing calls to pass to `Sudo.sudo`, multisig proposals, or governance. Works offline from cached metadata and does not require `--from`.
  1015. ```bash
  1016. # Encode a remark call
  1017. dot polkadot.tx.System.remark 0xdeadbeef --encode
  1018. # Output:
  1019. # 0x000010deadbeef
  1020. # Encode a transfer (use the hex output in a batch or sudo call)
  1021. dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000 --encode
  1022. # Output:
  1023. # 0x050300...02286bee
  1024. # Use encoded output with Sudo.sudo (Sudo only exists on testnets like Paseo)
  1025. dot paseo-asset-hub.tx.Sudo.sudo $(dot paseo-asset-hub.tx.System.remark 0xcafe --encode) --from alice --dry-run
  1026. # Output:
  1027. # Chain: paseo-asset-hub
  1028. # From: alice (5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY)
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 1,363 on GitHub
  1029. # Call: 0xfb00000008cafe
  1030. # Decode: Sudo.sudo
  1031. # {
  1032. # "call": { "type": "System", "value": { "type": "remark", "value": { "remark": "0xcafe" } } }
  1033. # }
  1034. # Estimated fees: ...
  1035. ```
  1036. #### Decode call data to YAML / JSON
  1037. Decode a hex-encoded call into a YAML or JSON file that is compatible with [file-based commands](#file-based-commands). This is useful for inspecting opaque call data, sharing human-readable transaction definitions, or editing parameters before re-submitting. Works offline from cached metadata and does not require `--from`.
  1038. ```bash
  1039. # Decode a raw hex call to YAML
  1040. dot polkadot.tx.0x000010deadbeef --to-yaml
  1041. # Output:
  1042. # chain: polkadot
  1043. # tx:
  1044. # System:
  1045. # remark:
  1046. # remark: "0xdeadbeef"
  1047. # Decode a raw hex call to JSON
  1048. dot polkadot.tx.0x000010deadbeef --to-json
  1049. # Output:
  1050. # {
  1051. # "chain": "polkadot",
  1052. # "tx": {
  1053. # "System": {
  1054. # "remark": {
  1055. # "remark": "0xdeadbeef"
  1056. # }
  1057. # }
  1058. # }
  1059. # }
  1060. # Encode a named call and output as YAML
  1061. dot polkadot.tx.System.remark 0xdeadbeef --to-yaml
  1062. # Round-trip: encode to hex, decode to YAML, re-encode from file
  1063. dot polkadot.tx.System.remark 0xdeadbeef --encode # 0x000010deadbeef
  1064. dot polkadot.tx.0x000010deadbeef --to-yaml > remark.yaml
  1065. dot ./remark.yaml --encode # chain comes from the file
  1066. ```
  1067. `--to-yaml` / `--to-json` are mutually exclusive with each other and with `--encode` and `--dry-run`.
  1068. Both dry-run and submission display the encoded call hex and a decoded human-readable form. The decoded call is rendered as JSON with two-space indentation under the `Decode:` header so even deeply nested calls (XCM, sudo, batch, dispatch_as) remain easy to scan:
  1069. ```
  1070. Call: 0x000010deadbeef
  1071. Decode: System.remark
  1072. {
  1073. "remark": "0xdeadbeef"
  1074. }
  1075. Tx: 0xabc123...
  1076. Status: ok
  1077. ```
  1078. Complex calls (XCM teleports, batched governance proposals) keep the same shape — every nested enum becomes a `{ "type": ..., "value": ... }` block, indented one level deeper, so you can read the structure top-down without it ever wrapping past the terminal width.
  1079. #### Exit codes
  1080. 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`).
  1081. ```bash
  1082. dot polkadot.tx.Balances.transfer_keep_alive bob 999999999999999999 --from alice
  1083. # ... events and explorer links ...
  1084. # Error: Transaction dispatch error: Balances.InsufficientBalance
  1085. echo $? # 1
  1086. ```
  1087. #### Stale metadata detection
  1088. When a `tx`, `--dry-run`, or `query` fails with an error that smells like stale metadata — a runtime wasm trap, a SCALE codec/decode error, or a fee-estimation panic — the CLI compares your locally cached metadata's runtime fingerprint against the live chain. If it has changed, the CLI appends a one-line suggestion telling you exactly which command to run:
  1089. ```
  1090. Error: The runtime rejected this transaction in the runtime's validate_transaction step.
  1091. Cause: a runtime invariant failed — typically the call's arguments are out of range, …
  1092. ⚠ Local metadata for "paseo-people-next" is out of date (spec 1018 → 1020).
  1093. Run: dot chain update paseo-people-next
  1094. ```
  1095. The fingerprint includes the runtime code hash, so the check also catches local-node restarts where the wasm changed but `specVersion` was kept the same. No automatic refetch happens — the original error still propagates with a non-zero exit code, you just get an actionable suggestion.
  1096. The check only fires on suspected-stale errors, so the happy path pays no extra RPC. Set `DOT_TRUST_CACHED_METADATA=1` to disable the check entirely (e.g. for CI loops where you've just refreshed manually).
  1097. #### Argument parsing errors
  1098. ![Fuzzy suggestions for a misspelled pallet, a misspelled storage item, a wrong argument count and an unknown account name](docs/static/vhs/did-you-mean.gif)
  1099. Every name the CLI resolves is fuzzy-matched on failure — pallets, storage items, constants, runtime API methods and account names all answer with the candidates they were closest to. A call given the wrong number of arguments answers with its own signature.
  1100. When a call argument is invalid, the CLI shows a contextual error message with the argument name, the expected type, and a hint:
  1101. ```bash
  1102. dot polkadot.tx.Balances.transfer_keep_alive bob abc --encode
  1103. # Error: Invalid value for argument 'value' (expected Compact<u128>): "abc"
  1104. # Hint: Compact<u128>
  1105. ```
  1106. For struct-based calls, the error identifies the specific field that failed. For tuple-based calls, it shows the argument index. The original parse error is preserved as the `cause` for programmatic access.
  1107. #### Wait level
  1108. By default, `dot tx` waits for finalization (~30s on Polkadot). Use `--wait` / `-w` to return earlier:
  1109. ```bash
  1110. # Return as soon as the tx is broadcast (fastest)
  1111. dot polkadot.tx.System.remark 0xdead --from alice --wait broadcast
  1112. # Return when included in a best block
  1113. dot polkadot.tx.System.remark 0xdead --from alice -w best-block
  1114. dot polkadot.tx.System.remark 0xdead --from alice -w best # alias
  1115. # Wait for finalization (default, unchanged)
  1116. dot polkadot.tx.System.remark 0xdead --from alice --wait finalized
  1117. dot polkadot.tx.System.remark 0xdead --from alice # same
  1118. ```
  1119. | Level | Resolves when | Events shown | Explorer links |
  1120. |-------|---------------|:---:|:---:|
  1121. | `broadcast` | Tx is broadcast to the network | — | — |
  1122. | `best-block` / `best` | Tx is included in a best block | yes | yes |
  1123. | `finalized` (default) | Tx is finalized | yes | yes |
  1124. The `--wait` flag is silently ignored when combined with `--dry-run` or `--encode` (both return before submission).
  1125. #### Custom signed extensions
  1126. Chains with non-standard signed extensions are auto-handled:
  1127. - `void` → empty bytes
  1128. - `Option<T>` → `None`
  1129. - enum with `Disabled` variant → `Disabled`
  1130. For manual override, use `--ext` with a JSON object:
  1131. ```bash
  1132. dot polkadot.tx.System.remark 0xdeadbeef --from alice --ext '{"MyExtension":{"value":"..."}}'
  1133. ```
  1134. `--ext` overrides work for `[builtin]` extensions too — for example `--ext '{"CheckMetadataHash":{"value":{"type":"Enabled"}}}'` replaces the value `polkadot-api` would fill in itself. Passing an extension name the chain doesn't declare is an error.
  1135. Not sure which extensions a chain exposes? Run `dot <chain>.extensions` (see [Transaction extensions](#transaction-extensions)) to list them all with value types and a `[builtin]` / `[custom]` marker.
  1136. #### Transaction options
  1137. Override low-level transaction parameters. Useful for rapid-fire submission (custom nonce), priority fees (tip), or controlling transaction lifetime (mortality).
  1138. | Flag | Value | Description |
  1139. |------|-------|-------------|
  1140. | `--nonce <n>` | non-negative integer | Override the auto-detected nonce |
  1141. | `--tip <amount>` | non-negative integer (planck) | Priority tip for the transaction pool |
  1142. | `--mortality <spec>` | `immortal` or period (min 4) | Transaction mortality window |
  1143. | `--at <block>` | 0x-prefixed block hash, `"best"`, or `"finalized"` | Block to read/validate against (defaults to finalized). Also honored on `query.*` and `apis.*` for historical reads; tx submission rejects `"best"`. |
  1144. ```bash
  1145. # Fire-and-forget: submit two txs in rapid succession with manual nonces
  1146. dot polkadot.tx.System.remark 0xdead --from alice --nonce 0 --wait broadcast
  1147. dot polkadot.tx.System.remark 0xbeef --from alice --nonce 1 --wait broadcast
  1148. # Add a priority tip (in planck)
  1149. dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000 --from alice --tip 1000000
  1150. # Submit an immortal transaction (no expiry)
  1151. dot polkadot.tx.System.remark 0xdead --from alice --mortality immortal
  1152. # Set a custom mortality period (rounds up to nearest power of two)
  1153. dot polkadot.tx.System.remark 0xdead --from alice --mortality 128
  1154. # Validate against a specific block hash
  1155. dot polkadot.tx.System.remark 0xdead --from alice --at 0x1234...abcd
  1156. # Combine: rapid-fire with tip and broadcast-only
  1157. dot polkadot.tx.System.remark 0xdead --from alice --nonce 5 --tip 500000 --wait broadcast
  1158. ```
  1159. When set, nonce / tip / mortality / at are shown in both `--dry-run` and submission output. These flags are silently ignored with `--encode`, `--to-yaml`, and `--to-json` (which return before signing).
  1160. #### Pay fees in an alternative asset
  1161. On asset-hub-style chains (Polkadot Asset Hub, Paseo Asset Hub, etc.) the `ChargeAssetTxPayment` signed extension lets a transaction pay its fees in a non-native asset. Use `--asset <json>` to select the asset — the value is an XCM location (JSON) identifying the asset, which the runtime's asset-conversion pool swaps for native tokens at dispatch time.
  1162. ```bash
  1163. # Define the USDT location once (asset id 1337, PalletInstance 50)
  1164. USDT='{"parents":0,"interior":{"type":"X2","value":[{"type":"PalletInstance","value":50},{"type":"GeneralIndex","value":"1337"}]}}'
  1165. # Dry-run to see the native-denominated fee estimate
  1166. dot polkadot-asset-hub.tx.Balances.transfer_keep_alive bob 1000000000 \
  1167. --from alice --dry-run --asset "$USDT"
  1168. # Output:
  1169. # Chain: polkadot-asset-hub
  1170. # From: alice (5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY)
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 1,558 on GitHub
  1171. # Call: 0x0a0300d435...02286bee
  1172. # Decode: Balances.transfer_keep_alive { dest: Id(...), value: 1000000000 }
  1173. # Asset: {"parents":0,"interior":{"type":"X2","value":[{"type":"PalletInstance","value":50},{"type":"GeneralIndex","value":"1337"}]}}
  1174. # Estimated fees: 9249754
  1175. # Submit (omit --dry-run)
  1176. dot polkadot-asset-hub.tx.Balances.transfer_keep_alive bob 1000000000 \
  1177. --from alice --asset "$USDT"
  1178. ```
  1179. The `--asset` echo is included in dry-run and submission output (and `--json`). A few things to know:
  1180. - The target chain must expose `ChargeAssetTxPayment` in its signed extensions — asset-hub-style chains do; plain relay chains don't, and `--asset` is silently ignored on those.
  1181. - The estimated fee shown is **native-denominated**. The on-chain asset-conversion pool determines the actual asset amount charged at execution time.
  1182. - `--asset` is unnecessary (and not compatible) with `--general`: general transactions default `ChargeAssetTxPayment` to zero tip / no asset.
  1183. - Combine freely with `--tip`, `--nonce`, `--mortality`, and `--at`. `--tip` is encoded inside the asset-payment extension alongside the asset id.
  1184. Under the hood, the CLI routes the asset through its custom signed-extension pipeline rather than polkadot-api's native `asset` option — this works around a papi compatibility check that rejects XCM Location JSON on the unsafe API path.
  1185. #### General (v5) transactions
  1186. Submit transactions without a signer using `--general`. This builds an extrinsic v5 *general* transaction: it carries no signature field of its own — authorization (a signature, or something else entirely) lives in the transaction extensions. Typical use is calls authorized by on-chain mechanisms (e.g. the `AuthorizeCall` extension) rather than a signer, such as governance-authorized calls on chains like the People chain.
  1187. ```bash
  1188. # Submit an authorized call on the People chain
  1189. dot polkadot-people.tx.People.create_people_collection --general
  1190. # Dry-run to inspect before submitting
  1191. dot polkadot-people.tx.People.create_people_collection --general --dry-run
  1192. # Encode the full general transaction bytes
  1193. dot polkadot-people.tx.People.create_people_collection --general --encode
  1194. # With raw hex call data
  1195. dot polkadot-people.tx 0x3306 --general
  1196. # JSON output for scripting
  1197. dot polkadot-people.tx.People.create_people_collection --general --json
  1198. ```
  1199. The CLI constructs a v5 general transaction with all extension values auto-defaulted (`VerifySignature::Disabled`, `Era::Immortal`, nonce `0`, tip `0`, etc.). Override individual extensions with `--ext` if needed.
  1200. `--general` is mutually exclusive with `--from`, `--nonce`, `--tip`, and `--mortality`. File-based input supports `general: true`:
  1201. ```yaml
  1202. chain: polkadot-people
  1203. general: true
  1204. tx:
  1205. People:
  1206. create_people_collection: null
  1207. ```
  1208. The old `--unsigned` flag (and the `unsigned: true` file key) still works as a deprecated alias — a v5 general transaction is not "unsigned", so the flag was renamed.
  1209. ### File-based commands
  1210. ![Encoding an XCM teleport from a YAML file with a run-time variable, then the file behind it](docs/static/vhs/xcm-file.gif)
  1211. Run any `dot` command from a YAML or JSON file. Especially useful for complex calls like XCM messages that are hard to construct inline.
  1212. **Teleport DOT** from Asset Hub to the relay chain:
  1213. ```yaml
  1214. # teleport-dot.xcm.yaml
  1215. chain: polkadot-asset-hub
  1216. tx:
  1217. PolkadotXcm:
  1218. limited_teleport_assets:
  1219. dest:
  1220. type: V4
  1221. value:
  1222. parents: 1
  1223. interior:
  1224. type: Here
  1225. beneficiary:
  1226. type: V4
  1227. value:
  1228. parents: 0
  1229. interior:
  1230. type: X1
  1231. value:
  1232. - type: AccountId32
  1233. value:
  1234. network: null
  1235. id: "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d"
  1236. assets:
  1237. type: V4
  1238. value:
  1239. - id:
  1240. parents: 1
  1241. interior:
  1242. type: Here
  1243. fun:
  1244. type: Fungible
  1245. value: 10000000000
  1246. fee_asset_item: 0
  1247. weight_limit:
  1248. type: Unlimited
  1249. ```
  1250. **Reserve transfer USDC** (asset 1337, 6 decimals) from Asset Hub to Hydration:
  1251. ```yaml
  1252. # reserve-transfer-usdc.xcm.yaml
  1253. chain: polkadot-asset-hub
  1254. tx:
  1255. PolkadotXcm:
  1256. limited_reserve_transfer_assets:
  1257. dest:
  1258. type: V4
  1259. value:
  1260. parents: 1
  1261. interior:
  1262. type: X1
  1263. value:
  1264. - type: Parachain
  1265. value: 2034
  1266. beneficiary:
  1267. type: V4
  1268. value:
  1269. parents: 0
  1270. interior:
  1271. type: X1
  1272. value:
  1273. - type: AccountId32
  1274. value:
  1275. network: null
  1276. id: "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d"
  1277. assets:
  1278. type: V4
  1279. value:
  1280. - id:
  1281. parents: 0
  1282. interior:
  1283. type: X2
  1284. value:
  1285. - type: PalletInstance
  1286. value: 50
  1287. - type: GeneralIndex
  1288. value: 1337
  1289. fun:
  1290. type: Fungible
  1291. value: 10000000
  1292. fee_asset_item: 0
  1293. weight_limit:
  1294. type: Unlimited
  1295. ```
  1296. The same teleport in JSON:
  1297. ```json
  1298. {
  1299. "chain": "polkadot-asset-hub",
  1300. "tx": {
  1301. "PolkadotXcm": {
  1302. "limited_teleport_assets": {
  1303. "dest": { "type": "V4", "value": { "parents": 1, "interior": { "type": "Here" } } },
  1304. "beneficiary": {
  1305. "type": "V4",
  1306. "value": {
  1307. "parents": 0,
  1308. "interior": {
  1309. "type": "X1",
  1310. "value": [{ "type": "AccountId32", "value": { "network": null, "id": "0xd435...a27d" } }]
  1311. }
  1312. }
  1313. },
  1314. "assets": {
  1315. "type": "V4",
  1316. "value": [{
  1317. "id": { "parents": 1, "interior": { "type": "Here" } },
  1318. "fun": { "type": "Fungible", "value": 10000000000 }
  1319. }]
  1320. },
  1321. "fee_asset_item": 0,
  1322. "weight_limit": { "type": "Unlimited" }
  1323. }
  1324. }
  1325. }
  1326. }
  1327. ```
  1328. ```bash
  1329. # Run from file (the `chain:` field comes from the YAML)
  1330. dot ./teleport-dot.xcm.yaml --from alice --dry-run
  1331. # Output:
  1332. # Chain: polkadot-asset-hub
  1333. # From: alice (5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY)
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 1,746 on GitHub
  1334. # Call: 0x1f0904...
  1335. # Decode: PolkadotXcm.limited_teleport_assets { dest: V4 { parents: 1, interior: Here }, ... }
  1336. # Estimated fees: ...
  1337. # Encode only
  1338. dot ./reserve-transfer-usdc.xcm.yaml --encode
  1339. # Override variables
  1340. dot ./transfer.xcm.yaml --var AMOUNT=2000000000000 --from alice
  1341. ```
  1342. The file format uses a required category wrapper (`tx`, `query`, `const`, or `apis`) with the structure `category > Pallet > Item > args`:
  1343. ```yaml
  1344. # Simple transaction
  1345. tx:
  1346. System:
  1347. remark:
  1348. - "0xdeadbeef"
  1349. ```
  1350. ```yaml
  1351. # Storage query
  1352. chain: polkadot
  1353. query:
  1354. System:
  1355. Account:
  1356. - "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 1,774 on GitHub
  1357. ```
  1358. ```yaml
  1359. # Constant lookup
  1360. chain: polkadot
  1361. const:
  1362. Balances:
  1363. ExistentialDeposit:
  1364. ```
  1365. **Variable substitution** uses shell-style `${VAR}` with optional defaults `${VAR:-default}`. Variables are resolved in order: `--var` flags > environment variables > `vars:` section defaults.
  1366. ```yaml
  1367. chain: ${CHAIN:-polkadot}
  1368. vars:
  1369. AMOUNT: "1000000000000"
  1370. tx:
  1371. Balances:
  1372. transfer_keep_alive:
  1373. dest: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
  1374. value: ${AMOUNT}
  1375. ```
  1376. Hex values passed via `--var` are preserved as-is, including leading zeros. This is important for encoded call data in XCM `Transact` instructions or similar byte-array fields:
  1377. ```bash
  1378. # Encode a remark, then embed it in an XCM Transact via --var
  1379. CALL=$(dot polkadot.tx.System.remark 0xdead --encode)
  1380. dot ./xcm-transact.yaml --var CALL=$CALL --encode
  1381. ```
  1382. All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--to-yaml`, `--to-json`, `--json`, `--output`, etc. behave identically to inline commands.
  1383. ### Compute hashes
  1384. Compute cryptographic hashes commonly used in Substrate. Supports BLAKE2b-256, BLAKE2b-128, Keccak-256, SHA-256, and the XXH64-based `twox64` / `twox128` / `twox256` family used to build Substrate storage keys.
  1385. ```bash
  1386. # Hash hex-encoded data
  1387. dot hash blake2b256 0xdeadbeef
  1388. # Output:
  1389. # 0xf3e925002fed7cc0ded46842569eb5c90c910c091d8d04a1bdf96e0db719fd91
  1390. # Hash plain text (UTF-8 encoded)
  1391. dot hash sha256 hello
  1392. # Output:
  1393. # 0x2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
  1394. # Hash file contents
  1395. dot hash keccak256 --file ./data.bin
  1396. # Read from stdin
  1397. echo -n "hello" | dot hash sha256 --stdin
  1398. # Output:
  1399. # 0x2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
  1400. # JSON output
  1401. dot hash blake2b256 0xdeadbeef --json
  1402. # Output:
  1403. # {
  1404. # "algorithm": "blake2b256",
  1405. # "input": "0xdeadbeef",
  1406. # "hash": "0xf3e925002fed7cc0ded46842569eb5c90c910c091d8d04a1bdf96e0db719fd91"
  1407. # }
  1408. # Substrate twox128 — pallet/storage prefix used everywhere in Substrate state
  1409. dot hash twox128 System
  1410. # Output:
  1411. # 0x26aa394eea5630e07c48ae0c9558cef7
  1412. # Build a full storage key for `System.Number` and read it raw via JSON-RPC
  1413. PALLET=$(dot hash twox128 System)
  1414. ITEM=$(dot hash twox128 Number)
  1415. dot polkadot.rpc.state_getStorage "${PALLET}${ITEM:2}"
  1416. ```
  1417. Run `dot hash` with no arguments to see all available algorithms.
  1418. ### Sign messages
  1419. Sign arbitrary messages with an account keypair. Output is a `Sr25519(0x...)` value directly usable as a `MultiSignature` enum argument in transaction calls.
  1420. ```bash
  1421. # Sign a text message
  1422. dot sign "hello world" --from alice
  1423. # Output:
  1424. # Type: Sr25519
  1425. # Message: 0x68656c6c6f20776f726c64
  1426. # Signature: 0x4283a3bbae463c39264ca193b1bcce61702794e54e482bc2e46202c85ef6a5446750e81db57cd28af4ffd5c69aadcf5b2b3068972e0cdcb68e51db0ff600d786
  1427. # Enum: Sr25519(0x4283a3bbae463c39264ca193b1bcce61702794e54e482bc2e46202c85ef6a5446750e81db57cd28af4ffd5c69aadcf5b2b3068972e0cdcb68e51db0ff600d786)
  1428. # Sign hex-encoded bytes
  1429. dot sign 0xdeadbeef --from alice
  1430. # Sign file contents
  1431. dot sign --file ./payload.bin --from alice
  1432. # Read from stdin
  1433. echo -n "hello" | dot sign --stdin --from alice
  1434. # JSON output (for scripting)
  1435. dot sign "hello" --from alice --json
  1436. # Output:
  1437. # {
  1438. # "type": "Sr25519",
  1439. # "message": "0x68656c6c6f",
  1440. # "signature": "0x5a058160b62eeb6c1194116d4613489e9c310075478c544761b9c8198d3fdb38...",
  1441. # "enum": "Sr25519(0x5a058160b62eeb6c1194116d4613489e9c310075478c544761b9c8198d3fdb38...)"
  1442. # }
  1443. ```
  1444. Output shows the crypto type, message bytes in hex, raw signature, and an `Enum` value directly pasteable into tx arguments (e.g. `Sr25519(0x...)`).
  1445. Use `--type` to select the signature algorithm (default: `sr25519`). Run `dot sign` with no arguments to see usage and examples.
  1446. ### Sovereign accounts (parachain & pallet)
  1447. ![Deriving a pallet sovereign and both parachain sovereigns, then querying one by name](docs/static/vhs/sovereign.gif)
  1448. `dot account add` accepts derivation flags that compute a deterministic sovereign address and store it as a named watch-only account — reusable in `--from` (for `--general` flows), as a tx argument, and in `dot account list`. Runs offline; no chain connection required.
  1449. Two kinds of sovereign:
  1450. - **Pallet sovereign** — every FRAME pallet that holds funds (Treasury, Bounties, Crowdloan, Society, NominationPools, ChildBounties, …) declares an 8-byte `PalletId`. The 32-byte account ID is `b"modl"` (4 bytes) + `palletId` (8 bytes) + 20 zero bytes. (`AccountIdConversion::into_account_truncating` with `PalletId::TYPE_ID = b"modl"` from `frame_support`.)
  1451. - **Parachain sovereign** — every parachain has a `child` account (its account on the relay chain, `b"para"` prefix) and a `sibling` account (its account on another parachain, `b"sibl"` prefix). Both are 32-byte IDs of the form `prefix (4 bytes)` + `paraId as LE u32 (4 bytes)` + 24 zero bytes.
  1452. ```bash
  1453. # Pallet sovereign — ASCII PalletId
  1454. dot account add Treasury --pallet-id py/trsry
  1455. # Output:
  1456. # Account Added (watch-only)
  1457. #
  1458. # Name: Treasury
  1459. # Address: 5EYCAe5ijiYfyeZ2JJCGq56LmPyNRAKzpG4QkoQkkQNB5e6Z
  1460. # Source: pallet py/trsry (0x70792f7472737279)
  1461. # Pallet sovereign — 0x-prefixed hex (16 hex chars)
  1462. dot account add Bounties --pallet-id 0x70792f626f756e74
  1463. # Parachain sovereign — child (relay-chain side) — type is required
  1464. dot account add People --parachain 1004 --parachain-type child
  1465. # Output:
  1466. # Account Added (watch-only)
  1467. #
  1468. # Name: People
  1469. # Address: 5Ec4AhPaYcfBz8fMoPd4EfnAgwbzRS7np3APZUnnFo12qEYk
  1470. # Source: parachain 1004 (child sovereign)
  1471. # Parachain sovereign — sibling (XCM peer side)
  1472. dot account add People-Sibling --parachain 1004 --parachain-type sibling
  1473. # JSON output includes a `derivation` object describing the source
  1474. dot account add Bnt --pallet-id py/bount --json
  1475. # {
  1476. # "name": "Bnt",
  1477. # "address": "5EYCAe5ijiYdYTM8d3VytEARdH7dFp4rdCPpAsPXrfopdm7d",
  1478. # "watchOnly": true,
  1479. # "derivation": {
  1480. # "kind": "pallet",
  1481. # "palletId": "py/bount",
  1482. # "palletIdHex": "0x70792f626f756e74"
  1483. # }
  1484. # }
  1485. # Stored sovereigns appear alongside other accounts
  1486. dot account list
  1487. ```
  1488. #### Discovering a chain's PalletId
  1489. Pallets that need a sovereign account expose their `PalletId` as a runtime constant. Read it via the `const` category and feed the hex straight into `--pallet-id`:
  1490. ```bash
  1491. # Pre-req: metadata cached for the chain (e.g. `dot chain update polkadot`)
  1492. dot polkadot.const.Treasury.PalletId
  1493. # Output (JSON-quoted hex):
  1494. # "0x70792f7472737279"
  1495. # Pipe into the add command (strip JSON quotes with tr)
  1496. dot account add Treasury --pallet-id "$(dot polkadot.const.Treasury.PalletId | tr -d '"')"
  1497. ```
  1498. There is no central registry of "well-known" PalletIds — each runtime author picks the 8 bytes when wiring up a pallet's `Config`. The chain's metadata is the authoritative source for that chain's values.
  1499. #### Constraints
  1500. - `--parachain` requires `--parachain-type child|sibling` (no implicit default — picking the wrong one silently produces a different address).
  1501. - `--parachain` and `--pallet-id` are mutually exclusive.
  1502. - A positional address (`dot account add foo <ss58>`) cannot be combined with derivation flags.
  1503. - Derivation flags cannot be combined with `--secret` or `--env` — a derived sovereign has no signing key.
  1504. #### Legacy `dot parachain` command (deprecated)
  1505. The standalone `dot parachain <paraId>` command from earlier releases is **still available for backward compatibility** and now prints a deprecation warning to stderr. Stdout output is unchanged, so existing pipes (e.g. `dot parachain 1000 --json | jq`) keep working. Migrate to `dot account inspect --parachain <id> --parachain-type <child|sibling>` at your convenience — it will be removed in a future release ([#208](https://github.com/paritytech/polkadot-cli/issues/208)).
  1506. ```bash
  1507. # Old (deprecated, still works — emits stderr warning)
  1508. dot parachain 1000 --type child --json
  1509. # New
  1510. dot account inspect --parachain 1000 --parachain-type child --json
  1511. ```
  1512. ### Bandersnatch / verifiable (member keys, ring-VRF proofs, signing)
  1513. `dot verifiable` is a set of composable, unopinionated primitives over the
  1514. [`verifiablejs`](https://github.com/paritytech/verifiablejs) WASM library: derive
  1515. member keys, sign, generate and verify ring-VRF proofs, and encode member sets.
  1516. Every action is bytes-in, bytes-out — it takes hex / `--file` / `--stdin` input
  1517. and supports `--output json`, so it pipes together and composes with any data
  1518. (for example values you fetched on-chain with `dot` beforehand). It makes no
  1519. assumptions and does no fetching or selection of its own.
  1520. #### Two concepts you must not conflate
  1521. ```
  1522. Mnemonic ─BIP39─▶ entropy ─keyed blake2b─▶ member entropy ─▶ member key / secret
  1523. (key = --entropy-key) │
  1524. ring proof: one_shot(…, --context, --message)
  1525. ```
  1526. - **`--entropy-key <text|0xhex>`** — the key mixed into the keyed-blake2b that
  1527. turns your mnemonic into the Bandersnatch member entropy. **Omit** it for a
  1528. **lite** person (unkeyed); use **`candidate`** for a **full** person. It must
  1529. match the key used when the member was recognised on-chain, or you derive a
  1530. different (unrecognised) member key. It is **not** an sr25519 derivation path

Lines 2,001–2,421 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.