@did-btcr2/method 0.36.1 → 0.38.0

package/dist/cjs/index.js

@@ -55,6 +55,7 @@ __export(index_exports, {
   BeaconUtils: () => BeaconUtils,
   CASBeacon: () => CASBeacon,
   CASBeaconError: () => CASBeaconError,
+  CHANGE_OUTPUT_VBYTES: () => CHANGE_OUTPUT_VBYTES,
   COHORT_ADVERT: () => COHORT_ADVERT,
   COHORT_OPT_IN: () => COHORT_OPT_IN,
   COHORT_OPT_IN_ACCEPT: () => COHORT_OPT_IN_ACCEPT,
@@ -63,17 +64,23 @@ __export(index_exports, {
   DEFAULT_ADVERT_REPEAT_INTERVAL_MS: () => DEFAULT_ADVERT_REPEAT_INTERVAL_MS,
   DEFAULT_BROADCAST_LOOKBACK_MS: () => DEFAULT_BROADCAST_LOOKBACK_MS,
   DEFAULT_CLOCK_SKEW_SEC: () => DEFAULT_CLOCK_SKEW_SEC,
+  DEFAULT_FEE_ESTIMATOR: () => DEFAULT_FEE_ESTIMATOR,
+  DEFAULT_FUNDING_MODEL: () => DEFAULT_FUNDING_MODEL,
   DEFAULT_MAX_UPDATE_SIZE_BYTES: () => DEFAULT_MAX_UPDATE_SIZE_BYTES,
   DEFAULT_NONCE_LEN_BYTES: () => DEFAULT_NONCE_LEN_BYTES,
   DEFAULT_NOSTR_RELAYS: () => DEFAULT_NOSTR_RELAYS,
+  DEFAULT_RECOVERY_SEQUENCE: () => DEFAULT_RECOVERY_SEQUENCE,
   DID_REGEX: () => DID_REGEX,
   DISTRIBUTE_AGGREGATED_DATA: () => DISTRIBUTE_AGGREGATED_DATA,
+  DUST_LIMIT_SATS: () => DUST_LIMIT_SATS2,
   DidBtcr2: () => DidBtcr2,
   DidCommTransport: () => DidCommTransport,
   DidDocument: () => DidDocument,
   DidDocumentBuilder: () => DidDocumentBuilder,
   DidVerificationMethod: () => DidVerificationMethod,
   Document: () => Document,
+  FALLBACK_AUTHORIZATION_REQUEST: () => FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE: () => FALLBACK_SIGNATURE,
   GenesisDocument: () => GenesisDocument,
   HTTP_ENVELOPE_VERSION: () => HTTP_ENVELOPE_VERSION,
   HTTP_ROUTE: () => HTTP_ROUTE,
@@ -87,7 +94,9 @@ __export(index_exports, {
   InMemoryTransport: () => InMemoryTransport,
   InboxBuffer: () => InboxBuffer,
   KNOWN_BEACON_TYPES: () => KNOWN_BEACON_TYPES,
+  KNOWN_FUNDING_MODELS: () => KNOWN_FUNDING_MODELS,
   KeyPairAggregationSigner: () => KeyPairAggregationSigner,
+  MAX_RECOVERY_SEQUENCE: () => MAX_RECOVERY_SEQUENCE,
   NONCE_CONTRIBUTION: () => NONCE_CONTRIBUTION,
   NonceCache: () => NonceCache,
   NostrTransport: () => NostrTransport,
@@ -104,6 +113,7 @@ __export(index_exports, {
   SMTBeacon: () => SMTBeacon,
   SMTBeaconError: () => SMTBeaconError,
   SSE_EVENT: () => SSE_EVENT,
+  SUBMIT_NONINCLUDED: () => SUBMIT_NONINCLUDED,
   SUBMIT_UPDATE: () => SUBMIT_UPDATE,
   ServiceCohortPhase: () => ServiceCohortPhase,
   SigningSessionError: () => SigningSessionError,
@@ -112,13 +122,20 @@ __export(index_exports, {
   SingletonBeacon: () => SingletonBeacon,
   SingletonBeaconError: () => SingletonBeaconError,
   StaticFeeEstimator: () => StaticFeeEstimator,
+  TAPROOT_LEAF_VERSION: () => TAPROOT_LEAF_VERSION,
   TransportAdapterError: () => TransportAdapterError,
   TransportError: () => TransportError,
   TransportFactory: () => TransportFactory,
   TypedEventEmitter: () => TypedEventEmitter,
   Updater: () => Updater,
   VALIDATION_ACK: () => VALIDATION_ACK,
+  beaconTxVsize: () => beaconTxVsize,
   buildAggregationBeaconTx: () => buildAggregationBeaconTx,
+  buildFallbackLeaf: () => buildFallbackLeaf,
+  buildFallbackSpend: () => buildFallbackSpend,
+  buildRecoveryLeaves: () => buildRecoveryLeaves,
+  buildRecoveryScript: () => buildRecoveryScript,
+  buildRecoverySpend: () => buildRecoverySpend,
   buildRequestAuth: () => buildRequestAuth,
   createAggregatedNonceMessage: () => createAggregatedNonceMessage,
   createAuthorizationRequestMessage: () => createAuthorizationRequestMessage,
@@ -127,13 +144,17 @@ __export(index_exports, {
   createCohortOptInMessage: () => createCohortOptInMessage,
   createCohortReadyMessage: () => createCohortReadyMessage,
   createDistributeAggregatedDataMessage: () => createDistributeAggregatedDataMessage,
+  createFallbackAuthorizationRequestMessage: () => createFallbackAuthorizationRequestMessage,
+  createFallbackSignatureMessage: () => createFallbackSignatureMessage,
   createNonceContributionMessage: () => createNonceContributionMessage,
   createSignatureAuthorizationMessage: () => createSignatureAuthorizationMessage,
+  createSubmitNonIncludedMessage: () => createSubmitNonIncludedMessage,
   createSubmitUpdateMessage: () => createSubmitUpdateMessage,
   createValidationAckMessage: () => createValidationAckMessage,
   defaultReconnectBackoff: () => defaultReconnectBackoff,
   deriveSingletonAddress: () => deriveSingletonAddress,
   detectSingletonScriptKind: () => detectSingletonScriptKind,
+  fallbackSighash: () => fallbackSighash,
   formatSseComment: () => formatSseComment,
   formatSseEvent: () => formatSseEvent,
   getBeaconStrategy: () => getBeaconStrategy,
@@ -145,10 +166,13 @@ __export(index_exports, {
   isCohortOptInMessage: () => isCohortOptInMessage,
   isCohortReadyMessage: () => isCohortReadyMessage,
   isDistributeAggregatedDataMessage: () => isDistributeAggregatedDataMessage,
+  isFallbackAuthorizationRequestMessage: () => isFallbackAuthorizationRequestMessage,
+  isFallbackSignatureMessage: () => isFallbackSignatureMessage,
   isKeygenMessageType: () => isKeygenMessageType,
   isNonceContributionMessage: () => isNonceContributionMessage,
   isSignMessageType: () => isSignMessageType,
   isSignatureAuthorizationMessage: () => isSignatureAuthorizationMessage,
+  isSubmitNonIncludedMessage: () => isSubmitNonIncludedMessage,
   isSubmitUpdateMessage: () => isSubmitUpdateMessage,
   isUpdateMessageType: () => isUpdateMessageType,
   isValidationAckMessage: () => isValidationAckMessage,
@@ -157,8 +181,11 @@ __export(index_exports, {
   parseRequestAuth: () => parseRequestAuth,
   parseSseStream: () => parseSseStream,
   registerBeaconStrategy: () => registerBeaconStrategy,
+  resolveChangeAddress: () => resolveChangeAddress,
+  resolveFallbackThreshold: () => resolveFallbackThreshold,
   reviveFromWire: () => reviveFromWire,
   signEnvelope: () => signEnvelope,
+  tapLeafHash: () => tapLeafHash,
   validateCohortConditions: () => validateCohortConditions,
   verifyEnvelope: () => verifyEnvelope,
   verifyRequestAuth: () => verifyRequestAuth
@@ -168,7 +195,8 @@ module.exports = __toCommonJS(index_exports);
 // src/core/aggregation/service.ts
 var import_common4 = require("@did-btcr2/common");
 var import_cryptosuite = require("@did-btcr2/cryptosuite");
-var import_utils2 = require("@noble/hashes/utils");
+var import_secp256k14 = require("@noble/curves/secp256k1.js");
+var import_utils3 = require("@noble/hashes/utils");
 
 // src/core/aggregation/beacon-strategy.ts
 var import_common = require("@did-btcr2/common");
@@ -181,9 +209,12 @@ var CAS_STRATEGY = {
   getDistributePayload(cohort) {
     return { casAnnouncement: cohort.casAnnouncement };
   },
-  validateParticipantView({ participantDid, expectedHash, body }) {
+  validateParticipantView({ participantDid, included, expectedHash, body }) {
     const casAnnouncement = body.casAnnouncement;
     if (!casAnnouncement) return { matches: false };
+    if (!included) {
+      return { matches: !(participantDid in casAnnouncement), casAnnouncement };
+    }
     return {
       matches: casAnnouncement[participantDid] === expectedHash,
       casAnnouncement
@@ -199,15 +230,20 @@ var SMT_STRATEGY = {
     const proof = cohort.smtProofs?.get(participantDid);
     return { smtProof: proof };
   },
-  validateParticipantView({ participantDid, submittedUpdate, body }) {
+  validateParticipantView({ participantDid, included, submittedUpdate, body }) {
     const smtProof = body.smtProof;
-    if (!smtProof?.updateId || !smtProof?.nonce) return { matches: false };
+    const index = (0, import_smt.didToIndex)(participantDid);
+    if (!included) {
+      if (!smtProof?.nonce || smtProof?.updateId) return { matches: false, smtProof };
+      const candidateHash2 = (0, import_smt.blockHash)((0, import_smt.blockHash)((0, import_smt.base64UrlToHash)(smtProof.nonce)));
+      return { matches: (0, import_smt.verifySerializedProof)(smtProof, index, candidateHash2), smtProof };
+    }
+    if (!smtProof?.updateId || !smtProof?.nonce || !submittedUpdate) return { matches: false, smtProof };
     const canonicalBytes = new TextEncoder().encode((0, import_common.canonicalize)(submittedUpdate));
     const expectedUpdateId = (0, import_smt.hashToBase64Url)((0, import_smt.blockHash)(canonicalBytes));
     if (smtProof.updateId !== expectedUpdateId) {
       return { matches: false, smtProof };
     }
-    const index = (0, import_smt.didToIndex)(participantDid);
     const candidateHash = (0, import_smt.blockHash)((0, import_smt.blockHash)((0, import_smt.base64UrlToHash)(smtProof.nonce)), (0, import_smt.base64UrlToHash)(smtProof.updateId));
     return {
       matches: (0, import_smt.verifySerializedProof)(smtProof, index, candidateHash),
@@ -230,10 +266,10 @@ function getBeaconStrategy(type) {
 var import_bitcoin = require("@did-btcr2/bitcoin");
 var import_common3 = require("@did-btcr2/common");
 var import_smt2 = require("@did-btcr2/smt");
-var import_secp256k1 = require("@noble/curves/secp256k1.js");
-var import_utils = require("@noble/hashes/utils");
-var import_btc_signer = require("@scure/btc-signer");
-var import_musig2 = require("@scure/btc-signer/musig2");
+var import_secp256k12 = require("@noble/curves/secp256k1.js");
+var import_utils2 = require("@noble/hashes/utils");
+var import_btc_signer2 = require("@scure/btc-signer");
+var import_musig22 = require("@scure/btc-signer/musig2");
 
 // src/core/aggregation/errors.ts
 var import_common2 = require("@did-btcr2/common");
@@ -258,6 +294,105 @@ var SigningSessionError = class extends import_common2.MethodError {
   }
 };
 
+// src/core/aggregation/recovery-policy.ts
+var import_secp256k1 = require("@noble/curves/secp256k1.js");
+var import_utils = require("@noble/hashes/utils");
+var import_btc_signer = require("@scure/btc-signer");
+var import_musig2 = require("@scure/btc-signer/musig2");
+var DEFAULT_FUNDING_MODEL = "operator-funded";
+var DEFAULT_RECOVERY_SEQUENCE = 144;
+var MAX_RECOVERY_SEQUENCE = 65535;
+var TAPROOT_LEAF_VERSION = 192;
+function compactSize(n) {
+  if (n < 253) return new Uint8Array([n]);
+  if (n <= 65535) return new Uint8Array([253, n & 255, n >> 8 & 255]);
+  return new Uint8Array([254, n & 255, n >> 8 & 255, n >> 16 & 255, n >> 24 & 255]);
+}
+function tapLeafHash(script, leafVersion = TAPROOT_LEAF_VERSION) {
+  return import_secp256k1.schnorr.utils.taggedHash(
+    "TapLeaf",
+    (0, import_utils.concatBytes)(new Uint8Array([leafVersion]), compactSize(script.length), script)
+  );
+}
+function resolveFallbackThreshold(advertised, n) {
+  return advertised ?? Math.max(1, n - 1);
+}
+function assertFallbackParams({ cohortKeys, fallbackThreshold }) {
+  const n = cohortKeys.length;
+  if (n === 0) {
+    throw new AggregationCohortError(
+      "Cannot build fallback leaf: no cohort keys.",
+      "NO_COHORT_KEYS"
+    );
+  }
+  for (const key of cohortKeys) {
+    if (key.length !== 33) {
+      throw new AggregationCohortError(
+        `Cohort key must be a 33-byte compressed public key, got ${key.length} bytes.`,
+        "INVALID_COHORT_KEY",
+        { length: key.length }
+      );
+    }
+  }
+  if (!Number.isInteger(fallbackThreshold) || fallbackThreshold < 1 || fallbackThreshold > n) {
+    throw new AggregationCohortError(
+      `Fallback threshold must be an integer in [1, ${n}] (k-of-n), got ${fallbackThreshold}.`,
+      "INVALID_FALLBACK_THRESHOLD",
+      { fallbackThreshold, n }
+    );
+  }
+}
+function buildFallbackLeaf(params) {
+  assertFallbackParams(params);
+  const xOnlyKeys = (0, import_musig2.sortKeys)(params.cohortKeys).map((k) => k.slice(1));
+  return (0, import_btc_signer.p2tr_ms)(params.fallbackThreshold, xOnlyKeys).script;
+}
+function assertRecoveryParams({ recoveryKey, recoverySequence }) {
+  if (recoveryKey.length !== 32) {
+    throw new AggregationCohortError(
+      `Recovery key must be a 32-byte x-only public key, got ${recoveryKey.length} bytes.`,
+      "INVALID_RECOVERY_KEY"
+    );
+  }
+  if (!Number.isInteger(recoverySequence) || recoverySequence < 1 || recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    throw new AggregationCohortError(
+      `Recovery sequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}], got ${recoverySequence}.`,
+      "INVALID_RECOVERY_SEQUENCE"
+    );
+  }
+}
+function buildRecoveryScript(params) {
+  assertRecoveryParams(params);
+  return import_btc_signer.Script.encode([
+    params.recoverySequence,
+    "CHECKSEQUENCEVERIFY",
+    "DROP",
+    params.recoveryKey,
+    "CHECKSIG"
+  ]);
+}
+function buildRecoveryLeaves(fundingModel, params) {
+  switch (fundingModel) {
+    case "operator-funded":
+      return [
+        { script: buildFallbackLeaf(params) },
+        { script: buildRecoveryScript(params) }
+      ];
+    case "participant-funded":
+      throw new AggregationCohortError(
+        "Funding model 'participant-funded' is reserved and not yet implemented.",
+        "UNSUPPORTED_FUNDING_MODEL",
+        { fundingModel }
+      );
+    default:
+      throw new AggregationCohortError(
+        `Unknown funding model: ${fundingModel}.`,
+        "UNKNOWN_FUNDING_MODEL",
+        { fundingModel }
+      );
+  }
+}
+
 // src/core/aggregation/cohort.ts
 var AggregationCohort = class {
   /** Unique identifier for the cohort. */
@@ -273,8 +408,8 @@ var AggregationCohort = class {
   /** List of participant DIDs that have been accepted into the cohort. */
   participants = [];
   /**
-   * 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.
    */
@@ -282,16 +417,41 @@ var AggregationCohort = class {
   /** Sorted list of cohort participants' compressed public keys. */
   #cohortKeys = [];
   /**
-   * 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 = 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 = new Uint8Array();
+  /** BIP-341 Taproot Merkle root of the recovery script tree, set by computeBeaconAddress(). */
+  tapMerkleRoot = new Uint8Array();
+  /** Operator recovery key, x-only (32 bytes). Used to build the CSV recovery leaf. */
+  recoveryKey;
+  /** Relative-timelock (BIP-68 nSequence) before the recovery leaf is spendable. */
+  recoverySequence;
+  /** Funding model governing the recovery leaves (default 'operator-funded'). */
+  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;
+  /** The Taproot beacon address: key path is the MuSig2 aggregate, script path is fallback + recovery. */
   beaconAddress = "";
   /** Pending DID updates submitted by participants, keyed by DID. */
   pendingUpdates = /* @__PURE__ */ 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 = /* @__PURE__ */ new Set();
+  /** CAS Beacon Announcement Map (DID to updateHash), set by buildCASAnnouncement(). */
   casAnnouncement;
   /** Per-participant SMT proofs, set by buildSMTTree(). */
   smtProofs;
@@ -301,23 +461,45 @@ var AggregationCohort = class {
   validationAcks = /* @__PURE__ */ new Set();
   /** Set of participant DIDs that have rejected the aggregated data. */
   validationRejections = /* @__PURE__ */ new Set();
-  constructor({ id, minParticipants, serviceDid, network, beaconType }) {
+  constructor({ id, minParticipants, serviceDid, network, beaconType, recoveryKey, recoverySequence, fundingModel, fallbackThreshold }) {
     this.id = id || crypto.randomUUID();
     this.minParticipants = minParticipants ?? 2;
     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). */
   get cohortKeys() {
     return this.#cohortKeys;
   }
   set cohortKeys(keys) {
-    this.#cohortKeys = (0, import_musig2.sortKeys)(keys);
+    this.#cohortKeys = (0, import_musig22.sortKeys)(keys);
+  }
+  /**
+   * 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.
+   */
+  get effectiveFallbackThreshold() {
+    if (this.#cohortKeys.length === 0) return 0;
+    return resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length);
   }
   /**
-   * Computes the n-of-n MuSig2 Taproot beacon address from cohort keys.
-   * Sets `tapTweak` to the BIP-341 key-path-only tweak.
+   * 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.
    */
   computeBeaconAddress() {
     if (this.#cohortKeys.length === 0) {
@@ -327,10 +509,25 @@ var AggregationCohort = class {
         { cohortId: this.id }
       );
     }
-    const keyAggContext = (0, import_musig2.keyAggregate)(this.#cohortKeys);
-    const aggPubkey = (0, import_musig2.keyAggExport)(keyAggContext);
-    const payment = (0, import_btc_signer.p2tr)(aggPubkey, void 0, (0, import_bitcoin.getNetwork)(this.network));
-    this.tapTweak = import_secp256k1.schnorr.utils.taggedHash("TapTweak", aggPubkey);
+    if (!this.recoveryKey || this.recoveryKey.length === 0 || this.recoverySequence === void 0) {
+      throw new AggregationCohortError(
+        "Cannot compute beacon address: missing recovery key or sequence.",
+        "NO_RECOVERY_PARAMS",
+        { cohortId: this.id }
+      );
+    }
+    const keyAggContext = (0, import_musig22.keyAggregate)(this.#cohortKeys);
+    const aggPubkey = (0, import_musig22.keyAggExport)(keyAggContext);
+    const leaves = buildRecoveryLeaves(this.fundingModel, {
+      recoveryKey: this.recoveryKey,
+      recoverySequence: this.recoverySequence,
+      cohortKeys: this.#cohortKeys,
+      fallbackThreshold: resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length)
+    });
+    const payment = (0, import_btc_signer2.p2tr)(aggPubkey, leaves, (0, import_bitcoin.getNetwork)(this.network), true);
+    this.internalKey = aggPubkey;
+    this.tapMerkleRoot = payment.tapMerkleRoot;
+    this.tapTweak = import_secp256k12.schnorr.utils.taggedHash("TapTweak", (0, import_utils2.concatBytes)(aggPubkey, payment.tapMerkleRoot));
     if (!payment.address) {
       throw new AggregationCohortError(
         "Failed to compute Taproot address",
@@ -354,7 +551,7 @@ var AggregationCohort = class {
         { cohortId: this.id, participantPkHex }
       );
     }
-    this.cohortKeys = cohortKeysHex.map((k) => (0, import_utils.hexToBytes)(k));
+    this.cohortKeys = cohortKeysHex.map((k) => (0, import_utils2.hexToBytes)(k));
     const computed = this.computeBeaconAddress();
     if (computed !== expectedBeaconAddress) {
       throw new AggregationCohortError(
@@ -386,20 +583,54 @@ var AggregationCohort = class {
     }
     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.
+   */
+  addNonInclusion(participantDid) {
+    if (!this.participants.includes(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} is not in cohort ${this.id}.`,
+        "UNKNOWN_PARTICIPANT",
+        { cohortId: this.id, participantDid }
+      );
+    }
+    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);
+  }
   hasAllUpdates() {
     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.
+   */
+  hasAllResponses() {
+    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.
    */
   buildCASAnnouncement() {
-    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 = {};
@@ -411,31 +642,41 @@ var AggregationCohort = class {
     return announcement;
   }
   /**
-   * 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.
    */
   buildSMTTree() {
-    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 import_smt2.BTCR2MerkleTree();
     const entries = [];
     const encoder = new TextEncoder();
-    for (const [did, signedUpdate] of this.pendingUpdates) {
-      const canonicalBytes = encoder.encode((0, import_common3.canonicalize)(signedUpdate));
-      const nonce = (0, import_utils.randomBytes)(32);
-      entries.push({ did, nonce, signedUpdate: canonicalBytes });
+    for (const did of this.participants) {
+      const nonce = (0, import_utils2.randomBytes)(32);
+      const signedUpdate = this.pendingUpdates.get(did);
+      if (signedUpdate) {
+        entries.push({ did, nonce, signedUpdate: encoder.encode((0, import_common3.canonicalize)(signedUpdate)) });
+      } else {
+        entries.push({ did, nonce });
+      }
     }
     tree.addEntries(entries);
     tree.finalize();
     this.signalBytes = tree.rootHash;
     this.smtProofs = /* @__PURE__ */ new Map();
-    for (const [did] of this.pendingUpdates) {
+    for (const did of this.participants) {
       this.smtProofs.set(did, tree.proof(did));
     }
     return this.smtProofs;
@@ -461,7 +702,7 @@ var AggregationCohort = class {
     return this.validationAcks.size + this.validationRejections.size === this.participants.length;
   }
   /**
-   * 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.
    */
   isFullyValidated() {
@@ -471,6 +712,7 @@ var AggregationCohort = class {
 
 // src/core/aggregation/conditions.ts
 var KNOWN_BEACON_TYPES = ["CASBeacon", "SMTBeacon"];
+var KNOWN_FUNDING_MODELS = ["operator-funded", "participant-funded"];
 function checkPair(problems, label, min, max) {
   if (min !== void 0 && (!Number.isInteger(min) || min < 0)) {
     problems.push(`min${label} must be an integer >= 0`);
@@ -514,11 +756,130 @@ function validateCohortConditions(c) {
   if (c.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c.pendingUpdateTrigger) || c.pendingUpdateTrigger < 1)) {
     problems.push("pendingUpdateTrigger must be an integer >= 1");
   }
+  if (c.fallbackThreshold !== void 0) {
+    if (!Number.isInteger(c.fallbackThreshold) || c.fallbackThreshold < 1) {
+      problems.push("fallbackThreshold must be an integer >= 1");
+    } else if (c.maxParticipants !== void 0 && Number.isInteger(c.maxParticipants) && c.fallbackThreshold > c.maxParticipants) {
+      problems.push("fallbackThreshold must be <= maxParticipants");
+    }
+  }
   checkCost(problems, "costOfEnrollment", c.costOfEnrollment);
   checkCost(problems, "costPerAnnouncement", c.costPerAnnouncement);
+  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 !== void 0 && !KNOWN_FUNDING_MODELS.includes(c.fundingModel)) {
+    problems.push(`fundingModel must be one of ${KNOWN_FUNDING_MODELS.join(", ")}`);
+  }
   return problems;
 }
 
+// src/core/aggregation/fallback-spend.ts
+var import_bitcoin2 = require("@did-btcr2/bitcoin");
+var import_secp256k13 = require("@noble/curves/secp256k1.js");
+var import_btc_signer3 = require("@scure/btc-signer");
+var import_musig23 = require("@scure/btc-signer/musig2");
+function bytesEqual(a, b) {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+function fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeafScript) {
+  return tx.preimageWitnessV1(
+    inputIndex,
+    [prevOutScript],
+    import_btc_signer3.SigHash.DEFAULT,
+    [prevOutValue],
+    void 0,
+    fallbackLeafScript,
+    TAPROOT_LEAF_VERSION
+  );
+}
+function buildFallbackSpend(params) {
+  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"
+    );
+  }
+  const fallbackThreshold = resolveFallbackThreshold(params.fallbackThreshold, cohortKeys.length);
+  const internalKey = (0, import_musig23.keyAggExport)((0, import_musig23.keyAggregate)((0, import_musig23.sortKeys)(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey,
+    recoverySequence,
+    cohortKeys,
+    fallbackThreshold
+  });
+  const net = (0, import_bitcoin2.getNetwork)(network);
+  const payment = (0, import_btc_signer3.p2tr)(internalKey, leaves, net, true);
+  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 });
+  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"
+    );
+  }
+  const cohortXOnly = (0, import_musig23.sortKeys)(cohortKeys).map((k) => k.slice(1));
+  const tx = pendingTx;
+  const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+  const leafHash = tapLeafHash(fallbackLeaf);
+  const accepted = /* @__PURE__ */ new Map();
+  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 = import_secp256k13.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 }
+    );
+  }
+  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;
+}
+
 // src/core/aggregation/messages/base.ts
 var AGGREGATION_WIRE_VERSION = 1;
 var BaseMessage = class {
@@ -556,12 +917,15 @@ var COHORT_OPT_IN = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in`;
 var COHORT_OPT_IN_ACCEPT = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in_accept`;
 var COHORT_READY = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_ready`;
 var SUBMIT_UPDATE = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_update`;
+var SUBMIT_NONINCLUDED = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_nonincluded`;
 var DISTRIBUTE_AGGREGATED_DATA = `${AGGREGATION_MESSAGE_PREFIX}/update/distribute_aggregated_data`;
 var VALIDATION_ACK = `${AGGREGATION_MESSAGE_PREFIX}/update/validation_ack`;
 var AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/authorization_request`;
 var NONCE_CONTRIBUTION = `${AGGREGATION_MESSAGE_PREFIX}/sign/nonce_contribution`;
 var AGGREGATED_NONCE = `${AGGREGATION_MESSAGE_PREFIX}/sign/aggregated_nonce`;
 var SIGNATURE_AUTHORIZATION = `${AGGREGATION_MESSAGE_PREFIX}/sign/signature_authorization`;
+var FALLBACK_AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_authorization_request`;
+var FALLBACK_SIGNATURE = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_signature`;
 
 // src/core/aggregation/messages/factories.ts
 function createCohortAdvertMessage(fields) {
@@ -584,6 +948,10 @@ function createSubmitUpdateMessage(fields) {
   const { from: from2, to, ...body } = fields;
   return new BaseMessage({ type: SUBMIT_UPDATE, from: from2, to, body });
 }
+function createSubmitNonIncludedMessage(fields) {
+  const { from: from2, to, ...body } = fields;
+  return new BaseMessage({ type: SUBMIT_NONINCLUDED, from: from2, to, body });
+}
 function createDistributeAggregatedDataMessage(fields) {
   const { from: from2, to, ...body } = fields;
   return new BaseMessage({ type: DISTRIBUTE_AGGREGATED_DATA, from: from2, to, body });
@@ -608,6 +976,14 @@ function createSignatureAuthorizationMessage(fields) {
   const { from: from2, to, ...body } = fields;
   return new BaseMessage({ type: SIGNATURE_AUTHORIZATION, from: from2, to, body });
 }
+function createFallbackAuthorizationRequestMessage(fields) {
+  const { from: from2, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_AUTHORIZATION_REQUEST, from: from2, to, body });
+}
+function createFallbackSignatureMessage(fields) {
+  const { from: from2, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_SIGNATURE, from: from2, to, body });
+}
 
 // src/core/aggregation/phases.ts
 var ServiceCohortPhase = /* @__PURE__ */ ((ServiceCohortPhase2) => {
@@ -621,6 +997,7 @@ var ServiceCohortPhase = /* @__PURE__ */ ((ServiceCohortPhase2) => {
   ServiceCohortPhase2["SigningStarted"] = "SigningStarted";
   ServiceCohortPhase2["NoncesCollected"] = "NoncesCollected";
   ServiceCohortPhase2["AwaitingPartialSigs"] = "AwaitingPartialSigs";
+  ServiceCohortPhase2["FallbackRequested"] = "FallbackRequested";
   ServiceCohortPhase2["Complete"] = "Complete";
   ServiceCohortPhase2["Failed"] = "Failed";
   return ServiceCohortPhase2;
@@ -630,11 +1007,13 @@ var ParticipantCohortPhase = /* @__PURE__ */ ((ParticipantCohortPhase2) => {
   ParticipantCohortPhase2["OptedIn"] = "OptedIn";
   ParticipantCohortPhase2["CohortReady"] = "CohortReady";
   ParticipantCohortPhase2["UpdateSubmitted"] = "UpdateSubmitted";
+  ParticipantCohortPhase2["NonIncluded"] = "NonIncluded";
   ParticipantCohortPhase2["AwaitingValidation"] = "AwaitingValidation";
   ParticipantCohortPhase2["ValidationSent"] = "ValidationSent";
   ParticipantCohortPhase2["AwaitingSigning"] = "AwaitingSigning";
   ParticipantCohortPhase2["NonceSent"] = "NonceSent";
   ParticipantCohortPhase2["AwaitingPartialSig"] = "AwaitingPartialSig";
+  ParticipantCohortPhase2["AwaitingFallbackSig"] = "AwaitingFallbackSig";
   ParticipantCohortPhase2["Complete"] = "Complete";
   ParticipantCohortPhase2["Failed"] = "Failed";
   return ParticipantCohortPhase2;
@@ -651,7 +1030,7 @@ var SigningSessionPhase = /* @__PURE__ */ ((SigningSessionPhase2) => {
 
 // src/core/aggregation/signing-session.ts
 var import_keypair = require("@did-btcr2/keypair");
-var import_btc_signer2 = require("@scure/btc-signer");
+var import_btc_signer4 = require("@scure/btc-signer");
 var musig2 = __toESM(require("@scure/btc-signer/musig2"), 1);
 var BeaconSigningSession = class {
   /** Unique identifier for this signing session. */
@@ -664,11 +1043,11 @@ var BeaconSigningSession = class {
   prevOutScripts;
   /** Previous output values for Taproot sighash computation. */
   prevOutValues;
-  /** Map of participant publicKey-hex → public nonce contribution. */
+  /** Map of participant publicKey-hex to public nonce contribution. */
   nonceContributions = /* @__PURE__ */ new Map();
   /** Aggregated MuSig2 nonce (66 bytes). */
   aggregatedNonce;
-  /** Map of participant DID → partial signature. */
+  /** Map of participant DID to partial signature. */
   partialSignatures = /* @__PURE__ */ new Map();
   /** Final 64-byte Schnorr signature. */
   signature;
@@ -703,7 +1082,7 @@ var BeaconSigningSession = class {
     return this.pendingTx.preimageWitnessV1(
       0,
       this.prevOutScripts,
-      import_btc_signer2.SigHash.DEFAULT,
+      import_btc_signer4.SigHash.DEFAULT,
       this.prevOutValues
     );
   }
@@ -851,7 +1230,7 @@ var BeaconSigningSession = class {
       throw new SigningSessionError("Aggregated nonce not available.", "MISSING_AGGREGATED_NONCE");
     }
     if (!this.#secretNonce) {
-      throw new SigningSessionError("Secret nonce not available \u2014 generateNonceContribution() must be called first.", "MISSING_SECRET_NONCE");
+      throw new SigningSessionError("Secret nonce not available - generateNonceContribution() must be called first.", "MISSING_SECRET_NONCE");
     }
     const session = new musig2.Session(
       this.aggregatedNonce,
@@ -921,6 +1300,9 @@ var AggregationService = class {
       case SUBMIT_UPDATE:
         this.#handleSubmitUpdate(message);
         break;
+      case SUBMIT_NONINCLUDED:
+        this.#handleSubmitNonInclusion(message);
+        break;
       case VALIDATION_ACK:
         this.#handleValidationAck(message);
         break;
@@ -930,6 +1312,9 @@ var AggregationService = class {
       case SIGNATURE_AUTHORIZATION:
         this.#handleSignatureAuthorization(message);
         break;
+      case FALLBACK_SIGNATURE:
+        this.#handleFallbackSignature(message);
+        break;
       default:
         break;
     }
@@ -948,7 +1333,7 @@ var AggregationService = class {
   }
   /**
    * Create a new cohort with the given config. Returns the cohort ID.
-   * Cohort starts in `Created` phase — call `advertise()` to broadcast.
+   * Cohort starts in `Created` phase - call `advertise()` to broadcast.
    */
   createCohort(config) {
     const problems = validateCohortConditions(config);
@@ -963,7 +1348,11 @@ var AggregationService = class {
       serviceDid: this.did,
       minParticipants: config.minParticipants,
       network: config.network,
-      beaconType: config.beaconType
+      beaconType: config.beaconType,
+      recoveryKey: (0, import_utils3.hexToBytes)(config.recoveryKey),
+      recoverySequence: config.recoverySequence,
+      fundingModel: config.fundingModel,
+      fallbackThreshold: config.fallbackThreshold
     });
     this.#cohortStates.set(cohort.id, {
       phase: "Created" /* Created */,
@@ -1164,11 +1553,64 @@ var AggregationService = class {
       });
       return;
     }
+    if (state.cohort.nonIncluded.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already declined this round; cannot also submit an update"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already submitted an update this round; cannot resubmit"
+      });
+      return;
+    }
     state.cohort.addUpdate(message.from, signedUpdate);
     if (state.phase === "CohortSet" /* CohortSet */) {
       state.phase = "CollectingUpdates" /* CollectingUpdates */;
     }
-    if (state.cohort.hasAllUpdates()) {
+    if (state.cohort.hasAllResponses()) {
+      state.phase = "UpdatesCollected" /* UpdatesCollected */;
+    }
+  }
+  /**
+   * Handle an incoming SUBMIT_NONINCLUDED message: a member declares it has no
+   * update this round (cooperative non-inclusion). Membership is proven by the
+   * signed transport envelope, so the body carries only the cohortId. The member
+   * stays in the cohort and still signs; it is absent from the CAS map and
+   * carries a non-inclusion leaf in the SMT.
+   */
+  #handleSubmitNonInclusion(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return;
+    if (state.phase !== "CohortSet" /* CohortSet */ && state.phase !== "CollectingUpdates" /* CollectingUpdates */) return;
+    if (!state.cohort.participants.includes(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Sender is not a member of this cohort"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message.from) || state.cohort.nonIncluded.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already responded this round"
+      });
+      return;
+    }
+    state.cohort.addNonInclusion(message.from);
+    if (state.phase === "CohortSet" /* CohortSet */) {
+      state.phase = "CollectingUpdates" /* CollectingUpdates */;
+    }
+    if (state.cohort.hasAllResponses()) {
       state.phase = "UpdatesCollected" /* UpdatesCollected */;
     }
   }
@@ -1227,7 +1669,7 @@ var AggregationService = class {
       );
     }
     strategy.buildAggregatedData(state.cohort);
-    const signalBytesHex = (0, import_utils2.bytesToHex)(state.cohort.signalBytes);
+    const signalBytesHex = (0, import_utils3.bytesToHex)(state.cohort.signalBytes);
     state.phase = "DataDistributed" /* DataDistributed */;
     const messages = [];
     for (const participantDid of state.cohort.participants) {
@@ -1278,7 +1720,7 @@ var AggregationService = class {
   }
   /**
    * Start a signing session by creating auth requests for all participants.
-   * The caller provides the transaction data — typically built via
+   * The caller provides the transaction data - typically built via
    * `buildBeaconTransaction()` against a Bitcoin connection.
    */
   startSigning(cohortId, txData) {
@@ -1317,7 +1759,7 @@ var AggregationService = class {
         cohortId,
         sessionId: session.id,
         pendingTx: txData.tx.hex,
-        prevOutScriptHex: (0, import_utils2.bytesToHex)(prevOutScript),
+        prevOutScriptHex: (0, import_utils3.bytesToHex)(prevOutScript),
         prevOutValue: txData.prevOutValues[0]?.toString() ?? "0"
       }));
     }
@@ -1385,11 +1827,144 @@ var AggregationService = class {
       state.result = {
         cohortId,
         signature,
-        signedTx: state.signingSession.pendingTx
+        signedTx: state.signingSession.pendingTx,
+        path: "key-path"
       };
       state.phase = "Complete" /* Complete */;
     }
   }
+  /**
+   * Abandon the optimistic n-of-n key path and ask members to authorize the
+   * k-of-n fallback (script-path) spend of the SAME beacon transaction (graceful
+   * liveness, ADR 042). Reuses the in-flight signing session's transaction and
+   * spent output, so the announcement and its outputs are unchanged: only the
+   * witness path differs. Returns one FALLBACK_AUTHORIZATION_REQUEST per
+   * participant.
+   *
+   * Callable once optimistic signing has started (the session and its tx exist)
+   * and before it completes. A cohort can take exactly one of the two paths: the
+   * caller (runner) must commit to fallback and stop driving the optimistic path.
+   */
+  startFallbackSigning(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (!state.signingSession) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: no signing session.`,
+        "NO_SIGNING_SESSION",
+        { cohortId }
+      );
+    }
+    const signingPhases = [
+      "SigningStarted" /* SigningStarted */,
+      "NoncesCollected" /* NoncesCollected */,
+      "AwaitingPartialSigs" /* AwaitingPartialSigs */
+    ];
+    if (!signingPhases.includes(state.phase)) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    const session = state.signingSession;
+    const prevOutScript = session.prevOutScripts[0];
+    const prevOutValue = session.prevOutValues[0];
+    if (!prevOutScript || prevOutValue === void 0) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: signing session missing prevout data.`,
+        "MISSING_PREV_OUT",
+        { cohortId }
+      );
+    }
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    state.fallbackSignatures = /* @__PURE__ */ new Map();
+    state.phase = "FallbackRequested" /* FallbackRequested */;
+    const messages = [];
+    for (const participantDid of state.cohort.participants) {
+      messages.push(createFallbackAuthorizationRequestMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        sessionId: session.id,
+        pendingTx: session.pendingTx.hex,
+        prevOutScriptHex: (0, import_utils3.bytesToHex)(prevOutScript),
+        prevOutValue: prevOutValue.toString(),
+        fallbackLeafScriptHex: (0, import_utils3.bytesToHex)(fallbackLeaf)
+      }));
+    }
+    return messages;
+  }
+  /**
+   * Handle an incoming FALLBACK_SIGNATURE: a member's standalone BIP-340
+   * signature over the fallback script-path sighash. The signature is
+   * authenticated to the sender (its `signerPk` must be the sender's own cohort
+   * key and the signature must verify against the sighash) and collected. Once k
+   * valid signatures are in, the k-of-n fallback spend is assembled and the
+   * cohort completes via the script path.
+   */
+  #handleFallbackSignature(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || !state.signingSession || !state.fallbackSignatures) return;
+    if (state.phase !== "FallbackRequested" /* FallbackRequested */) return;
+    const sessionId = message.body?.sessionId;
+    if (sessionId !== state.signingSession.id) return;
+    const signerPk = message.body?.signerPk;
+    const fallbackSignature = message.body?.fallbackSignature;
+    if (!signerPk || !fallbackSignature) return;
+    const prevOutScript = state.signingSession.prevOutScripts[0];
+    const prevOutValue = state.signingSession.prevOutValues[0];
+    if (!prevOutScript || prevOutValue === void 0) return;
+    const memberKey = state.cohort.participantKeys.get(message.from);
+    if (!memberKey) {
+      state.rejections.push({ from: message.from, code: "UPDATE_MALFORMED", reason: "Fallback signature from a non-member" });
+      return;
+    }
+    const memberXOnly = memberKey.slice(1);
+    if (signerPk.length !== 32 || !memberXOnly.every((b, i) => b === signerPk[i])) {
+      state.rejections.push({ from: message.from, code: "UPDATE_MALFORMED", reason: "Fallback signerPk does not match the sender cohort key" });
+      return;
+    }
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    const sighash = fallbackSighash(state.signingSession.pendingTx, 0, prevOutScript, prevOutValue, fallbackLeaf);
+    let valid = false;
+    try {
+      valid = fallbackSignature.length === 64 && import_secp256k14.schnorr.verify(fallbackSignature, sighash, signerPk);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      state.rejections.push({ from: message.from, code: "UPDATE_VERIFICATION_FAILED", reason: "Fallback signature failed verification" });
+      return;
+    }
+    state.fallbackSignatures.set(message.from, { pubKey: signerPk, signature: fallbackSignature });
+    if (state.fallbackSignatures.size >= state.cohort.effectiveFallbackThreshold) {
+      const signedTx = buildFallbackSpend({
+        pendingTx: state.signingSession.pendingTx,
+        cohortKeys: state.cohort.cohortKeys,
+        fallbackThreshold: state.cohort.effectiveFallbackThreshold,
+        recoveryKey: state.cohort.recoveryKey,
+        recoverySequence: state.cohort.recoverySequence,
+        fundingModel: state.cohort.fundingModel,
+        network: state.cohort.network,
+        prevOutScript,
+        prevOutValue,
+        signatures: [...state.fallbackSignatures.values()]
+      });
+      state.result = { cohortId, signature: new Uint8Array(), signedTx, path: "script-path" };
+      state.phase = "Complete" /* Complete */;
+    }
+  }
   getResult(cohortId) {
     return this.#cohortStates.get(cohortId)?.result;
   }
@@ -1421,8 +1996,9 @@ var AggregationService = class {
 
 // src/core/aggregation/participant.ts
 var import_common5 = require("@did-btcr2/common");
-var import_utils3 = require("@noble/hashes/utils");
-var import_btc_signer3 = require("@scure/btc-signer");
+var import_secp256k15 = require("@noble/curves/secp256k1.js");
+var import_utils4 = require("@noble/hashes/utils");
+var import_btc_signer5 = require("@scure/btc-signer");
 
 // src/core/aggregation/messages/bodies.ts
 var hasStr = (b, k) => !!b && typeof b[k] === "string";
@@ -1434,6 +2010,14 @@ var optIntMin = (b, k, min) => {
   const v = b ? b[k] : void 0;
   return v === void 0 || typeof v === "number" && Number.isInteger(v) && v >= min;
 };
+var intInRange = (b, k, min, max) => {
+  const v = b ? b[k] : void 0;
+  return typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+};
+var optStrOneOf = (b, k, allowed) => {
+  const v = b ? b[k] : void 0;
+  return v === void 0 || typeof v === "string" && allowed.includes(v);
+};
 var hasBool = (b, k) => !!b && typeof b[k] === "boolean";
 var hasBytes = (b, k) => !!b && b[k] instanceof Uint8Array;
 var hasBytesArray = (b, k) => {
@@ -1441,7 +2025,7 @@ var hasBytesArray = (b, k) => {
   return Array.isArray(v) && v.every((x) => x instanceof Uint8Array);
 };
 function isCohortAdvertMessage(m) {
-  return m.type === COHORT_ADVERT && hasStr(m.body, "cohortId") && hasIntMin(m.body, "minParticipants", 1) && optIntMin(m.body, "maxParticipants", 1) && hasStr(m.body, "beaconType") && hasStr(m.body, "network") && hasBytes(m.body, "communicationPk");
+  return m.type === COHORT_ADVERT && hasStr(m.body, "cohortId") && hasIntMin(m.body, "minParticipants", 1) && optIntMin(m.body, "maxParticipants", 1) && hasStr(m.body, "beaconType") && hasStr(m.body, "network") && hasStr(m.body, "recoveryKey") && intInRange(m.body, "recoverySequence", 1, MAX_RECOVERY_SEQUENCE) && optStrOneOf(m.body, "fundingModel", KNOWN_FUNDING_MODELS) && optIntMin(m.body, "fallbackThreshold", 1) && hasBytes(m.body, "communicationPk");
 }
 function isCohortOptInMessage(m) {
   return m.type === COHORT_OPT_IN && hasStr(m.body, "cohortId") && hasBytes(m.body, "participantPk") && hasBytes(m.body, "communicationPk");
@@ -1455,6 +2039,9 @@ function isCohortReadyMessage(m) {
 function isSubmitUpdateMessage(m) {
   return m.type === SUBMIT_UPDATE && hasStr(m.body, "cohortId") && !!m.body && typeof m.body.signedUpdate === "object";
 }
+function isSubmitNonIncludedMessage(m) {
+  return m.type === SUBMIT_NONINCLUDED && hasStr(m.body, "cohortId");
+}
 function isDistributeAggregatedDataMessage(m) {
   return m.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m.body, "cohortId") && hasStr(m.body, "beaconType") && hasStr(m.body, "signalBytesHex");
 }
@@ -1473,8 +2060,38 @@ function isAggregatedNonceMessage(m) {
 function isSignatureAuthorizationMessage(m) {
   return m.type === SIGNATURE_AUTHORIZATION && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "partialSignature");
 }
+function isFallbackAuthorizationRequestMessage(m) {
+  return m.type === FALLBACK_AUTHORIZATION_REQUEST && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasStr(m.body, "pendingTx") && hasStr(m.body, "prevOutScriptHex") && hasStr(m.body, "prevOutValue") && hasStr(m.body, "fallbackLeafScriptHex");
+}
+function isFallbackSignatureMessage(m) {
+  return m.type === FALLBACK_SIGNATURE && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "signerPk") && hasBytes(m.body, "fallbackSignature");
+}
 
 // src/core/aggregation/participant.ts
+function txEmbedsSignal(tx, signalHex) {
+  let expected;
+  try {
+    expected = (0, import_utils4.hexToBytes)(signalHex);
+  } catch {
+    return false;
+  }
+  if (expected.length === 0) return false;
+  for (let i = 0; i < tx.outputsLength; i++) {
+    const script = tx.getOutput(i)?.script;
+    if (!script) continue;
+    let decoded;
+    try {
+      decoded = import_btc_signer5.Script.decode(script);
+    } catch {
+      continue;
+    }
+    if (decoded.length === 2 && decoded[0] === "RETURN" && decoded[1] instanceof Uint8Array) {
+      const payload = decoded[1];
+      if (payload.length === expected.length && payload.every((b, j) => b === expected[j])) return true;
+    }
+  }
+  return false;
+}
 var AggregationParticipant = class {
   did;
   /** MuSig2 signing capability. The raw secret never lives as a field here. */
@@ -1491,7 +2108,7 @@ var AggregationParticipant = class {
   }
   /**
    * Process an incoming message. Updates internal state but never produces
-   * outgoing messages — those come exclusively from action methods.
+   * outgoing messages: those come exclusively from action methods.
    */
   receive(message) {
     if (message.version === void 0 || message.version !== AGGREGATION_WIRE_VERSION) {
@@ -1517,6 +2134,9 @@ var AggregationParticipant = class {
       case AGGREGATED_NONCE:
         this.#handleAggregatedNonce(message);
         break;
+      case FALLBACK_AUTHORIZATION_REQUEST:
+        this.#handleFallbackAuthorizationRequest(message);
+        break;
       default:
         break;
     }
@@ -1562,12 +2182,17 @@ var AggregationParticipant = class {
         { cohortId, phase: state?.phase }
       );
     }
+    const advert = state.advert;
     const cohort = new AggregationCohort({
       id: cohortId,
       serviceDid: state.serviceDid,
-      minParticipants: state.advert.minParticipants,
-      network: state.advert.network,
-      beaconType: state.advert.beaconType
+      minParticipants: advert.minParticipants,
+      network: advert.network,
+      beaconType: advert.beaconType,
+      recoveryKey: advert.recoveryKey ? (0, import_utils4.hexToBytes)(advert.recoveryKey) : void 0,
+      recoverySequence: advert.recoverySequence,
+      fundingModel: advert.fundingModel,
+      fallbackThreshold: advert.fallbackThreshold
     });
     state.cohort = cohort;
     state.phase = "OptedIn" /* OptedIn */;
@@ -1583,7 +2208,7 @@ var AggregationParticipant = class {
   #handleOptInAccept(message) {
     void message;
   }
-  /** Cohorts that have been finalized — beacon address available. */
+  /** Cohorts that have been finalized: beacon address available. */
   get joinedCohorts() {
     const map = /* @__PURE__ */ new Map();
     for (const [id, state] of this.#cohortStates) {
@@ -1607,8 +2232,8 @@ var AggregationParticipant = class {
     const beaconAddress = message.body?.beaconAddress;
     const cohortKeys = message.body?.cohortKeys;
     if (!beaconAddress || !cohortKeys) return;
-    const participantPkHex = (0, import_utils3.bytesToHex)(this.publicKey);
-    const cohortKeysHex = cohortKeys.map((k) => (0, import_utils3.bytesToHex)(new Uint8Array(k)));
+    const participantPkHex = (0, import_utils4.bytesToHex)(this.publicKey);
+    const cohortKeysHex = cohortKeys.map((k) => (0, import_utils4.bytesToHex)(new Uint8Array(k)));
     state.cohort.validateMembership(participantPkHex, cohortKeysHex, beaconAddress);
     state.phase = "CohortReady" /* CohortReady */;
   }
@@ -1626,6 +2251,7 @@ var AggregationParticipant = class {
       );
     }
     state.submittedUpdate = signedUpdate;
+    state.included = true;
     state.phase = "UpdateSubmitted" /* UpdateSubmitted */;
     const message = createSubmitUpdateMessage({
       from: this.did,
@@ -1635,6 +2261,30 @@ var AggregationParticipant = class {
     });
     return [message];
   }
+  /**
+   * User action: decline to submit an update this round (cooperative
+   * non-inclusion). The member stays in the cohort and still signs; it will be
+   * absent from the CAS Announcement Map, or carry a non-inclusion leaf in the
+   * SMT. Returns the SUBMIT_NONINCLUDED message to send.
+   */
+  declineUpdate(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || state.phase !== "CohortReady" /* CohortReady */) {
+      throw new AggregationParticipantError(
+        `Cannot decline in cohort ${cohortId}: not in CohortReady phase.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state?.phase }
+      );
+    }
+    state.included = false;
+    state.phase = "NonIncluded" /* NonIncluded */;
+    const message = createSubmitNonIncludedMessage({
+      from: this.did,
+      to: state.serviceDid,
+      cohortId
+    });
+    return [message];
+  }
   /** Aggregated data awaiting user validation. */
   get pendingValidations() {
     const map = /* @__PURE__ */ new Map();
@@ -1648,9 +2298,9 @@ var AggregationParticipant = class {
   /**
    * The validated aggregated data retained for a cohort, regardless of phase.
    * Unlike {@link pendingValidations} (which lists only cohorts still awaiting
-   * the validate decision), this returns the stored validation — including the
-   * participant's sidecar (the CAS Announcement map or its SMT inclusion proof)
-   * — so it is still readable once the cohort reaches Complete. Returns
+   * the validate decision), this returns the stored validation, including the
+   * participant's sidecar (the CAS Announcement map or its SMT inclusion proof),
+   * so it is still readable once the cohort reaches Complete. Returns
    * undefined before aggregated data has been received.
    */
   getValidation(cohortId) {
@@ -1660,18 +2310,20 @@ var AggregationParticipant = class {
     const cohortId = message.body?.cohortId;
     if (!cohortId) return;
     const state = this.#cohortStates.get(cohortId);
-    if (!state || state.phase !== "UpdateSubmitted" /* UpdateSubmitted */) return;
-    if (!state.submittedUpdate) return;
+    if (!state || state.phase !== "UpdateSubmitted" /* UpdateSubmitted */ && state.phase !== "NonIncluded" /* NonIncluded */) return;
+    const declined = state.included === false;
+    if (!declined && !state.submittedUpdate) return;
     const beaconType = message.body?.beaconType;
     if (!beaconType) return;
     const strategy = getBeaconStrategy(beaconType);
     if (!strategy) return;
     const signalBytesHex = message.body?.signalBytesHex ?? "";
-    const expectedHash = (0, import_common5.canonicalHash)(state.submittedUpdate);
+    const expectedHash = declined ? "" : (0, import_common5.canonicalHash)(state.submittedUpdate);
     const result = strategy.validateParticipantView({
       participantDid: this.did,
-      submittedUpdate: state.submittedUpdate,
-      expectedHash,
+      included: !declined,
+      submittedUpdate: declined ? void 0 : state.submittedUpdate,
+      expectedHash: declined ? void 0 : expectedHash,
       body: message.body
     });
     state.validation = {
@@ -1681,7 +2333,8 @@ var AggregationParticipant = class {
       expectedHash,
       matches: result.matches,
       casAnnouncement: result.casAnnouncement,
-      smtProof: result.smtProof
+      smtProof: result.smtProof,
+      included: !declined
     };
     state.phase = "AwaitingValidation" /* AwaitingValidation */;
   }
@@ -1755,6 +2408,31 @@ var AggregationParticipant = class {
     };
     state.phase = "AwaitingSigning" /* AwaitingSigning */;
   }
+  /**
+   * Bind a signing approval to the announcement the member validated: a beacon
+   * transaction MUST carry an OP_RETURN with the exact 32-byte signal stored when
+   * the aggregated data was distributed. Both the optimistic nonce approval and
+   * the fallback approval sign with SIGHASH_DEFAULT (committing to every output)
+   * while the coordinator drives output selection, so without this check a
+   * coordinator could anchor a different signal under the member's signature.
+   */
+  #assertTxAnchorsValidatedSignal(cohortId, state, tx) {
+    const signalHex = state.validation?.signalBytesHex;
+    if (!signalHex) {
+      throw new AggregationParticipantError(
+        `Cohort ${cohortId} has no validated signal to bind the signature to.`,
+        "MISSING_STATE",
+        { cohortId }
+      );
+    }
+    if (!txEmbedsSignal(tx, signalHex)) {
+      throw new AggregationParticipantError(
+        `Transaction for cohort ${cohortId} does not anchor the validated signal.`,
+        "SIGNAL_MISMATCH",
+        { cohortId }
+      );
+    }
+  }
   /**
    * User action: approve signing and generate nonce contribution.
    */
@@ -1774,8 +2452,9 @@ var AggregationParticipant = class {
         { cohortId }
       );
     }
-    const tx = import_btc_signer3.Transaction.fromRaw((0, import_utils3.hexToBytes)(state.signingRequest.pendingTxHex));
-    const prevOutScripts = [(0, import_utils3.hexToBytes)(state.signingRequest.prevOutScriptHex)];
+    const tx = import_btc_signer5.Transaction.fromRaw((0, import_utils4.hexToBytes)(state.signingRequest.pendingTxHex), { allowUnknownOutputs: true });
+    this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
+    const prevOutScripts = [(0, import_utils4.hexToBytes)(state.signingRequest.prevOutScriptHex)];
     const prevOutValues = [BigInt(state.signingRequest.prevOutValue)];
     const session = new BeaconSigningSession({
       id: state.signingRequest.sessionId,
@@ -1810,7 +2489,7 @@ var AggregationParticipant = class {
   }
   /**
    * User action: generate and return the partial signature.
-   * In most UIs this is automatic after AwaitingPartialSig — but exposing it
+   * In most UIs this is automatic after AwaitingPartialSig, but exposing it
    * as an explicit action lets the client UI confirm before signing if desired.
    */
   generatePartialSignature(cohortId) {
@@ -1842,6 +2521,83 @@ var AggregationParticipant = class {
       partialSignature: partialSig
     })];
   }
+  /** Fallback signing requests awaiting user approval (UI: review the fallback spend). */
+  get pendingFallbackRequests() {
+    const map = /* @__PURE__ */ new Map();
+    for (const [id, state] of this.#cohortStates) {
+      if (state.phase === "AwaitingFallbackSig" /* AwaitingFallbackSig */ && state.fallbackRequest) {
+        map.set(id, state.fallbackRequest);
+      }
+    }
+    return map;
+  }
+  #handleFallbackAuthorizationRequest(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || !state.cohort) return;
+    const acceptFrom = [
+      "ValidationSent" /* ValidationSent */,
+      "AwaitingSigning" /* AwaitingSigning */,
+      "NonceSent" /* NonceSent */,
+      "AwaitingPartialSig" /* AwaitingPartialSig */,
+      "Complete" /* Complete */
+    ];
+    if (!acceptFrom.includes(state.phase)) return;
+    const sessionId = message.body?.sessionId;
+    const pendingTxHex = message.body?.pendingTx;
+    const prevOutScriptHex = message.body?.prevOutScriptHex;
+    const prevOutValue = message.body?.prevOutValue;
+    const fallbackLeafScriptHex = message.body?.fallbackLeafScriptHex;
+    if (!sessionId || !pendingTxHex || !prevOutScriptHex || !prevOutValue || !fallbackLeafScriptHex) return;
+    state.fallbackRequest = { cohortId, sessionId, pendingTxHex, prevOutScriptHex, prevOutValue, fallbackLeafScriptHex };
+    state.signingSession?.clearSecrets();
+    state.phase = "AwaitingFallbackSig" /* AwaitingFallbackSig */;
+  }
+  /**
+   * User action: authorize the fallback spend. Recomputes the k-of-n fallback
+   * leaf from the member's OWN cohort state (not the service-provided script),
+   * computes the BIP-341 script-path sighash over the requested transaction, and
+   * returns a standalone BIP-340 signature (no nonce round). The member completes
+   * once it has contributed; the service needs only k of these.
+   */
+  approveFallback(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || state.phase !== "AwaitingFallbackSig" /* AwaitingFallbackSig */) {
+      throw new AggregationParticipantError(
+        `Cannot approve fallback for cohort ${cohortId}: not in AwaitingFallbackSig phase.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state?.phase }
+      );
+    }
+    if (!state.fallbackRequest || !state.cohort) {
+      throw new AggregationParticipantError(
+        `Cohort ${cohortId} missing fallback request or cohort state.`,
+        "MISSING_STATE",
+        { cohortId }
+      );
+    }
+    const req = state.fallbackRequest;
+    const tx = import_btc_signer5.Transaction.fromRaw((0, import_utils4.hexToBytes)(req.pendingTxHex), { allowUnknownOutputs: true });
+    const prevOutScript = (0, import_utils4.hexToBytes)(req.prevOutScriptHex);
+    const prevOutValue = BigInt(req.prevOutValue);
+    this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    const sighash = fallbackSighash(tx, 0, prevOutScript, prevOutValue, fallbackLeaf);
+    const signature = this.#signer.withSecret((secretKey) => import_secp256k15.schnorr.sign(sighash, secretKey));
+    state.phase = "Complete" /* Complete */;
+    return [createFallbackSignatureMessage({
+      from: this.did,
+      to: state.serviceDid,
+      cohortId,
+      sessionId: req.sessionId,
+      signerPk: this.publicKey.slice(1),
+      fallbackSignature: signature
+    })];
+  }
   getCohortPhase(cohortId) {
     return this.#cohortStates.get(cohortId)?.phase;
   }
@@ -1878,6 +2634,87 @@ var KeyPairAggregationSigner = class {
   }
 };
 
+// src/core/aggregation/recovery-spend.ts
+var import_bitcoin3 = require("@did-btcr2/bitcoin");
+var import_secp256k16 = require("@noble/curves/secp256k1.js");
+var import_btc_signer6 = require("@scure/btc-signer");
+var import_musig24 = require("@scure/btc-signer/musig2");
+var DUST_LIMIT_SATS = 546n;
+function bytesEqual2(a, b) {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+function buildRecoverySpend(params) {
+  const {
+    cohortKeys,
+    recoverySecretKey,
+    recoveryKey,
+    recoverySequence,
+    fallbackThreshold,
+    fundingModel,
+    network,
+    utxo,
+    destinationAddress,
+    fee,
+    beaconAddress
+  } = params;
+  if (cohortKeys.length === 0) {
+    throw new AggregationCohortError(
+      "Cannot build recovery spend: no cohort keys.",
+      "NO_COHORT_KEYS"
+    );
+  }
+  const derivedPub = import_secp256k16.schnorr.getPublicKey(recoverySecretKey);
+  if (!bytesEqual2(derivedPub, recoveryKey)) {
+    throw new AggregationCohortError(
+      "Recovery secret key does not correspond to the committed recovery key.",
+      "RECOVERY_KEY_MISMATCH"
+    );
+  }
+  const out = utxo.value - fee;
+  if (out <= 0n) {
+    throw new AggregationCohortError(
+      `Recovery fee ${fee} exceeds UTXO value ${utxo.value}.`,
+      "FEE_EXCEEDS_VALUE",
+      { fee: fee.toString(), value: utxo.value.toString() }
+    );
+  }
+  if (out < DUST_LIMIT_SATS) {
+    throw new AggregationCohortError(
+      `Recovered output ${out} is below the dust limit ${DUST_LIMIT_SATS}; the spend would not relay.`,
+      "DUST_OUTPUT",
+      { output: out.toString(), dustLimit: DUST_LIMIT_SATS.toString() }
+    );
+  }
+  const internalKey = (0, import_musig24.keyAggExport)((0, import_musig24.keyAggregate)((0, import_musig24.sortKeys)(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey,
+    recoverySequence,
+    cohortKeys,
+    fallbackThreshold: resolveFallbackThreshold(fallbackThreshold, cohortKeys.length)
+  });
+  const net = (0, import_bitcoin3.getNetwork)(network);
+  const payment = (0, import_btc_signer6.p2tr)(internalKey, leaves, net, true);
+  if (beaconAddress !== void 0 && payment.address !== beaconAddress) {
+    throw new AggregationCohortError(
+      `Reconstructed beacon address ${payment.address} does not match the cohort's funded address ${beaconAddress}.`,
+      "BEACON_ADDRESS_MISMATCH",
+      { reconstructed: payment.address, expected: beaconAddress }
+    );
+  }
+  const tx = new import_btc_signer6.Transaction({ version: 2, allowUnknownInputs: true });
+  tx.addInput({
+    txid: utxo.txid,
+    index: utxo.vout,
+    witnessUtxo: { script: payment.script, amount: utxo.value },
+    tapLeafScript: payment.tapLeafScript,
+    sequence: recoverySequence
+  });
+  tx.addOutputAddress(destinationAddress, out, net);
+  tx.signIdx(recoverySecretKey, 0);
+  tx.finalize();
+  return tx;
+}
+
 // src/core/aggregation/logger.ts
 var CONSOLE_LOGGER = {
   debug: (msg, ...args) => console.debug(msg, ...args),
@@ -1905,6 +2742,7 @@ var KEYGEN_VALUES = /* @__PURE__ */ new Set([
 ]);
 var UPDATE_VALUES = /* @__PURE__ */ new Set([
   SUBMIT_UPDATE,
+  SUBMIT_NONINCLUDED,
   DISTRIBUTE_AGGREGATED_DATA,
   VALIDATION_ACK
 ]);
@@ -1912,7 +2750,9 @@ var SIGN_VALUES = /* @__PURE__ */ new Set([
   AUTHORIZATION_REQUEST,
   NONCE_CONTRIBUTION,
   AGGREGATED_NONCE,
-  SIGNATURE_AUTHORIZATION
+  SIGNATURE_AUTHORIZATION,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE
 ]);
 function isAggregationMessageType(type) {
   return KEYGEN_VALUES.has(type) || UPDATE_VALUES.has(type) || SIGN_VALUES.has(type);
@@ -2140,7 +2980,7 @@ var Identifier = class _Identifier {
 
 // src/core/aggregation/transport/http/envelope.ts
 var import_common8 = require("@did-btcr2/common");
-var import_utils4 = require("@noble/hashes/utils");
+var import_utils5 = require("@noble/hashes/utils");
 
 // src/core/aggregation/transport/http/errors.ts
 var HttpTransportError = class extends TransportAdapterError {
@@ -2168,7 +3008,7 @@ var DEFAULT_NONCE_LEN_BYTES = 16;
 // src/core/aggregation/transport/http/envelope.ts
 function signEnvelope(message, sender, opts = {}) {
   const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1e3);
-  const nonce = opts.nonce ?? (0, import_utils4.bytesToHex)((0, import_utils4.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
+  const nonce = opts.nonce ?? (0, import_utils5.bytesToHex)((0, import_utils5.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
   const messageJson = normalizeForWire(normalizeMessage(message));
   const unsigned = {
     v: HTTP_ENVELOPE_VERSION,
@@ -2180,7 +3020,7 @@ function signEnvelope(message, sender, opts = {}) {
   };
   const digest = (0, import_common8.canonicalHashBytes)(unsigned);
   const sig = sender.keys.secretKey.sign(digest, { scheme: "schnorr" });
-  return { ...unsigned, sig: (0, import_utils4.bytesToHex)(sig) };
+  return { ...unsigned, sig: (0, import_utils5.bytesToHex)(sig) };
 }
 function verifyEnvelope(envelope, senderPk, opts = {}) {
   if (envelope.v !== HTTP_ENVELOPE_VERSION) {
@@ -2217,7 +3057,7 @@ function verifyEnvelope(envelope, senderPk, opts = {}) {
   }
   let sigBytes;
   try {
-    sigBytes = (0, import_utils4.hexToBytes)(envelope.sig);
+    sigBytes = (0, import_utils5.hexToBytes)(envelope.sig);
   } catch {
     throw new HttpTransportError(
       "Envelope signature is not valid hex",
@@ -2250,7 +3090,7 @@ function normalizeMessage(message) {
 }
 function normalizeForWire(value) {
   if (value instanceof Uint8Array) {
-    return { __bytes: (0, import_utils4.bytesToHex)(value) };
+    return { __bytes: (0, import_utils5.bytesToHex)(value) };
   }
   if (Array.isArray(value)) {
     return value.map((v) => normalizeForWire(v));
@@ -2269,7 +3109,7 @@ function reviveFromWire(value) {
     const rec = value;
     const keys = Object.keys(rec);
     if (keys.length === 1 && keys[0] === "__bytes" && typeof rec.__bytes === "string") {
-      return (0, import_utils4.hexToBytes)(rec.__bytes);
+      return (0, import_utils5.hexToBytes)(rec.__bytes);
     }
     const out = {};
     for (const [k, v] of Object.entries(rec)) out[k] = reviveFromWire(v);
@@ -2283,11 +3123,11 @@ function reviveFromWire(value) {
 
 // src/core/aggregation/transport/http/request-auth.ts
 var import_common9 = require("@did-btcr2/common");
-var import_utils5 = require("@noble/hashes/utils");
+var import_utils6 = require("@noble/hashes/utils");
 var REQUEST_AUTH_SCHEME = "BTCR2-Sig";
 function buildRequestAuth(did, keys, path, opts = {}) {
   const ts = opts.timestamp ?? Math.floor(Date.now() / 1e3);
-  const nonce = opts.nonce ?? (0, import_utils5.bytesToHex)((0, import_utils5.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
+  const nonce = opts.nonce ?? (0, import_utils6.bytesToHex)((0, import_utils6.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
   const digest = (0, import_common9.canonicalHashBytes)({
     v: HTTP_ENVELOPE_VERSION,
     did,
@@ -2296,7 +3136,7 @@ function buildRequestAuth(did, keys, path, opts = {}) {
     path
   });
   const sig = keys.secretKey.sign(digest, { scheme: "schnorr" });
-  return `${REQUEST_AUTH_SCHEME} v=${HTTP_ENVELOPE_VERSION},did=${did},ts=${ts},nonce=${nonce},sig=${(0, import_utils5.bytesToHex)(sig)}`;
+  return `${REQUEST_AUTH_SCHEME} v=${HTTP_ENVELOPE_VERSION},did=${did},ts=${ts},nonce=${nonce},sig=${(0, import_utils6.bytesToHex)(sig)}`;
 }
 function parseRequestAuth(headerValue) {
   const prefix = `${REQUEST_AUTH_SCHEME} `;
@@ -2347,7 +3187,7 @@ function verifyRequestAuth(headerValue, expectedPath, senderPk, opts = {}) {
   }
   let sigBytes;
   try {
-    sigBytes = (0, import_utils5.hexToBytes)(parsed.sig);
+    sigBytes = (0, import_utils6.hexToBytes)(parsed.sig);
   } catch {
     throw new HttpTransportError("Auth signature is not valid hex", "REQUEST_AUTH_SIG_HEX");
   }
@@ -3326,7 +4166,7 @@ function flattenMessage2(msg) {
 
 // src/core/aggregation/transport/nostr.ts
 var import_keypair6 = require("@did-btcr2/keypair");
-var import_utils6 = require("@noble/hashes/utils");
+var import_utils7 = require("@noble/hashes/utils");
 var import_nostr_tools = require("nostr-tools");
 var import_pool = require("nostr-tools/pool");
 var DEFAULT_NOSTR_RELAYS = [
@@ -3524,14 +4364,14 @@ var NostrTransport = class _NostrTransport {
     }
     const senderKeys = actor.keys;
     const tags = [
-      ["p", (0, import_utils6.bytesToHex)(senderKeys.publicKey.x)],
+      ["p", (0, import_utils7.bytesToHex)(senderKeys.publicKey.x)],
       ["t", type]
     ];
     if (to) {
       const recipientPkBytes = this.#peerRegistry.get(to);
       if (recipientPkBytes) {
         const recipientPk = new import_keypair6.CompressedSecp256k1PublicKey(recipientPkBytes);
-        tags.push(["p", (0, import_utils6.bytesToHex)(recipientPk.x)]);
+        tags.push(["p", (0, import_utils7.bytesToHex)(recipientPk.x)]);
       }
     }
     if (isKeygenMessageType(type)) {
@@ -3564,7 +4404,7 @@ var NostrTransport = class _NostrTransport {
       const recipientPk = new import_keypair6.CompressedSecp256k1PublicKey(recipientPkBytes);
       const conversationKey = import_nostr_tools.nip44.v2.utils.getConversationKey(
         senderKeys.secretKey.bytes,
-        (0, import_utils6.bytesToHex)(recipientPk.x)
+        (0, import_utils7.bytesToHex)(recipientPk.x)
       );
       const content = import_nostr_tools.nip44.v2.encrypt(JSON.stringify(message, _NostrTransport.#jsonReplacer), conversationKey);
       const event = (0, import_nostr_tools.finalizeEvent)({
@@ -3587,7 +4427,7 @@ var NostrTransport = class _NostrTransport {
    * backfill historical events to late subscribers: republishing gives late
    * joiners a window to discover the message without requiring protocol
    * changes. Relay rate-limit / publish failures inside the interval are
-   * caught and logged rather than propagated — the caller should stop the
+   * caught and logged rather than propagated - the caller should stop the
    * repeater once the protocol condition is satisfied.
    */
   publishRepeating(message, sender, intervalMs, recipient) {
@@ -3618,7 +4458,7 @@ var NostrTransport = class _NostrTransport {
    */
   #subscribeDirected(did, entry) {
     if (!this.pool) return;
-    const pkHex = (0, import_utils6.bytesToHex)(entry.keys.publicKey.x);
+    const pkHex = (0, import_utils7.bytesToHex)(entry.keys.publicKey.x);
     const sub = this.pool.subscribeMany(this.#relays, { kinds: [1, 1059], "#p": [pkHex] }, {
       onclose: (reasons) => this.#logger.debug(`Nostr directed subscription closed for ${did}`, reasons),
       onevent: this.#makeActorEventHandler(did)
@@ -3636,7 +4476,7 @@ var NostrTransport = class _NostrTransport {
     return async (event) => {
       const actor = this.#actors.get(actorDid);
       if (!actor) return;
-      if (event.pubkey === (0, import_utils6.bytesToHex)(actor.keys.publicKey.x)) return;
+      if (event.pubkey === (0, import_utils7.bytesToHex)(actor.keys.publicKey.x)) return;
       let message;
       try {
         if (event.kind === 1) {
@@ -3749,7 +4589,7 @@ var NostrTransport = class _NostrTransport {
    */
   static #jsonReplacer(_key, value) {
     if (value instanceof Uint8Array) {
-      return { __bytes: (0, import_utils6.bytesToHex)(value) };
+      return { __bytes: (0, import_utils7.bytesToHex)(value) };
     }
     return value;
   }
@@ -3767,7 +4607,7 @@ var NostrTransport = class _NostrTransport {
    */
   static #jsonReviver(_key, value) {
     if (value && typeof value === "object" && "__bytes" in value) {
-      return (0, import_utils6.hexToBytes)(value.__bytes);
+      return (0, import_utils7.hexToBytes)(value.__bytes);
     }
     return value;
   }
@@ -3802,7 +4642,7 @@ var TransportFactory = class {
 };
 
 // src/core/aggregation/transport/in-memory.ts
-var import_utils7 = require("@noble/hashes/utils");
+var import_utils8 = require("@noble/hashes/utils");
 var InMemoryBus = class {
   #transports = /* @__PURE__ */ new Set();
   /** Attach a transport to this bus. Called by the transport's constructor. */
@@ -3821,8 +4661,8 @@ var InMemoryBus = class {
   async deliver(message, _sender, recipient) {
     const type = message.type;
     if (!type) return;
-    const replacer = (_k, v) => v instanceof Uint8Array ? { __bytes: (0, import_utils7.bytesToHex)(v) } : v;
-    const reviver = (_k, v) => v && typeof v === "object" && "__bytes" in v ? (0, import_utils7.hexToBytes)(v.__bytes) : v;
+    const replacer = (_k, v) => v instanceof Uint8Array ? { __bytes: (0, import_utils8.bytesToHex)(v) } : v;
+    const reviver = (_k, v) => v && typeof v === "object" && "__bytes" in v ? (0, import_utils8.hexToBytes)(v.__bytes) : v;
     const raw = JSON.parse(JSON.stringify(message, replacer), reviver);
     const serialized = { ...raw, ...raw.body ?? {} };
     if (!recipient) {
@@ -4021,6 +4861,27 @@ var TypedEventEmitter = class {
   }
 };
 
+// src/core/beacon/fee-estimator.ts
+var StaticFeeEstimator = class {
+  satsPerVbyte;
+  /**
+   * @param satsPerVbyte Fee rate in satoshis per virtual byte. Default: 5 sat/vB.
+   */
+  constructor(satsPerVbyte = 5) {
+    if (satsPerVbyte < 0 || !Number.isFinite(satsPerVbyte)) {
+      throw new Error(`Invalid satsPerVbyte: ${satsPerVbyte}`);
+    }
+    this.satsPerVbyte = satsPerVbyte;
+  }
+  async estimateFee(vsize) {
+    if (vsize < 0 || !Number.isFinite(vsize)) {
+      throw new Error(`Invalid vsize: ${vsize}`);
+    }
+    return BigInt(Math.ceil(vsize * this.satsPerVbyte));
+  }
+};
+var DEFAULT_FEE_ESTIMATOR = new StaticFeeEstimator(5);
+
 // src/core/aggregation/runner/service-runner.ts
 var DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 6e4;
 var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEventEmitter {
@@ -4032,9 +4893,17 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   #onOptInReceived;
   #onReadyToFinalize;
   #onProvideTxData;
+  #feeEstimator;
   #cohortTtlMs;
   #phaseTimeoutMs;
   #advertRepeatIntervalMs;
+  #autoFallbackOnStall;
+  /** Phases during which a stall can be salvaged by the k-of-n fallback (ADR 042). */
+  static #SIGNING_PHASES = [
+    "SigningStarted" /* SigningStarted */,
+    "NoncesCollected" /* NoncesCollected */,
+    "AwaitingPartialSigs" /* AwaitingPartialSigs */
+  ];
   /** Per-cohort run state, keyed by cohortId. */
   #contexts = /* @__PURE__ */ new Map();
   #handlersRegistered = false;
@@ -4049,9 +4918,11 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       finalize: acceptedCount >= minRequired
     }));
     this.#onProvideTxData = options.onProvideTxData;
+    this.#feeEstimator = options.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
     this.#cohortTtlMs = options.cohortTtlMs;
     this.#phaseTimeoutMs = options.phaseTimeoutMs;
     this.#advertRepeatIntervalMs = options.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+    this.#autoFallbackOnStall = options.autoFallbackOnStall ?? false;
     this.session = new AggregationService({
       // The coordinator never signs, so the state machine receives only the
       // public half of the operator's keypair (see ADR 038). The full keypair
@@ -4213,11 +5084,42 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
     ctx.phaseTimer = void 0;
     if (this.#phaseTimeoutMs === void 0) return;
     ctx.phaseTimer = setTimeout(() => {
+      const phase = this.session.getCohortPhase(ctx.cohortId);
+      const inSigning = phase !== void 0 && _AggregationServiceRunner.#SIGNING_PHASES.includes(phase);
+      if (this.#autoFallbackOnStall && inSigning && !ctx.committedPath && !ctx.settled) {
+        this.triggerFallback(ctx.cohortId).catch((err) => this.#failCohort(ctx, err));
+        return;
+      }
       const reason = `Cohort ${ctx.cohortId} stalled in phase ${ctx.lastObservedPhase ?? "?"} for ${this.#phaseTimeoutMs}ms`;
       this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
       this.#failCohort(ctx, new Error(reason));
     }, this.#phaseTimeoutMs);
   }
+  /**
+   * Abandon the optimistic n-of-n key path for a cohort and collect k-of-n
+   * fallback (script-path) signatures instead (ADR 042). Idempotent and safe
+   * against the optimistic completion: it commits the cohort to the fallback
+   * path synchronously (the `committedPath` latch) before sending anything, so a
+   * late optimistic signature can no longer complete-and-broadcast a competing
+   * spend of the same UTXO. No-op if the cohort is unknown, already settled, or
+   * already committed to a path.
+   *
+   * Wired automatically to the phase-stall timer when `autoFallbackOnStall` is
+   * set; otherwise call it from an operator decision (a UI "fall back now"
+   * action). Throws only if the underlying state machine rejects the transition
+   * (e.g. signing has not started).
+   */
+  async triggerFallback(cohortId) {
+    const ctx = this.#contexts.get(cohortId);
+    if (!ctx || ctx.settled || ctx.committedPath) return;
+    const messages = this.session.startFallbackSigning(cohortId);
+    ctx.committedPath = "fallback";
+    this.#stopAdvertRepeating(ctx);
+    this.#onPhaseMaybeChanged(ctx);
+    const sessionId = this.session.getSigningSessionId(cohortId) ?? "";
+    this.emit("fallback-started", { cohortId, sessionId });
+    await this.#sendAll(messages);
+  }
   /** Detect a phase change for a cohort since the last observation and reset its phase timer. */
   #onPhaseMaybeChanged(ctx) {
     const phase = this.session.getCohortPhase(ctx.cohortId);
@@ -4306,13 +5208,15 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   static #HANDLED_MESSAGE_TYPES = [
     COHORT_OPT_IN,
     SUBMIT_UPDATE,
+    SUBMIT_NONINCLUDED,
     VALIDATION_ACK,
     NONCE_CONTRIBUTION,
-    SIGNATURE_AUTHORIZATION
+    SIGNATURE_AUTHORIZATION,
+    FALLBACK_SIGNATURE
   ];
   /**
    * Internal: handler registration with the transport. Idempotent. Handlers
-   * are DID-scoped and cohort-agnostic — one registration serves every cohort
+   * are DID-scoped and cohort-agnostic - one registration serves every cohort
    * this runner drives; demux to the right {@link RunContext} happens in each
    * handler via the inbound message's cohortId.
    */
@@ -4321,9 +5225,11 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
     this.#handlersRegistered = true;
     this.#transport.registerMessageHandler(this.#did, COHORT_OPT_IN, this.#handleOptIn.bind(this));
     this.#transport.registerMessageHandler(this.#did, SUBMIT_UPDATE, this.#handleSubmitUpdate.bind(this));
+    this.#transport.registerMessageHandler(this.#did, SUBMIT_NONINCLUDED, this.#handleSubmitUpdate.bind(this));
     this.#transport.registerMessageHandler(this.#did, VALIDATION_ACK, this.#handleValidationAck.bind(this));
     this.#transport.registerMessageHandler(this.#did, NONCE_CONTRIBUTION, this.#handleNonceContribution.bind(this));
     this.#transport.registerMessageHandler(this.#did, SIGNATURE_AUTHORIZATION, this.#handleSignatureAuthorization.bind(this));
+    this.#transport.registerMessageHandler(this.#did, FALLBACK_SIGNATURE, this.#handleFallbackSignature.bind(this));
   }
   /** Internal: detach from the transport. Safe to call repeatedly. */
   #unregisterHandlers() {
@@ -4443,7 +5349,8 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
         const txData = await this.#onProvideTxData({
           cohortId: ctx.cohortId,
           beaconAddress: cohort.beaconAddress,
-          signalBytes: cohort.signalBytes
+          signalBytes: cohort.signalBytes,
+          feeEstimator: this.#feeEstimator
         });
         const authMsgs = this.session.startSigning(ctx.cohortId, txData);
         const sessionId = this.session.getSigningSessionId(ctx.cohortId) ?? "";
@@ -4484,6 +5391,32 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
    * @returns {Promise<void>} Resolves when handling is complete.
    */
   async #handleSignatureAuthorization(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      if (ctx.committedPath === "fallback") return;
+      const result = this.session.getResult(ctx.cohortId);
+      if (result) {
+        ctx.committedPath = "optimistic";
+        this.#completeCohort(ctx, result);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Handler for receiving fallback (k-of-n script-path) signatures. The state
+   * machine assembles and finalizes the fallback spend once k valid signatures
+   * are in; the result is then emitted and the cohort's completion resolves. The
+   * cohort is already committed to the fallback path (via {@link triggerFallback}).
+   * @param {BaseMessage} msg - The incoming FALLBACK_SIGNATURE message.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleFallbackSignature(msg) {
     if (this.#stopped) return;
     const ctx = this.#contextFor(msg);
     if (!ctx) return;
@@ -4556,7 +5489,8 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
     COHORT_READY,
     DISTRIBUTE_AGGREGATED_DATA,
     AUTHORIZATION_REQUEST,
-    AGGREGATED_NONCE
+    AGGREGATED_NONCE,
+    FALLBACK_AUTHORIZATION_REQUEST
   ];
   /** Internal: detach from the transport. Safe to call repeatedly. */
   #unregisterHandlers() {
@@ -4591,7 +5525,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
    *
    * For an open-ended, long-lived subscriber (no fixed count), construct an
    * {@link AggregationParticipantRunner} directly, set `shouldJoin`, call
-   * `start()`, and listen for `cohort-complete` — the runner already drives
+   * `start()`, and listen for `cohort-complete` - the runner already drives
    * any number of cohorts concurrently.
    *
    * @param options Participant runner options (set `shouldJoin` to select cohorts).
@@ -4626,6 +5560,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
     this.#transport.registerMessageHandler(this.#did, DISTRIBUTE_AGGREGATED_DATA, this.#handleDistributeData.bind(this));
     this.#transport.registerMessageHandler(this.#did, AUTHORIZATION_REQUEST, this.#handleAuthorizationRequest.bind(this));
     this.#transport.registerMessageHandler(this.#did, AGGREGATED_NONCE, this.#handleAggregatedNonce.bind(this));
+    this.#transport.registerMessageHandler(this.#did, FALLBACK_AUTHORIZATION_REQUEST, this.#handleFallbackAuthorizationRequest.bind(this));
   }
   /**
    * Internal: handler for cohort adverts. Applies the `shouldJoin` filter and joins if approved.
@@ -4681,8 +5616,13 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
         cohortId,
         beaconAddress: info.beaconAddress
       });
-      await this.#sendAll(this.session.submitUpdate(cohortId, signedUpdate));
-      this.emit("update-submitted", { cohortId });
+      if (signedUpdate === null) {
+        await this.#sendAll(this.session.declineUpdate(cohortId));
+        this.emit("update-declined", { cohortId });
+      } else {
+        await this.#sendAll(this.session.submitUpdate(cohortId, signedUpdate));
+        this.emit("update-submitted", { cohortId });
+      }
     } catch (err) {
       this.emit("error", err);
     }
@@ -4758,23 +5698,62 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
       const cohortId = msg.body?.cohortId;
       if (!cohortId) return;
       await this.#sendAll(this.session.generatePartialSignature(cohortId));
-      if (this.session.getCohortPhase(cohortId) === "Complete" /* Complete */) {
-        const info = this.session.joinedCohorts.get(cohortId);
-        if (info) {
-          const validation = this.session.getValidation(cohortId);
-          this.emit("cohort-complete", {
-            cohortId,
-            beaconAddress: info.beaconAddress,
-            beaconType: validation?.beaconType ?? "",
-            casAnnouncement: validation?.casAnnouncement,
-            smtProof: validation?.smtProof
-          });
-        }
+      this.#emitCohortCompleteIfDone(cohortId);
+    } catch (err) {
+      this.emit("error", err);
+    }
+  }
+  /**
+   * Internal: handler for fallback authorization requests. The service abandoned
+   * the optimistic key path; the member authorizes the k-of-n script-path spend
+   * of the same beacon transaction (ADR 042). Reuses `onApproveSigning` to gate
+   * the decision, signs the fallback, and completes once it has contributed (the
+   * service needs only k members).
+   * @param {BaseMessage} msg - The received fallback authorization request message.
+   * @returns {Promise<void>} Resolves when processing is complete.
+   */
+  async #handleFallbackAuthorizationRequest(msg) {
+    if (this.#stopped) return;
+    try {
+      this.session.receive(msg);
+      const cohortId = msg.body?.cohortId;
+      if (!cohortId) return;
+      const req = this.session.pendingFallbackRequests.get(cohortId);
+      if (!req) return;
+      this.emit("fallback-requested", req);
+      const decision = await this.#onApproveSigning(req);
+      if (!decision.approved) {
+        this.emit("cohort-failed", { cohortId, reason: "Fallback signing rejected by participant" });
+        return;
       }
+      await this.#sendAll(this.session.approveFallback(cohortId));
+      this.#emitCohortCompleteIfDone(cohortId);
     } catch (err) {
       this.emit("error", err);
     }
   }
+  /**
+   * Internal: emit `cohort-complete` with the participant's retained sidecar once
+   * the cohort has reached the Complete phase. Surfaces the CAS Announcement map
+   * (CAS beacons) or the SMT proof (SMT beacons) the participant keeps for future
+   * DID resolution. Read via getValidation (not pendingValidations, which lists
+   * only the AwaitingValidation phase) so the sidecar is still available at
+   * Complete. Shared by the optimistic and fallback completion paths.
+   */
+  #emitCohortCompleteIfDone(cohortId) {
+    if (this.session.getCohortPhase(cohortId) !== "Complete" /* Complete */) return;
+    const info = this.session.joinedCohorts.get(cohortId);
+    if (!info) return;
+    const validation = this.session.getValidation(cohortId);
+    this.emit("cohort-complete", {
+      cohortId,
+      beaconAddress: info.beaconAddress,
+      beaconType: validation?.beaconType ?? "",
+      included: validation?.included ?? true,
+      casAnnouncement: validation?.casAnnouncement,
+      smtProof: validation?.smtProof
+    });
+  }
   /**
    * Internal: send helper to ensure messages are sent sequentially. This is important for protocol
    * correctness, as some transports may not guarantee message order if sent in parallel.
@@ -4790,6 +5769,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
 };
 
 // src/core/aggregation/runner/aggregation-runner.ts
+var import_utils9 = require("@noble/hashes/utils");
 var AggregationRunner = class {
   /**
    * Run a cohort of ONE participant entirely in-process and return the
@@ -4797,8 +5777,8 @@ var AggregationRunner = class {
    *
    * One party plays both the coordinating service and the lone participant,
    * connected over an {@link InMemoryTransport} (no relay or HTTP server). This
-   * makes the single-participant aggregate-beacon path — the N=1 corner of the
-   * two-axis beacon matrix (see ADR 037) — first-class, useful for generating
+   * makes the single-participant aggregate-beacon path (the N=1 corner of the
+   * two-axis beacon matrix, see ADR 037) first-class, useful for generating
    * and reproducing single-participant aggregate test vectors.
    *
    * The service advertises a cohort with `minParticipants: 1`; the participant
@@ -4816,12 +5796,15 @@ var AggregationRunner = class {
     transport.registerPeer(options.participant.did, options.participant.keys.publicKey.compressed);
     transport.registerPeer(options.service.did, options.service.keys.publicKey.compressed);
     transport.start();
+    const recoveryKey = options.config.recoveryKey ?? (0, import_utils9.bytesToHex)(options.service.keys.publicKey.compressed.slice(1));
+    const recoverySequence = options.config.recoverySequence ?? DEFAULT_RECOVERY_SEQUENCE;
     const service = new AggregationServiceRunner({
       transport,
       did: options.service.did,
       keys: options.service.keys,
-      config: { minParticipants: 1, network: options.config.network, beaconType: options.config.beaconType },
+      config: { minParticipants: 1, network: options.config.network, beaconType: options.config.beaconType, recoveryKey, recoverySequence, fundingModel: DEFAULT_FUNDING_MODEL },
       onProvideTxData: options.onProvideTxData,
+      feeEstimator: options.feeEstimator,
       cohortTtlMs: options.cohortTtlMs,
       phaseTimeoutMs: options.phaseTimeoutMs,
       // In-process bus with the participant already listening: a single advert
@@ -4846,8 +5829,8 @@ var AggregationRunner = class {
 };
 
 // src/core/beacon/beacon.ts
-var import_utils8 = require("@noble/hashes/utils.js");
-var import_btc_signer4 = require("@scure/btc-signer");
+var import_utils10 = require("@noble/hashes/utils.js");
+var import_btc_signer7 = require("@scure/btc-signer");
 
 // src/core/beacon/error.ts
 var import_common12 = require("@did-btcr2/common");
@@ -4877,28 +5860,7 @@ var SMTBeaconError = class extends import_common12.MethodError {
   }
 };
 
-// src/core/beacon/fee-estimator.ts
-var StaticFeeEstimator = class {
-  satsPerVbyte;
-  /**
-   * @param satsPerVbyte Fee rate in satoshis per virtual byte. Default: 5 sat/vB.
-   */
-  constructor(satsPerVbyte = 5) {
-    if (satsPerVbyte < 0 || !Number.isFinite(satsPerVbyte)) {
-      throw new Error(`Invalid satsPerVbyte: ${satsPerVbyte}`);
-    }
-    this.satsPerVbyte = satsPerVbyte;
-  }
-  async estimateFee(vsize) {
-    if (vsize < 0 || !Number.isFinite(vsize)) {
-      throw new Error(`Invalid vsize: ${vsize}`);
-    }
-    return BigInt(Math.ceil(vsize * this.satsPerVbyte));
-  }
-};
-
 // src/core/beacon/beacon.ts
-var DEFAULT_FEE_ESTIMATOR = new StaticFeeEstimator(5);
 var P2TR_BEACON_TX_VSIZE = 160;
 var P2WPKH_BEACON_TX_VSIZE = 155;
 var P2PKH_BEACON_TX_VSIZE = 240;
@@ -4907,8 +5869,22 @@ var SINGLETON_BEACON_TX_VSIZE = {
   p2wpkh: P2WPKH_BEACON_TX_VSIZE,
   p2tr: P2TR_BEACON_TX_VSIZE
 };
+var CHANGE_OUTPUT_VBYTES = {
+  p2pkh: 34,
+  p2wpkh: 31,
+  p2tr: 43
+};
+var DUST_LIMIT_SATS2 = {
+  p2pkh: 546,
+  p2wpkh: 294,
+  p2tr: 330
+};
+function beaconTxVsize(beaconKind, changeKind) {
+  const base2 = SINGLETON_BEACON_TX_VSIZE[beaconKind] - CHANGE_OUTPUT_VBYTES[beaconKind];
+  return base2 + CHANGE_OUTPUT_VBYTES[changeKind];
+}
 function detectSingletonScriptKind(bitcoinAddress, network) {
-  const decoded = (0, import_btc_signer4.Address)(network).decode(bitcoinAddress);
+  const decoded = (0, import_btc_signer7.Address)(network).decode(bitcoinAddress);
   if (decoded.type === "pkh") return "p2pkh";
   if (decoded.type === "wpkh") return "p2wpkh";
   if (decoded.type === "tr") return "p2tr";
@@ -4919,12 +5895,32 @@ function detectSingletonScriptKind(bitcoinAddress, network) {
   );
 }
 function deriveSingletonAddress(kind, pubkey, network) {
-  if (kind === "p2pkh") return (0, import_btc_signer4.p2pkh)(pubkey, network).address;
-  if (kind === "p2wpkh") return (0, import_btc_signer4.p2wpkh)(pubkey, network).address;
-  return (0, import_btc_signer4.p2tr)(pubkey.slice(1, 33), void 0, network).address;
+  if (kind === "p2pkh") return (0, import_btc_signer7.p2pkh)(pubkey, network).address;
+  if (kind === "p2wpkh") return (0, import_btc_signer7.p2wpkh)(pubkey, network).address;
+  return (0, import_btc_signer7.p2tr)(pubkey.slice(1, 33), void 0, network).address;
+}
+function resolveChangeAddress(beaconAddress, network, changeAddress) {
+  if (!changeAddress || changeAddress === beaconAddress) return beaconAddress;
+  try {
+    (0, import_btc_signer7.Address)(network).decode(changeAddress);
+  } catch {
+    throw new BeaconError(
+      `Invalid change address "${changeAddress}" for network "${network}".`,
+      "INVALID_CHANGE_ADDRESS",
+      { changeAddress, network }
+    );
+  }
+  return changeAddress;
+}
+function changeOutputKind(changeAddress, network) {
+  try {
+    return detectSingletonScriptKind(changeAddress, network);
+  } catch {
+    return "p2tr";
+  }
 }
 function opReturnScript(signalBytes) {
-  return import_btc_signer4.Script.encode(["RETURN", signalBytes]);
+  return import_btc_signer7.Script.encode(["RETURN", signalBytes]);
 }
 async function fetchSpendableUtxo(bitcoinAddress, bitcoin) {
   const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
@@ -4944,14 +5940,15 @@ async function fetchSpendableUtxo(bitcoinAddress, bitcoin) {
     );
   }
   const prevTxHex = await bitcoin.rest.transaction.getHex(utxo.txid);
-  return { utxo, prevTxBytes: (0, import_utils8.hexToBytes)(prevTxHex) };
+  return { utxo, prevTxBytes: (0, import_utils10.hexToBytes)(prevTxHex) };
 }
 async function buildAggregationBeaconTx(opts) {
   const feeEstimator = opts.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
   const { utxo, prevTxBytes } = await fetchSpendableUtxo(opts.beaconAddress, opts.bitcoin);
-  const tapOut = (0, import_btc_signer4.p2tr)(opts.internalPubkey, void 0, opts.network);
-  const witnessScript = tapOut.script;
-  const feeSats = await feeEstimator.estimateFee(P2TR_BEACON_TX_VSIZE);
+  const changeAddress = resolveChangeAddress(opts.beaconAddress, opts.network, opts.changeAddress);
+  const witnessScript = import_btc_signer7.OutScript.encode((0, import_btc_signer7.Address)(opts.network).decode(opts.beaconAddress));
+  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}).`,
@@ -4959,7 +5956,7 @@ async function buildAggregationBeaconTx(opts) {
       { address: opts.beaconAddress, valueSats: utxo.value, feeSats }
     );
   }
-  const tx = new import_btc_signer4.Transaction({ allowUnknownOutputs: true });
+  const tx = new import_btc_signer7.Transaction({ allowUnknownOutputs: true });
   tx.addInput({
     txid: utxo.txid,
     index: utxo.vout,
@@ -4967,13 +5964,17 @@ async function buildAggregationBeaconTx(opts) {
     witnessUtxo: { amount: BigInt(utxo.value), script: witnessScript },
     tapInternalKey: opts.internalPubkey
   });
-  tx.addOutputAddress(opts.beaconAddress, BigInt(utxo.value) - feeSats, opts.network);
+  const changeValue = BigInt(utxo.value) - feeSats;
+  if (changeValue >= BigInt(DUST_LIMIT_SATS2[changeKind])) {
+    tx.addOutputAddress(changeAddress, changeValue, opts.network);
+  }
   tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
   return {
     tx,
     prevOutScripts: [witnessScript],
     prevOutValues: [BigInt(utxo.value)],
     beaconAddress: opts.beaconAddress,
+    changeAddress,
     utxo,
     feeSats,
     scriptKind: "p2tr"
@@ -4982,16 +5983,16 @@ async function buildAggregationBeaconTx(opts) {
 async function signSingletonInput(tx, inputIdx, kind, signer, prevOutScript, amount) {
   const pubkey = signer.publicKey;
   if (kind === "p2pkh") {
-    const sighashType = import_btc_signer4.SigHash.ALL;
+    const sighashType = import_btc_signer7.SigHash.ALL;
     const sighash2 = tx.preimageLegacy(inputIdx, prevOutScript, sighashType);
     const sig2 = signer.sign(sighash2, "ecdsa");
-    const sigWithType = (0, import_utils8.concatBytes)(sig2, new Uint8Array([sighashType]));
+    const sigWithType = (0, import_utils10.concatBytes)(sig2, new Uint8Array([sighashType]));
     tx.updateInput(inputIdx, { partialSig: [[pubkey, sigWithType]] }, true);
     tx.finalize();
     return tx.hex;
   }
   if (kind === "p2wpkh") {
-    const decoded = import_btc_signer4.OutScript.decode(prevOutScript);
+    const decoded = import_btc_signer7.OutScript.decode(prevOutScript);
     if (decoded.type !== "wpkh") {
       throw new BeaconError(
         `Expected P2WPKH prev-output script, got "${decoded.type}".`,
@@ -4999,16 +6000,16 @@ async function signSingletonInput(tx, inputIdx, kind, signer, prevOutScript, amo
         { kind, observedScriptType: decoded.type }
       );
     }
-    const sighashScript = import_btc_signer4.OutScript.encode({ type: "pkh", hash: decoded.hash });
-    const sighashType = import_btc_signer4.SigHash.ALL;
+    const sighashScript = import_btc_signer7.OutScript.encode({ type: "pkh", hash: decoded.hash });
+    const sighashType = import_btc_signer7.SigHash.ALL;
     const sighash2 = tx.preimageWitnessV0(inputIdx, sighashScript, sighashType, amount);
     const sig2 = signer.sign(sighash2, "ecdsa");
-    const sigWithType = (0, import_utils8.concatBytes)(sig2, new Uint8Array([sighashType]));
+    const sigWithType = (0, import_utils10.concatBytes)(sig2, new Uint8Array([sighashType]));
     tx.updateInput(inputIdx, { partialSig: [[pubkey, sigWithType]] }, true);
     tx.finalize();
     return tx.hex;
   }
-  const sighash = tx.preimageWitnessV1(inputIdx, [prevOutScript], import_btc_signer4.SigHash.DEFAULT, [amount]);
+  const sighash = tx.preimageWitnessV1(inputIdx, [prevOutScript], import_btc_signer7.SigHash.DEFAULT, [amount]);
   const sig = signer.sign(sighash, "bip341");
   tx.updateInput(inputIdx, { tapKeySig: sig });
   tx.finalize();
@@ -5029,7 +6030,7 @@ var SinglePartyBeacon = class {
    *
    * 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.
    *
@@ -5051,7 +6052,8 @@ var SinglePartyBeacon = class {
       prevTxBytes,
       signer,
       bitcoin,
-      feeEstimator
+      feeEstimator,
+      changeAddress: options?.changeAddress
     });
     const signedHex = await this.signSinglePartyTx(plan, signer);
     return this.broadcastRawTx(bitcoin, signedHex);
@@ -5061,15 +6063,17 @@ var SinglePartyBeacon = class {
    *
    * 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.
    */
   async buildSinglePartyTx(opts) {
     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) {
       throw new BeaconError(
@@ -5078,7 +6082,8 @@ var SinglePartyBeacon = class {
         { kind, address: opts.beaconAddress, derivedAddress }
       );
     }
-    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(
@@ -5087,17 +6092,17 @@ var SinglePartyBeacon = class {
         { address: opts.beaconAddress, valueSats: opts.utxo.value, feeSats }
       );
     }
-    const tx = new import_btc_signer4.Transaction({ allowUnknownOutputs: true });
+    const tx = new import_btc_signer7.Transaction({ allowUnknownOutputs: true });
     let prevOutScript;
     if (kind === "p2pkh") {
-      prevOutScript = (0, import_btc_signer4.p2pkh)(pubkey, network).script;
+      prevOutScript = (0, import_btc_signer7.p2pkh)(pubkey, network).script;
       tx.addInput({
         txid: opts.utxo.txid,
         index: opts.utxo.vout,
         nonWitnessUtxo: opts.prevTxBytes
       });
     } else if (kind === "p2wpkh") {
-      prevOutScript = (0, import_btc_signer4.p2wpkh)(pubkey, network).script;
+      prevOutScript = (0, import_btc_signer7.p2wpkh)(pubkey, network).script;
       tx.addInput({
         txid: opts.utxo.txid,
         index: opts.utxo.vout,
@@ -5106,7 +6111,7 @@ var SinglePartyBeacon = class {
       });
     } else {
       const internalKey = pubkey.slice(1, 33);
-      prevOutScript = (0, import_btc_signer4.p2tr)(internalKey, void 0, network).script;
+      prevOutScript = (0, import_btc_signer7.p2tr)(internalKey, void 0, network).script;
       tx.addInput({
         txid: opts.utxo.txid,
         index: opts.utxo.vout,
@@ -5115,13 +6120,17 @@ var SinglePartyBeacon = class {
         tapInternalKey: internalKey
       });
     }
-    tx.addOutputAddress(opts.beaconAddress, amount - feeSats, network);
+    const changeValue = amount - feeSats;
+    if (changeValue >= BigInt(DUST_LIMIT_SATS2[changeKind])) {
+      tx.addOutputAddress(changeAddress, changeValue, network);
+    }
     tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
     return {
       tx,
       prevOutScripts: [prevOutScript],
       prevOutValues: [amount],
       beaconAddress: opts.beaconAddress,
+      changeAddress,
       utxo: opts.utxo,
       feeSats,
       scriptKind: kind
@@ -5295,7 +6304,7 @@ var SingletonBeacon = class extends SinglePartyBeacon {
 // src/core/beacon/smt-beacon.ts
 var import_common15 = require("@did-btcr2/common");
 var import_smt3 = require("@did-btcr2/smt");
-var import_utils9 = require("@noble/hashes/utils");
+var import_utils11 = require("@noble/hashes/utils");
 var SMTBeacon = class extends SinglePartyBeacon {
   /**
    * Creates an instance of SMTBeacon.
@@ -5384,7 +6393,7 @@ var SMTBeacon = class extends SinglePartyBeacon {
   async broadcastSignal(signedUpdate, signer, bitcoin, options) {
     const did = this.service.id.split("#")[0];
     const canonicalBytes = new TextEncoder().encode((0, import_common15.canonicalize)(signedUpdate));
-    const nonce = (0, import_utils9.randomBytes)(32);
+    const nonce = (0, import_utils11.randomBytes)(32);
     const tree = new import_smt3.BTCR2MerkleTree();
     tree.addEntries([{ did, nonce, signedUpdate: canonicalBytes }]);
     tree.finalize();
@@ -5415,13 +6424,13 @@ var BeaconFactory = class {
 };
 
 // src/core/beacon/signal-discovery.ts
-var import_bitcoin3 = require("@did-btcr2/bitcoin");
+var import_bitcoin5 = require("@did-btcr2/bitcoin");
 var import_common18 = require("@did-btcr2/common");
 
 // src/core/beacon/utils.ts
-var import_bitcoin2 = require("@did-btcr2/bitcoin");
+var import_bitcoin4 = require("@did-btcr2/bitcoin");
 var import_common17 = require("@did-btcr2/common");
-var import_btc_signer5 = require("@scure/btc-signer");
+var import_btc_signer8 = require("@scure/btc-signer");
 
 // src/utils/appendix.ts
 var import_dids = require("@web5/dids");
@@ -6526,10 +7535,10 @@ var BeaconUtils = class {
   static createBeaconService(did, addressType, beaconType) {
     try {
       const components = Identifier.decode(did);
-      const network = (0, import_bitcoin2.getNetwork)(components.network);
+      const network = (0, import_bitcoin4.getNetwork)(components.network);
       const pubkey = components.genesisBytes;
       const id = `${did}#initial${addressType.toUpperCase()}`;
-      const address = addressType === "p2tr" ? (0, import_btc_signer5.p2tr)(pubkey.slice(1, 33), void 0, network).address : addressType === "p2wpkh" ? (0, import_btc_signer5.p2wpkh)(pubkey, network).address : (0, import_btc_signer5.p2pkh)(pubkey, network).address;
+      const address = addressType === "p2tr" ? (0, import_btc_signer8.p2tr)(pubkey.slice(1, 33), void 0, network).address : addressType === "p2wpkh" ? (0, import_btc_signer8.p2wpkh)(pubkey, network).address : (0, import_btc_signer8.p2pkh)(pubkey, network).address;
       const serviceEndpoint = `bitcoin:${address}`;
       return { id, type: beaconType, serviceEndpoint };
     } catch (error) {
@@ -6548,9 +7557,9 @@ var BeaconUtils = class {
    */
   static generateBeaconServices({ id, publicKey, network, beaconType }) {
     try {
-      const p2pkhAddr = (0, import_btc_signer5.p2pkh)(publicKey, network).address;
-      const p2wpkhAddr = (0, import_btc_signer5.p2wpkh)(publicKey, network).address;
-      const p2trAddr = (0, import_btc_signer5.p2tr)(publicKey.slice(1, 33), void 0, network).address;
+      const p2pkhAddr = (0, import_btc_signer8.p2pkh)(publicKey, network).address;
+      const p2wpkhAddr = (0, import_btc_signer8.p2wpkh)(publicKey, network).address;
+      const p2trAddr = (0, import_btc_signer8.p2tr)(publicKey.slice(1, 33), void 0, network).address;
       if (!p2pkhAddr || !p2wpkhAddr || !p2trAddr) {
         throw new import_common17.DidMethodError("Failed to generate bitcoin addresses");
       }
@@ -6677,14 +7686,14 @@ var BeaconSignalDiscovery = class {
     console.info(`Searching for beacon signals, please wait ...`);
     while (block.height <= targetHeight) {
       for (const tx of block.tx) {
-        if (tx.txid === import_bitcoin3.GENESIS_TX_ID) {
+        if (tx.txid === import_bitcoin5.GENESIS_TX_ID) {
           continue;
         }
         for (const vin of tx.vin) {
           if (vin.coinbase) {
             continue;
           }
-          if (vin.txinwitness && vin.txinwitness.length === 1 && vin.txinwitness[0] === import_bitcoin3.TXIN_WITNESS_COINBASE) {
+          if (vin.txinwitness && vin.txinwitness.length === 1 && vin.txinwitness[0] === import_bitcoin5.TXIN_WITNESS_COINBASE) {
             continue;
           }
           if (!vin.txid) {
@@ -6738,7 +7747,7 @@ var BeaconSignalDiscovery = class {
 };
 
 // src/core/resolver.ts
-var import_bitcoin5 = require("@did-btcr2/bitcoin");
+var import_bitcoin7 = require("@did-btcr2/bitcoin");
 var import_common22 = require("@did-btcr2/common");
 var import_cryptosuite3 = require("@did-btcr2/cryptosuite");
 var import_keypair8 = require("@did-btcr2/keypair");
@@ -6752,11 +7761,11 @@ var import_common20 = require("@did-btcr2/common");
 var import_cryptosuite2 = require("@did-btcr2/cryptosuite");
 
 // src/utils/did-document.ts
-var import_bitcoin4 = require("@did-btcr2/bitcoin");
+var import_bitcoin6 = require("@did-btcr2/bitcoin");
 var import_common19 = require("@did-btcr2/common");
 var import_keypair7 = require("@did-btcr2/keypair");
-var import_utils11 = require("@web5/dids/utils");
-var import_btc_signer6 = require("@scure/btc-signer");
+var import_utils13 = require("@web5/dids/utils");
+var import_btc_signer9 = require("@scure/btc-signer");
 var BTCR2_DID_DOCUMENT_CONTEXT = [
   "https://www.w3.org/ns/did/v1.1",
   "https://btcr2.dev/context/v1"
@@ -6965,7 +7974,7 @@ var DidDocument = class _DidDocument {
    * @returns {boolean} True if the services are valid.
    */
   static isValidServices(service) {
-    return Array.isArray(service) && service.every(import_utils11.isDidService);
+    return Array.isArray(service) && service.every(import_utils13.isDidService);
   }
   /**
    * Validates verification relationships (authentication, assertionMethod, capabilityInvocation, capabilityDelegation).
@@ -7078,7 +8087,7 @@ var GenesisDocument = class _GenesisDocument extends DidDocument {
   static fromPublicKey(publicKey, network) {
     const pk = new import_keypair7.CompressedSecp256k1PublicKey(publicKey);
     const id = ID_PLACEHOLDER_VALUE;
-    const address = (0, import_btc_signer6.p2pkh)(pk.compressed, (0, import_bitcoin4.getNetwork)(network)).address;
+    const address = (0, import_btc_signer9.p2pkh)(pk.compressed, (0, import_bitcoin6.getNetwork)(network)).address;
     const services = [{
       id: `${id}#service-0`,
       serviceEndpoint: `bitcoin:${address}`,
@@ -7127,7 +8136,7 @@ var Updater = class _Updater {
   #verificationMethod;
   #beaconService;
   /**
-   * @internal — Use {@link DidBtcr2.update} to create instances.
+   * @internal Use {@link DidBtcr2.update} to create instances.
    */
   constructor(params) {
     this.#sourceDocument = params.sourceDocument;
@@ -7164,7 +8173,7 @@ var Updater = class _Updater {
     const targetDocument = import_common20.JSONPatch.apply(sourceDocument, patches);
     if (targetDocument.id !== sourceDocument.id) {
       throw new import_common20.UpdateError(
-        `Patches must not change the DID document id (source "${sourceDocument.id}" \u2192 target "${targetDocument.id}").`,
+        `Patches must not change the DID document id (source "${sourceDocument.id}" to target "${targetDocument.id}").`,
         import_common20.INVALID_DID_UPDATE,
         { sourceId: sourceDocument.id, targetId: targetDocument.id }
       );
@@ -7248,8 +8257,8 @@ var Updater = 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() {
     while (true) {
@@ -7262,7 +8271,7 @@ var Updater = class _Updater {
           continue;
         }
         // 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",
@@ -7445,8 +8454,8 @@ var DidBtcr2 = class {
    *
    * 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
@@ -7545,7 +8554,7 @@ var DidBtcr2 = class {
 };
 
 // src/core/resolver.ts
-var import_utils13 = require("@noble/curves/utils.js");
+var import_utils15 = require("@noble/curves/utils.js");
 var Resolver = class _Resolver {
   // --- Immutable inputs ---
   #didComponents;
@@ -7564,7 +8573,7 @@ var Resolver = class _Resolver {
   #unsortedUpdates = [];
   #resolvedResponse = null;
   /**
-   * @internal — Use {@link DidBtcr2.resolve} to create instances.
+   * @internal Use {@link DidBtcr2.resolve} to create instances.
    */
   constructor(didComponents, sidecarData, currentDocument, options) {
     this.#didComponents = didComponents;
@@ -7589,7 +8598,7 @@ var Resolver = class _Resolver {
     const service = BeaconUtils.generateBeaconServices({
       id: did,
       publicKey: genesisBytes,
-      network: (0, import_bitcoin5.getNetwork)(didComponents.network),
+      network: (0, import_bitcoin7.getNetwork)(didComponents.network),
       beaconType: "SingletonBeacon"
     });
     return new DidDocument({
@@ -7612,7 +8621,7 @@ var Resolver = class _Resolver {
    */
   static external(didComponents, genesisDocument) {
     const genesisDocumentHash = (0, import_common22.canonicalHashBytes)(genesisDocument);
-    if (!(0, import_utils13.equalBytes)(didComponents.genesisBytes, genesisDocumentHash)) {
+    if (!(0, import_utils15.equalBytes)(didComponents.genesisBytes, genesisDocumentHash)) {
       throw new import_common22.ResolveError(
         `Initial document mismatch: genesisBytes !== genesisDocumentHash`,
         import_common22.INVALID_DID_DOCUMENT,
@@ -7689,7 +8698,7 @@ var Resolver = class _Resolver {
         this.confirmDuplicate(update, updateHashHistory);
       } else if (update.targetVersionId === currentVersionId + 1) {
         const sourceHashBytes = (0, import_common22.decode)(update.sourceHash, "base64urlnopad");
-        if (!(0, import_utils13.equalBytes)(sourceHashBytes, currentDocumentHash)) {
+        if (!(0, import_utils15.equalBytes)(sourceHashBytes, currentDocumentHash)) {
           throw new import_common22.ResolveError(
             `Hash mismatch: update.sourceHash !== currentDocumentHash`,
             import_common22.INVALID_DID_UPDATE,
@@ -7736,7 +8745,7 @@ var Resolver = class _Resolver {
     const { proof: _, ...unsignedUpdate } = update;
     const unsignedUpdateHash = (0, import_common22.canonicalHashBytes)(unsignedUpdate);
     const historicalUpdateHash = updateHashHistory[update.targetVersionId - 2];
-    if (!(0, import_utils13.equalBytes)(historicalUpdateHash, unsignedUpdateHash)) {
+    if (!(0, import_utils15.equalBytes)(historicalUpdateHash, unsignedUpdateHash)) {
       throw new import_common22.ResolveError(
         `Invalid duplicate: unsigned update hash does not match historical hash`,
         import_common22.LATE_PUBLISHING_ERROR,
@@ -7789,7 +8798,7 @@ var Resolver = class _Resolver {
     DidDocument.validate(updatedDocument);
     const currentDocumentHash = (0, import_common22.canonicalHashBytes)(updatedDocument);
     const updateTargetHash = (0, import_common22.decode)(update.targetHash);
-    if (!(0, import_utils13.equalBytes)(updateTargetHash, currentDocumentHash)) {
+    if (!(0, import_utils15.equalBytes)(updateTargetHash, currentDocumentHash)) {
       throw new import_common22.ResolveError(
         `Invalid update: update.targetHash !== currentDocumentHash`,
         import_common22.INVALID_DID_UPDATE,
@@ -7800,8 +8809,8 @@ var Resolver = 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()`.
    */
@@ -8031,6 +9040,7 @@ var DidDocumentBuilder = class {
   BeaconUtils,
   CASBeacon,
   CASBeaconError,
+  CHANGE_OUTPUT_VBYTES,
   COHORT_ADVERT,
   COHORT_OPT_IN,
   COHORT_OPT_IN_ACCEPT,
@@ -8039,17 +9049,23 @@ var DidDocumentBuilder = class {
   DEFAULT_ADVERT_REPEAT_INTERVAL_MS,
   DEFAULT_BROADCAST_LOOKBACK_MS,
   DEFAULT_CLOCK_SKEW_SEC,
+  DEFAULT_FEE_ESTIMATOR,
+  DEFAULT_FUNDING_MODEL,
   DEFAULT_MAX_UPDATE_SIZE_BYTES,
   DEFAULT_NONCE_LEN_BYTES,
   DEFAULT_NOSTR_RELAYS,
+  DEFAULT_RECOVERY_SEQUENCE,
   DID_REGEX,
   DISTRIBUTE_AGGREGATED_DATA,
+  DUST_LIMIT_SATS,
   DidBtcr2,
   DidCommTransport,
   DidDocument,
   DidDocumentBuilder,
   DidVerificationMethod,
   Document,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE,
   GenesisDocument,
   HTTP_ENVELOPE_VERSION,
   HTTP_ROUTE,
@@ -8063,7 +9079,9 @@ var DidDocumentBuilder = class {
   InMemoryTransport,
   InboxBuffer,
   KNOWN_BEACON_TYPES,
+  KNOWN_FUNDING_MODELS,
   KeyPairAggregationSigner,
+  MAX_RECOVERY_SEQUENCE,
   NONCE_CONTRIBUTION,
   NonceCache,
   NostrTransport,
@@ -8080,6 +9098,7 @@ var DidDocumentBuilder = class {
   SMTBeacon,
   SMTBeaconError,
   SSE_EVENT,
+  SUBMIT_NONINCLUDED,
   SUBMIT_UPDATE,
   ServiceCohortPhase,
   SigningSessionError,
@@ -8088,13 +9107,20 @@ var DidDocumentBuilder = class {
   SingletonBeacon,
   SingletonBeaconError,
   StaticFeeEstimator,
+  TAPROOT_LEAF_VERSION,
   TransportAdapterError,
   TransportError,
   TransportFactory,
   TypedEventEmitter,
   Updater,
   VALIDATION_ACK,
+  beaconTxVsize,
   buildAggregationBeaconTx,
+  buildFallbackLeaf,
+  buildFallbackSpend,
+  buildRecoveryLeaves,
+  buildRecoveryScript,
+  buildRecoverySpend,
   buildRequestAuth,
   createAggregatedNonceMessage,
   createAuthorizationRequestMessage,
@@ -8103,13 +9129,17 @@ var DidDocumentBuilder = class {
   createCohortOptInMessage,
   createCohortReadyMessage,
   createDistributeAggregatedDataMessage,
+  createFallbackAuthorizationRequestMessage,
+  createFallbackSignatureMessage,
   createNonceContributionMessage,
   createSignatureAuthorizationMessage,
+  createSubmitNonIncludedMessage,
   createSubmitUpdateMessage,
   createValidationAckMessage,
   defaultReconnectBackoff,
   deriveSingletonAddress,
   detectSingletonScriptKind,
+  fallbackSighash,
   formatSseComment,
   formatSseEvent,
   getBeaconStrategy,
@@ -8121,10 +9151,13 @@ var DidDocumentBuilder = class {
   isCohortOptInMessage,
   isCohortReadyMessage,
   isDistributeAggregatedDataMessage,
+  isFallbackAuthorizationRequestMessage,
+  isFallbackSignatureMessage,
   isKeygenMessageType,
   isNonceContributionMessage,
   isSignMessageType,
   isSignatureAuthorizationMessage,
+  isSubmitNonIncludedMessage,
   isSubmitUpdateMessage,
   isUpdateMessageType,
   isValidationAckMessage,
@@ -8133,8 +9166,11 @@ var DidDocumentBuilder = class {
   parseRequestAuth,
   parseSseStream,
   registerBeaconStrategy,
+  resolveChangeAddress,
+  resolveFallbackThreshold,
   reviveFromWire,
   signEnvelope,
+  tapLeafHash,
   validateCohortConditions,
   verifyEnvelope,
   verifyRequestAuth