@did-btcr2/method 0.29.0 → 0.33.0

package/README.md

@@ -1,6 +1,6 @@
 # @did-btcr2/method
 
-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.
+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.
 
 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.
 
@@ -16,12 +16,13 @@ pnpm add @did-btcr2/method
 |---|---|
 | 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 a DID (sans-I/O state machine) | `DidBtcr2.update()` returns an `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` |
+| Transport abstraction (Nostr, HTTP/REST, DIDComm stub) | `Transport`, `NostrTransport`, `HttpClientTransport`, `HttpServerTransport` |
+| Signer abstraction (local key, KMS, custom) | `Signer` / `LocalSigner` from `@did-btcr2/keypair`; `KeyManagerSigner` from `@did-btcr2/key-manager` |
 | DID document types and builders | `Btcr2DidDocument`, `DidDocumentBuilder` |
 
 ## Quick Start
@@ -32,7 +33,7 @@ pnpm add @did-btcr2/method
 import { DidBtcr2 } from '@did-btcr2/method';
 import { SchnorrKeyPair } from '@did-btcr2/keypair';
 
-// Deterministic (k-type) — the identifier IS the public key
+// Deterministic (k-type): the identifier IS the public key
 const keys = SchnorrKeyPair.generate();
 const did = DidBtcr2.create(keys.publicKey.compressed, {
   idType  : 'KEY',
@@ -66,10 +67,17 @@ See [`src/core/resolver.ts`](./src/core/resolver.ts) for the full `DataNeed` uni
 
 ### 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).
+`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';
+import { LocalSigner } from '@did-btcr2/keypair';
+import { BitcoinConnection } from '@did-btcr2/bitcoin';
+
+// Build a Signer from a raw secret key. For KMS-backed keys use KeyManagerSigner
+// from '@did-btcr2/key-manager' instead.
+const signer = new LocalSigner(secretKeyBytes);
+const bitcoin = BitcoinConnection.forNetwork('mutinynet');
 
 const updater = DidBtcr2.update({
   sourceDocument,
@@ -84,14 +92,14 @@ while (state.status === 'action-required') {
   for (const need of state.needs) {
     switch (need.kind) {
       case 'NeedSigningKey':
-        updater.provide(need, secretKeyBytes);
+        updater.provide(need, signer);
         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);
+        await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
         updater.provide(need);
         break;
     }
@@ -109,9 +117,16 @@ See [`src/core/updater.ts`](./src/core/updater.ts) for the full `UpdaterDataNeed
 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:
 
 ```typescript
-import { AggregationServiceRunner, NostrTransport } from '@did-btcr2/method';
+import { AggregationServiceRunner, TransportFactory } from '@did-btcr2/method';
+
+// Pick a transport. Nostr (relay-based) or HTTP/REST (operator-hosted).
+const transport = TransportFactory.establish({
+  type   : 'nostr',
+  relays : ['wss://relay.damus.io'],
+});
+// Or for HTTP: { type: 'http', role: 'server' } on the operator side,
+//              { type: 'http', role: 'client', baseUrl: '...' } on the participant side.
 
-const transport = new NostrTransport({ relays: ['wss://relay.damus.io'] });
 transport.registerActor(serviceDid, serviceKeys);
 transport.start();
 
@@ -127,13 +142,13 @@ runner.on('signing-complete', (result) => console.log('done'));
 const result = await runner.run();
 ```
 
-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).
+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). The HTTP/REST transport has its own walkthrough in [`docs/http-transport.md`](./docs/http-transport.md).
 
 ## Architecture Principles
 
 - **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.
+- **Pluggable transport.** The `Transport` interface decouples protocol logic from the wire format. Ships with `NostrTransport` (relay-based) and `HttpClientTransport` + `HttpServerTransport` (HTTP/REST, framework-agnostic, browser-compatible). 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.
 
 ## Build & Test
@@ -150,8 +165,13 @@ Tests run from compiled JS, so run `pnpm build:tests` before `pnpm test` after a
 
 ## Documentation
 
-- **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.
+- **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/http-transport.md`](./docs/http-transport.md)** HTTP/REST transport: wire protocol, signed envelopes, SSE subscriptions, Hono/Node framework mount example, permissive CORS
+- **[`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.
+
+## License
+
+[MPL-2.0](https://github.com/dcdpr/did-btcr2-js/blob/main/LICENSE)