@did-btcr2/method 0.26.0 → 0.28.0

package/README.md

@@ -1,275 +1,157 @@
-# Method
+# @did-btcr2/method
 
-TypeScript implementation of [did:btcr2 DID Method](https://dcdpr.github.io/did-btcr2/).
+TypeScript reference implementation of the [did:btcr2 DID Method](https://dcdpr.github.io/did-btcr2/) — a censorship-resistant Decentralized Identifier method using Bitcoin as a verifiable data registry.
 
-## Documentation
-
-Visit [btcr2.dev](https://btcr2.dev/impls/ts) to learn more about how to use [@did-btcr2/method](https://www.npmjs.com/package/@did-btcr2/method).
-
-## Test Vector Generator
-
-An incremental CLI tool for generating did:btcr2 test vectors through a stepped workflow: `create` → `update` (offline) → `fund` → `announce` → `resolve`. It produces JSON files under `lib/data/`.
-
-The first positional argument is the action. `create` runs offline. All subsequent actions only need `--hash` — the type and network are derived from the DID itself.
+This package is the core of the `did-btcr2-js` monorepo. It implements DID create/resolve/update operations, the three beacon types (Singleton, CAS, SMT), multi-party aggregation over MuSig2, and a pluggable transport layer for peer-to-peer coordination.
 
-### Quick Start
+## Installation
 
 ```bash
-# From packages/method/
-
-# 1. Create a new DID (only action that takes --type and --network)
-pnpm generate:vector create
-pnpm generate:vector create --type external --network mutinynet
-
-# 2. Construct and sign an update offline (use the hash printed by step 1)
-pnpm generate:vector update --hash <hash> --offline
-
-# 3. Fund the beacon address(es)
-source .env
-pnpm generate:vector fund --hash <hash>
-
-# 4. Announce the signed update on-chain
-pnpm generate:vector announce --hash <hash>
-
-# 5. Resolve the DID against a live Bitcoin node
-pnpm generate:vector resolve --hash <hash>
-
-# List existing vectors
-pnpm generate:vector list
-pnpm generate:vector list --network regtest --type key
-```
-
-### CLI Reference
-
+pnpm add @did-btcr2/method
 ```
-pnpm generate:vector <action> [options]
-```
-
-#### Actions
-
-| Action | Description |
-|--------|-------------|
-| `create` | Create a new DID and initial test vector files |
-| `update` | Construct and sign an update (optionally announce) |
-| `fund` | Fund beacon address(es) via RPC `sendtoaddress` + mine a block |
-| `announce` | Announce a previously signed update on-chain |
-| `resolve` | Resolve a DID against a live Bitcoin node |
-| `list` | Show existing test vectors |
-
-#### Options
 
-| Flag | Values | Default | Applies to | Description |
-|------|--------|---------|------------|-------------|
-| `--type` | `key`, `external` | `key` | `create`, `list` | DID identifier type |
-| `--network` | `regtest`, `bitcoin`, `mutinynet`, etc. | `regtest` | `create`, `list` | Bitcoin network |
-| `--genesis` | hex string | prompt / auto-generate | `create` | Genesis bytes hex (see below) |
-| `--hash` | 8-char short hash | — | `update`, `fund`, `announce`, `resolve` | Vector identifier (required) |
-| `--interactive` | flag (no value) | off | `update` | Enable interactive patch builder |
-| `--amount` | BTC amount | `0.001` | `fund` | BTC amount to send to each beacon address |
-| `--offline` | flag (no value) | off | `update`, `resolve` | Skip on-chain announcement or live resolution |
+## What's in the Box
 
-> After `create`, the hash uniquely identifies the vector. The script finds the directory
-> automatically and derives the type and network from the stored DID.
+| Feature | Entry point |
+|---|---|
+| Create a DID (offline, deterministic or external) | `DidBtcr2.create()` |
+| Resolve a DID (sans-I/O state machine) | `DidBtcr2.resolve()` |
+| Update a DID (sans-I/O state machine) | `DidBtcr2.update()` → `Updater` |
+| Update utilities (construct, sign, announce) | `Updater.construct()`, `Updater.sign()`, `Updater.announce()` |
+| Beacon types (Singleton, CAS, SMT) | `SingletonBeacon`, `CASBeacon`, `SMTBeacon` |
+| Fee estimation (pluggable) | `FeeEstimator`, `StaticFeeEstimator` |
+| Multi-party aggregation (MuSig2) | `AggregationServiceRunner`, `AggregationParticipantRunner` |
+| Transport abstraction (Nostr, DIDComm stub) | `Transport`, `NostrTransport` |
+| DID document types and builders | `Btcr2DidDocument`, `DidDocumentBuilder` |
 
-### Actions
+## Quick Start
 
-#### `create`
+### Create a DID
 
-Creates a DID and writes the initial vector files. The `--genesis` flag behavior depends on the `--type`:
+```typescript
+import { DidBtcr2 } from '@did-btcr2/method';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
 
-- **k1**: `--genesis` is a compressed public key hex. If omitted, prompts for one. If blank, auto-generates a keypair.
-- **x1**: `--genesis` is a SHA-256 hash hex of a genesis document. If omitted, prompts for a JSON genesis document or hex hash. If blank, auto-generates a keypair and default genesis document.
-
-```bash
-# Auto-generate everything
-pnpm generate:vector create
-pnpm generate:vector create --type external --network regtest
-
-# Bring your own genesis bytes
-pnpm generate:vector create --type key --genesis 02abc...def
-pnpm generate:vector create --type external --network regtest --genesis 82830a78...f83a99
-```
-
-**Outputs:**
+// Deterministic (k-type) — the identifier IS the public key
+const keys = SchnorrKeyPair.generate();
+const did = DidBtcr2.create(keys.publicKey.compressed, {
+  idType  : 'KEY',
+  network : 'mutinynet',
+});
+// did:btcr2:k1q5p...
 ```
-lib/data/{network}/{type}/{hash}/
-  create/input.json    # { idType, version, network, genesisBytes }
-  create/output.json   # { did }
-  other.json           # { genesisKeys: { secret, public }, genesisDocument? }
-```
-
-The `--hash` for subsequent steps is printed to the console.
-
-#### `update`
 
-Reads back the create output, rebuilds the source document, constructs and signs an update.
+### Resolve a DID
 
-**Without `--interactive`:** applies a default patch that rotates the first SingletonBeacon service endpoint (P2PKH key rotation).
+`DidBtcr2.resolve()` returns a sans-I/O state machine. The caller drives resolution by fulfilling typed data needs (beacon signals, CAS announcements, signed updates).
 
-**With `--interactive`:** prompts for JSON Patch operations with smart auto-generation (see below).
+```typescript
+import { DidBtcr2 } from '@did-btcr2/method';
 
-**With `--offline`:** builds and signs the update but skips the on-chain announcement. This is the typical workflow — use `fund` and `announce` as separate steps afterward.
+const resolver = DidBtcr2.resolve(did, { sidecar });
+let state = resolver.resolve();
 
-**Without `--offline`:** also announces the update on-chain immediately (requires a funded beacon address and `BITCOIN_NETWORK_CONFIG`).
-
-```bash
-# Recommended: sign offline, then fund and announce separately
-pnpm generate:vector update --hash <hash> --offline
-pnpm generate:vector update --hash <hash> --offline --interactive
-
-# Or sign and announce in one step (beacon must already be funded)
-source .env
-pnpm generate:vector update --hash <hash>
-```
-
-**Outputs:**
-```
-lib/data/{network}/{type}/{hash}/
-  update/input.json    # { sourceDocument, patches, sourceVersionId, ... }
-  update/output.json   # { signedUpdate }
-  other.json           # (updated with generated keys)
-```
-
-#### `fund`
-
-Funds all beacon service addresses in the DID document via RPC `sendtoaddress`, then mines blocks to confirm the funding transaction(s). **Requires a live Bitcoin node with a loaded wallet.**
-
-```bash
-source .env
-pnpm generate:vector fund --hash <hash>
-pnpm generate:vector fund --hash <hash> --amount 0.01
-```
-
-> Requires `BITCOIN_NETWORK_CONFIG` to be set with connection info
-> for the DID's network. Source your `.env` file or export it directly.
-
-#### `announce`
+while (state.status === 'action-required') {
+  for (const need of state.needs) {
+    const data = await fetchData(need);  // your I/O goes here
+    resolver.provide(need, data);
+  }
+  state = resolver.resolve();
+}
 
-Announces a previously signed update on-chain via the beacon service. Reads the signed update and beacon metadata from the `update` step's persisted files. Useful for retrying a failed announcement without re-running the full update pipeline.
+const { didDocument, metadata } = state.result;
+```
+
+See [`src/core/resolver.ts`](./src/core/resolver.ts) for the full `DataNeed` union and phase transitions.
+
+### Update a DID
+
+`DidBtcr2.update()` returns a sans-I/O state machine — the counterpart to the Resolver. The caller drives the update by fulfilling typed data needs (signing key, funding confirmation, broadcast).
+
+```typescript
+import { DidBtcr2, Updater } from '@did-btcr2/method';
+
+const updater = DidBtcr2.update({
+  sourceDocument,
+  patches              : [{ op: 'add', path: '/service/-', value: newService }],
+  sourceVersionId      : 1,
+  verificationMethodId : '#initialKey',
+  beaconId             : '#beacon-0',
+});
+
+let state = updater.advance();
+while (state.status === 'action-required') {
+  for (const need of state.needs) {
+    switch (need.kind) {
+      case 'NeedSigningKey':
+        updater.provide(need, secretKeyBytes);
+        break;
+      case 'NeedFunding':
+        // Check UTXOs at need.beaconAddress, fund if needed
+        updater.provide(need);
+        break;
+      case 'NeedBroadcast':
+        await Updater.announce(need.beaconService, need.signedUpdate, secretKey, bitcoin);
+        updater.provide(need);
+        break;
+    }
+  }
+  state = updater.advance();
+}
 
-```bash
-source .env
-pnpm generate:vector announce --hash <hash>
+const { signedUpdate } = state.result;
 ```
 
-> Requires `BITCOIN_NETWORK_CONFIG` to be set with connection info
-> for the DID's network. Source your `.env` file or export it directly.
+See [`src/core/updater.ts`](./src/core/updater.ts) for the full `UpdaterDataNeed` union and phase transitions.
 
-#### `resolve`
+### Update Aggregation (Multi-Party MuSig2)
 
-Resolves a DID against a live Bitcoin node. Assembles a sidecar from the signed update (if the update step has been run) and the genesis document (for x1 types).
+Aggregation lets multiple DID controllers coordinate a single Bitcoin transaction that announces all of their updates at once, signed n-of-n with MuSig2. The high-level `Runner` API hides the message routing and decision plumbing:
 
-**With `--offline`:** writes only the sidecar input file without connecting to Bitcoin.
+```typescript
+import { AggregationServiceRunner, NostrTransport } from '@did-btcr2/method';
 
-```bash
-# Resolve against a live Bitcoin node
-source .env
-pnpm generate:vector resolve --hash <hash>
+const transport = new NostrTransport({ relays: ['wss://relay.damus.io'] });
+transport.registerActor(serviceDid, serviceKeys);
+transport.start();
 
-# Offline — build sidecar input only
-pnpm generate:vector resolve --hash <hash> --offline
-```
+const runner = new AggregationServiceRunner({
+  transport,
+  did    : serviceDid,
+  keys   : serviceKeys,
+  config : { minParticipants: 2, network: 'mutinynet', beaconType: 'CASBeacon' },
+  onProvideTxData: async ({ beaconAddress, signalBytes }) => buildBeaconTx(beaconAddress, signalBytes),
+});
 
-**Outputs:**
-```
-lib/data/{network}/{type}/{hash}/
-  resolve/input.json   # { did, resolutionOptions: { sidecar } }
-  resolve/output.json  # { didDocument, didResolutionMetadata, didDocumentMetadata } (live only)
+runner.on('signing-complete', (result) => console.log('done'));
+const result = await runner.run();
 ```
 
-> Live resolution requires `BITCOIN_NETWORK_CONFIG` to be set with connection info
-> for the DID's network. Source your `.env` file or export it directly.
+The full step-by-step protocol walkthrough — service flow, participant flow, decision callbacks, events, the low-level state machine API, and production deployment notes — is in [`docs/aggregation.md`](./docs/aggregation.md).
 
-#### `list`
+## Architecture Principles
 
-Displays existing test vectors filtered by network and type. If `--network` or `--type` are not provided, prompts interactively.
+- **Sans-I/O core.** Resolver, Updater, and aggregation state machines perform zero I/O. They compute state transitions and emit typed needs or messages. Callers handle all network operations.
+- **Layered APIs.** High-level facades (like `AggregationServiceRunner`) encapsulate boilerplate; low-level state machines stay available for tests, custom transports, and fine-grained control.
+- **Pluggable transport.** The `Transport` interface decouples protocol logic from the wire format. Ships with `NostrTransport`; add your own for DIDComm, libp2p, or anything else.
+- **Browser-compatible.** All code targets both Node.js (>= 22) and modern browsers. No Node-only APIs in the core.
 
-```bash
-pnpm generate:vector list
-pnpm generate:vector list --network regtest --type key
-```
-
-### Interactive Mode
-
-Pass `--interactive` to the `update` step to build custom patches. The tool detects common patch targets and auto-generates values.
+## Build & Test
 
 ```bash
-pnpm generate:vector update --hash <hash> --interactive
-```
-
-#### Service patches (`/service/<n>`)
-
-When `add` or `replace` targets a path like `/service/0`, the tool:
-
-1. Prompts for **address type** (`p2pkh`, `p2wpkh`, `p2tr`) — defaults to `p2pkh`
-2. Prompts for **pubkey hex** — leave empty to auto-generate a new keypair
-3. Derives the Bitcoin address and builds the complete service object
-
-```
---- Add a JSON Patch operation ---
-  op: add
-  path: /service/1
-  Detected service patch — auto-generating value.
-  address type (p2pkh | p2wpkh | p2tr) [p2pkh]: p2wpkh
-  pubkey hex (leave empty to auto-generate):
-  Auto-generated keypair (stored as "service-service-1")
-  Added: {"op":"add","path":"/service/1","value":{"id":"did:btcr2:...#service-1","type":"SingletonBeacon","serviceEndpoint":"bitcoin:bcrt1q..."}}
-```
-
-#### Verification method patches (`/verificationMethod/<n>`)
-
-When `add` or `replace` targets a path like `/verificationMethod/1`, the tool:
-
-1. Prompts for an **id fragment** (e.g. `someNewId` or `#someNewId`) — defaults to `key-1`, `key-2`, etc.
-2. Validates the id is unique against existing verification methods
-3. Prompts for **pubkey hex** — leave empty to auto-generate
-4. Builds the complete verification method object with `publicKeyMultibase`
-
-```
---- Add a JSON Patch operation ---
-  op: add
-  path: /verificationMethod/1
-  Detected verificationMethod patch — auto-generating value.
-  id fragment (e.g. "someNewId" or "#someNewId") [key-1]: recoveryKey
-  pubkey hex (leave empty to auto-generate):
-  Auto-generated keypair (stored as "verificationMethod-verificationMethod-1")
-  Added: {"op":"add","path":"/verificationMethod/1","value":{"id":"did:btcr2:...#recoveryKey","type":"Multikey","controller":"did:btcr2:...","publicKeyMultibase":"zQ3sh..."}}
+# From packages/method/
+pnpm build              # Compile ESM + CJS + browser bundle
+pnpm build:tests        # Compile tests to tests/compiled/
+pnpm test               # Run the test suite with coverage
+pnpm lint               # ESLint (zero warnings tolerated)
 ```
 
-#### Other patches
-
-For any path not matching the above patterns, or for operations like `remove`, `move`, `copy`, the tool falls back to manual JSON value input.
+Tests run from compiled JS, so run `pnpm build:tests` before `pnpm test` after any test changes.
 
-### Key Storage
-
-All generated and user-provided keys are persisted in `other.json` for later reuse:
-
-- **Auto-generated keys** include both `secret` and `public` hex values
-- **User-provided keys** store the `public` hex with an empty `secret` field for you to fill in if needed
-
-```json
-{
-    "genesisKeys": { "secret": "...", "public": "..." },
-    "newBeaconKeys": { "secret": "...", "public": "..." },
-    "generatedKeys": {
-        "service-service-1": { "secret": "...", "public": "..." },
-        "verificationMethod-verificationMethod-1": { "secret": "", "public": "..." }
-    }
-}
-```
-
-### Output Directory Structure
+## Documentation
 
-```
-lib/data/{network}/{type}/{hash}/
-  create/
-    input.json
-    output.json
-  update/
-    input.json
-    output.json
-  resolve/
-    input.json
-    output.json    # (live mode only)
-  other.json
-```
+- **Package docs on btcr2.dev** — [btcr2.dev/impls/ts](https://btcr2.dev/impls/ts)
+- **[`docs/beacon-system-overview.md`](./docs/beacon-system-overview.md)** — Beacon architecture, Singleton / CAS / SMT behavior, signal discovery
+- **[`docs/aggregation.md`](./docs/aggregation.md)** — Multi-party aggregation protocol, Runner and state machine APIs, e2e examples
+- **[`docs/test-vectors.md`](./docs/test-vectors.md)** — CLI tool for generating did:btcr2 test vectors via a stepped workflow
+- **Source reference** — See JSDoc comments on public classes; the most important entry points are `DidBtcr2` (facade), `Resolver` (read path), `Updater` (write path), and the aggregation runners.