@did-btcr2/method 0.36.1 → 0.38.0

package/dist/browser.js

@@ -93172,6 +93172,7 @@ a=end-of-candidates
     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,
@@ -93180,17 +93181,23 @@ a=end-of-candidates
     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,
@@ -93204,7 +93211,9 @@ a=end-of-candidates
     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,
@@ -93221,6 +93230,7 @@ a=end-of-candidates
     SMTBeacon: () => SMTBeacon,
     SMTBeaconError: () => SMTBeaconError,
     SSE_EVENT: () => SSE_EVENT,
+    SUBMIT_NONINCLUDED: () => SUBMIT_NONINCLUDED,
     SUBMIT_UPDATE: () => SUBMIT_UPDATE,
     ServiceCohortPhase: () => ServiceCohortPhase,
     SigningSessionError: () => SigningSessionError,
@@ -93229,13 +93239,20 @@ a=end-of-candidates
     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,
@@ -93244,13 +93261,17 @@ a=end-of-candidates
     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,
@@ -93262,10 +93283,13 @@ a=end-of-candidates
     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,
@@ -93274,8 +93298,11 @@ a=end-of-candidates
     parseRequestAuth: () => parseRequestAuth,
     parseSseStream: () => parseSseStream,
     registerBeaconStrategy: () => registerBeaconStrategy,
+    resolveChangeAddress: () => resolveChangeAddress,
+    resolveFallbackThreshold: () => resolveFallbackThreshold,
     reviveFromWire: () => reviveFromWire,
     signEnvelope: () => signEnvelope,
+    tapLeafHash: () => tapLeafHash2,
     validateCohortConditions: () => validateCohortConditions,
     verifyEnvelope: () => verifyEnvelope,
     verifyRequestAuth: () => verifyRequestAuth
@@ -100261,7 +100288,7 @@ a=end-of-candidates
      * @readonly
      * Get signing ability of the Multikey: true if a local Secp256k1SecretKey
      * is present (note: the SchnorrKeyPair.secretKey getter throws when absent;
-     * that throw is the historical error contract — see multikey tests) or if
+     * that throw is the historical error contract - see multikey tests) or if
      * an external signer is available.
      */
     get signer() {
@@ -100366,6 +100393,7 @@ a=end-of-candidates
   init_shim();
 
   // src/core/aggregation/service.ts
+  init_secp256k1();
   init_utils();
 
   // src/core/aggregation/beacon-strategy.ts
@@ -100666,9 +100694,12 @@ a=end-of-candidates
     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
@@ -100684,15 +100715,20 @@ a=end-of-candidates
       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 = didToIndex(participantDid);
+      if (!included) {
+        if (!smtProof?.nonce || smtProof?.updateId) return { matches: false, smtProof };
+        const candidateHash2 = blockHash(blockHash(base64UrlToHash(smtProof.nonce)));
+        return { matches: verifySerializedProof(smtProof, index, candidateHash2), smtProof };
+      }
+      if (!smtProof?.updateId || !smtProof?.nonce || !submittedUpdate) return { matches: false, smtProof };
       const canonicalBytes = new TextEncoder().encode(canonicalize2(submittedUpdate));
       const expectedUpdateId = hashToBase64Url(blockHash(canonicalBytes));
       if (smtProof.updateId !== expectedUpdateId) {
         return { matches: false, smtProof };
       }
-      const index = didToIndex(participantDid);
       const candidateHash = blockHash(blockHash(base64UrlToHash(smtProof.nonce)), base64UrlToHash(smtProof.updateId));
       return {
         matches: verifySerializedProof(smtProof, index, candidateHash),
@@ -101691,6 +101727,15 @@ a=end-of-candidates
         checkWSH(r2, witnessScript);
     }
   }
+  function uniqPubkey(pubkeys) {
+    const map3 = {};
+    for (const pub of pubkeys) {
+      const key = hex.encode(pub);
+      if (map3[key])
+        throw new Error(`Multisig: non-uniq pubkey: ${pubkeys.map(hex.encode)}`);
+      map3[key] = true;
+    }
+  }
   var p2pkh = (publicKey2, network = NETWORK) => {
     if (!isValidPubkey(publicKey2, PubT.ecdsa))
       throw new Error("P2PKH: invalid publicKey");
@@ -101863,6 +101908,14 @@ a=end-of-candidates
       };
     }
   }
+  function p2tr_ms(m2, pubkeys, allowSamePubkeys = false) {
+    if (!allowSamePubkeys)
+      uniqPubkey(pubkeys);
+    return {
+      type: "tr_ms",
+      script: OutScript.encode({ type: "tr_ms", pubkeys, m: m2 })
+    };
+  }
   var base58check = createBase58check(sha256);
   function validateWitness(version3, data) {
     if (data.length < 2 || data.length > 40)
@@ -103338,6 +103391,104 @@ a=end-of-candidates
     }
   };
 
+  // src/core/aggregation/recovery-policy.ts
+  init_shim();
+  init_secp256k1();
+  init_utils();
+  var DEFAULT_FUNDING_MODEL = "operator-funded";
+  var DEFAULT_RECOVERY_SEQUENCE = 144;
+  var MAX_RECOVERY_SEQUENCE = 65535;
+  var TAPROOT_LEAF_VERSION = 192;
+  function compactSize(n2) {
+    if (n2 < 253) return new Uint8Array([n2]);
+    if (n2 <= 65535) return new Uint8Array([253, n2 & 255, n2 >> 8 & 255]);
+    return new Uint8Array([254, n2 & 255, n2 >> 8 & 255, n2 >> 16 & 255, n2 >> 24 & 255]);
+  }
+  function tapLeafHash2(script, leafVersion = TAPROOT_LEAF_VERSION) {
+    return schnorr2.utils.taggedHash(
+      "TapLeaf",
+      concatBytes(new Uint8Array([leafVersion]), compactSize(script.length), script)
+    );
+  }
+  function resolveFallbackThreshold(advertised, n2) {
+    return advertised ?? Math.max(1, n2 - 1);
+  }
+  function assertFallbackParams({ cohortKeys, fallbackThreshold }) {
+    const n2 = cohortKeys.length;
+    if (n2 === 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 > n2) {
+      throw new AggregationCohortError(
+        `Fallback threshold must be an integer in [1, ${n2}] (k-of-n), got ${fallbackThreshold}.`,
+        "INVALID_FALLBACK_THRESHOLD",
+        { fallbackThreshold, n: n2 }
+      );
+    }
+  }
+  function buildFallbackLeaf(params) {
+    assertFallbackParams(params);
+    const xOnlyKeys = sortKeys(params.cohortKeys).map((k) => k.slice(1));
+    return 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 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. */
@@ -103353,8 +103504,8 @@ a=end-of-candidates
     /** 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.
      */
@@ -103362,16 +103513,41 @@ a=end-of-candidates
     /** 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;
@@ -103381,12 +103557,16 @@ a=end-of-candidates
     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() {
@@ -103396,8 +103576,26 @@ a=end-of-candidates
       this.#cohortKeys = sortKeys(keys);
     }
     /**
-     * Computes the n-of-n MuSig2 Taproot beacon address from cohort keys.
-     * Sets `tapTweak` to the BIP-341 key-path-only tweak.
+     * The resolved k of the k-of-n fallback leaf: the advertised
+     * {@link fallbackThreshold}, or n-1 (floored at 1) when unadvertised, where n is
+     * the current cohort size. This is the value the beacon address commits to and
+     * the spend builders must reproduce. Returns 0 before any cohort keys are set.
+     */
+    get effectiveFallbackThreshold() {
+      if (this.#cohortKeys.length === 0) return 0;
+      return resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length);
+    }
+    /**
+     * Computes the Taproot beacon address from the cohort keys and recovery params.
+     *
+     * The output's key path is the n-of-n MuSig2 aggregate of the cohort keys; its
+     * script path is the recovery tree (a CSV recovery leaf so a missing signer
+     * cannot permanently lock the UTXO). Sets `internalKey`, `tapMerkleRoot`, and
+     * the `tapTweak` the MuSig2 session must apply for the key-path spend.
+     *
+     * The tweak is derived from the Merkle root the address was built with (read
+     * back from the payment), never recomputed by hand, so the MuSig2 key-path
+     * signature is guaranteed to validate against the funded address.
      */
     computeBeaconAddress() {
       if (this.#cohortKeys.length === 0) {
@@ -103407,10 +103605,25 @@ a=end-of-candidates
           { cohortId: this.id }
         );
       }
+      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 = keyAggregate(this.#cohortKeys);
       const aggPubkey = keyAggExport(keyAggContext);
-      const payment = p2tr(aggPubkey, void 0, getNetwork(this.network));
-      this.tapTweak = schnorr2.utils.taggedHash("TapTweak", aggPubkey);
+      const leaves = buildRecoveryLeaves(this.fundingModel, {
+        recoveryKey: this.recoveryKey,
+        recoverySequence: this.recoverySequence,
+        cohortKeys: this.#cohortKeys,
+        fallbackThreshold: resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length)
+      });
+      const payment = p2tr(aggPubkey, leaves, getNetwork(this.network), true);
+      this.internalKey = aggPubkey;
+      this.tapMerkleRoot = payment.tapMerkleRoot;
+      this.tapTweak = schnorr2.utils.taggedHash("TapTweak", concatBytes(aggPubkey, payment.tapMerkleRoot));
       if (!payment.address) {
         throw new AggregationCohortError(
           "Failed to compute Taproot address",
@@ -103466,20 +103679,54 @@ a=end-of-candidates
       }
       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 = {};
@@ -103491,31 +103738,41 @@ a=end-of-candidates
       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 tree2 = new BTCR2MerkleTree();
       const entries = [];
       const encoder4 = new TextEncoder();
-      for (const [did, signedUpdate] of this.pendingUpdates) {
-        const canonicalBytes = encoder4.encode(canonicalize2(signedUpdate));
+      for (const did of this.participants) {
         const nonce = randomBytes(32);
-        entries.push({ did, nonce, signedUpdate: canonicalBytes });
+        const signedUpdate = this.pendingUpdates.get(did);
+        if (signedUpdate) {
+          entries.push({ did, nonce, signedUpdate: encoder4.encode(canonicalize2(signedUpdate)) });
+        } else {
+          entries.push({ did, nonce });
+        }
       }
       tree2.addEntries(entries);
       tree2.finalize();
       this.signalBytes = tree2.rootHash;
       this.smtProofs = /* @__PURE__ */ new Map();
-      for (const [did] of this.pendingUpdates) {
+      for (const did of this.participants) {
         this.smtProofs.set(did, tree2.proof(did));
       }
       return this.smtProofs;
@@ -103541,7 +103798,7 @@ a=end-of-candidates
       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() {
@@ -103552,6 +103809,7 @@ a=end-of-candidates
   // src/core/aggregation/conditions.ts
   init_shim();
   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`);
@@ -103595,11 +103853,128 @@ a=end-of-candidates
     if (c2.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c2.pendingUpdateTrigger) || c2.pendingUpdateTrigger < 1)) {
       problems.push("pendingUpdateTrigger must be an integer >= 1");
     }
+    if (c2.fallbackThreshold !== void 0) {
+      if (!Number.isInteger(c2.fallbackThreshold) || c2.fallbackThreshold < 1) {
+        problems.push("fallbackThreshold must be an integer >= 1");
+      } else if (c2.maxParticipants !== void 0 && Number.isInteger(c2.maxParticipants) && c2.fallbackThreshold > c2.maxParticipants) {
+        problems.push("fallbackThreshold must be <= maxParticipants");
+      }
+    }
     checkCost(problems, "costOfEnrollment", c2.costOfEnrollment);
     checkCost(problems, "costPerAnnouncement", c2.costPerAnnouncement);
+    if (typeof c2.recoveryKey !== "string" || !/^[0-9a-fA-F]{64}$/.test(c2.recoveryKey)) {
+      problems.push("recoveryKey must be a 64-character hex string (x-only public key)");
+    }
+    if (!Number.isInteger(c2.recoverySequence) || c2.recoverySequence < 1 || c2.recoverySequence > MAX_RECOVERY_SEQUENCE) {
+      problems.push(`recoverySequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}]`);
+    }
+    if (c2.fundingModel !== void 0 && !KNOWN_FUNDING_MODELS.includes(c2.fundingModel)) {
+      problems.push(`fundingModel must be one of ${KNOWN_FUNDING_MODELS.join(", ")}`);
+    }
     return problems;
   }
 
+  // src/core/aggregation/fallback-spend.ts
+  init_shim();
+  init_secp256k1();
+  function bytesEqual(a2, b) {
+    return a2.length === b.length && a2.every((x, i4) => x === b[i4]);
+  }
+  function fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeafScript) {
+    return tx.preimageWitnessV1(
+      inputIndex,
+      [prevOutScript],
+      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 = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+    const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+      recoveryKey,
+      recoverySequence,
+      cohortKeys,
+      fallbackThreshold
+    });
+    const net = getNetwork(network);
+    const payment = 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 = sortKeys(cohortKeys).map((k) => k.slice(1));
+    const tx = pendingTx;
+    const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+    const leafHash = tapLeafHash2(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 hex2 = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+      if (accepted.has(hex2)) continue;
+      let ok = false;
+      try {
+        ok = schnorr2.verify(signature, sighash, pubKey);
+      } catch {
+        ok = false;
+      }
+      if (ok) accepted.set(hex2, 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 hex2 = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+        return [{ pubKey, leafHash }, accepted.get(hex2)];
+      })
+    });
+    tx.finalize();
+    return tx;
+  }
+
   // src/core/aggregation/messages/base.ts
   init_shim();
   var AGGREGATION_WIRE_VERSION = 1;
@@ -103639,12 +104014,15 @@ a=end-of-candidates
   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
   init_shim();
@@ -103668,6 +104046,10 @@ a=end-of-candidates
     const { from: from8, to, ...body } = fields;
     return new BaseMessage({ type: SUBMIT_UPDATE, from: from8, to, body });
   }
+  function createSubmitNonIncludedMessage(fields) {
+    const { from: from8, to, ...body } = fields;
+    return new BaseMessage({ type: SUBMIT_NONINCLUDED, from: from8, to, body });
+  }
   function createDistributeAggregatedDataMessage(fields) {
     const { from: from8, to, ...body } = fields;
     return new BaseMessage({ type: DISTRIBUTE_AGGREGATED_DATA, from: from8, to, body });
@@ -103692,6 +104074,14 @@ a=end-of-candidates
     const { from: from8, to, ...body } = fields;
     return new BaseMessage({ type: SIGNATURE_AUTHORIZATION, from: from8, to, body });
   }
+  function createFallbackAuthorizationRequestMessage(fields) {
+    const { from: from8, to, ...body } = fields;
+    return new BaseMessage({ type: FALLBACK_AUTHORIZATION_REQUEST, from: from8, to, body });
+  }
+  function createFallbackSignatureMessage(fields) {
+    const { from: from8, to, ...body } = fields;
+    return new BaseMessage({ type: FALLBACK_SIGNATURE, from: from8, to, body });
+  }
 
   // src/core/aggregation/phases.ts
   init_shim();
@@ -103706,6 +104096,7 @@ a=end-of-candidates
     ServiceCohortPhase2["SigningStarted"] = "SigningStarted";
     ServiceCohortPhase2["NoncesCollected"] = "NoncesCollected";
     ServiceCohortPhase2["AwaitingPartialSigs"] = "AwaitingPartialSigs";
+    ServiceCohortPhase2["FallbackRequested"] = "FallbackRequested";
     ServiceCohortPhase2["Complete"] = "Complete";
     ServiceCohortPhase2["Failed"] = "Failed";
     return ServiceCohortPhase2;
@@ -103715,11 +104106,13 @@ a=end-of-candidates
     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;
@@ -103747,11 +104140,11 @@ a=end-of-candidates
     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;
@@ -103934,7 +104327,7 @@ a=end-of-candidates
         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 Session(
         this.aggregatedNonce,
@@ -104004,6 +104397,9 @@ a=end-of-candidates
         case SUBMIT_UPDATE:
           this.#handleSubmitUpdate(message2);
           break;
+        case SUBMIT_NONINCLUDED:
+          this.#handleSubmitNonInclusion(message2);
+          break;
         case VALIDATION_ACK:
           this.#handleValidationAck(message2);
           break;
@@ -104013,6 +104409,9 @@ a=end-of-candidates
         case SIGNATURE_AUTHORIZATION:
           this.#handleSignatureAuthorization(message2);
           break;
+        case FALLBACK_SIGNATURE:
+          this.#handleFallbackSignature(message2);
+          break;
         default:
           break;
       }
@@ -104031,7 +104430,7 @@ a=end-of-candidates
     }
     /**
      * 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);
@@ -104046,7 +104445,11 @@ a=end-of-candidates
         serviceDid: this.did,
         minParticipants: config.minParticipants,
         network: config.network,
-        beaconType: config.beaconType
+        beaconType: config.beaconType,
+        recoveryKey: hexToBytes(config.recoveryKey),
+        recoverySequence: config.recoverySequence,
+        fundingModel: config.fundingModel,
+        fallbackThreshold: config.fallbackThreshold
       });
       this.#cohortStates.set(cohort.id, {
         phase: "Created" /* Created */,
@@ -104247,11 +104650,64 @@ a=end-of-candidates
         });
         return;
       }
+      if (state.cohort.nonIncluded.has(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Participant already declined this round; cannot also submit an update"
+        });
+        return;
+      }
+      if (state.cohort.pendingUpdates.has(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Participant already submitted an update this round; cannot resubmit"
+        });
+        return;
+      }
       state.cohort.addUpdate(message2.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(message2) {
+      const cohortId = message2.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(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Sender is not a member of this cohort"
+        });
+        return;
+      }
+      if (state.cohort.pendingUpdates.has(message2.from) || state.cohort.nonIncluded.has(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Participant already responded this round"
+        });
+        return;
+      }
+      state.cohort.addNonInclusion(message2.from);
+      if (state.phase === "CohortSet" /* CohortSet */) {
+        state.phase = "CollectingUpdates" /* CollectingUpdates */;
+      }
+      if (state.cohort.hasAllResponses()) {
         state.phase = "UpdatesCollected" /* UpdatesCollected */;
       }
     }
@@ -104361,7 +104817,7 @@ a=end-of-candidates
     }
     /**
      * 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) {
@@ -104468,11 +104924,144 @@ a=end-of-candidates
         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 messages2 = [];
+      for (const participantDid of state.cohort.participants) {
+        messages2.push(createFallbackAuthorizationRequestMessage({
+          from: this.did,
+          to: participantDid,
+          cohortId,
+          sessionId: session.id,
+          pendingTx: session.pendingTx.hex,
+          prevOutScriptHex: bytesToHex(prevOutScript),
+          prevOutValue: prevOutValue.toString(),
+          fallbackLeafScriptHex: bytesToHex(fallbackLeaf)
+        }));
+      }
+      return messages2;
+    }
+    /**
+     * 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(message2) {
+      const cohortId = message2.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 = message2.body?.sessionId;
+      if (sessionId !== state.signingSession.id) return;
+      const signerPk = message2.body?.signerPk;
+      const fallbackSignature = message2.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(message2.from);
+      if (!memberKey) {
+        state.rejections.push({ from: message2.from, code: "UPDATE_MALFORMED", reason: "Fallback signature from a non-member" });
+        return;
+      }
+      const memberXOnly = memberKey.slice(1);
+      if (signerPk.length !== 32 || !memberXOnly.every((b, i4) => b === signerPk[i4])) {
+        state.rejections.push({ from: message2.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 && schnorr2.verify(fallbackSignature, sighash, signerPk);
+      } catch {
+        valid = false;
+      }
+      if (!valid) {
+        state.rejections.push({ from: message2.from, code: "UPDATE_VERIFICATION_FAILED", reason: "Fallback signature failed verification" });
+        return;
+      }
+      state.fallbackSignatures.set(message2.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;
     }
@@ -104504,6 +105093,7 @@ a=end-of-candidates
 
   // src/core/aggregation/participant.ts
   init_shim();
+  init_secp256k1();
   init_utils();
 
   // src/core/aggregation/messages/bodies.ts
@@ -104517,6 +105107,14 @@ a=end-of-candidates
     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) => {
@@ -104524,7 +105122,7 @@ a=end-of-candidates
     return Array.isArray(v) && v.every((x) => x instanceof Uint8Array);
   };
   function isCohortAdvertMessage(m2) {
-    return m2.type === COHORT_ADVERT && hasStr(m2.body, "cohortId") && hasIntMin(m2.body, "minParticipants", 1) && optIntMin(m2.body, "maxParticipants", 1) && hasStr(m2.body, "beaconType") && hasStr(m2.body, "network") && hasBytes(m2.body, "communicationPk");
+    return m2.type === COHORT_ADVERT && hasStr(m2.body, "cohortId") && hasIntMin(m2.body, "minParticipants", 1) && optIntMin(m2.body, "maxParticipants", 1) && hasStr(m2.body, "beaconType") && hasStr(m2.body, "network") && hasStr(m2.body, "recoveryKey") && intInRange(m2.body, "recoverySequence", 1, MAX_RECOVERY_SEQUENCE) && optStrOneOf(m2.body, "fundingModel", KNOWN_FUNDING_MODELS) && optIntMin(m2.body, "fallbackThreshold", 1) && hasBytes(m2.body, "communicationPk");
   }
   function isCohortOptInMessage(m2) {
     return m2.type === COHORT_OPT_IN && hasStr(m2.body, "cohortId") && hasBytes(m2.body, "participantPk") && hasBytes(m2.body, "communicationPk");
@@ -104538,6 +105136,9 @@ a=end-of-candidates
   function isSubmitUpdateMessage(m2) {
     return m2.type === SUBMIT_UPDATE && hasStr(m2.body, "cohortId") && !!m2.body && typeof m2.body.signedUpdate === "object";
   }
+  function isSubmitNonIncludedMessage(m2) {
+    return m2.type === SUBMIT_NONINCLUDED && hasStr(m2.body, "cohortId");
+  }
   function isDistributeAggregatedDataMessage(m2) {
     return m2.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m2.body, "cohortId") && hasStr(m2.body, "beaconType") && hasStr(m2.body, "signalBytesHex");
   }
@@ -104556,8 +105157,38 @@ a=end-of-candidates
   function isSignatureAuthorizationMessage(m2) {
     return m2.type === SIGNATURE_AUTHORIZATION && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "partialSignature");
   }
+  function isFallbackAuthorizationRequestMessage(m2) {
+    return m2.type === FALLBACK_AUTHORIZATION_REQUEST && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasStr(m2.body, "pendingTx") && hasStr(m2.body, "prevOutScriptHex") && hasStr(m2.body, "prevOutValue") && hasStr(m2.body, "fallbackLeafScriptHex");
+  }
+  function isFallbackSignatureMessage(m2) {
+    return m2.type === FALLBACK_SIGNATURE && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "signerPk") && hasBytes(m2.body, "fallbackSignature");
+  }
 
   // src/core/aggregation/participant.ts
+  function txEmbedsSignal(tx, signalHex) {
+    let expected;
+    try {
+      expected = hexToBytes(signalHex);
+    } catch {
+      return false;
+    }
+    if (expected.length === 0) return false;
+    for (let i4 = 0; i4 < tx.outputsLength; i4++) {
+      const script = tx.getOutput(i4)?.script;
+      if (!script) continue;
+      let decoded;
+      try {
+        decoded = 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. */
@@ -104574,7 +105205,7 @@ a=end-of-candidates
     }
     /**
      * 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(message2) {
       if (message2.version === void 0 || message2.version !== AGGREGATION_WIRE_VERSION) {
@@ -104600,6 +105231,9 @@ a=end-of-candidates
         case AGGREGATED_NONCE:
           this.#handleAggregatedNonce(message2);
           break;
+        case FALLBACK_AUTHORIZATION_REQUEST:
+          this.#handleFallbackAuthorizationRequest(message2);
+          break;
         default:
           break;
       }
@@ -104645,12 +105279,17 @@ a=end-of-candidates
           { 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 ? hexToBytes(advert.recoveryKey) : void 0,
+        recoverySequence: advert.recoverySequence,
+        fundingModel: advert.fundingModel,
+        fallbackThreshold: advert.fallbackThreshold
       });
       state.cohort = cohort;
       state.phase = "OptedIn" /* OptedIn */;
@@ -104665,7 +105304,7 @@ a=end-of-candidates
     }
     #handleOptInAccept(message2) {
     }
-    /** Cohorts that have been finalized — beacon address available. */
+    /** Cohorts that have been finalized: beacon address available. */
     get joinedCohorts() {
       const map3 = /* @__PURE__ */ new Map();
       for (const [id, state] of this.#cohortStates) {
@@ -104708,6 +105347,7 @@ a=end-of-candidates
         );
       }
       state.submittedUpdate = signedUpdate;
+      state.included = true;
       state.phase = "UpdateSubmitted" /* UpdateSubmitted */;
       const message2 = createSubmitUpdateMessage({
         from: this.did,
@@ -104717,6 +105357,30 @@ a=end-of-candidates
       });
       return [message2];
     }
+    /**
+     * 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 message2 = createSubmitNonIncludedMessage({
+        from: this.did,
+        to: state.serviceDid,
+        cohortId
+      });
+      return [message2];
+    }
     /** Aggregated data awaiting user validation. */
     get pendingValidations() {
       const map3 = /* @__PURE__ */ new Map();
@@ -104730,9 +105394,9 @@ a=end-of-candidates
     /**
      * 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) {
@@ -104742,18 +105406,20 @@ a=end-of-candidates
       const cohortId = message2.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 = message2.body?.beaconType;
       if (!beaconType) return;
       const strategy = getBeaconStrategy(beaconType);
       if (!strategy) return;
       const signalBytesHex = message2.body?.signalBytesHex ?? "";
-      const expectedHash = canonicalHash(state.submittedUpdate);
+      const expectedHash = declined ? "" : 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: message2.body
       });
       state.validation = {
@@ -104763,7 +105429,8 @@ a=end-of-candidates
         expectedHash,
         matches: result.matches,
         casAnnouncement: result.casAnnouncement,
-        smtProof: result.smtProof
+        smtProof: result.smtProof,
+        included: !declined
       };
       state.phase = "AwaitingValidation" /* AwaitingValidation */;
     }
@@ -104837,6 +105504,31 @@ a=end-of-candidates
       };
       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.
      */
@@ -104856,7 +105548,8 @@ a=end-of-candidates
           { cohortId }
         );
       }
-      const tx = Transaction.fromRaw(hexToBytes(state.signingRequest.pendingTxHex));
+      const tx = Transaction.fromRaw(hexToBytes(state.signingRequest.pendingTxHex), { allowUnknownOutputs: true });
+      this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
       const prevOutScripts = [hexToBytes(state.signingRequest.prevOutScriptHex)];
       const prevOutValues = [BigInt(state.signingRequest.prevOutValue)];
       const session = new BeaconSigningSession({
@@ -104892,7 +105585,7 @@ a=end-of-candidates
     }
     /**
      * 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) {
@@ -104924,6 +105617,83 @@ a=end-of-candidates
         partialSignature: partialSig
       })];
     }
+    /** Fallback signing requests awaiting user approval (UI: review the fallback spend). */
+    get pendingFallbackRequests() {
+      const map3 = /* @__PURE__ */ new Map();
+      for (const [id, state] of this.#cohortStates) {
+        if (state.phase === "AwaitingFallbackSig" /* AwaitingFallbackSig */ && state.fallbackRequest) {
+          map3.set(id, state.fallbackRequest);
+        }
+      }
+      return map3;
+    }
+    #handleFallbackAuthorizationRequest(message2) {
+      const cohortId = message2.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 = message2.body?.sessionId;
+      const pendingTxHex = message2.body?.pendingTx;
+      const prevOutScriptHex = message2.body?.prevOutScriptHex;
+      const prevOutValue = message2.body?.prevOutValue;
+      const fallbackLeafScriptHex = message2.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 = Transaction.fromRaw(hexToBytes(req.pendingTxHex), { allowUnknownOutputs: true });
+      const prevOutScript = 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) => schnorr2.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;
     }
@@ -104960,6 +105730,85 @@ a=end-of-candidates
     }
   };
 
+  // src/core/aggregation/recovery-spend.ts
+  init_shim();
+  init_secp256k1();
+  var DUST_LIMIT_SATS = 546n;
+  function bytesEqual2(a2, b) {
+    return a2.length === b.length && a2.every((x, i4) => x === b[i4]);
+  }
+  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 = schnorr2.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 = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+    const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+      recoveryKey,
+      recoverySequence,
+      cohortKeys,
+      fallbackThreshold: resolveFallbackThreshold(fallbackThreshold, cohortKeys.length)
+    });
+    const net = getNetwork(network);
+    const payment = 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 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
   init_shim();
   var CONSOLE_LOGGER = {
@@ -104992,6 +105841,7 @@ a=end-of-candidates
   ]);
   var UPDATE_VALUES = /* @__PURE__ */ new Set([
     SUBMIT_UPDATE,
+    SUBMIT_NONINCLUDED,
     DISTRIBUTE_AGGREGATED_DATA,
     VALIDATION_ACK
   ]);
@@ -104999,7 +105849,9 @@ a=end-of-candidates
     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);
@@ -111160,7 +112012,7 @@ ${value2}`;
      * 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(message2, sender, intervalMs, recipient) {
@@ -111608,6 +112460,30 @@ ${value2}`;
 
   // src/core/aggregation/runner/service-runner.ts
   init_shim();
+
+  // src/core/beacon/fee-estimator.ts
+  init_shim();
+  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 {
     /** Direct access to the underlying state machine for advanced use. */
@@ -111618,9 +112494,17 @@ ${value2}`;
     #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;
@@ -111635,9 +112519,11 @@ ${value2}`;
         finalize: acceptedCount >= minRequired
       }));
       this.#onProvideTxData = options2.onProvideTxData;
+      this.#feeEstimator = options2.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
       this.#cohortTtlMs = options2.cohortTtlMs;
       this.#phaseTimeoutMs = options2.phaseTimeoutMs;
       this.#advertRepeatIntervalMs = options2.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+      this.#autoFallbackOnStall = options2.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
@@ -111799,11 +112685,42 @@ ${value2}`;
       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 messages2 = 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(messages2);
+    }
     /** 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);
@@ -111892,13 +112809,15 @@ ${value2}`;
     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.
      */
@@ -111907,9 +112826,11 @@ ${value2}`;
       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() {
@@ -112029,7 +112950,8 @@ ${value2}`;
           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) ?? "";
@@ -112070,6 +112992,32 @@ ${value2}`;
      * @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;
@@ -112143,7 +113091,8 @@ ${value2}`;
       COHORT_READY,
       DISTRIBUTE_AGGREGATED_DATA,
       AUTHORIZATION_REQUEST,
-      AGGREGATED_NONCE
+      AGGREGATED_NONCE,
+      FALLBACK_AUTHORIZATION_REQUEST
     ];
     /** Internal: detach from the transport. Safe to call repeatedly. */
     #unregisterHandlers() {
@@ -112178,7 +113127,7 @@ ${value2}`;
      *
      * 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).
@@ -112213,6 +113162,7 @@ ${value2}`;
       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.
@@ -112268,8 +113218,13 @@ ${value2}`;
           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);
       }
@@ -112345,23 +113300,62 @@ ${value2}`;
         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.
@@ -112378,6 +113372,7 @@ ${value2}`;
 
   // src/core/aggregation/runner/aggregation-runner.ts
   init_shim();
+  init_utils();
   var AggregationRunner = class {
     /**
      * Run a cohort of ONE participant entirely in-process and return the
@@ -112385,8 +113380,8 @@ ${value2}`;
      *
      * 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
@@ -112404,12 +113399,15 @@ ${value2}`;
       transport.registerPeer(options2.participant.did, options2.participant.keys.publicKey.compressed);
       transport.registerPeer(options2.service.did, options2.service.keys.publicKey.compressed);
       transport.start();
+      const recoveryKey = options2.config.recoveryKey ?? bytesToHex(options2.service.keys.publicKey.compressed.slice(1));
+      const recoverySequence = options2.config.recoverySequence ?? DEFAULT_RECOVERY_SEQUENCE;
       const service = new AggregationServiceRunner({
         transport,
         did: options2.service.did,
         keys: options2.service.keys,
-        config: { minParticipants: 1, network: options2.config.network, beaconType: options2.config.beaconType },
+        config: { minParticipants: 1, network: options2.config.network, beaconType: options2.config.beaconType, recoveryKey, recoverySequence, fundingModel: DEFAULT_FUNDING_MODEL },
         onProvideTxData: options2.onProvideTxData,
+        feeEstimator: options2.feeEstimator,
         cohortTtlMs: options2.cohortTtlMs,
         phaseTimeoutMs: options2.phaseTimeoutMs,
         // In-process bus with the participant already listening: a single advert
@@ -112465,29 +113463,7 @@ ${value2}`;
     }
   };
 
-  // src/core/beacon/fee-estimator.ts
-  init_shim();
-  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;
@@ -112496,6 +113472,20 @@ ${value2}`;
     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 base5 = SINGLETON_BEACON_TX_VSIZE[beaconKind] - CHANGE_OUTPUT_VBYTES[beaconKind];
+    return base5 + CHANGE_OUTPUT_VBYTES[changeKind];
+  }
   function detectSingletonScriptKind(bitcoinAddress, network) {
     const decoded = Address(network).decode(bitcoinAddress);
     if (decoded.type === "pkh") return "p2pkh";
@@ -112512,6 +113502,26 @@ ${value2}`;
     if (kind === "p2wpkh") return p2wpkh(pubkey, network).address;
     return p2tr(pubkey.slice(1, 33), void 0, network).address;
   }
+  function resolveChangeAddress(beaconAddress, network, changeAddress) {
+    if (!changeAddress || changeAddress === beaconAddress) return beaconAddress;
+    try {
+      Address(network).decode(changeAddress);
+    } catch {
+      throw new BeaconError(
+        `Invalid change address "${changeAddress}" for network "${network}".`,
+        "INVALID_CHANGE_ADDRESS",
+        { changeAddress, network }
+      );
+    }
+    return changeAddress;
+  }
+  function changeOutputKind(changeAddress, network) {
+    try {
+      return detectSingletonScriptKind(changeAddress, network);
+    } catch {
+      return "p2tr";
+    }
+  }
   function opReturnScript(signalBytes) {
     return Script.encode(["RETURN", signalBytes]);
   }
@@ -112538,9 +113548,10 @@ ${value2}`;
   async function buildAggregationBeaconTx(opts) {
     const feeEstimator = opts.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
     const { utxo, prevTxBytes } = await fetchSpendableUtxo(opts.beaconAddress, opts.bitcoin);
-    const tapOut = p2tr(opts.internalPubkey, 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 = OutScript.encode(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}).`,
@@ -112556,13 +113567,17 @@ ${value2}`;
       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"
@@ -112618,7 +113633,7 @@ ${value2}`;
      *
      * 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.
      *
@@ -112640,7 +113655,8 @@ ${value2}`;
         prevTxBytes,
         signer,
         bitcoin,
-        feeEstimator
+        feeEstimator,
+        changeAddress: options2?.changeAddress
       });
       const signedHex = await this.signSinglePartyTx(plan, signer);
       return this.broadcastRawTx(bitcoin, signedHex);
@@ -112650,15 +113666,17 @@ ${value2}`;
      *
      * 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(
@@ -112667,7 +113685,8 @@ ${value2}`;
           { 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(
@@ -112704,13 +113723,17 @@ ${value2}`;
           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
@@ -128537,7 +129560,7 @@ ${value2}`;
     #verificationMethod;
     #beaconService;
     /**
-     * @internal — Use {@link DidBtcr2.update} to create instances.
+     * @internal Use {@link DidBtcr2.update} to create instances.
      */
     constructor(params) {
       this.#sourceDocument = params.sourceDocument;
@@ -128574,7 +129597,7 @@ ${value2}`;
       const targetDocument = JSONPatch.apply(sourceDocument, patches);
       if (targetDocument.id !== sourceDocument.id) {
         throw new 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}").`,
           INVALID_DID_UPDATE,
           { sourceId: sourceDocument.id, targetId: targetDocument.id }
         );
@@ -128658,8 +129681,8 @@ ${value2}`;
     }
     /**
      * 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) {
@@ -128672,7 +129695,7 @@ ${value2}`;
             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",
@@ -128855,8 +129878,8 @@ ${value2}`;
      *
      * 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
@@ -128974,7 +129997,7 @@ ${value2}`;
     #unsortedUpdates = [];
     #resolvedResponse = null;
     /**
-     * @internal — Use {@link DidBtcr2.resolve} to create instances.
+     * @internal Use {@link DidBtcr2.resolve} to create instances.
      */
     constructor(didComponents, sidecarData, currentDocument, options2) {
       this.#didComponents = didComponents;
@@ -129210,8 +130233,8 @@ ${value2}`;
     }
     /**
      * 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()`.
      */