did-btcr2-js

@did-btcr2/cli

Command-line interface for the did:btcr2 DID method.

Part of the did-btcr2-js monorepo.

Summary

This package provides the btcr2 CLI for creating, resolving, updating, and deactivating did:btcr2 decentralized identifiers. It wraps the @did-btcr2/api SDK via dependency injection, using 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.

Install

npm install -g @did-btcr2/cli

Or with pnpm:

pnpm add -g @did-btcr2/cli

Requires Node.js >= 22.

Usage

Create a DID

# Deterministic (type=k): from a compressed secp256k1 public key (33 bytes hex)
btcr2 create -t k -n regtest -b 02aa...

# External (type=x): from a SHA-256 hash of a genesis document (32 bytes hex)
btcr2 create -t x -n bitcoin -b bb...

Resolve a DID

# Zero-config: network and endpoints are derived from the DID
btcr2 resolve -i did:btcr2:k1qq...

# With resolution options from a JSON file
btcr2 resolve -i did:btcr2:k1qq... -p resolution-options.json

# JSON output
btcr2 -o json resolve -i did:btcr2:k1qq...

Update a DID

btcr2 update \
  -s '{"id":"did:btcr2:k1qq...","service":[...]}' \
  --source-version-id 1 \
  -p '[{"op":"add","path":"/service/1","value":{...}}]' \
  -m '#initialKey' \
  -b '#beacon-0'

Deactivate a DID

btcr2 deactivate \
  -s '{"id":"did:btcr2:k1qq...","service":[...]}' \
  --source-version-id 2 \
  -m '#initialKey' \
  -b '#beacon-0'

Configuration

Override precedence, highest wins: CLI flags, then environment variables, then config file, then network defaults.

CLI flags

Flag	Description
`-o, --output <format>`	Output format: `json` or `text` (default: `text`)
`-c, --config <path>`	Path to config file
`--profile <name>`	Config profile name (default: auto-detected from network)
`--btc-rest <url>`	Override Bitcoin REST endpoint (Esplora API)
`--btc-rpc-url <url>`	Override Bitcoin Core RPC endpoint
`--btc-rpc-user <user>`	Bitcoin Core RPC username
`--btc-rpc-pass <pass>`	Bitcoin Core RPC password
`--cas-gateway <url>`	IPFS HTTP gateway for CAS reads

Environment variables

Variable	Equivalent flag
`BTCR2_BTC_REST`	`--btc-rest`
`BTCR2_BTC_RPC_URL`	`--btc-rpc-url`
`BTCR2_BTC_RPC_USER`	`--btc-rpc-user`
`BTCR2_BTC_RPC_PASS`	`--btc-rpc-pass`
`BTCR2_CAS_GATEWAY`	`--cas-gateway`

Config file

Default location: $XDG_CONFIG_HOME/btcr2/config.json (falls back to ~/.config/btcr2/config.json).

Profiles are matched by network name when --profile is not specified. For example, resolving a regtest DID automatically selects the "regtest" profile.

{
  "profiles": {
    "regtest": {
      "btc": {
        "rest": "http://localhost:3000",
        "rpcUrl": "http://localhost:18443",
        "rpcUser": "polaruser",
        "rpcPass": "polarpass"
      }
    },
    "bitcoin": {
      "btc": { "rest": "https://my-mempool/api" },
      "cas": { "gateway": "https://ipfs.io" }
    }
  }
}

Defaults

When no overrides are configured:

Bitcoin REST: mempool.space for public networks, localhost:3000 for regtest
Bitcoin RPC: localhost:18443 for regtest (credentials required), not configured for public networks
CAS: ipfs.io HTTP gateway (read-only)

Links

This site is open source. Improve this page.