@did-btcr2/method 0.33.0 → 0.35.0

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.
  */

package/src/index.ts

@@ -1,6 +1,7 @@
 // Aggregation
 export * from './core/aggregation/service.js';
 export * from './core/aggregation/participant.js';
+export * from './core/aggregation/signer.js';
 export * from './core/aggregation/cohort.js';
 export * from './core/aggregation/signing-session.js';
 export * from './core/aggregation/phases.js';