polkadot-cli 1.11.0 → 1.13.0

package/README.md

@@ -15,31 +15,34 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 - ✅ Exposes all on-chain metadata documentation
 - ✅ Encode, dry-run, and submit extrinsics
 - ✅ Support for custom signed extensions
-- ✅ Built with agent use in mind — pipe-safe JSON output (`--output json`)
+- ✅ Built with agent use in mind — structured JSON output on every command (`--json`)
 - ✅ Fuzzy matching with typo suggestions
 - ✅ Account management — BIP39 mnemonics, derivation paths, env-backed secrets, watch-only, dev accounts
 - ✅ Named address resolution across all commands
 - ✅ Runtime API calls — `dot apis.Core.version`
+- ✅ Chain topology — relay/parachain hierarchy with tree display and auto-detection
 - ✅ Batteries included — all system parachains and testnets already setup to be used
 - ✅ File-based commands — run any command from a YAML/JSON file with variable substitution
 - ✅ Parachain sovereign accounts — derive child and sibling addresses from a parachain ID
+- ✅ Message signing — sign arbitrary bytes with account keypairs for use as `MultiSignature` arguments
+- ✅ Bandersnatch member keys — derive Ring VRF member keys from mnemonics for on-chain member sets
 
 ### Preconfigured chains
 
-| Network | Chain | Light client |
-|---------|-------|:---:|
-| Polkadot | `polkadot` (relay, default) | yes |
-| | `polkadot-asset-hub` | yes |
-| | `polkadot-bridge-hub` | yes |
-| | `polkadot-collectives` | yes |
-| | `polkadot-coretime` | yes |
-| | `polkadot-people` | yes |
-| Paseo (testnet) | `paseo` (relay) | yes |
-| | `paseo-asset-hub` | yes |
-| | `paseo-bridge-hub` | — |
-| | `paseo-collectives` | — |
-| | `paseo-coretime` | yes |
-| | `paseo-people` | yes |
+| Network | Chain |
+|---------|-------|
+| Polkadot | `polkadot` (relay, default) |
+| | `polkadot-asset-hub` |
+| | `polkadot-bridge-hub` |
+| | `polkadot-collectives` |
+| | `polkadot-coretime` |
+| | `polkadot-people` |
+| Paseo (testnet) | `paseo` (relay) |
+| | `paseo-asset-hub` |
+| | `paseo-bridge-hub` |
+| | `paseo-collectives` |
+| | `paseo-coretime` |
+| | `paseo-people` |
 
 Each chain ships with multiple RPC endpoints from decentralized infrastructure providers (IBP, Dotters, Dwellir, and others). The CLI automatically falls back to the next endpoint if the primary is unreachable.
 
@@ -66,10 +69,13 @@ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
 # Add a chain with fallback RPCs (repeat --rpc for each endpoint)
 dot chain add kusama --rpc wss://kusama-rpc.polkadot.io --rpc wss://kusama-rpc.dwellir.com
 
-# Add a chain via light client
-dot chain add westend --light-client
+# Add a parachain under a relay (auto-detects parachain ID)
+dot chain add local-asset-hub --rpc ws://localhost:9945 --relay local-relay
 
-# List configured chains
+# Add a parachain with explicit parachain ID
+dot chain add my-para --rpc wss://rpc.example.com --relay polkadot --parachain-id 2000
+
+# List configured chains (shows relay/parachain hierarchy)
 dot chain list
 
 # Re-fetch metadata after a runtime upgrade
@@ -84,6 +90,31 @@ dot chain default kusama
 dot chain remove westend
 ```
 
+#### Chain topology
+
+`dot chain list` displays chains as a tree, grouping parachains under their parent relay:
+
+```
+Configured Chains
+
+  polkadot (default)  wss://polkadot.ibp.network
+  ├─ polkadot-asset-hub [1000]  wss://...
+  ├─ polkadot-bridge-hub [1002]  wss://...
+  ├─ polkadot-collectives [1001]  wss://...
+  ├─ polkadot-coretime [1005]  wss://...
+  └─ polkadot-people [1004]  wss://...
+
+  paseo  wss://paseo.ibp.network
+  ├─ paseo-asset-hub [1000]  wss://...
+  └─ paseo-people [1004]  wss://...
+
+  my-solo-chain  wss://...
+```
+
+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.
+
+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.
+
 ### Manage accounts
 
 Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
@@ -133,7 +164,7 @@ dot account alice                    # shorthand (same as inspect)
 dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 dot account inspect 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
 dot account inspect alice --prefix 0         # Polkadot mainnet prefix
-dot account inspect alice --output json      # JSON output
+dot account inspect alice --json             # JSON output
 ```
 
 #### Watch-only accounts
@@ -164,7 +195,18 @@ dot query System.Account treasury
 dot tx Balances.transferKeepAlive bob 1000000000000 --from alice
 ```
 
-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 available account names.
+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:
+
+```
+Error: Unknown account or address "people-sudo-signer".
+  Did you mean: people-paseo-sudo?
+  Available accounts:
+    - alice
+    - bob
+    - charlie
+    - people-paseo-sudo
+    - ...
+```
 
 #### Inspect accounts
 
@@ -193,7 +235,7 @@ dot account inspect alice --prefix 2     # Kusama (prefix 2)
 JSON output:
 
 ```bash
-dot account inspect alice --output json
+dot account inspect alice --json
 # {"publicKey":"0xd435...a27d","ss58":"5Grw...utQY","prefix":42,"name":"Alice"}
 ```
 
@@ -296,15 +338,15 @@ dot query System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 # Map without key — shows help/usage (use --dump to fetch all entries)
 dot query System.Account
 
-# Dump all map entries (requires --dump, default limit: 100)
-dot query System.Account --dump --limit 10
+# Dump all map entries (requires --dump)
+dot query System.Account --dump
 
 # Enum variant as map key (case-insensitive)
 dot query people-preview.ChunksManager.Chunks R2e9 1
 
 # Pipe-safe — stdout is clean data, progress messages go to stderr
-dot query System.Account --dump --limit 5 | jq '.[0].value.data.free'
-dot query System.Number --output json | jq '.+1'
+dot query System.Account --dump | jq '.[0].value.data.free'
+dot query System.Number --json | jq '.+1'
 
 # Query a specific chain using chain prefix
 dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
@@ -324,12 +366,9 @@ dot query Staking.ErasStakers 100 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKut
 dot query Staking.ErasStakers 100
 
 # No keys — requires --dump (safety net for large maps)
-dot query Staking.ErasStakers --dump --limit 10
+dot query Staking.ErasStakers --dump
 ```
 
-The `--limit` option applies to partial key results just like it does for
-`--dump` (default: 100, use `--limit 0` for unlimited).
-
 #### Output formatting
 
 Query results automatically convert on-chain types for readability:
@@ -352,7 +391,7 @@ dot const System.SS58Prefix --chain kusama
 dot const kusama.Balances.ExistentialDeposit
 
 # Pipe-safe — stdout is clean JSON, progress messages go to stderr
-dot const Balances.ExistentialDeposit --output json | jq
+dot const Balances.ExistentialDeposit --json | jq
 ```
 
 ### Inspect metadata
@@ -526,21 +565,21 @@ Decode a hex-encoded call into a YAML or JSON file that is compatible with [file
 
 ```bash
 # Decode a raw hex call to YAML
-dot tx.0x0001076465616462656566 --yaml
+dot tx.0x0001076465616462656566 --to-yaml
 
 # Decode a raw hex call to JSON
-dot tx.0x0001076465616462656566 --json
+dot tx.0x0001076465616462656566 --to-json
 
 # Encode a named call and output as YAML
-dot tx.System.remark 0xdeadbeef --yaml
+dot tx.System.remark 0xdeadbeef --to-yaml
 
 # Round-trip: encode to hex, decode to YAML, re-encode from file
-dot tx.System.remark 0xdeadbeef --encode           # 0x0001076465616462656566
-dot tx.0x0001076465616462656566 --yaml > remark.yaml
-dot ./remark.yaml --encode                          # same hex
+dot tx.System.remark 0xdeadbeef --encode              # 0x0001076465616462656566
+dot tx.0x0001076465616462656566 --to-yaml > remark.yaml
+dot ./remark.yaml --encode                             # same hex
 ```
 
-`--yaml` / `--json` are mutually exclusive with each other and with `--encode` and `--dry-run`.
+`--to-yaml` / `--to-json` are mutually exclusive with each other and with `--encode` and `--dry-run`.
 
 Both dry-run and submission display the encoded call hex and a decoded human-readable form:
 
@@ -628,7 +667,7 @@ Override low-level transaction parameters. Useful for rapid-fire submission (cus
 | `--nonce <n>` | non-negative integer | Override the auto-detected nonce |
 | `--tip <amount>` | non-negative integer (planck) | Priority tip for the transaction pool |
 | `--mortality <spec>` | `immortal` or period (min 4) | Transaction mortality window |
-| `--at <block>` | `best`, `finalized`, or 0x-prefixed block hash | Block state to validate against |
+| `--at <block>` | 0x-prefixed block hash | Block hash to validate against (defaults to finalized) |
 
 ```bash
 # Fire-and-forget: submit two txs in rapid succession with manual nonces
@@ -644,14 +683,14 @@ dot tx System.remark 0xdead --from alice --mortality immortal
 # Set a custom mortality period (rounds up to nearest power of two)
 dot tx System.remark 0xdead --from alice --mortality 128
 
-# Validate against the best (not finalized) block
-dot tx System.remark 0xdead --from alice --at best
+# Validate against a specific block hash
+dot tx System.remark 0xdead --from alice --at 0x1234...abcd
 
 # Combine: rapid-fire with tip and broadcast-only
 dot tx System.remark 0xdead --from alice --nonce 5 --tip 500000 --wait broadcast
 ```
 
-When set, nonce / tip / mortality / at are shown in both `--dry-run` and submission output. These flags are silently ignored with `--encode`, `--yaml`, and `--json` (which return before signing).
+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).
 
 ### File-based commands
 
@@ -838,7 +877,7 @@ CALL=$(dot tx.System.remark 0xdead --encode)
 dot ./xcm-transact.yaml --var CALL=$CALL --encode
 ```
 
-All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--yaml`, `--json`, `--output`, etc. behave identically to inline commands.
+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.
 
 ### Compute hashes
 
@@ -858,11 +897,36 @@ dot hash keccak256 --file ./data.bin
 echo -n "hello" | dot hash sha256 --stdin
 
 # JSON output
-dot hash blake2b256 0xdeadbeef --output json
+dot hash blake2b256 0xdeadbeef --json
 ```
 
 Run `dot hash` with no arguments to see all available algorithms.
 
+### Sign messages
+
+Sign arbitrary messages with an account keypair. Output is a `Sr25519(0x...)` value directly usable as a `MultiSignature` enum argument in transaction calls.
+
+```bash
+# Sign a text message
+dot sign "hello world" --from alice
+
+# Sign hex-encoded bytes
+dot sign 0xdeadbeef --from alice
+
+# Sign file contents
+dot sign --file ./payload.bin --from alice
+
+# Read from stdin
+echo -n "hello" | dot sign --stdin --from alice
+
+# JSON output (for scripting)
+dot sign "hello" --from alice --json
+```
+
+Output shows the crypto type, message bytes in hex, raw signature, and an `Enum` value directly pasteable into tx arguments (e.g. `Sr25519(0x...)`).
+
+Use `--type` to select the signature algorithm (default: `sr25519`). Run `dot sign` with no arguments to see usage and examples.
+
 ### Parachain sovereign accounts
 
 Derive the sovereign account addresses for a parachain. These are deterministic accounts derived from a parachain ID — no chain connection required.
@@ -884,11 +948,43 @@ dot parachain 2004 --type sibling
 dot parachain 1000 --prefix 0
 
 # JSON output
-dot parachain 1000 --output json
+dot parachain 1000 --json
 ```
 
 Run `dot parachain` with no arguments to see usage and examples.
 
+### Bandersnatch member keys
+
+Derive Bandersnatch member keys from account mnemonics for on-chain member set registration (personhood proofs, Ring VRF). Uses the [`verifiablejs`](https://github.com/paritytech/verifiablejs) WASM library.
+
+```bash
+# Derive unkeyed member key (lite person)
+dot verifiable alice
+
+# Derive keyed member key (full person — "candidate" context)
+dot verifiable alice --context candidate
+
+# Arbitrary context string
+dot verifiable alice --context pps
+
+# JSON output (for scripting)
+dot verifiable alice --context candidate --json
+```
+
+The derivation flow:
+
+```
+Mnemonic → mnemonicToEntropy() → blake2b256(entropy, context?) → member_from_entropy() → 32-byte member key
+```
+
+- **Unkeyed** (no `--context`): `blake2b256(entropy)` — used for lite person registration
+- **With context** (e.g. `--context candidate`): `blake2b256(entropy, key="candidate")` — used for full person registration. The `--context` value is passed as the raw UTF-8 bytes of the blake2b key parameter.
+- Both 12-word and 24-word mnemonics are supported
+
+Derived keys are saved to the account store. For stored accounts, saved keys appear in `dot account inspect` output. When creating a new account with `dot account create`, both unkeyed and `candidate` keys are automatically derived and saved.
+
+Run `dot verifiable` with no arguments to see usage and the full derivation diagram.
+
 ### Getting help
 
 Every command supports `--help` to show its detailed usage, available actions, and examples:
@@ -926,19 +1022,46 @@ dot tx.System.remark 0xdead               # shows call help (no error)
 | `--help` | Show help (global or command-specific) |
 | `--chain <name>` | Target chain (default from config) |
 | `--rpc <url>` | Override RPC endpoint(s) for this call (repeat for fallback) |
-| `--light-client` | Use Smoldot light client |
-| `--output json` | Raw JSON output (default: pretty) |
+
+| `--json` | Structured JSON output (shorthand for `--output json`) |
+| `--output json` | Structured JSON output |
 | `--dump` | Dump all entries of a storage map (required for keyless map queries) |
-| `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
 | `-w, --wait <level>` | Tx wait level: `broadcast`, `best-block` / `best`, `finalized` (default) |
 
+### Structured JSON output
+
+Every command supports `--json` for machine-readable output. This works on data queries, metadata inspection, account management, chain configuration, and transaction submission:
+
+```bash
+dot inspect --json                          # All pallets as JSON
+dot inspect Balances --json                 # Pallet detail with storage, constants, calls, events, errors
+dot chain list --json                       # Configured chains
+dot account list --json                     # Dev and stored accounts
+dot account create my-key --json            # New account details (mnemonic warning on stderr)
+dot tx.System.remark 0xdead --encode --json # Encoded call hex wrapped in JSON
+dot events.Balances --json                  # Event listing with field signatures
+dot const.System --json                     # Constant listing with types
+```
+
+For transaction submission, `--json` emits NDJSON (one JSON object per lifecycle event):
+
+```bash
+dot tx.System.remark 0xdead --from alice --json
+# {"event":"signed","txHash":"0x..."}
+# {"event":"broadcasted","txHash":"0x..."}
+# {"event":"finalized","blockNumber":123,"blockHash":"0x...","ok":true,"events":[...]}
+```
+
 ### Pipe-safe output
 
-All commands follow Unix conventions: **data goes to stdout, progress goes to stderr**. This means you can safely pipe `--output json` into `jq` or other tools without progress messages ("Fetching metadata...", spinner output, "Connecting...") corrupting the data stream:
+All commands follow Unix conventions: **data goes to stdout, progress goes to stderr**. This means you can safely pipe `--json` into `jq` or other tools without progress messages ("Fetching metadata...", spinner output, "Connecting...") corrupting the data stream:
 
 ```bash
-dot const System.SS58Prefix --output json | jq '.+1'
-dot query System.Number --output json | jq
+dot const System.SS58Prefix --json | jq '.+1'
+dot query System.Number --json | jq
+dot chain list --json | jq '.chains[].name'
+dot account list --json | jq '.stored[].address'
+dot inspect --json | jq '.pallets[] | select(.events > 10) | .name'
 ```
 
 In an interactive terminal, both streams render together so you see progress and results normally.
@@ -1030,7 +1153,7 @@ Config and metadata caches live in `~/.polkadot/`:
 
 ## Environment compatibility
 
-The CLI works in Node.js, Bun, and sandboxed runtimes (e.g. LLM tool-use / MCP environments) that lack a native `globalThis.WebSocket`. WebSocket connections use the [`ws`](https://github.com/websockets/ws) package explicitly, so no global polyfill is required.
+The CLI works in Node.js (v22+), Bun, and sandboxed runtimes (e.g. LLM tool-use / MCP environments). WebSocket connections use the native `WebSocket` implementation provided by the runtime — no external WebSocket package is required.
 
 ## Development