@did-btcr2/method 0.36.1 → 0.37.0

package/src/core/beacon/beacon.ts

@@ -16,28 +16,28 @@ const DEFAULT_FEE_ESTIMATOR: FeeEstimator = new StaticFeeEstimator(5);
 
 /**
  * Singleton beacon script kinds. Per the did:btcr2 spec, deterministic DID documents
- * include three beacon services: P2PKH, P2WPKH, and P2TR (taproot key-path) — all
+ * include three beacon services: P2PKH, P2WPKH, and P2TR (taproot key-path), all
  * derived from the genesis secp256k1 public key. The singleton broadcast path must
  * support signing for all three.
  */
 export type SingletonScriptKind = 'p2pkh' | 'p2wpkh' | 'p2tr';
 
 /**
- * Conservative vsize estimate for a 1-input P2TR key-path → 1 P2TR change + 1 OP_RETURN(32) tx.
+ * Conservative vsize estimate for a 1-input P2TR key-path to 1 P2TR change + 1 OP_RETURN(32) tx.
  * Stripped 137 + witness ≈ 68 (marker + flag + stack-count + sig-len + 64 BIP-340 sig).
  * Weight = 137*4 + 68 = 616, vsize ≈ 154, rounded to 160 for headroom.
  */
 export const P2TR_BEACON_TX_VSIZE = 160;
 
 /**
- * Conservative vsize estimate for a 1-input P2WPKH → 1 P2WPKH change + 1 OP_RETURN(32) tx.
+ * Conservative vsize estimate for a 1-input P2WPKH to 1 P2WPKH change + 1 OP_RETURN(32) tx.
  * Stripped 125 + witness ≈ 110 (worst-case DER ECDSA sig 72 + sighash byte + 33 pubkey + framing).
  * vsize = ceil((125*4 + 110) / 4) ≈ 153, rounded to 155.
  */
 export const P2WPKH_BEACON_TX_VSIZE = 155;
 
 /**
- * Conservative vsize estimate for a 1-input P2PKH → 1 P2PKH change + 1 OP_RETURN(32) tx.
+ * Conservative vsize estimate for a 1-input P2PKH to 1 P2PKH change + 1 OP_RETURN(32) tx.
  * Legacy (non-segwit): scriptSig carries the full sig+pubkey (~108 bytes), no witness
  * discount. Stripped ≈ 4 nVer + 1 vin-count + (32+4+1+108+4) input + 1 vout-count +
  * 34 P2PKH-change + 43 OP_RETURN + 4 nLockTime ≈ 236 bytes. vsize = 236, rounded to 240.
@@ -169,7 +169,7 @@ async function fetchSpendableUtxo(
  * signing session consumes (via {@link SigningTxData}).
  *
  * This is the reusable counterpart to {@link SinglePartyBeacon.buildSignAndBroadcast}'s internal
- * construction step — the aggregation path must produce an unsigned tx because the
+ * 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.
@@ -192,8 +192,13 @@ export async function buildAggregationBeaconTx(opts: {
   const feeEstimator = opts.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
   const { utxo, prevTxBytes } = await fetchSpendableUtxo(opts.beaconAddress, opts.bitcoin);
 
-  const tapOut = p2tr(opts.internalPubkey, undefined, opts.network);
-  const witnessScript = tapOut.script;
+  // The funded beacon output is a Taproot script-tree output: key path is the
+  // MuSig2 aggregate, script path is the k-of-n fallback + CSV recovery leaves
+  // (see cohort.ts and ADR 042). Derive the witnessUtxo scriptPubKey from the
+  // funded address itself; recomputing a key-path-only p2tr(internalPubkey) here
+  // would not match the script-tree UTXO on chain and would invalidate both the
+  // key-path sighash and the fallback script-path sighash.
+  const witnessScript = OutScript.encode(Address(opts.network).decode(opts.beaconAddress));
 
   // Fee cannot be probe-measured (no secret key for MuSig2 round). Use fixed P2TR vsize.
   const feeSats = await feeEstimator.estimateFee(P2TR_BEACON_TX_VSIZE);
@@ -258,7 +263,7 @@ async function signSingletonInput(
     // directly. We need only the sighash bytes so an external Signer can produce
     // the signature, so we reach through the type system here. If scure ever
     // renames this method, the P2PKH path tests fail loudly.
-    // TODO: track https://github.com/paulmillr/scure-btc-signer/issues/142 —
+    // TODO: track https://github.com/paulmillr/scure-btc-signer/issues/142 -
     // drop the cast once a public preimage (e.g. `preimageP2PKH`) lands upstream.
     const sighashType = SigHash.ALL;
     const sighash = (tx as unknown as {
@@ -302,7 +307,7 @@ async function signSingletonInput(
   // `d' = taprootTweakPrivKey(d, merkleRoot)`; the verifier checks against the
   // tweaked output internal key `Q = P + tG`. The tweak lives inside the Signer
   // (it needs the secret key), so we use scheme 'bip341' rather than the raw
-  // 'bip340' scheme. No script tree on singleton beacons → no merkleRoot.
+  // 'bip340' scheme. No script tree on singleton beacons, no merkleRoot.
   const sighash = tx.preimageWitnessV1(inputIdx, [prevOutScript], SigHash.DEFAULT, [amount]);
   const sig = signer.sign(sighash, 'bip341');
   tx.updateInput(inputIdx, { tapKeySig: sig });
@@ -377,7 +382,7 @@ export abstract class SinglePartyBeacon {
    *
    * 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 —
+   * 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.
    *
@@ -409,7 +414,7 @@ export abstract class SinglePartyBeacon {
    *
    * Detects the beacon address script kind (P2PKH / P2WPKH / P2TR) and configures
    * the input accordingly. Validates that the signer's pubkey produces the beacon
-   * address under that script kind — without this check, a misconfigured caller
+   * address under that script kind: without this check, a misconfigured caller
    * would burn a real UTXO on a tx that fails at broadcast. Fees are computed from
    * the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant, avoiding any probe-sign
    * round-trip.

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

@@ -9,7 +9,7 @@ import { SinglePartyBeacon } from './beacon.js';
 import type { BeaconService, BeaconSignal, BlockMetadata, CasPublishFn } from './interfaces.js';
 
 /**
- * CAS-specific broadcast options — extends {@link BroadcastOptions} with an optional
+ * CAS-specific broadcast options: extends {@link BroadcastOptions} with an optional
  * `casPublish` callback used to publish the CAS Announcement off-chain after the
  * OP_RETURN signal is broadcast.
  */
@@ -21,7 +21,7 @@ export interface CASBroadcastOptions extends BroadcastOptions {
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#cas-beacon | CAS Beacon}.
  *
  * A CAS (Content-Addressed Store) Beacon aggregates updates for multiple DIDs
- * into a single CAS Announcement — a mapping of DIDs to their update hashes.
+ * into a single CAS Announcement: a mapping of DIDs to their update hashes.
  * The hash of the CAS Announcement is broadcast on-chain via OP_RETURN.
  * During resolution, the CAS Announcement is retrieved from the sidecar (or CAS)
  * and used to look up the individual signed update for the DID being resolved.
@@ -63,14 +63,14 @@ export class CASBeacon extends SinglePartyBeacon {
     const did = this.service.id.split('#')[0];
 
     for(const signal of signals) {
-      // Signal bytes are hex — matches hex-keyed sidecar maps directly
+      // Signal bytes are hex, matches hex-keyed sidecar maps directly
       const announcementHash = signal.signalBytes;
 
       // Look up the CAS Announcement in sidecar casMap
       const casAnnouncement = sidecar.casMap.get(announcementHash);
 
       if(!casAnnouncement) {
-        // CAS Announcement not available — emit a need
+        // CAS Announcement not available, emit a need
         needs.push({
           kind              : 'NeedCASAnnouncement',
           announcementHash,
@@ -80,10 +80,10 @@ export class CASBeacon extends SinglePartyBeacon {
       }
 
       // Look up this DID's update hash in the CAS Announcement
-      // Announcement values are base64urlnopad per spec — convert to hex for map lookup
+      // Announcement values are base64urlnopad per spec, convert to hex for map lookup
       const updateHashEncoded = casAnnouncement[did];
 
-      // If no entry for this DID, this announcement doesn't contain an update for us — skip
+      // If no entry for this DID, this announcement doesn't contain an update for us, skip
       if(!updateHashEncoded) {
         continue;
       }
@@ -94,7 +94,7 @@ export class CASBeacon extends SinglePartyBeacon {
       const signedUpdate = sidecar.updateMap.get(updateHash);
 
       if(!signedUpdate) {
-        // Signed update not available — emit a need
+        // Signed update not available, emit a need
         needs.push({
           kind             : 'NeedSignedUpdate',
           updateHash,

package/src/core/beacon/interfaces.ts

@@ -71,6 +71,6 @@ export interface BeaconSignal {
  * The method package defines this type; the api layer provides the implementation
  * (e.g., via CasApi.publish backed by IPFS/Helia).
  *
- * @param announcement The CAS Announcement object (DID → update hash mapping).
+ * @param announcement The CAS Announcement object (DID to update hash mapping).
  */
 export type CasPublishFn = (announcement: Record<string, string>) => Promise<void>;

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

@@ -38,14 +38,14 @@ export class SingletonBeacon extends SinglePartyBeacon {
     const needs = new Array<DataNeed>();
 
     for(const signal of signals) {
-      // Signal bytes are hex — matches hex-keyed sidecar maps directly
+      // Signal bytes are hex, matches hex-keyed sidecar maps directly
       const updateHash = signal.signalBytes;
 
       // Look up the signed update in sidecar updateMap
       const signedUpdate = sidecar.updateMap.get(updateHash);
 
       if(!signedUpdate) {
-        // Data not available — emit a need instead of throwing
+        // Data not available, emit a need instead of throwing
         needs.push({
           kind             : 'NeedSignedUpdate',
           updateHash,

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

@@ -60,7 +60,7 @@ export class SMTBeacon extends SinglePartyBeacon {
       const smtProof = sidecar.smtMap.get(signal.signalBytes);
 
       if(!smtProof) {
-        // SMT Proof not available — emit a need
+        // SMT Proof not available, emit a need
         needs.push({
           kind            : 'NeedSMTProof',
           smtRootHash     : signal.signalBytes,
@@ -95,7 +95,7 @@ export class SMTBeacon extends SinglePartyBeacon {
         );
       }
 
-      // Non-inclusion proof verified — no update for this DID this epoch, skip.
+      // Non-inclusion proof verified: no update for this DID this epoch, skip.
       if(!smtProof.updateId) {
         continue;
       }
@@ -106,7 +106,7 @@ export class SMTBeacon extends SinglePartyBeacon {
       const signedUpdate = sidecar.updateMap.get(updateHashHex);
 
       if(!signedUpdate) {
-        // Signed update not available — emit a need
+        // Signed update not available, emit a need
         needs.push({
           kind             : 'NeedSignedUpdate',
           updateHash       : updateHashHex,

package/src/core/resolver.ts

@@ -164,7 +164,7 @@ export class Resolver {
   #resolvedResponse: DidResolutionResponse | null = null;
 
   /**
-   * @internal — Use {@link DidBtcr2.resolve} to create instances.
+   * @internal Use {@link DidBtcr2.resolve} to create instances.
    */
   constructor(
     didComponents: DidComponents,
@@ -540,13 +540,13 @@ export class Resolver {
 
   /**
    * Advance the state machine. Returns either:
-   * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
-   * - `{ status: 'resolved', result }` — resolution complete
+   * - `{ status: 'action-required', needs }` - caller must provide data via {@link provide}
+   * - `{ status: 'resolved', result }` - resolution complete
    *
    * Analogous to Rust's `Resolver::resolve()`.
    */
   resolve(): ResolverState {
-    // Internal loop — keeps advancing through phases until data is needed or done
+    // Internal loop: keeps advancing through phases until data is needed or done
     while(true) {
       switch(this.#phase) {
 
@@ -554,7 +554,7 @@ export class Resolver {
         // Only entered for EXTERNAL (x HRP) identifiers when genesis doc was not in sidecar.
         case ResolverPhase.GenesisDocument: {
           if(this.#providedGenesisDocument) {
-            // Genesis doc was provided — establish the current document
+            // Genesis doc was provided, establish the current document
             this.#currentDocument = Resolver.external(
               this.#didComponents, this.#providedGenesisDocument
             );
@@ -595,7 +595,7 @@ export class Resolver {
             };
           }
 
-          // No new beacon services to query — move to processing
+          // No new beacon services to query, move to processing
           this.#phase = ResolverPhase.BeaconProcess;
           continue;
         }
@@ -614,10 +614,10 @@ export class Resolver {
             const result = beacon.processSignals(signals, this.#sidecarData);
 
             if(result.needs.length > 0) {
-              // This service has unmet data needs — collect them
+              // This service has unmet data needs, collect them
               allNeeds.push(...result.needs);
             } else {
-              // All signals for this service resolved — collect updates, mark processed
+              // All signals for this service resolved, collect updates, mark processed
               this.#unsortedUpdates.push(...result.updates);
               this.#processedServices.add(service.id);
             }

package/src/core/updater.ts

@@ -116,7 +116,7 @@ export interface UpdaterParams {
 }
 
 /**
- * Sans-I/O state machine for did:btcr2 updates — the counterpart to {@link Resolver}.
+ * 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}:
@@ -168,7 +168,7 @@ export class Updater {
   readonly #beaconService: BeaconService;
 
   /**
-   * @internal — Use {@link DidBtcr2.update} to create instances.
+   * @internal Use {@link DidBtcr2.update} to create instances.
    */
   constructor(params: UpdaterParams) {
     this.#sourceDocument = params.sourceDocument;
@@ -216,7 +216,7 @@ export class Updater {
     // checks W3C conformance but not this equality, so it's enforced explicitly here.
     if(targetDocument.id !== sourceDocument.id) {
       throw new UpdateError(
-        `Patches must not change the DID document id (source "${sourceDocument.id}" → target "${targetDocument.id}").`,
+        `Patches must not change the DID document id (source "${sourceDocument.id}" to target "${targetDocument.id}").`,
         INVALID_DID_UPDATE, { sourceId: sourceDocument.id, targetId: targetDocument.id }
       );
     }
@@ -315,8 +315,8 @@ export class Updater {
 
   /**
    * 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
+   * - `{ status: 'action-required', needs }` caller must provide data via {@link provide}
+   * - `{ status: 'complete', result }` update is signed and broadcast
    */
   advance(): UpdaterState {
     while(true) {
@@ -331,7 +331,7 @@ export class Updater {
         }
 
         // Phase: Sign
-        // Emit NeedSigningKey — the caller supplies the secret key (or a KMS signature).
+        // Emit NeedSigningKey: the caller supplies the secret key (or a KMS signature).
         case 'Sign': {
           return {
             status : 'action-required',

package/src/did-btcr2.ts

@@ -135,8 +135,8 @@ export class DidBtcr2 implements DidMethod {
    *
    * 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
+   * 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

package/src/index.ts

@@ -3,6 +3,9 @@ export * from './core/aggregation/service.js';
 export * from './core/aggregation/participant.js';
 export * from './core/aggregation/signer.js';
 export * from './core/aggregation/conditions.js';
+export * from './core/aggregation/recovery-policy.js';
+export * from './core/aggregation/recovery-spend.js';
+export * from './core/aggregation/fallback-spend.js';
 export * from './core/aggregation/cohort.js';
 export * from './core/aggregation/signing-session.js';
 export * from './core/aggregation/phases.js';