polkadot-cli 1.19.0 → 1.21.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
@@ -280,6 +281,10 @@ dot account create my-staking --path //staking
 # Add a keyed account from a BIP39 mnemonic
 dot account add treasury --secret "word1 word2 ... word12"
 
+# Add from a 32-byte hex seed or a 64-byte raw sr25519 private key
+dot account add seeded --secret 0x1111111111111111111111111111111111111111111111111111111111111111
+dot account add raw-key --secret 0x<128-hex-char expanded secret>   # no --path
+
 # Add with a derivation path
 dot account add hot-wallet --secret "word1 word2 ... word12" --path //hot
 
@@ -313,6 +318,7 @@ dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 dot account inspect 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
 dot account inspect alice --prefix 0         # Polkadot mainnet prefix
 dot account inspect alice --json             # JSON output
+dot account inspect dave --show-secret       # reveal mnemonic + sr25519 private key
 ```
 
 #### Watch-only accounts
@@ -484,16 +490,21 @@ dot account inspect --pallet-id py/trsry --json
 
 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).
 
-#### Reveal the sr25519 private key
+#### Reveal the mnemonic and sr25519 private key
 
-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:
+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:
 
 ```bash
-dot account inspect dave --show-secret
-# Private Key: 0x<128 hex chars>   (sr25519 expanded, 64 bytes — never share)
+dot account inspect my-validator --show-secret
+# Mnemonic:    word1 word2 ... word12   (only for accounts stored as a phrase)
+# Private Key: 0x<128 hex chars>        (sr25519 expanded, 64 bytes — never share)
 ```
 
-Works for dev accounts (derived on-the-fly from the standard dev mnemonic) and for stored accounts that have a secret (mnemonic or hex seed). Refuses on watch-only accounts, bare SS58 addresses, or hex public keys. The hex 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 it under the `privateKey` field.
+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.
+
+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).
+
+> **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.
 
 #### Env-var-backed accounts
 
@@ -540,12 +551,29 @@ Signers
 
 **Supported secret formats for import:**
 
-| Format | Example | Status |
-|--------|---------|--------|
-| BIP39 mnemonic (12/24 words) | `"abandon abandon ... about"` | Supported |
-| Hex seed (`0x` + 64 hex chars) | `0xabcdef0123...` | Not supported via CLI (see below) |
+| Format | Example | `--path`? |
+|--------|---------|-----------|
+| BIP39 mnemonic (12/24 words) | `"abandon abandon ... about"` | Yes |
+| Hex seed (`0x` + 64 hex chars = 32 bytes) | `0x1111...1111` | Yes |
+| Raw private key (`0x` + 128 hex chars = 64-byte sr25519 expanded secret) | `0x20e0...5568` | No (cannot be HD-derived) |
+
+All three formats work directly from the command line via `--secret` or via `--env`.
+
+#### Import a raw private key
+
+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):
 
-**Known limitation:** Hex seed import (`--secret 0x...`) does not work from the command line. The CLI argument parser (`cac`) interprets `0x`-prefixed values as JavaScript numbers, which loses precision for 32-byte seeds. Use a BIP39 mnemonic instead. If you need to import a raw seed programmatically, write it directly to `~/.polkadot/accounts.json`.
+```bash
+# Round-trip: reveal dave's expanded secret, then import it under a new name
+SECRET=$(dot account inspect dave --show-secret --json | jq -r .privateKey)
+dot account add raw-dave --secret "$SECRET"
+# raw-dave now has the same address as dave and can sign
+
+# Or from an environment variable (secret stays off disk)
+dot account add server-signer --env PROXY_PRIVATE_KEY
+```
+
+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.
 
 #### Export/import accounts
 
@@ -1860,48 +1888,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)
+```
+
+- **`--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.
 
-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.
+#### Member keys
 
 ```bash
-# Derive unkeyed member key (lite person)
+# Lite person (unkeyed)
 dot verifiable alice
-# Output:
-# Bandersnatch Member Key
-#
 #   Account:    alice
-#   Member Key: 0x66813b70ba616b374c90ac92edff6e3be95e12adbc93ea7a6c37cbf334ab87e2
+#   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: 0x2fd5b74033d904cf5575b932507939c5d43811e488223229eaf5596565f15ae6
+# 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
 
@@ -2084,13 +2153,52 @@ 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_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