@did-btcr2/method 0.28.0 → 0.29.0

package/dist/types/core/aggregation/transport/nostr.d.ts

@@ -1,6 +1,7 @@
 import type { Did } from '@did-btcr2/common';
 import type { SchnorrKeyPair } from '@did-btcr2/keypair';
 import { SimplePool } from 'nostr-tools/pool';
+import type { Logger } from '../logger.js';
 import type { BaseMessage } from '../messages/base.js';
 import type { MessageHandler, Transport } from './transport.js';
 /**
@@ -10,7 +11,24 @@ import type { MessageHandler, Transport } from './transport.js';
 export declare const DEFAULT_NOSTR_RELAYS: string[];
 export interface NostrTransportConfig {
     relays?: string[];
+    /**
+     * Optional logger for transport-level diagnostics (publish/subscribe events,
+     * relay rejections, parse failures). Defaults to {@link CONSOLE_LOGGER}.
+     */
+    logger?: Logger;
+    /**
+     * How far back (in milliseconds) to set the `since` filter on the broadcast
+     * (COHORT_ADVERT) subscription. Some public relays do NOT replay historical
+     * events to late subscribers when the filter has no `since`, so the advert
+     * gets lost if the subscription lands after the publish. A short lookback
+     * window nudges those relays into delivering recent adverts. Set to 0 to
+     * disable the filter entirely (unbounded history). Defaults to
+     * {@link DEFAULT_BROADCAST_LOOKBACK_MS} (5 minutes).
+     */
+    broadcastLookbackMs?: number;
 }
+/** Default `since` lookback for broadcast (COHORT_ADVERT) subscriptions: 5 minutes. */
+export declare const DEFAULT_BROADCAST_LOOKBACK_MS: number;
 /**
  * Nostr Transport for did:btcr2 aggregation messages.
  *
@@ -41,15 +59,95 @@ export declare class NostrTransport implements Transport {
      * @example
      * const transport = new NostrTransport();
      * const keys = SchnorrKeyPair.generate();
-     * transport.registerActor('did:btcr2:...', keys);
+     * const did = DidBtcr2.create(keys.publicKey.compressed, { idType: 'KEY', network: 'mutinynet' });
+     * transport.registerActor(did, keys);
      * transport.start();
      */
     registerActor(did: string, keys: SchnorrKeyPair): void;
+    /**
+     * Detach an actor: drop its handlers, close its relay subscriptions, and remove its keys + peer
+     * mapping. Idempotent.
+     * @param {string} did - The DID of the actor to unregister.
+     * @returns {void}
+     * @throws {TransportAdapterError} If the transport is not started or if the pool is unavailable.
+     * @example
+     * transport.unregisterActor(did);
+     */
+    unregisterActor(did: string): void;
+    /**
+     * Remove a single (actor, messageType) handler. Idempotent.
+     * @param {string} actorDid - The DID of the actor.
+     * @param {string} messageType - The type of message to unregister the handler for.
+     * @returns {void}
+     * @example
+     * transport.unregisterMessageHandler(actorDid, messageType);
+     */
+    unregisterMessageHandler(actorDid: string, messageType: string): void;
+    /**
+     * Gets the public key for a registered actor by their DID.
+     * @param {string} did - The DID of the registered actor to get the public key for.
+     * @returns {Uint8Array | undefined} The compressed public key bytes for the actor's DID, or
+     * undefined if the DID is not registered.
+     */
     getActorPk(did: string): Uint8Array | undefined;
+    /**
+     * Registers a peer's communication public key for encrypted messages.
+     * @param {string} did - The DID of the peer to register.
+     * @param {Uint8Array} communicationPk - The compressed secp256k1 public key bytes for the peer.
+     */
     registerPeer(did: string, communicationPk: Uint8Array): void;
+    /**
+     * Gets the registered communication public key for a peer by their DID.
+     * @param {string} did - The DID of the peer to get the communication public key for.
+     * @returns {Uint8Array | undefined} The compressed secp256k1 public key bytes for the peer, or
+     * undefined if the peer is not registered.
+     */
     getPeerPk(did: string): Uint8Array | undefined;
+    /**
+     * Registers a message handler function for a specific actor and message type. The handler will be called
+     * when a message of the specified type is received for the actor's DID. The transport must have been
+     * started for handlers to be invoked. If the transport is already started, the handler will be registered
+     * immediately; otherwise, it will be registered when the transport starts and the actor's subscription is created.
+     * @param {string} actorDid - The DID of the actor to register the message handler for.
+     * @param {string} messageType - The type of message to handle.
+     * @param {MessageHandler} handler - The function to handle incoming messages of the specified type.
+     * @throws {TransportAdapterError} If the actor DID is not registered or if the handler is invalid.
+     */
     registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void;
+    /**
+     * Starts the transport by connecting to the configured Nostr relays and setting up subscriptions
+     * for all registered actors. This method must be called after registering actors via registerActor()
+     * and before sending or receiving messages. The transport will subscribe to broadcast events (kind 1)
+     * for cohort adverts and directed events (kinds 1 and 1059) for each registered actor based on their
+     * public keys. Incoming events are processed and dispatched to the appropriate handlers based on
+     * message type. If the transport is already started, this method has no effect.
+     * @returns {NostrTransport}
+     */
     start(): NostrTransport;
+    /**
+     * Sends a message by publishing a Nostr event to the configured relays. The message is serialized
+     * as JSON and included in the event content.
+     * @param {BaseMessage} message - The aggregation message to send. Must include a valid `type` property.
+     * @param {Did} sender - The DID of the registered actor sending the message. Must have been
+     * registered via registerActor().
+     * @param {Did} [to] - Optional recipient DID for directed messages. Required for encrypted message
+     * types. If provided, must have been registered via registerPeer().
+     * @returns {Promise<void>} Resolves when the message has been published to the relays. Note that
+     * publication is best-effort: the method will resolve as long as at least one relay accepts the
+     * event, even if others reject it.
+     */
     sendMessage(message: BaseMessage, sender: Did, to?: Did): Promise<void>;
+    /**
+     * Publish the message once immediately and then re-publish on an interval
+     * until the returned stop function is invoked.
+     *
+     * Useful for broadcast messages (COHORT_ADVERT) on relays that don't
+     * backfill historical events to late subscribers: republishing gives late
+     * joiners a window to discover the message without requiring protocol
+     * changes. Relay rate-limit / publish failures inside the interval are
+     * caught and logged rather than propagated — the caller should stop the
+     * repeater once the protocol condition is satisfied.
+     */
+    publishRepeating(message: BaseMessage, sender: Did, intervalMs: number, recipient?: Did): () => void;
 }
 //# sourceMappingURL=nostr.d.ts.map

package/dist/types/core/aggregation/transport/nostr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nostr.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/nostr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAQD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,SAAS;;IAC9C,IAAI,EAAE,MAAM,CAAW;IAEvB,IAAI,CAAC,EAAE,UAAU,CAAC;gBAMN,MAAM,CAAC,EAAE,oBAAoB;IAIzC;;;;;;;;;;;OAWG;IACI,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAUtD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI;IAY5D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9C,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAW5F,KAAK,IAAI,cAAc;IAsBjB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;CAkMrF"}
+{"version":3,"file":"nostr.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/nostr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,uFAAuF;AACvF,eAAO,MAAM,6BAA6B,QAAgB,CAAC;AAU3D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,SAAS;;IAC9C,IAAI,EAAE,MAAM,CAAW;IAEvB,IAAI,CAAC,EAAE,UAAU,CAAC;gBAQN,MAAM,CAAC,EAAE,oBAAoB;IAMzC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAUtD;;;;;;;;OAQG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAYlC;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAMrE;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI;IAY5D;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9C;;;;;;;;;OASG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAW5F;;;;;;;;OAQG;IACH,KAAK,IAAI,cAAc;IAsCvB;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAmF7E;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,GAAG,MAAM,IAAI;CAwNrG"}

package/dist/types/core/aggregation/transport/transport.d.ts

@@ -31,7 +31,32 @@ export interface Transport {
     getPeerPk(did: string): Uint8Array | undefined;
     /** Register a message handler scoped to a specific actor. */
     registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void;
+    /** Remove a previously-registered handler. No-op if not registered. */
+    unregisterMessageHandler(actorDid: string, messageType: string): void;
+    /**
+     * Detach an actor: unregister all its handlers, drop its keys, and close any
+     * transport-level subscriptions created for it. No-op if the actor is not
+     * registered.
+     */
+    unregisterActor(did: string): void;
     /** Send a message. The transport looks up sender to resolve signing keys. */
     sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void>;
+    /**
+     * Publish the message once immediately and then repeat it on a fixed
+     * interval. Returns a stop function the caller MUST invoke when the repeat
+     * is no longer needed (e.g. once the protocol state that required the
+     * message is satisfied).
+     *
+     * Useful for broadcasts on transports that don't reliably backfill
+     * historical events to late subscribers (many Nostr relays) — republishing
+     * gives late joiners a window in which to discover the message. The first
+     * publish is synchronous-ish (fired before the method returns).
+     *
+     * Callers specify `recipient` only for directed messages; for broadcasts
+     * it is omitted.
+     *
+     * @returns A stop function. Idempotent — safe to call more than once.
+     */
+    publishRepeating(message: BaseMessage, sender: string, intervalMs: number, recipient?: string): () => void;
 }
 //# sourceMappingURL=transport.d.ts.map

package/dist/types/core/aggregation/transport/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEtE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IAEb,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAAC;IAEd,sEAAsE;IACtE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAEvD,uEAAuE;IACvE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEhD,4EAA4E;IAC5E,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D,yDAAyD;IACzD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAE/C,6DAA6D;IAC7D,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7F,6EAA6E;IAC7E,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEtE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IAEb,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAAC;IAEd,sEAAsE;IACtE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAEvD,uEAAuE;IACvE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEhD,4EAA4E;IAC5E,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D,yDAAyD;IACzD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAE/C,6DAA6D;IAC7D,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7F,uEAAuE;IACvE,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtE;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,6EAA6E;IAC7E,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CACd,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,IAAI,CAAC;CACf"}

package/dist/types/core/beacon/beacon.d.ts

@@ -1,17 +1,68 @@
-import type { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type { AddressUtxo, BitcoinConnection, BTCNetwork } from '@did-btcr2/bitcoin';
 import type { KeyBytes } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { Transaction } from '@scure/btc-signer';
 import type { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { FeeEstimator } from './fee-estimator.js';
 import type { BeaconService, BeaconSignal } from './interfaces.js';
 /**
- * Options accepted by {@link Beacon.buildSignAndBroadcast}.
+ * Options accepted by {@link Beacon.buildSignAndBroadcast} and related helpers.
  */
 export interface BroadcastOptions {
     /** Fee estimator for computing the transaction fee. Defaults to {@link DEFAULT_FEE_ESTIMATOR}. */
     feeEstimator?: FeeEstimator;
 }
+/**
+ * Unsigned beacon transaction + the prev-output metadata needed for downstream
+ * signing (single-party ECDSA or multi-party MuSig2 Taproot).
+ */
+export interface BeaconTxPlan {
+    /** The unsigned scure @scure/btc-signer Transaction. */
+    tx: Transaction;
+    /** Scripts of the consumed previous outputs (needed for Taproot sighash). */
+    prevOutScripts: Uint8Array[];
+    /** Amounts (sats) of the consumed previous outputs. */
+    prevOutValues: bigint[];
+    /** Address change was sent back to (same as the beacon address). */
+    beaconAddress: string;
+    /** The UTXO this tx consumes. */
+    utxo: AddressUtxo;
+    /** The fee (sats) already deducted from the change output. */
+    feeSats: bigint;
+}
+/**
+ * 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
+ * `onProvideTxData` callback) can produce identical output.
+ */
+export declare function opReturnScript(signalBytes: Uint8Array): Uint8Array;
+/**
+ * Build an aggregation beacon transaction (P2TR key-path spend) ready for MuSig2 signing.
+ * 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
+ * construction step — the aggregation path must produce an unsigned tx because the
+ * signature comes from a MuSig2 round, not a local secret key.
+ *
+ * @param opts Parameters including the cohort's aggregate internal pubkey.
+ * @returns A {@link BeaconTxPlan} with the unsigned tx and sighash inputs.
+ */
+export declare function buildAggregationBeaconTx(opts: {
+    /** The beacon (cohort) address where UTXOs live and change returns to. */
+    beaconAddress: string;
+    /** The cohort's MuSig2-aggregated x-only internal pubkey (32 bytes). */
+    internalPubkey: Uint8Array;
+    /** 32-byte beacon signal embedded in the OP_RETURN output. */
+    signalBytes: Uint8Array;
+    /** Bitcoin REST connection for UTXO / prev-tx lookup. */
+    bitcoin: BitcoinConnection;
+    /** Network params used to derive the P2TR witnessUtxo script. */
+    network: BTCNetwork;
+    /** Optional fee estimator (defaults to 5 sat/vB). */
+    feeEstimator?: FeeEstimator;
+}): Promise<BeaconTxPlan>;
 /**
  * Abstract base class for all BTCR2 Beacon types.
  * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
@@ -28,6 +79,7 @@ export interface BroadcastOptions {
  * @type {Beacon}
  */
 export declare abstract class Beacon {
+    #private;
     /**
      * The Beacon service configuration parsed from the DID Document.
      */
@@ -56,30 +108,45 @@ export declare abstract class Beacon {
      */
     abstract broadcastSignal(signedUpdate: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<SignedBTCR2Update>;
     /**
-     * Shared PSBT construction + signing + broadcast helper used by all beacon types.
-     *
-     * Steps:
-     * 1. Parse the beacon's `serviceEndpoint` (stripping `bitcoin:` prefix) into a Bitcoin address.
-     * 2. Query the address for unconfirmed/confirmed UTXOs.
-     * 3. Select the most recent confirmed UTXO.
-     * 4. Fetch the previous transaction hex for `nonWitnessUtxo`.
-     * 5. Build a PSBT: input (UTXO) → change output + OP_RETURN(signalBytes).
-     * 6. Compute the fee via the supplied (or default) {@link FeeEstimator} against the tx vsize.
-     * 7. Sign input 0 with an ECDSA signer derived from `secretKey`.
-     * 8. Finalize, extract, and broadcast via the REST transaction endpoint.
+     * Build + sign + broadcast a single-party beacon signal transaction (P2WPKH spend).
      *
-     * Fee handling: the PSBT is constructed with a placeholder change amount, signed to measure
-     * vsize, then the change is adjusted to pay the actual fee and the input re-signed. This
-     * two-pass approach avoids hardcoded fee constants and produces a tx that matches the
-     * estimator's rate.
+     * Composed from the three extracted phases ({@link buildSinglePartyTx},
+     * {@link signSinglePartyTx}, {@link broadcastRawTx}) so each piece can be exercised
+     * in isolation. Aggregation beacons use {@link buildAggregationBeaconTx} instead —
+     * the multi-party path can't share the signing phase, but the tx-construction
+     * plumbing (UTXO fetch + OP_RETURN output + change output) is shared.
      *
      * @param signalBytes 32-byte payload to embed in OP_RETURN.
      * @param secretKey Secret key used to sign the spending input.
      * @param bitcoin Bitcoin network connection.
      * @param options Broadcast options (fee estimator, etc.).
      * @returns The txid of the broadcast transaction.
-     * @throws {BeaconError} if the address is unfunded or no UTXO is available.
+     * @throws {BeaconError} if the address is unfunded, no UTXO is available, or fee exceeds value.
      */
     protected buildSignAndBroadcast(signalBytes: Uint8Array, secretKey: KeyBytes, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<string>;
+    /**
+     * Build an unsigned P2WPKH single-party beacon tx + probe-sign to determine vsize,
+     * then rebuild with the real fee. Returns the tx and prev-output metadata.
+     *
+     * The secret key is required here (not just in `signSinglePartyTx`) because the
+     * two-pass fee estimation requires an actual signature to measure vsize accurately.
+     */
+    protected buildSinglePartyTx(opts: {
+        signalBytes: Uint8Array;
+        beaconAddress: string;
+        utxo: AddressUtxo;
+        prevTxBytes: Uint8Array;
+        secretKey: KeyBytes;
+        bitcoin: BitcoinConnection;
+        feeEstimator: FeeEstimator;
+    }): Promise<BeaconTxPlan>;
+    /**
+     * Sign + finalize the unsigned single-party tx and return its raw hex.
+     */
+    protected signSinglePartyTx(tx: Transaction, secretKey: KeyBytes): string;
+    /**
+     * Broadcast raw transaction hex via the Bitcoin REST endpoint. Returns the txid.
+     */
+    protected broadcastRawTx(bitcoin: BitcoinConnection, rawHex: string): Promise<string>;
 }
 //# sourceMappingURL=beacon.d.ts.map

package/dist/types/core/beacon/beacon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAIhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKnE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,MAAM;IAC1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;gBAEpB,OAAO,EAAE,aAAa;IAIlC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CACrB,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IAEtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CACtB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,QAAQ,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;cACa,qBAAqB,CACnC,WAAW,EAAE,UAAU,EACvB,SAAS,EAAE,QAAQ,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC;CAsEnB"}
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/beacon.ts"],"names":[],"mappings":"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"}

package/dist/types/core/beacon/utils.d.ts

@@ -1,5 +1,5 @@
+import type { BTCNetwork } from '@did-btcr2/bitcoin';
 import type { KeyBytes, Maybe } from '@did-btcr2/common';
-import type { networks } from 'bitcoinjs-lib';
 import type { DidDocument } from '../../utils/did-document.js';
 import type { BeaconService } from './interfaces.js';
 /**
@@ -53,7 +53,7 @@ export declare class BeaconUtils {
     static generateBeaconServices({ id, publicKey, network, beaconType }: {
         id: string;
         publicKey: KeyBytes;
-        network: networks.Network;
+        network: BTCNetwork;
         beaconType: string;
     }): Array<BeaconService>;
     /**

package/dist/types/core/beacon/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAC,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAC,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAO/C;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO;IAc1D;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,aAAa,EAAE;IAKnE;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IAiBlF;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa;IAsBpH;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;QACpE,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,QAAQ,CAAC;QACpB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,KAAK,CAAC,aAAa,CAAC;IAoCxB;;;;OAIG;IACH,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;IAIvE;;;;OAIG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC;IAQtF;;;;OAIG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;CAG/D"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAC,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAO/C;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO;IAc1D;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,aAAa,EAAE;IAKnE;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IAiBlF;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa;IA2BpH;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;QACpE,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,QAAQ,CAAC;QACpB,OAAO,EAAE,UAAU,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,KAAK,CAAC,aAAa,CAAC;IAoCxB;;;;OAIG;IACH,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;IAIvE;;;;OAIG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC;IAQtF;;;;OAIG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;CAG/D"}

package/dist/types/did-btcr2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"did-btcr2.d.ts","sourceRoot":"","sources":["../../src/did-btcr2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAS3C,OAAO,KAAK,EACV,SAAS,EAAC,MAAM,YAAY,CAAC;AAU/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,YAAW,SAAS;IACxC;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,CAAW;IAEpC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,GAAG,aAAa,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM;IAezF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CACZ,GAAG,EAAE,MAAM,EACX,iBAAiB,GAAE,iBAAsB,GACxC,QAAQ;IAsBX;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,MAAM,CAAC,EACZ,cAAc,EACd,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,QAAQ,GACT,EAAE;QACD,cAAc,EAAE,gBAAgB,CAAC;QACjC,OAAO,EAAE,cAAc,EAAE,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO;IA2DX;;;;;;;;;OASG;IACH,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,gBAAgB,EAAG,QAAQ,CAAC,EAAE,MAAM,GAAG,qBAAqB;CA0BlG"}
+{"version":3,"file":"did-btcr2.d.ts","sourceRoot":"","sources":["../../src/did-btcr2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAS3C,OAAO,KAAK,EACV,SAAS,EAAC,MAAM,YAAY,CAAC;AAQ/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,YAAW,SAAS;IACxC;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,CAAW;IAEpC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,GAAG,aAAa,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM;IAezF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CACZ,GAAG,EAAE,MAAM,EACX,iBAAiB,GAAE,iBAAsB,GACxC,QAAQ;IAsBX;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,MAAM,CAAC,EACZ,cAAc,EACd,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,QAAQ,GACT,EAAE;QACD,cAAc,EAAE,gBAAgB,CAAC;QACjC,OAAO,EAAE,cAAc,EAAE,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO;IA2DX;;;;;;;;;OASG;IACH,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,gBAAgB,EAAG,QAAQ,CAAC,EAAE,MAAM,GAAG,qBAAqB;CA0BlG"}

package/dist/types/index.d.ts

@@ -4,6 +4,8 @@ export * from './core/aggregation/cohort.js';
 export * from './core/aggregation/signing-session.js';
 export * from './core/aggregation/phases.js';
 export * from './core/aggregation/errors.js';
+export * from './core/aggregation/beacon-strategy.js';
+export * from './core/aggregation/logger.js';
 export * from './core/aggregation/messages/index.js';
 export * from './core/aggregation/transport/index.js';
 export * from './core/aggregation/runner/index.js';

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.28.0",
+  "version": "0.29.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",
@@ -64,7 +64,6 @@
     "bitcoin"
   ],
   "dependencies": {
-    "@bitcoinerlab/secp256k1": "^1.2.0",
     "@helia/strings": "^4.1.0",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
@@ -76,17 +75,16 @@
     "@web5/common": "^1.1.0",
     "@web5/crypto": "^1.0.6",
     "@web5/dids": "^1.2.0",
-    "bitcoinjs-lib": "7.0.0-rc.0",
     "canonicalize": "^2.1.0",
     "dotenv": "^16.6.1",
     "helia": "^5.5.1",
     "multiformats": "^13.4.2",
     "nostr-tools": "^2.23.3",
-    "@did-btcr2/bitcoin": "^0.5.3",
-    "@did-btcr2/cryptosuite": "^6.0.6",
     "@did-btcr2/smt": "^0.2.4",
-    "@did-btcr2/keypair": "^0.11.4",
-    "@did-btcr2/common": "^9.0.0"
+    "@did-btcr2/cryptosuite": "^6.0.6",
+    "@did-btcr2/bitcoin": "^0.6.0",
+    "@did-btcr2/common": "^9.0.0",
+    "@did-btcr2/keypair": "^0.11.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/aggregation/beacon-strategy.ts

@@ -0,0 +1,123 @@
+import { canonicalize } from '@did-btcr2/common';
+import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SerializedSMTProof } from '@did-btcr2/smt';
+import { blockHash, didToIndex, hashToHex, hexToHash, verifySerializedProof } from '@did-btcr2/smt';
+import type { AggregationCohort } from './cohort.js';
+import type { BaseBody } from './messages/base.js';
+
+/** Validation result returned to the participant for a distribute-data message. */
+export interface BeaconValidationResult {
+  matches: boolean;
+  casAnnouncement?: Record<string, string>;
+  smtProof?: SerializedSMTProof;
+}
+
+/** Per-participant body attached to DISTRIBUTE_AGGREGATED_DATA by the service. */
+export interface BeaconDistributePayload {
+  casAnnouncement?: Record<string, string>;
+  smtProof?: Record<string, unknown>;
+}
+
+/**
+ * Pluggable strategy for beacon-type-specific aggregation, distribution, and
+ * participant-side validation. Lets new beacon types be added without
+ * modifying the service or participant state machines: register a new strategy
+ * via {@link registerBeaconStrategy}.
+ */
+export interface AggregateBeaconStrategy {
+  /** String constant used as `beaconType` on CohortConfig / BaseMessage bodies. */
+  readonly type: string;
+
+  /**
+   * Service: build the aggregated data on the cohort after all updates are
+   * collected. Implementation should mutate the cohort (set signalBytes,
+   * casAnnouncement, smtProofs, etc.).
+   */
+  buildAggregatedData(cohort: AggregationCohort): void;
+
+  /**
+   * Service: produce the body fields to attach to DISTRIBUTE_AGGREGATED_DATA
+   * for a specific participant. Called once per cohort member.
+   */
+  getDistributePayload(cohort: AggregationCohort, participantDid: string): BeaconDistributePayload;
+
+  /**
+   * Participant: verify the aggregated data they received reflects their own
+   * submitted update. Pure function — returns matches + sidecar fields for
+   * the caller to store.
+   */
+  validateParticipantView(params: {
+    participantDid: string;
+    submittedUpdate: SignedBTCR2Update;
+    expectedHash: string;
+    body: BaseBody;
+  }): BeaconValidationResult;
+}
+
+const CAS_STRATEGY: AggregateBeaconStrategy = {
+  type : 'CASBeacon',
+
+  buildAggregatedData(cohort) {
+    cohort.buildCASAnnouncement();
+  },
+
+  getDistributePayload(cohort) {
+    return { casAnnouncement: cohort.casAnnouncement };
+  },
+
+  validateParticipantView({ participantDid, expectedHash, body }) {
+    const casAnnouncement = body.casAnnouncement;
+    if(!casAnnouncement) return { matches: false };
+    return {
+      matches : casAnnouncement[participantDid] === expectedHash,
+      casAnnouncement,
+    };
+  },
+};
+
+const SMT_STRATEGY: AggregateBeaconStrategy = {
+  type : 'SMTBeacon',
+
+  buildAggregatedData(cohort) {
+    cohort.buildSMTTree();
+  },
+
+  getDistributePayload(cohort, participantDid) {
+    const proof = cohort.smtProofs?.get(participantDid);
+    return { smtProof: proof as unknown as Record<string, unknown> | undefined };
+  },
+
+  validateParticipantView({ participantDid, submittedUpdate, body }) {
+    const smtProof = body.smtProof as unknown as SerializedSMTProof | undefined;
+    if(!smtProof?.updateId || !smtProof?.nonce) return { matches: false };
+    // Verify updateId matches the canonicalized update hash
+    const canonicalBytes = new TextEncoder().encode(canonicalize(submittedUpdate as unknown as Record<string, unknown>));
+    const expectedUpdateId = hashToHex(blockHash(canonicalBytes));
+    if(smtProof.updateId !== expectedUpdateId) {
+      return { matches: false, smtProof };
+    }
+    // Verify Merkle inclusion
+    const index = didToIndex(participantDid);
+    const candidateHash = blockHash(blockHash(hexToHash(smtProof.nonce)), hexToHash(smtProof.updateId));
+    return {
+      matches : verifySerializedProof(smtProof, index, candidateHash),
+      smtProof,
+    };
+  },
+};
+
+/** Registered strategies keyed by `beaconType` string. */
+const STRATEGIES: Map<string, AggregateBeaconStrategy> = new Map([
+  [CAS_STRATEGY.type, CAS_STRATEGY],
+  [SMT_STRATEGY.type, SMT_STRATEGY],
+]);
+
+/** Register a custom beacon strategy. Overwrites any existing entry with the same type. */
+export function registerBeaconStrategy(strategy: AggregateBeaconStrategy): void {
+  STRATEGIES.set(strategy.type, strategy);
+}
+
+/** Look up a registered beacon strategy by type, or undefined if not registered. */
+export function getBeaconStrategy(type: string): AggregateBeaconStrategy | undefined {
+  return STRATEGIES.get(type);
+}

package/src/core/aggregation/cohort.ts

@@ -2,9 +2,10 @@ import { canonicalHash, canonicalize, hash } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import type { SerializedSMTProof, TreeEntry } from '@did-btcr2/smt';
 import { BTCR2MerkleTree } from '@did-btcr2/smt';
+import { schnorr } from '@noble/curves/secp256k1.js';
 import { hexToBytes, randomBytes } from '@noble/hashes/utils';
+import { p2tr } from '@scure/btc-signer';
 import { keyAggExport, keyAggregate, sortKeys } from '@scure/btc-signer/musig2';
-import { crypto as btcCrypto, payments } from 'bitcoinjs-lib';
 import type { CASAnnouncement } from '../types.js';
 import { AggregationCohortError } from './errors.js';
 
@@ -48,11 +49,23 @@ export class AggregationCohort {
   /** List of participant DIDs that have been accepted into the cohort. */
   participants: Array<string> = [];
 
+  /**
+   * Mapping from participant DID → their compressed secp256k1 public key.
+   * Distinct from {@link cohortKeys} (which is sorted per BIP-327) — this lets
+   * callers look up a participant's key without knowing their position in the
+   * sorted array. Populated by the service at `acceptParticipant` time.
+   */
+  participantKeys: Map<string, Uint8Array> = new Map();
+
   /** Sorted list of cohort participants' compressed public keys. */
   #cohortKeys: Array<Uint8Array> = [];
 
-  /** Taproot tweak (BIP-341 key-path-only). */
-  trMerkleRoot: Uint8Array = new Uint8Array();
+  /**
+   * BIP-341 TapTweak — `taggedHash("TapTweak", internalPubkey)` for a key-path-only
+   * Taproot output. Despite prior naming, this is NOT a Merkle root: key-path-only
+   * spends have no script tree.
+   */
+  tapTweak: Uint8Array = new Uint8Array();
 
   /** The n-of-n MuSig2 Taproot beacon address. */
   beaconAddress: string = '';
@@ -94,7 +107,7 @@ export class AggregationCohort {
 
   /**
    * Computes the n-of-n MuSig2 Taproot beacon address from cohort keys.
-   * Sets `trMerkleRoot` to the BIP-341 key-path-only tweak.
+   * Sets `tapTweak` to the BIP-341 key-path-only tweak.
    */
   public computeBeaconAddress(): string {
     if(this.#cohortKeys.length === 0) {
@@ -105,11 +118,11 @@ export class AggregationCohort {
     }
     const keyAggContext = keyAggregate(this.#cohortKeys);
     const aggPubkey = keyAggExport(keyAggContext);
-    const payment = payments.p2tr({ internalPubkey: aggPubkey });
+    const payment = p2tr(aggPubkey);
 
-    // BIP-341: key-path-only P2TR has no script tree, so payment.hash is null.
-    // Compute the tweak: taggedHash("TapTweak", internalPubkey).
-    this.trMerkleRoot = payment.hash ?? btcCrypto.taggedHash('TapTweak', aggPubkey);
+    // BIP-341: key-path-only P2TR has no script tree. Compute the tweak:
+    // taggedHash("TapTweak", internalPubkey).
+    this.tapTweak = schnorr.utils.taggedHash('TapTweak', aggPubkey);
 
     if(!payment.address) {
       throw new AggregationCohortError(
@@ -147,6 +160,19 @@ export class AggregationCohort {
     }
   }
 
+  /**
+   * Returns the position of a participant's public key in the sorted
+   * {@link cohortKeys} array, or -1 if the participant is not in the cohort.
+   * Required by MuSig2 partial-sig verification which indexes by signer position.
+   */
+  public indexOfParticipant(did: string): number {
+    const pk = this.participantKeys.get(did);
+    if(!pk) return -1;
+    return this.#cohortKeys.findIndex(k =>
+      k.length === pk.length && k.every((b, i) => b === pk[i])
+    );
+  }
+
   public addUpdate(participantDid: string, signedUpdate: SignedBTCR2Update): void {
     if(!this.participants.includes(participantDid)) {
       throw new AggregationCohortError(