polkadot-cli 1.13.0 → 1.14.1

package/README.md

@@ -25,13 +25,16 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 - ✅ 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
+- ✅ Unsigned/authorized transactions — submit governance-authorized calls without a signer (`--unsigned`)
+- ✅ Non-native fee payment — pay tx fees in any asset the chain accepts via `--asset` (asset-hub-style chains)
 - ✅ Bandersnatch member keys — derive Ring VRF member keys from mnemonics for on-chain member sets
+- ✅ Export/import — portable chain and account configuration for backup, sharing, and CI bootstrapping
 
 ### Preconfigured chains
 
 | Network | Chain |
 |---------|-------|
-| Polkadot | `polkadot` (relay, default) |
+| Polkadot | `polkadot` (relay) |
 | | `polkadot-asset-hub` |
 | | `polkadot-bridge-hub` |
 | | `polkadot-collectives` |
@@ -79,13 +82,9 @@ dot chain add my-para --rpc wss://rpc.example.com --relay polkadot --parachain-i
 dot chain list
 
 # Re-fetch metadata after a runtime upgrade
-dot chain update          # updates default chain
 dot chain update kusama   # updates a specific chain
 dot chain update --all    # updates all configured chains in parallel
 
-# Set default chain
-dot chain default kusama
-
 # Remove a chain
 dot chain remove westend
 ```
@@ -97,7 +96,7 @@ dot chain remove westend
 ```
 Configured Chains
 
-  polkadot (default)  wss://polkadot.ibp.network
+  polkadot  wss://polkadot.ibp.network
   ├─ polkadot-asset-hub [1000]  wss://...
   ├─ polkadot-bridge-hub [1002]  wss://...
   ├─ polkadot-collectives [1001]  wss://...
@@ -115,6 +114,55 @@ All built-in system parachains are preconfigured with their relay chain and para
 
 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.
 
+#### Selecting a chain
+
+Every chain-consuming command must specify a chain explicitly — either with the global `--chain <name>` flag or with a dotpath chain prefix. There is no hidden default; running a command without a chain errors out with a message listing the configured chains.
+
+```bash
+# Via --chain flag
+dot query.System.Number --chain polkadot
+
+# Via dotpath chain prefix
+dot polkadot.query.System.Number
+
+# Both at once errors
+dot polkadot.query.System.Number --chain polkadot  # ✗ errors
+```
+
+Chain names are case-insensitive. The prefix form also works with the space-separated syntax (`dot query polkadot.System.Account ...`).
+
+#### Export/import chain configuration
+
+Export and import chain configurations for backup, sharing across machines, or team collaboration. Metadata is not included — re-fetch with `dot chain update --all` after importing.
+
+```bash
+# Export custom chains to stdout (pipe-friendly JSON)
+dot chain export
+
+# Export all chains including built-ins
+dot chain export --all
+
+# Export specific chains
+dot chain export my-relay my-para
+
+# Export to a file
+dot chain export --all --file my-chains.json
+
+# Import from a file
+dot chain import my-chains.json
+
+# Preview without applying
+dot chain import my-chains.json --dry-run
+
+# Overwrite existing chains
+dot chain import my-chains.json --overwrite
+
+# Pipe between machines
+ssh remote-dev "dot chain export" | dot chain import -
+```
+
+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.
+
 ### Manage accounts
 
 Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
@@ -158,6 +206,16 @@ MY_SECRET="word1 word2 ..." dot tx System.remark 0xdead --from ci-signer
 dot account remove my-validator
 dot account delete my-validator stale-key
 
+# Export accounts (secrets redacted by default)
+dot account export
+dot account export --include-secrets --file backup.json
+dot account export --watch-only
+
+# Batch-import accounts from a file
+dot account import --file team-accounts.json
+dot account import --file accounts.json --dry-run
+dot account import --file accounts.json --overwrite
+
 # Inspect an account — show public key and SS58 address
 dot account inspect alice
 dot account alice                    # shorthand (same as inspect)
@@ -287,6 +345,38 @@ dot account derive treasury treasury-staking --path //staking
 
 **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`.
 
+#### Export/import accounts
+
+Export and import accounts for backup, sharing, or bootstrapping CI environments. Secrets are **redacted by default** — safe to share or commit.
+
+```bash
+# Export accounts (secrets redacted by default)
+dot account export
+
+# Export specific accounts
+dot account export treasury my-validator
+
+# Include secrets (explicit opt-in, prints warning)
+dot account export --include-secrets --file backup.json
+
+# Export only watch-only accounts (always safe)
+dot account export --watch-only
+
+# Batch-import accounts from a file
+dot account import --file team-accounts.json
+
+# Preview without applying
+dot account import --file accounts.json --dry-run
+
+# Overwrite existing accounts
+dot account import --file accounts.json --overwrite
+
+# Pipe from another machine
+ssh remote-dev "dot account export --watch-only" | dot account import --file /dev/stdin
+```
+
+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). The existing single-account `import` (`--secret`/`--env`) is unchanged — batch import uses `--file` to distinguish.
+
 ### Chain prefix
 
 Instead of the `--chain` flag, you can prefix any target with the chain name using dot notation:
@@ -299,9 +389,9 @@ dot inspect kusama.System
 dot inspect kusama.System.Account
 ```
 
-Chain names are case-insensitive — `Polkadot.System.Account`, `POLKADOT.System.Account`, and `polkadot.System.Account` all resolve the same way. The same applies to `--chain Polkadot` and `dot chain default Polkadot`.
+Chain names are case-insensitive — `Polkadot.System.Account`, `POLKADOT.System.Account`, and `polkadot.System.Account` all resolve the same way. The same applies to `--chain Polkadot`.
 
-The `--chain` flag and default chain still work as before. If both a chain prefix and `--chain` flag are provided, the CLI errors.
+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.
 
 ### Space-separated syntax
 
@@ -460,11 +550,66 @@ dot apis.Core.version --help
 Runtime API info requires v15 metadata. If `dot apis` shows 0 APIs, update the cached metadata:
 
 ```bash
-dot chain update              # default chain
 dot chain update people-paseo # specific chain
 dot chain update --all        # all configured chains
 ```
 
+#### Argument formats
+
+Runtime API arguments accept the same shorthand as `dot tx` arguments:
+
+| Type | Pass as | Example |
+|------|---------|---------|
+| Integers (`u8` … `u32`, `i8` … `i32`) | decimal | `0`, `42` |
+| Big integers (`u64`, `u128`, `u256`, `i64` …) | decimal | `1000000000000` |
+| `bool` | `true` / `false` | `true` |
+| `AccountId32` | dev name, stored account, SS58, or `0x` + 64 hex pubkey | `alice`, `5GrwvaEF…` |
+| `Vec<u8>` (unsized bytes) | `0x…` hex or text | `0xdeadbeef`, `hello` |
+| `[u8; N]` (sized bytes, e.g. `H160`/`H256`/raw `AccountId`) | `0x` + exactly `2 * N` hex chars (recommended), or text | `0x970951a12f975e6762482aca81e57d5a2a4e73f4` |
+| `Option<T>` | `null` (recommended), `none`, `undefined` — or a `T` value for `Some(value)` | `null` |
+| `Vec<T>` (non-byte) | JSON array or comma-separated | `[1,2,3]`, `1,2,3` |
+| Structs / nested enums | JSON | `{"type":"X1","value":{…}}` |
+
+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:
+
+```bash
+ALICE=5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+CONTRACT=0x970951a12f975e6762482aca81e57d5a2a4e73f4         # H160, [u8; 20]
+CALLDATA=$(cast calldata "set(uint256)" 42)
+
+dot --chain paseo-asset-hub apis.ReviveApi.call \
+  "$ALICE" "$CONTRACT" 0 null null "$CALLDATA"
+#   ^ origin   ^ dest    ^ value ^ gas_limit (Option, none) ^ deposit (Option, none) ^ input_data (Vec<u8>)
+```
+
+##### Passing `Option<T>`
+
+Absent options (`None`) can be written three ways, all equivalent:
+
+```bash
+dot apis.ReviveApi.call "$ALICE" "$CONTRACT" 0 null       null       "$CALLDATA"
+dot apis.ReviveApi.call "$ALICE" "$CONTRACT" 0 none       none       "$CALLDATA"
+dot apis.ReviveApi.call "$ALICE" "$CONTRACT" 0 undefined  undefined  "$CALLDATA"
+```
+
+`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.
+
+A present option (`Some(value)`) is just the value itself — no wrapping:
+
+```bash
+# gas_limit = Some({ ref_time: 1_000_000, proof_size: 100_000 })
+dot apis.ReviveApi.call "$ALICE" "$CONTRACT" 0 \
+  '{"ref_time":1000000,"proof_size":100000}' \
+  null \
+  "$CALLDATA"
+```
+
+Notes:
+- The `null` / `none` / `undefined` literals are case-sensitive (lowercase only).
+- There is no `Some(value)` prefix — bare values are already treated as `Some`.
+
+Use `dot apis.<ApiName>.<method> --help` to see the exact argument signature for any method.
+
 ### Focused commands
 
 Browse specific metadata categories directly without using `dot inspect`:
@@ -692,6 +837,64 @@ 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`, `--to-yaml`, and `--to-json` (which return before signing).
 
+#### Pay fees in an alternative asset
+
+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.
+
+```bash
+# Pay fees in USDT (asset id 1337, PalletInstance 50) on Polkadot Asset Hub
+dot tx Balances.transfer_keep_alive 5FHneW46... 1000000000000 \
+  --from alice --chain polkadot-asset-hub \
+  --asset '{"parents":0,"interior":{"type":"X2","value":[{"type":"PalletInstance","value":50},{"type":"GeneralIndex","value":"1337"}]}}'
+
+# Dry-run to see the native-denominated fee estimate
+dot tx Balances.transfer_keep_alive 5FHneW46... 1000000000000 \
+  --from alice --chain polkadot-asset-hub --dry-run \
+  --asset '{"parents":0,"interior":{"type":"X2","value":[{"type":"PalletInstance","value":50},{"type":"GeneralIndex","value":"1337"}]}}'
+```
+
+The `--asset` echo is included in dry-run and submission output (and `--json`). A few things to know:
+
+- 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.
+- The estimated fee shown is **native-denominated**. The on-chain asset-conversion pool determines the actual asset amount charged at execution time.
+- `--asset` is unnecessary (and not compatible) with `--unsigned`: unsigned transactions default `ChargeAssetTxPayment` to zero tip / no asset.
+- Combine freely with `--tip`, `--nonce`, `--mortality`, and `--at`. `--tip` is encoded inside the asset-payment extension alongside the asset id.
+
+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.
+
+#### Unsigned/authorized transactions
+
+Submit transactions without a signer using `--unsigned`. This is for calls authorized by on-chain mechanisms (e.g. the `AuthorizeCall` extension) rather than cryptographic signatures — typically governance-authorized calls on chains like the People chain.
+
+```bash
+# Submit an authorized call on the People chain
+dot tx People.create_people_collection --unsigned --chain people
+
+# Dry-run to inspect before submitting
+dot tx People.create_people_collection --unsigned --chain people --dry-run
+
+# Encode the full general transaction bytes
+dot tx People.create_people_collection --unsigned --chain people --encode
+
+# With raw hex call data
+dot tx 0x3306 --unsigned --chain people
+
+# JSON output for scripting
+dot tx People.create_people_collection --unsigned --chain people --json
+```
+
+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.
+
+`--unsigned` is mutually exclusive with `--from`, `--nonce`, `--tip`, and `--mortality`. File-based input supports `unsigned: true`:
+
+```yaml
+chain: people
+unsigned: true
+tx:
+  People:
+    create_people_collection: null
+```
+
 ### File-based commands
 
 Run any `dot` command from a YAML or JSON file. Especially useful for complex calls like XCM messages that are hard to construct inline.
@@ -1020,8 +1223,8 @@ dot tx.System.remark 0xdead               # shows call help (no error)
 | Flag | Description |
 |------|-------------|
 | `--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) |
+| `--chain <name>` | Target chain (required unless a dotpath chain prefix is used) |
+| `--rpc <url>` | Override RPC endpoint(s) for this call (repeat for fallback). Always fetches fresh metadata, bypassing the cache |
 
 | `--json` | Structured JSON output (shorthand for `--output json`) |
 | `--output json` | Structured JSON output |
@@ -1092,7 +1295,7 @@ dot apis.Core.<Tab>      # → apis.Core.version, ...
 dot polkadot.<Tab>       # → polkadot.query, polkadot.tx, ..., polkadot.apis
 dot --chain <Tab>        # → polkadot, paseo, ...
 dot --from <Tab>         # → alice, bob, ..., stored account names
-dot chain <Tab>          # → add, remove, update, list, default
+dot chain <Tab>          # → add, remove, update, list
 ```
 
 Completions are context-aware: `query.` shows pallets with storage items, `tx.` shows pallets with calls, `events.` and `errors.` filter accordingly, `apis.` shows runtime API names. Chain prefix paths like `polkadot.query.System.` work at any depth.
@@ -1141,7 +1344,7 @@ Config and metadata caches live in `~/.polkadot/`:
 
 ```
 ~/.polkadot/
-├── config.json          # chains and default chain
+├── config.json          # configured chains
 ├── accounts.json        # stored accounts (⚠️ secrets are NOT encrypted — see below)
 ├── update-check.json    # cached update check result
 └── chains/