@did-btcr2/method 0.36.1 → 0.37.0

package/src/core/aggregation/cohort.ts

@@ -4,11 +4,13 @@ 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 { concatBytes, hexToBytes, randomBytes } from '@noble/hashes/utils';
 import { p2tr } from '@scure/btc-signer';
 import { keyAggExport, keyAggregate, sortKeys } from '@scure/btc-signer/musig2';
 import type { CASAnnouncement } from '../types.js';
 import { AggregationCohortError } from './errors.js';
+import type { FundingModel } from './recovery-policy.js';
+import { DEFAULT_FUNDING_MODEL, buildRecoveryLeaves, resolveFallbackThreshold } from './recovery-policy.js';
 
 export type AggregationCohortParams = {
   id?: string;
@@ -16,14 +18,22 @@ export type AggregationCohortParams = {
   minParticipants?: number;
   network: string;
   beaconType?: string;
+  /** Operator recovery key, x-only (32 bytes). Required to compute the beacon address. */
+  recoveryKey?: Uint8Array;
+  /** Relative-timelock (BIP-68 nSequence) before recovery is spendable. Required to compute the beacon address. */
+  recoverySequence?: number;
+  /** Funding model governing the recovery leaves. Defaults to 'operator-funded'. */
+  fundingModel?: FundingModel;
+  /** Advertised k of the k-of-n fallback leaf. Absent defaults to n-1 at address computation. */
+  fallbackThreshold?: number;
 };
 
 /**
- * Represents an Aggregation Cohort — a set of Aggregation Participants who
+ * Represents an Aggregation Cohort: a set of Aggregation Participants who
  * submitted cryptographic material to an Aggregation Service to coordinate
  * signing of a shared n-of-n MuSig2 Bitcoin transaction.
  *
- * This is a pure data class — it holds cohort state and provides computation
+ * This is a pure data class: it holds cohort state and provides computation
  * helpers (key aggregation, CAS Announcement building, SMT tree building).
  * It performs no I/O and emits no messages. Both AggregationService and
  * AggregationParticipant create their own AggregationCohort instances to
@@ -51,8 +61,8 @@ export class AggregationCohort {
   participants: Array<string> = [];
 
   /**
-   * Mapping from participant DID → their compressed secp256k1 public key.
-   * Distinct from {@link cohortKeys} (which is sorted per BIP-327) — this lets
+   * Mapping from participant DID to 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.
    */
@@ -62,19 +72,51 @@ export class AggregationCohort {
   #cohortKeys: Array<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.
+   * BIP-341 TapTweak scalar: `taggedHash("TapTweak", internalPubkey || tapMerkleRoot)`.
+   * The beacon output is an internal key (the MuSig2 aggregate) plus a script
+   * tree (the recovery leaves), so the tweak commits to the tree's Merkle root.
+   * The MuSig2 signing session applies this as an x-only tweak; a value that does
+   * not match the root the funded address was derived from silently yields an
+   * invalid key-path signature.
    */
   tapTweak: Uint8Array = new Uint8Array();
 
-  /** The n-of-n MuSig2 Taproot beacon address. */
+  /** The n-of-n MuSig2 aggregate internal key, x-only (32 bytes), set by computeBeaconAddress(). */
+  internalKey: Uint8Array = new Uint8Array();
+
+  /** BIP-341 Taproot Merkle root of the recovery script tree, set by computeBeaconAddress(). */
+  tapMerkleRoot: Uint8Array = new Uint8Array();
+
+  /** Operator recovery key, x-only (32 bytes). Used to build the CSV recovery leaf. */
+  recoveryKey?: Uint8Array;
+
+  /** Relative-timelock (BIP-68 nSequence) before the recovery leaf is spendable. */
+  recoverySequence?: number;
+
+  /** Funding model governing the recovery leaves (default 'operator-funded'). */
+  fundingModel: FundingModel;
+
+  /**
+   * Advertised k of the k-of-n fallback leaf, or undefined to default to n-1 at
+   * address computation. Read the resolved value via {@link effectiveFallbackThreshold}.
+   */
+  fallbackThreshold?: number;
+
+  /** The Taproot beacon address: key path is the MuSig2 aggregate, script path is fallback + recovery. */
   beaconAddress: string = '';
 
   /** Pending DID updates submitted by participants, keyed by DID. */
   pendingUpdates: Map<string, SignedBTCR2Update> = new Map();
 
-  /** CAS Beacon Announcement Map (DID → updateHash), set by buildCASAnnouncement(). */
+  /**
+   * Participant DIDs that explicitly declined to submit an update this round
+   * (cooperative non-inclusion). A decliner is absent from the CAS Announcement
+   * Map and carries a non-inclusion leaf in the SMT, yet still signs. Kept
+   * disjoint from {@link pendingUpdates} so CAS correctness holds by construction.
+   */
+  nonIncluded: Set<string> = new Set();
+
+  /** CAS Beacon Announcement Map (DID to updateHash), set by buildCASAnnouncement(). */
   casAnnouncement?: CASAnnouncement;
 
   /** Per-participant SMT proofs, set by buildSMTTree(). */
@@ -89,7 +131,7 @@ export class AggregationCohort {
   /** Set of participant DIDs that have rejected the aggregated data. */
   validationRejections: Set<string> = new Set();
 
-  constructor({ id, minParticipants, serviceDid, network, beaconType }: AggregationCohortParams) {
+  constructor({ id, minParticipants, serviceDid, network, beaconType, recoveryKey, recoverySequence, fundingModel, fallbackThreshold }: AggregationCohortParams) {
     this.id = id || crypto.randomUUID();
     // `?? 2` (not `|| 2`) so a deliberately-passed 0 is preserved rather than
     // silently coerced; the service rejects an invalid count at createCohort.
@@ -97,6 +139,10 @@ export class AggregationCohort {
     this.serviceDid = serviceDid || '';
     this.network = network;
     this.beaconType = beaconType || 'CASBeacon';
+    this.recoveryKey = recoveryKey;
+    this.recoverySequence = recoverySequence;
+    this.fundingModel = fundingModel ?? DEFAULT_FUNDING_MODEL;
+    this.fallbackThreshold = fallbackThreshold;
   }
 
   /** Sorted cohort keys (sorted on assignment per BIP-327). */
@@ -109,8 +155,27 @@ export class AggregationCohort {
   }
 
   /**
-   * Computes the n-of-n MuSig2 Taproot beacon address from cohort keys.
-   * Sets `tapTweak` to the BIP-341 key-path-only tweak.
+   * The resolved k of the k-of-n fallback leaf: the advertised
+   * {@link fallbackThreshold}, or n-1 (floored at 1) when unadvertised, where n is
+   * the current cohort size. This is the value the beacon address commits to and
+   * the spend builders must reproduce. Returns 0 before any cohort keys are set.
+   */
+  public get effectiveFallbackThreshold(): number {
+    if(this.#cohortKeys.length === 0) return 0;
+    return resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length);
+  }
+
+  /**
+   * Computes the Taproot beacon address from the cohort keys and recovery params.
+   *
+   * The output's key path is the n-of-n MuSig2 aggregate of the cohort keys; its
+   * script path is the recovery tree (a CSV recovery leaf so a missing signer
+   * cannot permanently lock the UTXO). Sets `internalKey`, `tapMerkleRoot`, and
+   * the `tapTweak` the MuSig2 session must apply for the key-path spend.
+   *
+   * The tweak is derived from the Merkle root the address was built with (read
+   * back from the payment), never recomputed by hand, so the MuSig2 key-path
+   * signature is guaranteed to validate against the funded address.
    */
   public computeBeaconAddress(): string {
     if(this.#cohortKeys.length === 0) {
@@ -119,16 +184,39 @@ export class AggregationCohort {
         'NO_COHORT_KEYS', { cohortId: this.id }
       );
     }
+    if(!this.recoveryKey || this.recoveryKey.length === 0 || this.recoverySequence === undefined) {
+      throw new AggregationCohortError(
+        'Cannot compute beacon address: missing recovery key or sequence.',
+        'NO_RECOVERY_PARAMS', { cohortId: this.id }
+      );
+    }
     const keyAggContext = keyAggregate(this.#cohortKeys);
     const aggPubkey = keyAggExport(keyAggContext);
-    // Derive the address for the cohort's network. Without the network arg
-    // p2tr defaults to mainnet, so a mutinynet/signet/regtest cohort would
-    // otherwise advertise a `bc1p...` address that no participant can fund.
-    const payment = p2tr(aggPubkey, undefined, getNetwork(this.network));
 
-    // BIP-341: key-path-only P2TR has no script tree. Compute the tweak:
-    // taggedHash("TapTweak", internalPubkey).
-    this.tapTweak = schnorr.utils.taggedHash('TapTweak', aggPubkey);
+    // The beacon output commits to the script tree (k-of-n fallback leaf + CSV
+    // recovery leaf) alongside the MuSig2 internal key. Derive the address for
+    // the cohort's network. Without the network arg p2tr defaults to mainnet, so
+    // a mutinynet/signet/regtest cohort would otherwise advertise a `bc1p...`
+    // address that no participant can fund.
+    const leaves = buildRecoveryLeaves(this.fundingModel, {
+      recoveryKey       : this.recoveryKey,
+      recoverySequence  : this.recoverySequence,
+      cohortKeys        : this.#cohortKeys,
+      fallbackThreshold : resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length),
+    });
+    // allowUnknownOutputs: the CSV recovery leaf is a custom script, not one of
+    // p2tr's recognized templates (tr_ns/tr_ms), so the template check must be
+    // waived. The leaf hash (and thus the address) is computed from the raw
+    // script bytes regardless.
+    const payment = p2tr(aggPubkey, leaves, getNetwork(this.network), true);
+
+    // BIP-341: the key-path tweak commits to the script tree's Merkle root.
+    // taggedHash("TapTweak", internalPubkey || tapMerkleRoot). Use the root the
+    // library committed to (payment.tapMerkleRoot) so the tweak matches the
+    // funded address byte-for-byte.
+    this.internalKey = aggPubkey;
+    this.tapMerkleRoot = payment.tapMerkleRoot;
+    this.tapTweak = schnorr.utils.taggedHash('TapTweak', concatBytes(aggPubkey, payment.tapMerkleRoot));
 
     if(!payment.address) {
       throw new AggregationCohortError(
@@ -189,20 +277,56 @@ export class AggregationCohort {
     this.pendingUpdates.set(participantDid, signedUpdate);
   }
 
+  /**
+   * Record that a participant declined to submit an update this round
+   * (cooperative non-inclusion). The member stays in the cohort and still signs.
+   */
+  public addNonInclusion(participantDid: string): void {
+    if(!this.participants.includes(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} is not in cohort ${this.id}.`,
+        'UNKNOWN_PARTICIPANT', { cohortId: this.id, participantDid }
+      );
+    }
+    // A DID cannot both submit and decline. The service guards re-submission, but
+    // keep the invariant local so the response gate and builders stay consistent.
+    if(this.pendingUpdates.has(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} already submitted an update; cannot also decline.`,
+        'CONFLICTING_RESPONSE', { cohortId: this.id, participantDid }
+      );
+    }
+    this.nonIncluded.add(participantDid);
+  }
+
   public hasAllUpdates(): boolean {
     return this.pendingUpdates.size === this.participants.length;
   }
 
+  /**
+   * True when every participant has responded for this round, either with an
+   * update or with an explicit non-inclusion. This is the aggregation gate when
+   * non-inclusion is in play; it generalizes {@link hasAllUpdates} the same way
+   * {@link hasAllValidationResponses} generalizes a unanimous ack.
+   */
+  public hasAllResponses(): boolean {
+    return this.pendingUpdates.size + this.nonIncluded.size === this.participants.length;
+  }
+
   /**
    * Builds a CAS Announcement Map from collected updates.
-   * Maps each participant DID → base64url canonical hash of their signed update.
+   * Maps each participant DID to base64url canonical hash of their signed update.
    * Computes signal bytes as SHA-256 of canonicalized announcement.
+   *
+   * Members who declined (cooperative non-inclusion) are naturally absent from
+   * the map: the body iterates {@link pendingUpdates}, which never holds a
+   * decliner. Absence from the map is exactly the CAS non-inclusion signal.
    */
   public buildCASAnnouncement(): CASAnnouncement {
-    if(!this.hasAllUpdates()) {
+    if(!this.hasAllResponses()) {
       throw new AggregationCohortError(
-        'Cannot build CAS Announcement: not all updates collected.',
-        'INCOMPLETE_UPDATES', { cohortId: this.id, collected: this.pendingUpdates.size, total: this.participants.length }
+        'Cannot build CAS Announcement: not all participants have responded.',
+        'INCOMPLETE_RESPONSES', { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
       );
     }
     const announcement: CASAnnouncement = {};
@@ -215,25 +339,37 @@ export class AggregationCohort {
   }
 
   /**
-   * Builds an SMT tree from collected updates.
-   * Each entry uses a random 32-byte nonce + canonicalized signed update bytes.
-   * Stores per-participant proofs and the SMT root as signalBytes.
+   * Builds an SMT tree with one leaf per participant.
+   *
+   * A member who submitted an update gets an inclusion leaf
+   * (SHA-256(SHA-256(nonce) || SHA-256(update))); a member who declined gets a
+   * non-inclusion leaf (SHA-256(SHA-256(nonce)), the `signedUpdate` entry field
+   * omitted). The cohort mints each member's nonce and returns it inside that
+   * member's serialized proof, so a decliner can self-validate its own
+   * non-inclusion slot and the resolver can recompute the leaf. Stores
+   * per-participant proofs and the SMT root as signalBytes.
    */
   public buildSMTTree(): Map<string, SerializedSMTProof> {
-    if(!this.hasAllUpdates()) {
+    if(!this.hasAllResponses()) {
       throw new AggregationCohortError(
-        'Cannot build SMT tree: not all updates collected.',
-        'INCOMPLETE_UPDATES', { cohortId: this.id }
+        'Cannot build SMT tree: not all participants have responded.',
+        'INCOMPLETE_RESPONSES', { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
       );
     }
     const tree = new BTCR2MerkleTree();
     const entries: TreeEntry[] = [];
     const encoder = new TextEncoder();
 
-    for(const [did, signedUpdate] of this.pendingUpdates) {
-      const canonicalBytes = encoder.encode(canonicalize(signedUpdate));
+    // Slot every participant: an inclusion leaf for submitters, a non-inclusion
+    // leaf (signedUpdate omitted) for decliners.
+    for(const did of this.participants) {
       const nonce = randomBytes(32);
-      entries.push({ did, nonce, signedUpdate: canonicalBytes });
+      const signedUpdate = this.pendingUpdates.get(did);
+      if(signedUpdate) {
+        entries.push({ did, nonce, signedUpdate: encoder.encode(canonicalize(signedUpdate)) });
+      } else {
+        entries.push({ did, nonce });
+      }
     }
 
     tree.addEntries(entries);
@@ -241,7 +377,7 @@ export class AggregationCohort {
 
     this.signalBytes = tree.rootHash;
     this.smtProofs = new Map();
-    for(const [did] of this.pendingUpdates) {
+    for(const did of this.participants) {
       this.smtProofs.set(did, tree.proof(did));
     }
     return this.smtProofs;
@@ -269,7 +405,7 @@ export class AggregationCohort {
   }
 
   /**
-   * True when all participants approved. Note: differs from {@link hasAllValidationResponses} —
+   * True when all participants approved. Note: differs from {@link hasAllValidationResponses},
    * this returns false if any participant rejected, even if all responses are in.
    */
   public isFullyValidated(): boolean {

package/src/core/aggregation/conditions.ts

@@ -15,9 +15,15 @@
  * settlement (consistent with ADR 008).
  */
 
+import type { FundingModel } from './recovery-policy.js';
+import { MAX_RECOVERY_SEQUENCE } from './recovery-policy.js';
+
 /** Beacon types that support aggregation (singleton is single-party only, per ADR 037). */
 export const KNOWN_BEACON_TYPES = ['CASBeacon', 'SMTBeacon'] as const;
 
+/** Funding models an operator may advertise. Only 'operator-funded' is implemented (ADR 042). */
+export const KNOWN_FUNDING_MODELS = ['operator-funded', 'participant-funded'] as const;
+
 /**
  * An advertised price. `unit` is operator-defined (the spec does not specify a
  * currency); `basis` distinguishes a per-DID from a per-participant charge for
@@ -51,6 +57,31 @@ export interface CohortConditions {
   maxSecondsBetweenAnnouncements?: number;
   /** 7. Pending-update count that triggers an announcement. Advertised; enforcement staged (AGG-5) - generalizes hasAllUpdates(). */
   pendingUpdateTrigger?: number;
+  /**
+   * Who funds the beacon UTXO and holds the recovery path. Defaults to
+   * 'operator-funded' when absent. See ADR 042.
+   */
+  fundingModel?: FundingModel;
+  /**
+   * Operator recovery key, x-only (64-character hex / 32 bytes). The beacon
+   * output commits to a CSV recovery leaf keyed to this key, so a missing signer
+   * can never permanently lock the funded UTXO. Required (ADR 042).
+   */
+  recoveryKey: string;
+  /**
+   * Relative-timelock (BIP-68 nSequence, in blocks) before the recovery leaf is
+   * spendable. Required, >= 1 (ADR 042).
+   */
+  recoverySequence: number;
+  /**
+   * Number of signers (k) the k-of-n fallback leaf requires, so any k cohort
+   * members can still announce when the optimistic n-of-n key path stalls
+   * (graceful liveness, ADR 042). Optional: when absent it defaults to n-1 at
+   * keygen, where n is the finalized participant count. When advertised it must
+   * be an integer >= 1 (and <= maxParticipants when that is set); the upper bound
+   * against the actual cohort size n is enforced at keygen.
+   */
+  fallbackThreshold?: number;
 }
 
 /** Validate an optional [min, max] integer pair. */
@@ -109,8 +140,33 @@ export function validateCohortConditions(c: CohortConditions): string[] {
     problems.push('pendingUpdateTrigger must be an integer >= 1');
   }
 
+  // Fallback threshold (k of the k-of-n fallback leaf). Optional; when advertised
+  // it must be a positive integer and cannot exceed maxParticipants (the binding
+  // upper bound against the actual cohort size n is checked at keygen, where n is
+  // known). See ADR 042.
+  if(c.fallbackThreshold !== undefined) {
+    if(!Number.isInteger(c.fallbackThreshold) || c.fallbackThreshold < 1) {
+      problems.push('fallbackThreshold must be an integer >= 1');
+    } else if(c.maxParticipants !== undefined && Number.isInteger(c.maxParticipants) && c.fallbackThreshold > c.maxParticipants) {
+      problems.push('fallbackThreshold must be <= maxParticipants');
+    }
+  }
+
   checkCost(problems, 'costOfEnrollment', c.costOfEnrollment);
   checkCost(problems, 'costPerAnnouncement', c.costPerAnnouncement);
 
+  // Recovery params: the beacon output's CSV recovery leaf. Required so a
+  // missing signer can never permanently lock the funded UTXO (ADR 042). The
+  // key is an x-only (32-byte) Schnorr public key, carried as 64 hex chars.
+  if(typeof c.recoveryKey !== 'string' || !/^[0-9a-fA-F]{64}$/.test(c.recoveryKey)) {
+    problems.push('recoveryKey must be a 64-character hex string (x-only public key)');
+  }
+  if(!Number.isInteger(c.recoverySequence) || c.recoverySequence < 1 || c.recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    problems.push(`recoverySequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}]`);
+  }
+  if(c.fundingModel !== undefined && !(KNOWN_FUNDING_MODELS as readonly string[]).includes(c.fundingModel)) {
+    problems.push(`fundingModel must be one of ${KNOWN_FUNDING_MODELS.join(', ')}`);
+  }
+
   return problems;
 }

package/src/core/aggregation/fallback-spend.ts

@@ -0,0 +1,223 @@
+/**
+ * Fallback spend builder for aggregate beacon outputs.
+ *
+ * An aggregate beacon UTXO is a Taproot output whose key path is the cohort's
+ * n-of-n MuSig2 aggregate key and whose script path carries a k-of-n fallback
+ * leaf (`p2tr_ms` CHECKSIGADD) plus a CSV recovery leaf (see
+ * {@link ./recovery-policy.ts} and ADR 042). When the optimistic n-of-n key path
+ * stalls (a missing or defecting signer), the cohort can still push the SAME
+ * announcement transaction through the fallback leaf with any k members'
+ * signatures, instead of abandoning the round or waiting out the recovery
+ * timelock.
+ *
+ * Unlike the MuSig2 key path, the fallback is a plain k-of-n script-path spend:
+ * each signer produces a standalone BIP-340 signature over the script-path
+ * sighash (no nonce round), and the coordinator assembles k of them into the
+ * witness. The coordinator never holds a participant secret - it injects the
+ * collected signatures and finalizes.
+ *
+ * This module is pure with respect to the network: it takes the beacon
+ * transaction, the cohort and recovery parameters, the spent output, and the
+ * collected signatures, and returns a finalized {@link Transaction}.
+ * Broadcasting is the caller's concern.
+ */
+
+import { getNetwork } from '@did-btcr2/bitcoin';
+import { schnorr } from '@noble/curves/secp256k1.js';
+import type { Transaction} from '@scure/btc-signer';
+import { SigHash, p2tr } from '@scure/btc-signer';
+import { keyAggExport, keyAggregate, sortKeys } from '@scure/btc-signer/musig2';
+import { AggregationCohortError } from './errors.js';
+import type { FundingModel } from './recovery-policy.js';
+import {
+  DEFAULT_FUNDING_MODEL,
+  TAPROOT_LEAF_VERSION,
+  buildFallbackLeaf,
+  buildRecoveryLeaves,
+  resolveFallbackThreshold,
+  tapLeafHash,
+} from './recovery-policy.js';
+
+/** A single member's standalone signature over the fallback script-path sighash. */
+export interface FallbackSignature {
+  /** Signer's x-only public key (32 bytes). Must be one of the cohort's keys. */
+  pubKey: Uint8Array;
+  /** 64-byte BIP-340 Schnorr signature over the script-path sighash. */
+  signature: Uint8Array;
+}
+
+/** Inputs to {@link buildFallbackSpend}. */
+export interface FallbackSpendParams {
+  /**
+   * The beacon announcement transaction to finalize. Input {@link inputIndex}
+   * spends the beacon UTXO; its key-path witness must not be set (the fallback
+   * assembles a script-path witness instead).
+   */
+  pendingTx: Transaction;
+  /** Index of the beacon input within {@link pendingTx}. Defaults to 0. */
+  inputIndex?: number;
+  /**
+   * The cohort's participant public keys (compressed secp256k1, 33 bytes).
+   * Sorted internally per BIP-327 so the reconstructed tree matches the funded
+   * output.
+   */
+  cohortKeys: Uint8Array[];
+  /**
+   * The advertised k of the k-of-n fallback leaf, or omit for the cohort's n-1
+   * default. Resolved against `cohortKeys.length` exactly as the cohort does.
+   */
+  fallbackThreshold?: number;
+  /** Operator recovery key, x-only (32 bytes). Needed to reconstruct the script tree. */
+  recoveryKey: Uint8Array;
+  /** Relative-timelock (BIP-68) the recovery leaf enforces. Needed to reconstruct the script tree. */
+  recoverySequence: number;
+  /** Funding model governing the leaves. Defaults to 'operator-funded'. */
+  fundingModel?: FundingModel;
+  /** Bitcoin network name (bitcoin/mainnet, mutinynet, signet, testnet, regtest). */
+  network: string;
+  /** scriptPubKey of the beacon UTXO being spent. Must equal the reconstructed tree output script. */
+  prevOutScript: Uint8Array;
+  /** Value of the beacon UTXO in satoshis. */
+  prevOutValue: bigint;
+  /**
+   * Standalone signatures collected from cohort members. At least
+   * {@link fallbackThreshold} valid, distinct-by-key signatures are required;
+   * exactly k are injected (a k-of-n CHECKSIGADD leaf demands exactly k).
+   */
+  signatures: FallbackSignature[];
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+
+/**
+ * Compute the BIP-341 script-path sighash a cohort member must sign to authorize
+ * the fallback spend. The leaf is the k-of-n fallback leaf; signers produce a
+ * standalone BIP-340 signature over this digest with SIGHASH_DEFAULT.
+ */
+export function fallbackSighash(
+  tx: Transaction,
+  inputIndex: number,
+  prevOutScript: Uint8Array,
+  prevOutValue: bigint,
+  fallbackLeafScript: Uint8Array,
+): Uint8Array {
+  return tx.preimageWitnessV1(
+    inputIndex,
+    [ prevOutScript ],
+    SigHash.DEFAULT,
+    [ prevOutValue ],
+    undefined,
+    fallbackLeafScript,
+    TAPROOT_LEAF_VERSION,
+  );
+}
+
+/**
+ * Assemble and finalize a k-of-n fallback spend of an aggregate beacon UTXO.
+ *
+ * Reconstructs the funded Taproot output (MuSig2 internal key + fallback/recovery
+ * script tree), verifies each collected signature against the script-path
+ * sighash and a cohort key, injects exactly k distinct valid signatures into the
+ * fallback leaf, and finalizes the witness. The returned transaction is the same
+ * announcement the optimistic path would have produced, signed via the script
+ * path instead of the key path.
+ *
+ * @throws {AggregationCohortError} when there are no cohort keys, the spent
+ * script does not match the reconstructed tree output, or fewer than k valid
+ * distinct signatures were supplied.
+ */
+export function buildFallbackSpend(params: FallbackSpendParams): Transaction {
+  const {
+    pendingTx, cohortKeys, recoveryKey, recoverySequence,
+    fundingModel, network, prevOutScript, prevOutValue, signatures,
+  } = params;
+  const inputIndex = params.inputIndex ?? 0;
+
+  if(cohortKeys.length === 0) {
+    throw new AggregationCohortError(
+      'Cannot build fallback spend: no cohort keys.',
+      'NO_COHORT_KEYS'
+    );
+  }
+
+  // Resolve k the same way the cohort did, so the reconstructed leaf matches.
+  const fallbackThreshold = resolveFallbackThreshold(params.fallbackThreshold, cohortKeys.length);
+
+  // Reconstruct the funded output the same way the cohort derived its address.
+  const internalKey = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey, recoverySequence, cohortKeys, fallbackThreshold,
+  });
+  const net = getNetwork(network);
+  // allowUnknownOutputs: the CSV recovery leaf is a custom script (see cohort.ts).
+  const payment = p2tr(internalKey, leaves, net, true);
+
+  // The output we are spending must be the cohort's funded beacon output; if the
+  // reconstructed tree script differs, the witness would not match the chain.
+  if(!bytesEqual(payment.script, prevOutScript)) {
+    throw new AggregationCohortError(
+      'Reconstructed beacon output script does not match the spent prevout script.',
+      'PREVOUT_SCRIPT_MISMATCH'
+    );
+  }
+
+  const fallbackLeaf = buildFallbackLeaf({ cohortKeys, fallbackThreshold });
+  // Locate the fallback leaf's tapLeafScript entry: each entry is
+  // [controlBlock, script || leafVersion]; strip the trailing version byte to
+  // compare the script.
+  const leafEntry = payment.tapLeafScript?.find(([ , scriptVer ]) => {
+    const script = scriptVer.slice(0, scriptVer.length - 1);
+    return bytesEqual(script, fallbackLeaf);
+  });
+  if(!leafEntry) {
+    throw new AggregationCohortError(
+      'Could not locate the fallback leaf in the reconstructed beacon output.',
+      'FALLBACK_LEAF_NOT_FOUND'
+    );
+  }
+
+  // Validate the collected signatures against the script-path sighash. The leaf
+  // is keyed by x-only cohort keys, so a valid signature must verify against one
+  // of them. Keep only distinct, valid signatures (first occurrence per key).
+  const cohortXOnly = sortKeys(cohortKeys).map(k => k.slice(1));
+  const tx = pendingTx;
+  const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+
+  const leafHash = tapLeafHash(fallbackLeaf);
+  const accepted = new Map<string, Uint8Array>(); // x-only hex to signature
+  for(const { pubKey, signature } of signatures) {
+    if(pubKey.length !== 32 || signature.length !== 64) continue;
+    const isCohortKey = cohortXOnly.some(k => bytesEqual(k, pubKey));
+    if(!isCohortKey) continue;
+    const hex = Array.from(pubKey, b => b.toString(16).padStart(2, '0')).join('');
+    if(accepted.has(hex)) continue;
+    let ok = false;
+    try { ok = schnorr.verify(signature, sighash, pubKey); } catch { ok = false; }
+    if(ok) accepted.set(hex, signature);
+  }
+
+  if(accepted.size < fallbackThreshold) {
+    throw new AggregationCohortError(
+      `Not enough valid fallback signatures: have ${accepted.size}, need ${fallbackThreshold}.`,
+      'NOT_ENOUGH_FALLBACK_SIGNATURES', { have: accepted.size, need: fallbackThreshold }
+    );
+  }
+
+  // A k-of-n CHECKSIGADD leaf demands EXACTLY k satisfied signatures (the final
+  // <k> NUMEQUAL fails if the running count differs), so inject exactly k.
+  const chosen = cohortXOnly
+    .filter(k => accepted.has(Array.from(k, b => b.toString(16).padStart(2, '0')).join('')))
+    .slice(0, fallbackThreshold);
+
+  tx.updateInput(inputIndex, {
+    tapLeafScript : [ leafEntry ],
+    tapScriptSig  : chosen.map(pubKey => {
+      const hex = Array.from(pubKey, b => b.toString(16).padStart(2, '0')).join('');
+      return [ { pubKey, leafHash }, accepted.get(hex)! ];
+    }),
+  });
+  tx.finalize();
+  return tx;
+}

package/src/core/aggregation/logger.ts

@@ -6,7 +6,7 @@
  * {@link SILENT_LOGGER} to suppress output (useful for tests) or a custom
  * implementation to route logs to pino, winston, Sentry, etc.
  *
- * The interface is intentionally small — we don't want production code taking
+ * The interface is intentionally small: we don't want production code taking
  * a hard dependency on any specific logger library.
  */
 export interface Logger {

package/src/core/aggregation/messages/base.ts

@@ -22,6 +22,12 @@ export type BaseBody = Partial<CohortConditions> & {
   aggregatedNonce?: Uint8Array;
   nonceContribution?: Uint8Array;
   partialSignature?: Uint8Array;
+  /** Fallback (k-of-n script-path) leaf script, hex. Carried on FALLBACK_AUTHORIZATION_REQUEST. */
+  fallbackLeafScriptHex?: string;
+  /** Signer's x-only key for a fallback signature (which CHECKSIGADD slot it satisfies). */
+  signerPk?: Uint8Array;
+  /** A member's standalone BIP-340 fallback script-path signature (64 bytes). */
+  fallbackSignature?: Uint8Array;
   pendingTx?: string;
   /** Hex-encoded scriptPubKey of the UTXO being spent. Required for BIP-341 sighash. */
   prevOutScriptHex?: string;