@did-btcr2/method 0.36.1 → 0.38.0

package/src/core/beacon/beacon.ts

@@ -7,37 +7,34 @@ import { Address, OutScript, p2pkh, p2tr, p2wpkh, Script, SigHash, Transaction }
 import type { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import { BeaconError } from './error.js';
-import { StaticFeeEstimator } from './fee-estimator.js';
+import { DEFAULT_FEE_ESTIMATOR } from './fee-estimator.js';
 import type { FeeEstimator } from './fee-estimator.js';
 import type { BeaconService, BeaconSignal } from './interfaces.js';
 
-/** Default fee estimator used when none is supplied. ~5 sat/vB static rate. */
-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.
@@ -51,6 +48,54 @@ export const SINGLETON_BEACON_TX_VSIZE: Readonly<Record<SingletonScriptKind, num
   p2tr   : P2TR_BEACON_TX_VSIZE,
 };
 
+/**
+ * Serialized size (vbytes) of a single change output, by script kind:
+ * 8 (value) + 1 (scriptPubKey length) + scriptPubKey bytes. P2PKH 25, P2WPKH 22,
+ * P2TR 34. These are non-witness bytes, so each contributes its full byte count to
+ * the transaction vsize. The {@link SINGLETON_BEACON_TX_VSIZE} constants bake in a
+ * same-kind change output; {@link beaconTxVsize} uses these deltas to re-size the
+ * fee when a caller routes change to an address of a different kind (ADR 044).
+ */
+export const CHANGE_OUTPUT_VBYTES: Readonly<Record<SingletonScriptKind, number>> = {
+  p2pkh  : 34,
+  p2wpkh : 31,
+  p2tr   : 43,
+};
+
+/**
+ * Dust threshold (sats) below which a change output is not worth creating, by script
+ * kind (the standard Bitcoin Core dust relay thresholds at the default 3 sat/vB dust
+ * rate). When the change after fees falls below this, the builders omit the change
+ * output and let the remainder fall into the fee rather than emit an unspendable,
+ * relay-rejected dust output (ADR 044).
+ */
+export const DUST_LIMIT_SATS: Readonly<Record<SingletonScriptKind, number>> = {
+  p2pkh  : 546,
+  p2wpkh : 294,
+  p2tr   : 330,
+};
+
+/**
+ * vsize (vbytes) for a beacon transaction that spends one input of `beaconKind`
+ * and returns change to an output of `changeKind`, plus the OP_RETURN(32) signal.
+ *
+ * When `changeKind === beaconKind` (the default, change to the beacon address) this
+ * returns the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant unchanged, so the
+ * default path and the constants' lock-in tests are byte-identical. A differing
+ * `changeKind` swaps the assumed same-kind change output for the actual one, keeping
+ * the result a valid upper bound. The aggregation key-path spend is the
+ * `beaconKind: 'p2tr'` case (its input is always the cohort's P2TR key path; only the
+ * change output varies), the analytical sizing ADR 045 calls for, computed without a
+ * secret.
+ */
+export function beaconTxVsize(
+  beaconKind: SingletonScriptKind,
+  changeKind: SingletonScriptKind,
+): number {
+  const base = SINGLETON_BEACON_TX_VSIZE[beaconKind] - CHANGE_OUTPUT_VBYTES[beaconKind];
+  return base + CHANGE_OUTPUT_VBYTES[changeKind];
+}
+
 /**
  * Detect the singleton script kind of a Bitcoin address (P2PKH / P2WPKH / P2TR).
  * The deterministic-DID document emits all three kinds; the broadcast path needs
@@ -88,12 +133,56 @@ export function deriveSingletonAddress(
   return p2tr(pubkey.slice(1, 33), undefined, network).address!;
 }
 
+/**
+ * Resolve the change-output recipient for a beacon transaction. Returns the beacon
+ * address when no change address is supplied (preserving the prior behavior of
+ * returning change to the spent address), otherwise validates the caller-supplied
+ * address against the network and returns it. Validating here fails fast rather than
+ * burning a real UTXO on a transaction that breaks at broadcast (ADR 044).
+ */
+export function resolveChangeAddress(
+  beaconAddress: string,
+  network: BTCNetwork,
+  changeAddress?: string,
+): string {
+  if(!changeAddress || changeAddress === beaconAddress) return beaconAddress;
+  try {
+    Address(network).decode(changeAddress);
+  } catch {
+    throw new BeaconError(
+      `Invalid change address "${changeAddress}" for network "${network}".`,
+      'INVALID_CHANGE_ADDRESS',
+      { changeAddress, network }
+    );
+  }
+  return changeAddress;
+}
+
+/**
+ * Detect the change output's script kind for fee sizing. A change address that is not
+ * one of the three singleton kinds (for example P2SH or P2WSH) is sized as P2TR, the
+ * largest standard change output, so the estimated fee stays a valid upper bound.
+ */
+function changeOutputKind(changeAddress: string, network: BTCNetwork): SingletonScriptKind {
+  try {
+    return detectSingletonScriptKind(changeAddress, network);
+  } catch {
+    return 'p2tr';
+  }
+}
+
 /**
  * Options accepted by {@link SinglePartyBeacon.buildSignAndBroadcast} and related helpers.
  */
 export interface BroadcastOptions {
   /** Fee estimator for computing the transaction fee. Defaults to {@link DEFAULT_FEE_ESTIMATOR}. */
   feeEstimator?: FeeEstimator;
+  /**
+   * Address to send change to. Defaults to the beacon address (reuses the spent
+   * address, the prior behavior). Supply a fresh address the controller owns to
+   * stop linking the beacon's announcements into one on-chain chain (ADR 044).
+   */
+  changeAddress?: string;
 }
 
 /**
@@ -107,8 +196,10 @@ export interface BeaconTxPlan {
   prevOutScripts: Uint8Array[];
   /** Amounts (sats) of the consumed previous outputs. */
   prevOutValues: bigint[];
-  /** Address change was sent back to (same as the beacon address). */
+  /** The beacon address this tx spends from. */
   beaconAddress: string;
+  /** Address the change output was sent to (the beacon address unless a change address was supplied). */
+  changeAddress: string;
   /** The UTXO this tx consumes. */
   utxo: AddressUtxo;
   /** The fee (sats) already deducted from the change output. */
@@ -169,7 +260,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.
@@ -188,15 +279,31 @@ export async function buildAggregationBeaconTx(opts: {
   network: BTCNetwork;
   /** Optional fee estimator (defaults to 5 sat/vB). */
   feeEstimator?: FeeEstimator;
+  /**
+   * Address to send change to. Defaults to the beacon (cohort) address. Supply the
+   * funder's address (an operator-funded cohort's funding wallet) to stop reusing the
+   * cohort address for change (ADR 044). Change ownership is the funder's call, which
+   * the cohort-condition model leaves to the caller (ADR 039).
+   */
+  changeAddress?: string;
 }): Promise<BeaconTxPlan> {
   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;
-
-  // Fee cannot be probe-measured (no secret key for MuSig2 round). Use fixed P2TR vsize.
-  const feeSats = await feeEstimator.estimateFee(P2TR_BEACON_TX_VSIZE);
+  const changeAddress = resolveChangeAddress(opts.beaconAddress, opts.network, opts.changeAddress);
+
+  // 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));
+
+  // The fee cannot be probe-measured (no secret key until the downstream MuSig2
+  // round), so size it analytically. The input is the cohort's P2TR key path; only
+  // the change output's kind varies, so the vsize follows the change address (ADR 045).
+  const changeKind = changeOutputKind(changeAddress, opts.network);
+  const feeSats = await feeEstimator.estimateFee(beaconTxVsize('p2tr', changeKind));
   if(BigInt(utxo.value) <= feeSats) {
     throw new BeaconError(
       `UTXO value (${utxo.value}) insufficient to cover fee (${feeSats}).`,
@@ -216,7 +323,12 @@ export async function buildAggregationBeaconTx(opts: {
     witnessUtxo    : { amount: BigInt(utxo.value), script: witnessScript },
     tapInternalKey : opts.internalPubkey,
   });
-  tx.addOutputAddress(opts.beaconAddress, BigInt(utxo.value) - feeSats, opts.network);
+  // Change first (omitted when it would be dust, sweeping the remainder into the
+  // fee), then the OP_RETURN signal, which the spec requires to be the last output.
+  const changeValue = BigInt(utxo.value) - feeSats;
+  if(changeValue >= BigInt(DUST_LIMIT_SATS[changeKind])) {
+    tx.addOutputAddress(changeAddress, changeValue, opts.network);
+  }
   tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
 
   return {
@@ -224,6 +336,7 @@ export async function buildAggregationBeaconTx(opts: {
     prevOutScripts : [witnessScript],
     prevOutValues  : [BigInt(utxo.value)],
     beaconAddress  : opts.beaconAddress,
+    changeAddress,
     utxo,
     feeSats,
     scriptKind     : 'p2tr',
@@ -258,7 +371,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 +415,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 +490,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.
    *
@@ -399,6 +512,7 @@ export abstract class SinglePartyBeacon {
     const { utxo, prevTxBytes } = await fetchSpendableUtxo(beaconAddress, bitcoin);
     const plan = await this.buildSinglePartyTx({
       signalBytes, beaconAddress, utxo, prevTxBytes, signer, bitcoin, feeEstimator,
+      changeAddress : options?.changeAddress,
     });
     const signedHex = await this.signSinglePartyTx(plan, signer);
     return this.broadcastRawTx(bitcoin, signedHex);
@@ -409,10 +523,11 @@ 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.
+   * the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant (via {@link beaconTxVsize}),
+   * avoiding any probe-sign round-trip; a change address of a different kind re-sizes
+   * the fee by the change output's size delta so it stays a valid upper bound.
    */
   protected async buildSinglePartyTx(opts: {
     signalBytes: Uint8Array;
@@ -422,10 +537,12 @@ export abstract class SinglePartyBeacon {
     signer: Signer;
     bitcoin: BitcoinConnection;
     feeEstimator: FeeEstimator;
+    changeAddress?: string;
   }): Promise<BeaconTxPlan> {
     const network = opts.bitcoin.data;
     const pubkey = opts.signer.publicKey;
     const kind = detectSingletonScriptKind(opts.beaconAddress, network);
+    const changeAddress = resolveChangeAddress(opts.beaconAddress, network, opts.changeAddress);
 
     const derivedAddress = deriveSingletonAddress(kind, pubkey, network);
     if(derivedAddress !== opts.beaconAddress) {
@@ -436,7 +553,8 @@ export abstract class SinglePartyBeacon {
       );
     }
 
-    const feeSats = await opts.feeEstimator.estimateFee(SINGLETON_BEACON_TX_VSIZE[kind]);
+    const changeKind = changeOutputKind(changeAddress, network);
+    const feeSats = await opts.feeEstimator.estimateFee(beaconTxVsize(kind, changeKind));
     const amount = BigInt(opts.utxo.value);
     if(amount <= feeSats) {
       throw new BeaconError(
@@ -482,7 +600,12 @@ export abstract class SinglePartyBeacon {
       });
     }
 
-    tx.addOutputAddress(opts.beaconAddress, amount - feeSats, network);
+    // Change first (omitted when it would be dust, sweeping the remainder into the
+    // fee), then the OP_RETURN signal, which the spec requires to be the last output.
+    const changeValue = amount - feeSats;
+    if(changeValue >= BigInt(DUST_LIMIT_SATS[changeKind])) {
+      tx.addOutputAddress(changeAddress, changeValue, network);
+    }
     tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
 
     return {
@@ -490,6 +613,7 @@ export abstract class SinglePartyBeacon {
       prevOutScripts : [prevOutScript],
       prevOutValues  : [amount],
       beaconAddress  : opts.beaconAddress,
+      changeAddress,
       utxo           : opts.utxo,
       feeSats,
       scriptKind     : kind,

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/fee-estimator.ts

@@ -50,3 +50,12 @@ export class StaticFeeEstimator implements FeeEstimator {
     return BigInt(Math.ceil(vsize * this.satsPerVbyte));
   }
 }
+
+/**
+ * Default fee estimator used when a caller supplies none: a static 5 sat/vB rate.
+ * Suitable for tests and regtest. Production callers should inject a dynamic
+ * estimator (a mempool API, or Bitcoin Core `estimatesmartfee`) at the point the
+ * beacon transaction is built (single-party broadcast options, or the aggregation
+ * service runner's fee estimator).
+ */
+export const DEFAULT_FEE_ESTIMATOR: FeeEstimator = new StaticFeeEstimator(5);

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';