@did-btcr2/method 0.27.0 → 0.29.0

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/core/updater.d.ts

@@ -0,0 +1,178 @@
+import type { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type { KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { type SignedBTCR2Update, type UnsignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
+import type { BeaconService } from './beacon/interfaces.js';
+/**
+ * The updater needs the caller to supply a signing key (or a KMS-backed signature)
+ * for the given verification method. The unsigned update is attached so the caller
+ * can inspect it before producing a signature.
+ */
+export interface NeedSigningKey {
+    readonly kind: 'NeedSigningKey';
+    /** The verification method ID that requires a signing key. */
+    readonly verificationMethodId: string;
+    /** The unsigned update that will be signed. */
+    readonly unsignedUpdate: UnsignedBTCR2Update;
+}
+/**
+ * The updater needs the caller to ensure the beacon address is funded before
+ * broadcasting. The caller checks the beacon address for UTXOs, funds it if
+ * needed, and then calls `updater.provide(need)` to continue.
+ *
+ * If the beacon is already funded, the caller can provide immediately (no-op).
+ */
+export interface NeedFunding {
+    readonly kind: 'NeedFunding';
+    /** The Bitcoin address that must have a spendable UTXO for broadcast. */
+    readonly beaconAddress: string;
+    /** The beacon service this address belongs to. */
+    readonly beaconService: BeaconService;
+}
+/**
+ * The updater needs the caller to broadcast the signed update via the beacon.
+ *
+ * The caller decides how: for single-party beacons, call
+ * `Updater.announce(beaconService, signedUpdate, secretKey, bitcoin)` or
+ * `BeaconFactory.establish(beaconService).broadcastSignal(...)`. For multi-party
+ * aggregate beacons, hand off to the aggregation protocol.
+ *
+ * After the broadcast succeeds, the caller calls `updater.provide(need)` (with no
+ * data) to transition the updater to Complete.
+ */
+export interface NeedBroadcast {
+    readonly kind: 'NeedBroadcast';
+    /** The beacon service to broadcast through. Inspect `beaconService.type` to decide the path. */
+    readonly beaconService: BeaconService;
+    /** The signed update ready for broadcast. */
+    readonly signedUpdate: SignedBTCR2Update;
+}
+/** Discriminated union of all data needs the updater may request from the caller. */
+export type UpdaterDataNeed = NeedSigningKey | NeedFunding | NeedBroadcast;
+/**
+ * The result returned by the updater when it reaches the Complete phase.
+ */
+export interface UpdaterResult {
+    /** The signed update that was constructed, signed, and broadcast. */
+    signedUpdate: SignedBTCR2Update;
+}
+/**
+ * Output of {@link Updater.advance}. Either the updater needs data from the
+ * caller, or the update is complete.
+ */
+export type UpdaterState = {
+    status: 'action-required';
+    needs: ReadonlyArray<UpdaterDataNeed>;
+} | {
+    status: 'complete';
+    result: UpdaterResult;
+};
+/**
+ * Parameters for constructing an {@link Updater}. Built by
+ * {@link https://dcdpr.github.io/did-btcr2/operations/update.html | DidBtcr2.update}.
+ */
+export interface UpdaterParams {
+    sourceDocument: Btcr2DidDocument;
+    patches: PatchOperation[];
+    sourceVersionId: number;
+    verificationMethod: DidVerificationMethod;
+    beaconService: BeaconService;
+}
+/**
+ * Sans-I/O state machine for did:btcr2 updates — the counterpart to {@link Resolver}.
+ *
+ * Created by {@link DidBtcr2.update} (the factory). The caller drives the update by
+ * repeatedly calling {@link advance} and {@link provide}:
+ *
+ * ```typescript
+ * const updater = DidBtcr2.update({ sourceDocument, patches, ... });
+ * 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();
+ * }
+ *
+ * const { signedUpdate } = state.result;
+ * ```
+ *
+ * The Updater performs **zero I/O**. All external work (signing with a KMS or raw
+ * key, funding checks, Bitcoin transaction construction, broadcast) flows through
+ * the advance/provide protocol. This mirrors the {@link Resolver} pattern and makes
+ * the update path transport-agnostic and KMS-ready.
+ *
+ * The class also exposes static utility methods ({@link construct}, {@link sign},
+ * {@link announce}) for callers that need direct access to individual update steps
+ * outside the state machine (e.g., test vector generation scripts).
+ *
+ * @class Updater
+ */
+export declare class Updater {
+    #private;
+    /**
+     * @internal — Use {@link DidBtcr2.update} to create instances.
+     */
+    constructor(params: UpdaterParams);
+    /**
+     * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-unsigned-update | 7.3.b Construct BTCR2 Unsigned Update}.
+     *
+     * @param {Btcr2DidDocument} sourceDocument The source DID document to be updated.
+     * @param {PatchOperation[]} patches The JSON Patch operations to apply.
+     * @param {number} sourceVersionId The version ID of the source document.
+     * @returns {UnsignedBTCR2Update} The constructed UnsignedBTCR2Update object.
+     * @throws {UpdateError} If the target document fails DID Core validation.
+     */
+    static construct(sourceDocument: Btcr2DidDocument, patches: PatchOperation[], sourceVersionId: number): UnsignedBTCR2Update;
+    /**
+     * Implements subsection {@link http://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-signed-update | 7.3.c Construct BTCR2 Signed Update }.
+     *
+     * @param {string} did The did-btcr2 identifier to derive the root capability from.
+     * @param {UnsignedBTCR2Update} unsignedUpdate The unsigned update to sign.
+     * @param {DidVerificationMethod} verificationMethod The verification method for signing.
+     * @param {KeyBytes} secretKey The secret key bytes.
+     * @returns {SignedBTCR2Update} The signed update with a Data Integrity proof.
+     */
+    static sign(did: string, unsignedUpdate: UnsignedBTCR2Update, verificationMethod: DidVerificationMethod, secretKey: KeyBytes): SignedBTCR2Update;
+    /**
+     * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#announce-did-update | 7.3.d Announce DID Update}.
+     * Announces a signed update to the Bitcoin blockchain via the specified beacon.
+     *
+     * @param {BeaconService} beaconService The beacon service to broadcast through.
+     * @param {SignedBTCR2Update} update The signed update to announce.
+     * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+     * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
+     * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+     */
+    static announce(beaconService: BeaconService, update: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection): Promise<SignedBTCR2Update>;
+    /**
+     * Advance the state machine. Returns either:
+     * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
+     * - `{ status: 'complete', result }` — update is signed and broadcast
+     */
+    advance(): UpdaterState;
+    /**
+     * Provide data the updater requested in a previous {@link advance} call.
+     * Call once per need, then call {@link advance} again to continue.
+     *
+     * @param need The DataNeed being fulfilled (from the `needs` array).
+     * @param data The data payload corresponding to the need kind (omit for NeedFunding/NeedBroadcast).
+     */
+    provide(need: NeedSigningKey, data: KeyBytes): void;
+    provide(need: NeedFunding): void;
+    provide(need: NeedBroadcast): void;
+}
+//# sourceMappingURL=updater.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../../src/core/updater.ts"],"names":[],"mappings":"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"}

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

@@ -1,9 +1,8 @@
-import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { DocumentBytes, HexString, KeyBytes, PatchOperation } from '@did-btcr2/common';
-import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { DocumentBytes, KeyBytes, PatchOperation } from '@did-btcr2/common';
 import type { DidMethod } from '@web5/dids';
 import type { ResolutionOptions } from './core/interfaces.js';
 import { Resolver } from './core/resolver.js';
+import { Updater } from './core/updater.js';
 import type { Btcr2DidDocument, DidVerificationMethod } from './utils/did-document.js';
 export interface DidCreateOptions {
     /** Type of identifier to create (key or external) */
@@ -71,34 +70,35 @@ export declare class DidBtcr2 implements DidMethod {
      */
     static resolve(did: string, resolutionOptions?: ResolutionOptions): Resolver;
     /**
-     * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#read | 7.3 Update}.
-     * See specification for the {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#process | Resolve Process}.
-     * See {@link Update | Update (class)} for class implementation.
+     * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#update | 7.3 Update}.
      *
-     * BTCR2 DID documents can be updated by anchoring BTCR2 Updates to Bitcoin transactions. These transactions MAY be
-     * published to the Bitcoin network. Any property in the DID document may be updated except the id. Doing so would
-     * invalidate the DID document.
-     * @param params An object containing the parameters for the update operation.
+     * Factory method that validates the update parameters and returns a sans-I/O
+     * {@link Updater} state machine. The caller drives the updater through its
+     * phases (Construct → Sign → Broadcast → Complete) by calling `advance()` and
+     * `provide()`. The method package performs **zero I/O** — signing key retrieval
+     * (or KMS delegation) and the on-chain broadcast are the caller's responsibility.
+     *
+     * For a fully-wired version with Bitcoin broadcast and key handling, see
+     * `DidMethodApi.update()` in `@did-btcr2/api`.
+     *
+     * @param params Update construction parameters.
      * @param {Btcr2DidDocument} params.sourceDocument The DID document being updated.
-     * @param {PatchOperation[]} params.patches The array of JSON Patch operations to apply to the sourceDocument.
-     * @param {string} params.sourceVersionId The version ID before applying the update.
-     * @param {string} params.verificationMethodId The verificationMethod ID to sign the update with.
-     * @param {string} params.beaconId The beacon ID associated with the update.
-     * @param {KeyBytes | HexString} [params.signingMaterial] Optional signing material (key bytes or hex string).
-     * @param {BitcoinConnection} [params.bitcoin] Optional Bitcoin network connection for announcing the update. If not provided, a default connection will be initialized.
-     * @return {Promise<SignedBTCR2Update>} Promise resolving to the signed BTCR2 update.
-     * @throws {UpdateError} if no verificationMethod, verificationMethod type is not `Multikey` or the publicKeyMultibase
-     * header is not `zQ3s`
+     * @param {PatchOperation[]} params.patches The JSON Patch operations to apply.
+     * @param {number} params.sourceVersionId The version ID before applying the update.
+     * @param {string} params.verificationMethodId The verification method ID to sign with.
+     * @param {string} params.beaconId The beacon service ID to broadcast through.
+     * @returns {Updater} A sans-I/O state machine for driving the update.
+     * @throws {UpdateError} If the verification method is not authorized, not found,
+     *   not of type `Multikey`, or does not have a `zQ3s` publicKeyMultibase prefix.
+     *   Also throws if the beacon service is not found.
      */
-    static update({ sourceDocument, patches, sourceVersionId, verificationMethodId, beaconId, signingMaterial, bitcoin, }: {
+    static update({ sourceDocument, patches, sourceVersionId, verificationMethodId, beaconId, }: {
         sourceDocument: Btcr2DidDocument;
         patches: PatchOperation[];
         sourceVersionId: number;
         verificationMethodId: string;
         beaconId: string;
-        signingMaterial?: KeyBytes | HexString;
-        bitcoin?: BitcoinConnection;
-    }): Promise<SignedBTCR2Update>;
+    }): Updater;
     /**
      * Given the W3C DID Document of a `did:btcr2` identifier, return the signing verification method that will be used
      * for signing messages and credentials. If given, the `methodId` parameter is used to select the

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,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,QAAQ,EACR,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAS3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EACV,SAAS,EAAC,MAAM,YAAY,CAAC;AAW/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,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;;;;;;;;;;;;;;;;;;;OAmBG;WACU,MAAM,CAAC,EAClB,cAAc,EACd,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,QAAQ,EACR,eAAe,EACf,OAAO,GACR,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;QACjB,eAAe,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;QACvC,OAAO,CAAC,EAAE,iBAAiB,CAAC;KAC7B,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoF9B;;;;;;;;;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';
@@ -11,6 +13,7 @@ export * from './core/beacon/beacon.js';
 export * from './core/beacon/cas-beacon.js';
 export * from './core/beacon/error.js';
 export * from './core/beacon/factory.js';
+export * from './core/beacon/fee-estimator.js';
 export * from './core/beacon/interfaces.js';
 export * from './core/beacon/signal-discovery.js';
 export * from './core/beacon/singleton-beacon.js';
@@ -20,7 +23,7 @@ export * from './core/identifier.js';
 export * from './core/interfaces.js';
 export * from './core/resolver.js';
 export * from './core/types.js';
-export * from './core/update.js';
+export * from './core/updater.js';
 export * from './utils/appendix.js';
 export * from './utils/did-document-builder.js';
 export * from './utils/did-document.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,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,kBAAkB,CAAC;AAGjC,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.27.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,16 +75,15 @@
     "@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/common": "^9.0.0",
-    "@did-btcr2/cryptosuite": "^6.0.6",
     "@did-btcr2/smt": "^0.2.4",
+    "@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": {

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);
+}