polkadot-cli 1.20.0 → 1.22.0

package/README.md

@@ -18,6 +18,7 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 - ✅ 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
+- ✅ Local workspaces — `dot init` creates a `.polkadot/` in any directory, auto-discovered git-style and fully isolated from your global `~/.polkadot`
 - ✅ Named address resolution across all commands
 - ✅ Runtime API calls — `dot polkadot.apis.Core.version`
 - ✅ Raw JSON-RPC calls — `dot polkadot.rpc.system_health`, with discovery via `rpc_methods` and tab-completion
@@ -96,7 +97,8 @@ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
 dot chain add kusama --rpc wss://kusama-rpc.polkadot.io --rpc wss://kusama-rpc.dwellir.com
 
 # Add a parachain under a relay (auto-detects parachain ID)
-dot chain add local-asset-hub --rpc ws://localhost:9945 --relay local-relay
+# Name parachains `{relay}-{parachain}` — see "Naming convention" below
+dot chain add local-relay-asset-hub --rpc ws://localhost:9945 --relay local-relay
 
 # Add a parachain with explicit parachain ID
 dot chain add my-para --rpc wss://rpc.example.com --relay polkadot --parachain-id 2000
@@ -118,6 +120,24 @@ dot chain update --all      # updates all configured chains in parallel
 dot chain remove kusama
 ```
 
+#### Naming convention
+
+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.
+
+| Chain kind | Recommended name | Examples |
+|------------|------------------|----------|
+| Relay chain | `{relay}` | `polkadot`, `kusama`, `paseo` |
+| Parachain | `{relay}-{parachain}` | `polkadot-asset-hub`, `kusama-bridge-hub`, `paseo-people` |
+
+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.
+
+```bash
+# Recommended — relay-prefixed name
+dot chain add kusama-asset-hub --rpc wss://asset-hub-kusama-rpc.polkadot.io --relay kusama --parachain-id 1000
+```
+
+Use lowercase, hyphen-separated names (chain names resolve case-insensitively).
+
 #### Chain topology
 
 `dot chain list` displays chains as a tree, grouping parachains under their parent relay:
@@ -296,9 +316,10 @@ dot account derive treasury treasury-staking --path //staking
 # Use it — the env var is read at signing time
 MY_SECRET="word1 word2 ..." dot polkadot.tx.System.remark 0xdead --from ci-signer
 
-# Remove one or more accounts
+# Remove one or more accounts (delete and rm are aliases for remove)
 dot account remove my-validator
 dot account delete my-validator stale-key
+dot account rm my-validator stale-key
 
 # Export accounts (secrets redacted by default)
 dot account export
@@ -1199,6 +1220,13 @@ dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000000 --from alice --dr
 # Submit (omit --dry-run)
 dot polkadot.tx.System.remark 0xdeadbeef --from alice
 
+# Force every tx to dry-run via the global DOT_DRY_RUN env var — a safety net
+# for scripts and demos. A hint is printed to stderr; the command behaves
+# exactly as if --dry-run had been passed.
+DOT_DRY_RUN=1 dot polkadot.tx.System.remark 0xdeadbeef --from alice
+# stderr: ⚠ DOT_DRY_RUN is set — extrinsics will be simulated, not submitted.
+# stdout: (the dry-run output above — no broadcast)
+
 # Submit a raw SCALE-encoded call (e.g. from a multisig proposal or another tool)
 dot polkadot.tx 0x000010deadbeef --from alice --dry-run
 
@@ -1887,48 +1915,89 @@ dot parachain 1000 --type child --json
 dot account inspect --parachain 1000 --parachain-type child --json
 ```
 
-### Bandersnatch member keys
+### Bandersnatch / verifiable (member keys, ring-VRF proofs, signing)
+
+`dot verifiable` is a set of composable, unopinionated primitives over the
+[`verifiablejs`](https://github.com/paritytech/verifiablejs) WASM library: derive
+member keys, sign, generate and verify ring-VRF proofs, and encode member sets.
+Every action is bytes-in, bytes-out — it takes hex / `--file` / `--stdin` input
+and supports `--output json`, so it pipes together and composes with any data
+(for example values you fetched on-chain with `dot` beforehand). It makes no
+assumptions and does no fetching or selection of its own.
+
+#### Two concepts you must not conflate
+
+```
+Mnemonic ─BIP39─▶ entropy ─keyed blake2b─▶ member entropy ─▶ member key / secret
+                           (key = --entropy-key)                  │
+                                       ring proof: one_shot(…, --context, --message)
+```
 
-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.
+- **`--entropy-key <text|0xhex>`** — the key mixed into the keyed-blake2b that
+  turns your mnemonic into the Bandersnatch member entropy. **Omit** it for a
+  **lite** person (unkeyed); use **`candidate`** for a **full** person. It must
+  match the key used when the member was recognised on-chain, or you derive a
+  different (unrecognised) member key. It is **not** an sr25519 derivation path
+  and **not** the ring `--context`. (The value is the raw UTF-8 — or hex — bytes
+  of the blake2b key; this matches the iOS/Android clients, which key the
+  "full person" deriver with `"candidate"`.)
+- **`--context <text|0xhex>`** — the **32-byte ring/proof namespace** (e.g.
+  `"dotns"`), zero-padded right to 32 bytes like Solidity `bytes32()`. It
+  determines the alias and is named `context` across the runtime
+  (`type Context = [u8;32]`), the iOS client, and verifiablejs. Used by
+  `alias` / `prove` / `verify`.
+
+> **Migration (breaking):** previously `dot verifiable <account> --context
+> candidate` used `--context` as the entropy-derivation key. That key is now
+> `--entropy-key`, and `--context` means the ring context. For one release the
+> old form still works on the member command (with a deprecation warning); use
+> `--entropy-key` going forward.
+
+#### Member keys
 
 ```bash
-# Derive unkeyed member key (lite person)
+# Lite person (unkeyed)
 dot verifiable alice
-# Output:
-# Bandersnatch Member Key
-#
 #   Account:    alice
 #   Member Key: 0xbb6ee099b568f1844d62fc00e6305c2e83aa8da30ce59e664ef39e089204d43c
 
-# Derive keyed member key (full person — "candidate" context)
-dot verifiable alice --context candidate
-# Output:
-# Bandersnatch Member Key
-#
-#   Account:    alice
-#   Context:    candidate
-#   Member Key: 0x5f915576987547d3e55bb4129ac8cae1d338f8933073dc74272b4c825f738592
+# Full person (candidate-keyed)
+dot verifiable alice --entropy-key candidate
+#   Account:     alice
+#   Entropy Key: candidate
+#   Member Key:  0x5f915576987547d3e55bb4129ac8cae1d338f8933073dc74272b4c825f738592
+```
 
-# Arbitrary context string
-dot verifiable alice --context pps
+Derived keys are saved to the account store and shown in `dot account inspect`.
 
-# JSON output (for scripting)
-dot verifiable alice --context candidate --json
-```
+#### Alias, sign, prove, verify
 
-The derivation flow:
+```bash
+# Alias for a ring context (deterministic in entropy + context)
+dot verifiable alias alice --entropy-key candidate --context dotns
 
-```
-Mnemonic → mnemonicToEntropy() → blake2b256(entropy, context?) → member_from_entropy() → 32-byte member key
-```
+# Standalone Bandersnatch signature (64 bytes)
+dot verifiable sign alice --message "hello" --entropy-key candidate
+dot verifiable verify-sig --signature 0x… --member 0x… --message "hello"
 
-- **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
+# Ring-VRF proof over a members set, then verify it locally
+dot verifiable members 0x<key> 0x<key> --output json        # SCALE-encode the ring
+dot verifiable prove alice --entropy-key candidate --context dotns \
+    --message 0x… --members 0x… --output json
+dot verifiable verify --proof 0x… --context dotns --message 0x… --members 0x…
+# verify exits non-zero if the proof does not validate
+```
 
-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.
+`dot verifiable` is deliberately scoped to **raw verifiable crypto** — bytes in,
+bytes out, with no knowledge of Polkadot chains, pallets, or collections (the
+same way `dot sign` is just sr25519). It does no automated fetching or selection
+and assumes nothing about how the bytes were produced or where they go: supply
+the members/context/message yourself (e.g. read from chain with `dot` first), and
+use the resulting signature or proof however you need — as a value in a `dot`
+extrinsic or signed extension, or anywhere else.
 
-Run `dot verifiable` with no arguments to see usage and the full derivation diagram.
+Run `dot verifiable` with no arguments for the full action/option list and the
+derivation diagram. Both 12- and 24-word mnemonics are supported.
 
 ### Getting help
 
@@ -2111,13 +2180,70 @@ Config and metadata caches live in `~/.polkadot/` by default:
 
 > **Warning:** `accounts.json` stores secrets (mnemonics and seeds) in **plain text**. Encrypted-at-rest storage is planned but not yet implemented. Keep appropriate file permissions (`chmod 600 ~/.polkadot/accounts.json`) and do not use this for high-value mainnet accounts.
 
+### Local workspaces — `dot init`
+
+Create a self-contained, per-directory setup for chains and accounts. A workspace is just a `.polkadot/` directory that `dot` discovers automatically:
+
+```bash
+mkdir -p ~/dot/paseo && cd ~/dot/paseo
+dot init
+# Initialized empty dot workspace at /Users/you/dot/paseo/.polkadot
+# Check which workspace is active with: dot which
+```
+
+From this directory (and any subdirectory), every `dot` command reads and writes **all** state — accounts, custom chains, metadata cache — under `./.polkadot/` instead of `~/.polkadot/`:
+
+```bash
+dot account create sudo                          # stored in ./.polkadot/accounts.json
+dot chain add mytestnet --rpc ws://localhost:9944
+dot which
+# /Users/you/dot/paseo/.polkadot
+# Source: local workspace (discovered from current directory)
+```
+
+**Discovery** is git-style: `dot` looks for a `.polkadot/` directory in the current directory, then in each parent, stopping at `$HOME` or the filesystem root. The nearest workspace wins. The global `~/.polkadot` is never treated as a workspace — it is only ever the fallback.
+
+**Precedence:** `DOT_HOME` env var → discovered local workspace → global `~/.polkadot`.
+
+**Full isolation:** while a workspace is active, the global config is invisible. An account named `sudo` in `~/dot/paseo` and one in `~/dot/mytestnet` are unrelated identities — lookups never fall back to the global config, and resolution errors name the config root that was searched, so running in the wrong directory self-diagnoses. Built-in chains (Polkadot, Paseo, and the system parachains) still work everywhere; they ship with the binary.
+
+`dot init` is deliberately minimal: it creates an empty `.polkadot/` directory and nothing else. It refuses to run in `$HOME`, errors if the directory already has a workspace, and warns when the new workspace shadows a parent workspace or when a set `DOT_HOME` masks discovery. Nothing is copied from the global config, and no `.gitignore` is written — whether to commit or ignore a workspace (remember: `accounts.json` holds plain-text secrets) is your decision to make.
+
+**Throwaway sessions** are just disposable workspaces:
+
+```bash
+tmp=$(mktemp -d) && cd "$tmp" && dot init
+# ... add throwaway accounts and chains, run txs ...
+cd - && rm -rf "$tmp"        # nothing ever touched ~/.polkadot
+```
+
+For secrets that should never hit disk at all, combine workspaces with `--env` secret sources (see [Manage accounts](#manage-accounts)).
+
+### `DOT_DRY_RUN` — force every extrinsic to dry-run
+
+Set `DOT_DRY_RUN` to a truthy value (`1`, `true`, `yes`, or `on`, case-insensitive) to make **every** extrinsic-submitting command behave as if `--dry-run` had been passed: the transaction is simulated (call decoded, fees estimated) and **never broadcast**. This is a global safety net for scripts, demos, and CI dry-runs where you want to be sure nothing lands on-chain.
+
+When active, the CLI prints a one-line hint to **stderr** (so it never corrupts `--json` or piped stdout):
+
+```bash
+DOT_DRY_RUN=1 dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000000 --from alice
+# stderr: ⚠ DOT_DRY_RUN is set — extrinsics will be simulated, not submitted.
+# stdout: the usual dry-run report (Chain / From / Call / Decode / Estimated fees)
+
+# Set it for a whole shell session as a safety net:
+export DOT_DRY_RUN=1
+dot polkadot.tx.System.remark 0xdeadbeef --from alice   # simulated, not submitted
+```
+
+**Precedence:** an explicit per-command flag always wins. `--dry-run` forces a dry-run; `--no-dry-run` forces a real submission even when `DOT_DRY_RUN` is set. The env var only supplies the default when no flag is given. Decode-only paths (`--encode`, `--to-yaml`, `--to-json`) never submit anything, so `DOT_DRY_RUN` leaves them untouched.
+
 ### `DOT_TRUST_CACHED_METADATA` — skip the staleness check
 
 Set `DOT_TRUST_CACHED_METADATA=1` to disable the post-failure stale-metadata check on `dot tx`, `dot tx --dry-run`, and `dot query`. When set, errors propagate exactly as the runtime / RPC reported them, with no extra `state_getRuntimeVersion` / `state_getStorageHash` round-trip. Useful in CI loops where you've just refreshed metadata manually and don't want the overhead.
 
 ### `DOT_HOME` — redirect the config directory
 
-Set the `DOT_HOME` environment variable to point at a different directory. When set, the CLI reads and writes **everything** (config, accounts, metadata, update cache) under that path — no `.polkadot` suffix is appended.
+Set the `DOT_HOME` environment variable to point at a different directory. When set, the CLI reads and writes **everything** (config, accounts, metadata, update cache) under that path — no `.polkadot` suffix is appended. `DOT_HOME` takes precedence over both [local workspace discovery](#local-workspaces--dot-init) and the global `~/.polkadot`.
 
 ```bash
 # Use a scratch directory for experimentation