@did-btcr2/cli 0.20.0 → 0.22.0

package/README.md

@@ -6,7 +6,7 @@ Part of the [`did-btcr2-js`](https://github.com/dcdpr/did-btcr2-js) monorepo.
 
 ## Summary
 
-This package provides the `btcr2` CLI for creating, resolving, updating, and deactivating did:btcr2 decentralized identifiers. It also manages an encrypted keystore of keypairs, reads and writes CLI configuration and profiles, and prints shell completion scripts. It wraps the `@did-btcr2/api` SDK via dependency injection, using [commander.js](https://github.com/tj/commander.js/) for argument parsing.
+This package provides the `btcr2` CLI for creating, resolving, updating, and deactivating did:btcr2 decentralized identifiers. It decodes and validates identifiers offline. It also manages an encrypted keystore of keypairs, reads and writes CLI configuration and profiles, and prints shell completion scripts. It wraps the `@did-btcr2/api` SDK via dependency injection, using [commander.js](https://github.com/tj/commander.js/) for argument parsing.
 
 Out of the box, `btcr2 resolve` works with zero configuration. The Bitcoin network is derived from the DID itself, and public endpoints (mempool.space, ipfs.io) are used as defaults. Override endpoints via CLI flags, environment variables, or a config file.
 
@@ -44,6 +44,7 @@ npx @did-btcr2/cli resolve -i did:btcr2:k1qq...
 | `resolve` | `read` | Resolve a DID document |
 | `update` | - | Update a DID document (signs via the keystore) |
 | `deactivate` | `delete` | Deactivate a DID permanently (signs via the keystore) |
+| `identifier` | - | Decode and validate identifiers (offline) |
 | `key` | - | Manage keypairs in the keystore |
 | `keystore` | - | Establish, inspect, and re-key the keystore |
 | `config` | - | Read and write CLI configuration |
@@ -85,15 +86,19 @@ Required flag: `-i/--identifier`. If both `-r` and `-p` are given, `-r` wins and
 
 Signs and broadcasts an update to a DID document. The signing key comes from the encrypted keystore (choose one with `--signing-key <ref>` or set an active key with `btcr2 key use`).
 
-Required flags: `-s/--source-document`, `--source-version-id`, `-p/--patches`, `-m/--verification-method-id`, `-b/--beacon-id`.
+Required flags: `-i/--identifier`, `-p/--patches`. The command resolves the current document from the network unless you supply the source pair `-s/--source-document` and `--source-version-id` (both or neither). The api derives the verification method and the beacon unless you pass `-m` or `-b`.
 
 | Flag | Description |
 |---|---|
-| `-s, --source-document <json>` | Source DID document as a JSON string |
-| `--source-version-id <number>` | Source version ID as a non-negative integer |
-| `-p, --patches <json>` | JSON Patch operations as a JSON array string |
-| `-m, --verification-method-id <id>` | DID document verification method ID |
-| `-b, --beacon-id <json>` | Beacon ID as a JSON string |
+| `-i, --identifier <identifier>` | did:btcr2 identifier to update (required) |
+| `-p, --patches <json>` | JSON Patch operations as a JSON array string (required) |
+| `-s, --source-document <json>` | Source DID document as a JSON string. Requires `--source-version-id`. Omit both to resolve the current document first |
+| `--source-version-id <number>` | Version ID of the source document, a non-negative integer. Requires `--source-document` |
+| `-m, --verification-method-id <id>` | Verification method that signs the update. Default: the one method of the document that publishes the signing key. Pass it when the api names several candidates |
+| `-b, --beacon-id <id>` | Beacon service that announces the update, as a DID URL (`#initialP2WPKH` or absolute). Default: the only beacon of the document, else the one beacon with a spendable UTXO. Pass it when the api names several funded beacons |
+| `-r, --resolution-options <json>` | Resolution options as an inline JSON string, for the resolution of the source document. Supply sidecar data here if the DID's prior updates are not in a CAS. Not allowed with the source pair |
+| `--resolution-options-path <path>` | Path to a JSON file containing resolution options (`-r` wins if both are given). Not allowed with the source pair |
+| `--min-conf <n>` | Minimum block confirmations a beacon signal needs before the source resolution applies it. A positive integer; default `6`, the specification value. Overrides a `minConf` inside `-r`/`--resolution-options-path`. Not allowed with the source pair |
 | `--publish-to-cas <mode>` | Publish update artifacts to a writable CAS before broadcast: `auto`, `always`, or `never` (default: `never`). See [Publishing updates to CAS](#publishing-updates-to-cas) |
 | `--fee-rate <satsPerVByte>` | Fee rate in sats/vByte for the beacon transaction (default: `5`). Raise it under congestion so the transaction confirms (also `BTCR2_FEE_RATE`, profile `btc.feeRate`) |
 | `--change-address <address>` | Send transaction change to this address instead of the beacon address, so a DID's announcements are not linked on-chain (profile `btc.changeAddress`) |
@@ -102,9 +107,20 @@ On a network with a block explorer, text-mode `update` (and `deactivate`) also p
 
 ### deactivate (alias: delete)
 
-Permanently deactivates a DID. This is irreversible. Deactivation applies the `{ "op": "add", "path": "/deactivated", "value": true }` patch and routes through the same signed-update path as `update`, so it also signs via the keystore.
+Permanently deactivates a DID. This is irreversible. The command calls the api's `deactivateDid`, which applies the `{ "op": "add", "path": "/deactivated", "value": true }` patch and refuses a DID that is deactivated already. It signs via the keystore like `update`.
 
-Required flags: `-s/--source-document`, `--source-version-id`, `-m/--verification-method-id`, `-b/--beacon-id`. Optional: `--publish-to-cas <mode>`, `--fee-rate <satsPerVByte>`, `--change-address <address>` (same as `update`).
+Required flag: `-i/--identifier`. Optional: the same source, derivation, resolution, CAS, fee, and change-address flags as `update`, minus `-p`.
+
+### identifier
+
+Decodes and validates identifiers. Both subcommands are offline and keystore-free. The identifier is a positional argument.
+
+| Subcommand | Description |
+|---|---|
+| `identifier decode <did>` | Print the identifier type, the `hrp`, the version, the network, and the genesis bytes as hex. `--initial-document` adds the initial DID document; an `x` identifier needs `--genesis-document <path>` for it. |
+| `identifier validate <did>` | Run the checks of the identifier decoding algorithm in order and print the report. Exit code `1` if a check fails. `-b, --bytes <hex>` adds the `genesisBytesMatch` check: the identifier must encode these genesis bytes (`k` or `x`). `--genesis-document <path>` adds the `genesisDocument` check for an `x` identifier. |
+
+See [`docs/identifier.md`](./docs/identifier.md) for the check list and the output fields.
 
 ### init
 
@@ -247,24 +263,28 @@ btcr2 -o json resolve -i did:btcr2:k1qq...
 ### Update a DID
 
 ```bash
-# Signs with the active keystore key (or one chosen via --signing-key)
-btcr2 update \
-  -s "$(cat did.json)" \
-  --source-version-id 1 \
-  -p '[{"op":"add","path":"/service/-","value":{"id":"#svc","type":"X","serviceEndpoint":"https://x"}}]' \
-  -m 'did:btcr2:k1qq...#key-0' \
-  -b '{"id":"#beacon-0","type":"SingletonBeacon","serviceEndpoint":"bitcoin:bc1..."}'
+# Signs with the active keystore key (or one chosen via --signing-key).
+# The command resolves the current document, derives the verification
+# method and the beacon, then signs and broadcasts.
+btcr2 update -i did:btcr2:k1qq... \
+  -p '[{"op":"add","path":"/service/-","value":{"id":"#svc","type":"X","serviceEndpoint":"https://x"}}]'
+
+# A DID whose prior update is sidecar-only: hand that update to the source resolution
+btcr2 update -i did:btcr2:k1qq... --min-conf 1 -r '{"sidecar":{"updates":[...]}}' \
+  -p '[{"op":"remove","path":"/service/1"}]'
+
+# Offline source: supply the document and its version, and name the method and the beacon
+btcr2 update -i did:btcr2:k1qq... \
+  -s "$(cat did.json)" --source-version-id 1 \
+  -p '[{"op":"remove","path":"/service/1"}]' \
+  -m '#initialKey' -b '#initialP2WPKH'
 ```
 
 ### Deactivate a DID
 
 ```bash
-# Irreversible. Applies the deactivation patch and signs via the keystore.
-btcr2 deactivate \
-  -s "$(cat did.json)" \
-  --source-version-id 1 \
-  -m 'did:btcr2:k1qq...#key-0' \
-  -b '{"id":"#beacon-0","type":"SingletonBeacon","serviceEndpoint":"bitcoin:bc1..."}'
+# Irreversible. Resolves the current document, then signs the deactivation via the keystore.
+btcr2 deactivate -i did:btcr2:k1qq... --min-conf 1 -r '{"sidecar":{"updates":[...]}}'
 ```
 
 ### Manage keys
@@ -418,11 +438,8 @@ A writable CAS is configured with `--cas-rpc-url <url>` (an IPFS HTTP RPC endpoi
 btcr2 update \
   --cas-rpc-url http://127.0.0.1:5001 \
   --publish-to-cas auto \
-  -s "$(cat did.json)" \
-  --source-version-id 1 \
-  -p '[{"op":"add","path":"/service/-","value":{"id":"#svc","type":"X","serviceEndpoint":"https://x"}}]' \
-  -m 'did:btcr2:k1qq...#key-0' \
-  -b '{"id":"#beacon-0","type":"SingletonBeacon","serviceEndpoint":"bitcoin:bc1..."}'
+  -i did:btcr2:k1qq... \
+  -p '[{"op":"add","path":"/service/-","value":{"id":"#svc","type":"X","serviceEndpoint":"https://x"}}]'
 ```
 
 ## Links