@did-btcr2/method 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "description": "Reference implementation for the did:btcr2 DID method written in TypeScript and JavaScript. did:btcr2 is a censorship resistant DID Method using the Bitcoin blockchain as a Verifiable Data Registry to announce changes to the DID document. This is the core method implementation for the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -81,10 +81,10 @@
     "multiformats": "^13.4.2",
     "nostr-tools": "^2.23.3",
     "@did-btcr2/smt": "^0.3.0",
-    "@did-btcr2/keypair": "^0.13.0",
-    "@did-btcr2/cryptosuite": "^8.0.0",
+    "@did-btcr2/common": "^9.1.0",
     "@did-btcr2/bitcoin": "^0.6.0",
-    "@did-btcr2/common": "^9.1.0"
+    "@did-btcr2/keypair": "^0.13.0",
+    "@did-btcr2/cryptosuite": "^8.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/aggregation/runner/aggregation-runner.ts

@@ -0,0 +1,96 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { AggregationResult } from '../service.js';
+import { InMemoryBus, InMemoryTransport } from '../transport/in-memory.js';
+import { AggregationParticipantRunner } from './participant-runner.js';
+import type { OnProvideUpdate } from './participant-runner.js';
+import { AggregationServiceRunner } from './service-runner.js';
+import type { OnProvideTxData } from './service-runner.js';
+
+/** Identity (DID + keys) for one actor in an {@link AggregationRunner.solo} run. */
+export interface SoloActor {
+  did: string;
+  keys: SchnorrKeyPair;
+}
+
+/** Options for {@link AggregationRunner.solo}. */
+export interface SoloCohortOptions {
+  /** The coordinating service identity. */
+  service: SoloActor;
+  /** The single participant identity (the lone signer of the cohort). */
+  participant: SoloActor;
+  /** Bitcoin network and beacon type (`'CASBeacon'` | `'SMTBeacon'`) for the cohort. */
+  config: { network: string; beaconType: string };
+  /** Provide the participant's signed BTCR2 update for the cohort. */
+  onProvideUpdate: OnProvideUpdate;
+  /** Provide the Bitcoin transaction data the cohort signs. */
+  onProvideTxData: OnProvideTxData;
+  /** Optional overall wall-clock budget for the run (ms). */
+  cohortTtlMs?: number;
+  /** Optional per-phase stall timeout (ms). */
+  phaseTimeoutMs?: number;
+}
+
+/**
+ * High-level facades for driving an aggregation cohort to completion.
+ *
+ * @class AggregationRunner
+ */
+export class AggregationRunner {
+  /**
+   * Run a cohort of ONE participant entirely in-process and return the
+   * aggregated MuSig2 result.
+   *
+   * One party plays both the coordinating service and the lone participant,
+   * connected over an {@link InMemoryTransport} (no relay or HTTP server). This
+   * makes the single-participant aggregate-beacon path — the N=1 corner of the
+   * two-axis beacon matrix (see ADR 037) — first-class, useful for generating
+   * and reproducing single-participant aggregate test vectors.
+   *
+   * The service advertises a cohort with `minParticipants: 1`; the participant
+   * joins, submits its update, and the two complete keygen, data distribution,
+   * validation, and a one-signer MuSig2 P2TR key-path signing round.
+   *
+   * @param options Service + participant identities, cohort config, and the
+   *   update / tx-data callbacks.
+   * @returns The {@link AggregationResult} (cohort id, aggregated signature, signed tx).
+   */
+  static async solo(options: SoloCohortOptions): Promise<AggregationResult> {
+    const transport = new InMemoryTransport(new InMemoryBus());
+    transport.registerActor(options.service.did, options.service.keys);
+    transport.registerActor(options.participant.did, options.participant.keys);
+    // Pre-register communication keys both ways. Production exchanges these via
+    // the protocol handshake; in-process we wire them directly.
+    transport.registerPeer(options.participant.did, options.participant.keys.publicKey.compressed);
+    transport.registerPeer(options.service.did, options.service.keys.publicKey.compressed);
+    transport.start();
+
+    const service = new AggregationServiceRunner({
+      transport,
+      did                    : options.service.did,
+      keys                   : options.service.keys,
+      config                 : { minParticipants: 1, network: options.config.network, beaconType: options.config.beaconType },
+      onProvideTxData        : options.onProvideTxData,
+      cohortTtlMs            : options.cohortTtlMs,
+      phaseTimeoutMs         : options.phaseTimeoutMs,
+      // In-process bus with the participant already listening: a single advert
+      // suffices, so disable the republish loop (no dangling interval).
+      advertRepeatIntervalMs : 0,
+    });
+
+    const participant = new AggregationParticipantRunner({
+      transport,
+      did             : options.participant.did,
+      keys            : options.participant.keys,
+      shouldJoin      : async () => true,
+      onProvideUpdate : options.onProvideUpdate,
+    });
+
+    await participant.start();
+    try {
+      return await service.run();
+    } finally {
+      participant.stop();
+      service.stop();
+    }
+  }
+}

package/src/core/aggregation/runner/index.ts

@@ -2,3 +2,4 @@ export * from './typed-emitter.js';
 export * from './events.js';
 export * from './service-runner.js';
 export * from './participant-runner.js';
+export * from './aggregation-runner.js';

package/src/core/aggregation/transport/in-memory.ts

@@ -0,0 +1,174 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import type { BaseMessage } from '../messages/base.js';
+import type { MessageHandler, Transport } from './transport.js';
+
+/** Internal registration for a single actor sharing an {@link InMemoryTransport}. */
+interface ActorEntry {
+  keys: SchnorrKeyPair;
+  handlers: Map<string, MessageHandler>;
+}
+
+/**
+ * In-process message bus connecting one or more {@link InMemoryTransport}
+ * instances. Routes broadcasts to every registered actor and directed messages
+ * to the actor that owns the recipient DID — with no relay, server, or network.
+ *
+ * Each delivery does a JSON round-trip (Uint8Array preserved as `__bytes` hex)
+ * so handlers receive an isolated, serialization-faithful copy, exactly as a
+ * real transport would. The message `body` is merged to the top level to match
+ * the shape the {@link NostrTransport} dispatch produces.
+ *
+ * @class InMemoryBus
+ */
+export class InMemoryBus {
+  #transports: Set<InMemoryTransport> = new Set();
+
+  /** Attach a transport to this bus. Called by the transport's constructor. */
+  register(transport: InMemoryTransport): void {
+    this.#transports.add(transport);
+  }
+
+  /** Detach a transport from this bus. */
+  unregister(transport: InMemoryTransport): void {
+    this.#transports.delete(transport);
+  }
+
+  /**
+   * Deliver a message. With no `recipient` the message is broadcast to every
+   * actor on the bus; otherwise it is routed to the single transport that owns
+   * the recipient DID.
+   */
+  async deliver(message: BaseMessage, _sender: string, recipient?: string): Promise<void> {
+    const type = (message as { type?: string }).type;
+    if(!type) return;
+
+    // JSON round-trip to mimic transport serialization, preserving Uint8Array.
+    const replacer = (_k: string, v: unknown): unknown => v instanceof Uint8Array ? { __bytes: bytesToHex(v) } : v;
+    const reviver = (_k: string, v: unknown): unknown =>
+      v && typeof v === 'object' && '__bytes' in (v as Record<string, unknown>)
+        ? hexToBytes((v as { __bytes: string }).__bytes)
+        : v;
+    const raw = JSON.parse(JSON.stringify(message, replacer), reviver) as Record<string, unknown>;
+    const serialized = { ...raw, ...((raw.body as Record<string, unknown> | undefined) ?? {}) };
+
+    if(!recipient) {
+      for(const t of this.#transports) {
+        await t.dispatchBroadcast(type, serialized);
+      }
+      return;
+    }
+    for(const t of this.#transports) {
+      if(t.hasActor(recipient)) {
+        await t.dispatchDirected(recipient, type, serialized);
+        return;
+      }
+    }
+  }
+}
+
+/**
+ * In-process {@link Transport} that routes aggregation messages through an
+ * {@link InMemoryBus} instead of a relay or HTTP server. Supports multiple
+ * actors per instance, so a single transport can host both a service and its
+ * participants (e.g. a cohort-of-one via {@link AggregationRunner.solo}).
+ *
+ * Encryption is a no-op (in-process, same trust domain); `registerPeer` /
+ * `getPeerPk` keep a registry so the contract matches the wire transports.
+ *
+ * @class InMemoryTransport
+ * @implements {Transport}
+ */
+export class InMemoryTransport implements Transport {
+  name: string = 'in-memory';
+  readonly bus: InMemoryBus;
+
+  #actors: Map<string, ActorEntry> = new Map();
+  #peers: Map<string, Uint8Array> = new Map();
+
+  /** @param bus Shared bus. Pass the same bus to connect multiple transports. */
+  constructor(bus: InMemoryBus = new InMemoryBus()) {
+    this.bus = bus;
+    this.bus.register(this);
+  }
+
+  start(): void {
+    // No-op: there is no underlying connection to open.
+  }
+
+  registerActor(did: string, keys: SchnorrKeyPair): void {
+    this.#actors.set(did, { keys, handlers: new Map() });
+  }
+
+  getActorPk(did: string): Uint8Array | undefined {
+    return this.#actors.get(did)?.keys.publicKey.compressed;
+  }
+
+  /** True if `did` is registered on this transport. Used by the bus for routing. */
+  hasActor(did: string): boolean {
+    return this.#actors.has(did);
+  }
+
+  registerPeer(did: string, communicationPk: Uint8Array): void {
+    this.#peers.set(did, communicationPk);
+  }
+
+  getPeerPk(did: string): Uint8Array | undefined {
+    return this.#peers.get(did);
+  }
+
+  registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void {
+    const actor = this.#actors.get(actorDid);
+    if(actor) actor.handlers.set(messageType, handler);
+  }
+
+  unregisterMessageHandler(actorDid: string, messageType: string): void {
+    const actor = this.#actors.get(actorDid);
+    if(actor) actor.handlers.delete(messageType);
+  }
+
+  unregisterActor(did: string): void {
+    const actor = this.#actors.get(did);
+    if(!actor) return;
+    actor.handlers.clear();
+    this.#actors.delete(did);
+    this.#peers.delete(did);
+  }
+
+  async sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void> {
+    await this.bus.deliver(message, sender, recipient);
+  }
+
+  publishRepeating(
+    message: BaseMessage,
+    sender: string,
+    intervalMs: number,
+    recipient?: string,
+  ): () => void {
+    let stopped = false;
+    void this.sendMessage(message, sender, recipient).catch(() => { /* in-process: no relay to reject */ });
+    const timer = setInterval(() => {
+      if(stopped) return;
+      void this.sendMessage(message, sender, recipient).catch(() => { /* ignore */ });
+    }, intervalMs);
+    return () => {
+      if(stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    };
+  }
+
+  /** Deliver a broadcast message to every actor on this transport that handles `type`. */
+  async dispatchBroadcast(type: string, message: unknown): Promise<void> {
+    for(const actor of this.#actors.values()) {
+      const handler = actor.handlers.get(type);
+      if(handler) await handler(message);
+    }
+  }
+
+  /** Deliver a directed message to the recipient actor's handler for `type`. */
+  async dispatchDirected(recipientDid: string, type: string, message: unknown): Promise<void> {
+    const handler = this.#actors.get(recipientDid)?.handlers.get(type);
+    if(handler) await handler(message);
+  }
+}

package/src/core/aggregation/transport/index.ts

@@ -1,6 +1,7 @@
 export * from './transport.js';
 export * from './error.js';
 export * from './factory.js';
+export * from './in-memory.js';
 export * from './nostr.js';
 export * from './didcomm.js';
 export * from './http/index.js';

package/src/core/beacon/beacon.ts

@@ -89,7 +89,7 @@ export function deriveSingletonAddress(
 }
 
 /**
- * Options accepted by {@link Beacon.buildSignAndBroadcast} and related helpers.
+ * Options accepted by {@link SinglePartyBeacon.buildSignAndBroadcast} and related helpers.
  */
 export interface BroadcastOptions {
   /** Fee estimator for computing the transaction fee. Defaults to {@link DEFAULT_FEE_ESTIMATOR}. */
@@ -115,14 +115,14 @@ export interface BeaconTxPlan {
   feeSats: bigint;
   /**
    * Singleton beacon script kind, when applicable. Drives the signing dispatch
-   * in {@link Beacon.signSinglePartyTx}. Aggregation plans set this to `'p2tr'`.
+   * in {@link SinglePartyBeacon.signSinglePartyTx}. Aggregation plans set this to `'p2tr'`.
    */
   scriptKind: SingletonScriptKind;
 }
 
 /**
  * Build an OP_RETURN script carrying a 32-byte beacon signal.
- * Exported as a utility so callers building txs outside Beacon (e.g., the aggregation
+ * Exported as a utility so callers building txs outside SinglePartyBeacon (e.g., the aggregation
  * `onProvideTxData` callback) can produce identical output.
  *
  * Uses the opcode *string* `'RETURN'` rather than the numeric `OP.RETURN`
@@ -168,7 +168,7 @@ async function fetchSpendableUtxo(
  * Returns the unsigned Transaction + prev-output metadata that an aggregation service's
  * signing session consumes (via {@link SigningTxData}).
  *
- * This is the reusable counterpart to {@link Beacon.buildSignAndBroadcast}'s internal
+ * This is the reusable counterpart to {@link SinglePartyBeacon.buildSignAndBroadcast}'s internal
  * construction step — the aggregation path must produce an unsigned tx because the
  * signature comes from a MuSig2 round, not a local secret key.
  *
@@ -311,9 +311,11 @@ async function signSingletonInput(
 }
 
 /**
- * Abstract base class for all BTCR2 Beacon types.
- * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
- * how to find authentic updates to the DID.
+ * Abstract base class providing the single-party broadcast machinery shared by
+ * all BTCR2 beacon types: one party holds one key and broadcasts one 32-byte
+ * signal (P2PKH / P2WPKH / P2TR key-path). The aggregation (cohort of N >= 1)
+ * broadcast mode is the orthogonal axis, handled by the AggregationService and
+ * {@link buildAggregationBeaconTx}, not by this class hierarchy. See ADR 037.
  *
  * Beacons are lightweight typed wrappers around a {@link BeaconService} configuration.
  * Dependencies (signals, sidecar data, bitcoin connection) are passed as method
@@ -322,10 +324,10 @@ async function signSingletonInput(
  * Use {@link BeaconFactory.establish} to create typed instances from service config.
  *
  * @abstract
- * @class Beacon
- * @type {Beacon}
+ * @class SinglePartyBeacon
+ * @type {SinglePartyBeacon}
  */
-export abstract class Beacon {
+export abstract class SinglePartyBeacon {
   /**
    * The Beacon service configuration parsed from the DID Document.
    */

package/src/core/beacon/cas-beacon.ts

@@ -5,7 +5,7 @@ import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
-import { Beacon } from './beacon.js';
+import { SinglePartyBeacon } from './beacon.js';
 import type { BeaconService, BeaconSignal, BlockMetadata, CasPublishFn } from './interfaces.js';
 
 /**
@@ -28,9 +28,9 @@ export interface CASBroadcastOptions extends BroadcastOptions {
  *
  * @class CASBeacon
  * @type {CASBeacon}
- * @extends {Beacon}
+ * @extends {SinglePartyBeacon}
  */
-export class CASBeacon extends Beacon {
+export class CASBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of CASBeacon.
    * @param {BeaconService} service The service of the Beacon.
@@ -115,7 +115,7 @@ export class CASBeacon extends Beacon {
    * Creates a CAS Announcement mapping the DID to the update hash, broadcasts the hash of the
    * announcement via OP_RETURN, and optionally publishes the announcement off-chain via the
    * supplied `casPublish` callback. UTXO selection, PSBT construction, fee estimation, signing,
-   * and broadcast are delegated to {@link Beacon.buildSignAndBroadcast}.
+   * and broadcast are delegated to {@link SinglePartyBeacon.buildSignAndBroadcast}.
    *
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.

package/src/core/beacon/factory.ts

@@ -1,5 +1,5 @@
 import { MethodError } from '@did-btcr2/common';
-import type { Beacon } from './beacon.js';
+import type { SinglePartyBeacon } from './beacon.js';
 import { CASBeacon } from './cas-beacon.js';
 import type { BeaconService } from './interfaces.js';
 import { SingletonBeacon } from './singleton-beacon.js';
@@ -14,9 +14,9 @@ export class BeaconFactory {
   /**
    * Establish a Beacon instance based on the provided service and optional sidecar data.
    * @param {BeaconService} service The beacon service configuration.
-   * @returns {Beacon} The established Beacon instance.
+   * @returns {SinglePartyBeacon} The established Beacon instance.
    */
-  static establish(service: BeaconService): Beacon {
+  static establish(service: BeaconService): SinglePartyBeacon {
     switch (service.type) {
       case 'SingletonBeacon':
         return new SingletonBeacon(service);

package/src/core/beacon/singleton-beacon.ts

@@ -5,16 +5,16 @@ import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
-import { Beacon } from './beacon.js';
+import { SinglePartyBeacon } from './beacon.js';
 import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#singleton-beacon | Singleton Beacon}.
  * @class SingletonBeacon
  * @type {SingletonBeacon}
- * @extends {Beacon}
+ * @extends {SinglePartyBeacon}
  */
-export class SingletonBeacon extends Beacon {
+export class SingletonBeacon extends SinglePartyBeacon {
 
   /**
    * Creates an instance of SingletonBeacon.
@@ -64,7 +64,7 @@ export class SingletonBeacon extends Beacon {
    *
    * The signal bytes embedded in OP_RETURN are the SHA-256 canonical hash of the signed update.
    * UTXO selection, PSBT construction, fee estimation, signing, and broadcast are delegated to
-   * {@link Beacon.buildSignAndBroadcast}.
+   * {@link SinglePartyBeacon.buildSignAndBroadcast}.
    *
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.

package/src/core/beacon/smt-beacon.ts

@@ -7,7 +7,7 @@ import { randomBytes } from '@noble/hashes/utils';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
-import { Beacon } from './beacon.js';
+import { SinglePartyBeacon } from './beacon.js';
 import { SMTBeaconError } from './error.js';
 import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
@@ -21,9 +21,9 @@ import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js
  *
  * @class SMTBeacon
  * @type {SMTBeacon}
- * @extends {Beacon}
+ * @extends {SinglePartyBeacon}
  */
-export class SMTBeacon extends Beacon {
+export class SMTBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of SMTBeacon.
    * @param {BeaconService} service The Beacon service.
@@ -127,7 +127,7 @@ export class SMTBeacon extends Beacon {
    * Builds a single-entry Sparse Merkle Tree from the signed update, then broadcasts the tree's
    * root hash via OP_RETURN. For multi-party aggregation, use the {@link AggregationService}
    * subsystem directly instead of this method. UTXO selection, PSBT construction, fee estimation,
-   * signing, and broadcast are delegated to {@link Beacon.buildSignAndBroadcast}.
+   * signing, and broadcast are delegated to {@link SinglePartyBeacon.buildSignAndBroadcast}.
    *
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.

package/src/core/resolver.ts

@@ -102,7 +102,7 @@ export type ResolverState =
   | { status: 'resolved'; result: DidResolutionResponse };
 
 /**
- * Return type from {@link Beacon.processSignals}.
+ * Return type from {@link SinglePartyBeacon.processSignals}.
  * Contains successfully resolved updates and any data needs that must be
  * satisfied before the remaining signals can be processed.
  */