@did-btcr2/method 0.36.0 → 0.37.0

package/dist/types/core/aggregation/participant.d.ts

@@ -15,7 +15,7 @@ export interface CohortAdvert extends CohortConditions {
     network: string;
     serviceCommunicationPk: Uint8Array;
 }
-/** Joined cohort info — available after the cohort is finalized. */
+/** Joined cohort info, available after the cohort is finalized. */
 export interface JoinedCohortInfo {
     cohortId: string;
     serviceDid: string;
@@ -29,8 +29,11 @@ export interface PendingValidation {
     signalBytesHex: string;
     casAnnouncement?: Record<string, string>;
     smtProof?: SerializedSMTProof;
+    /** Canonical hash of this participant's update; empty for a decliner. */
     expectedHash: string;
     matches: boolean;
+    /** True if this participant submitted an update; false if it declined (non-inclusion). */
+    included: boolean;
 }
 /** Pending signing request (UI: review tx for approval). */
 export interface PendingSigningRequest {
@@ -41,6 +44,20 @@ export interface PendingSigningRequest {
     prevOutScriptHex: string;
     prevOutValue: string;
 }
+/**
+ * Pending fallback signing request (UI: review the fallback spend for approval).
+ * The service fell back to the k-of-n script path; the member signs the SAME
+ * beacon transaction over the fallback script-path sighash (ADR 042).
+ */
+export interface PendingFallbackRequest {
+    cohortId: string;
+    sessionId: string;
+    pendingTxHex: string;
+    prevOutScriptHex: string;
+    prevOutValue: string;
+    /** Fallback leaf script, hex (advisory; the member recomputes it from its own cohort). */
+    fallbackLeafScriptHex: string;
+}
 export interface AggregationParticipantParams {
     did: string;
     /**
@@ -68,7 +85,7 @@ export declare class AggregationParticipant {
     get publicKey(): Uint8Array;
     /**
      * Process an incoming message. Updates internal state but never produces
-     * outgoing messages — those come exclusively from action methods.
+     * outgoing messages: those come exclusively from action methods.
      */
     receive(message: BaseMessage): void;
     /** Cohorts the participant has discovered but not yet joined. */
@@ -78,15 +95,31 @@ export declare class AggregationParticipant {
      * Returns the opt-in message to send.
      */
     joinCohort(cohortId: string): BaseMessage[];
-    /** Cohorts that have been finalized — beacon address available. */
+    /** Cohorts that have been finalized: beacon address available. */
     get joinedCohorts(): ReadonlyMap<string, JoinedCohortInfo>;
     /**
      * User action: submit a signed BTCR2 update for inclusion in the cohort's
      * aggregated signal.
      */
     submitUpdate(cohortId: string, signedUpdate: SignedBTCR2Update): BaseMessage[];
+    /**
+     * 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: string): BaseMessage[];
     /** Aggregated data awaiting user validation. */
     get pendingValidations(): ReadonlyMap<string, PendingValidation>;
+    /**
+     * 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
+     * undefined before aggregated data has been received.
+     */
+    getValidation(cohortId: string): PendingValidation | undefined;
     /**
      * User action: approve aggregated data and send validation ack.
      */
@@ -103,10 +136,20 @@ export declare class AggregationParticipant {
     approveNonce(cohortId: string): BaseMessage[];
     /**
      * 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: string): BaseMessage[];
+    /** Fallback signing requests awaiting user approval (UI: review the fallback spend). */
+    get pendingFallbackRequests(): ReadonlyMap<string, PendingFallbackRequest>;
+    /**
+     * 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: string): BaseMessage[];
     getCohortPhase(cohortId: string): ParticipantCohortPhaseType | undefined;
     /**
      * Zeroize any retained MuSig2 secret nonces across all cohorts. The raw

package/dist/types/core/aggregation/participant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"participant.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/participant.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"participant.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/participant.ts"],"names":[],"mappings":"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"}

package/dist/types/core/aggregation/phases.d.ts

@@ -8,7 +8,7 @@
  * The signing session has its own phase enum because MuSig2 signing is a
  * sub-protocol within the larger aggregation protocol.
  */
-export type ServiceCohortPhaseType = 'Created' | 'Advertised' | 'CohortSet' | 'CollectingUpdates' | 'UpdatesCollected' | 'DataDistributed' | 'Validated' | 'SigningStarted' | 'NoncesCollected' | 'AwaitingPartialSigs' | 'Complete' | 'Failed';
+export type ServiceCohortPhaseType = 'Created' | 'Advertised' | 'CohortSet' | 'CollectingUpdates' | 'UpdatesCollected' | 'DataDistributed' | 'Validated' | 'SigningStarted' | 'NoncesCollected' | 'AwaitingPartialSigs' | 'FallbackRequested' | 'Complete' | 'Failed';
 export declare enum ServiceCohortPhase {
     Created = "Created",
     Advertised = "Advertised",
@@ -20,20 +20,26 @@ export declare enum ServiceCohortPhase {
     SigningStarted = "SigningStarted",
     NoncesCollected = "NoncesCollected",
     AwaitingPartialSigs = "AwaitingPartialSigs",
+    /** Optimistic n-of-n key path abandoned; collecting k-of-n fallback signatures (ADR 042). */
+    FallbackRequested = "FallbackRequested",
     Complete = "Complete",
     Failed = "Failed"
 }
-export type ParticipantCohortPhaseType = 'Discovered' | 'OptedIn' | 'CohortReady' | 'UpdateSubmitted' | 'AwaitingValidation' | 'ValidationSent' | 'AwaitingSigning' | 'NonceSent' | 'AwaitingPartialSig' | 'Complete' | 'Failed';
+export type ParticipantCohortPhaseType = 'Discovered' | 'OptedIn' | 'CohortReady' | 'UpdateSubmitted' | 'NonIncluded' | 'AwaitingValidation' | 'ValidationSent' | 'AwaitingSigning' | 'NonceSent' | 'AwaitingPartialSig' | 'AwaitingFallbackSig' | 'Complete' | 'Failed';
 export declare enum ParticipantCohortPhase {
     Discovered = "Discovered",
     OptedIn = "OptedIn",
     CohortReady = "CohortReady",
     UpdateSubmitted = "UpdateSubmitted",
+    /** Member declined to submit an update this round (cooperative non-inclusion); still signs. */
+    NonIncluded = "NonIncluded",
     AwaitingValidation = "AwaitingValidation",
     ValidationSent = "ValidationSent",
     AwaitingSigning = "AwaitingSigning",
     NonceSent = "NonceSent",
     AwaitingPartialSig = "AwaitingPartialSig",
+    /** Service fell back to the k-of-n script path; member can sign the fallback (ADR 042). */
+    AwaitingFallbackSig = "AwaitingFallbackSig",
     Complete = "Complete",
     Failed = "Failed"
 }

package/dist/types/core/aggregation/phases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phases.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,YAAY,GACZ,WAAW,GACX,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,qBAAqB,GACrB,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,iBAAiB,sBAAsB;IACvC,gBAAgB,qBAAqB;IACrC,eAAe,oBAAoB;IACnC,SAAS,cAAc;IACvB,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,mBAAmB,wBAAwB;IAC3C,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,MAAM,MAAM,0BAA0B,GAClC,YAAY,GACZ,SAAS,GACT,aAAa,GACb,iBAAiB,GACjB,oBAAoB,GACpB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,oBAAoB,GACpB,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,sBAAsB;IAChC,UAAU,eAAe;IACzB,OAAO,YAAY;IACnB,WAAW,gBAAgB;IAC3B,eAAe,oBAAoB;IACnC,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;IACzC,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,MAAM,MAAM,uBAAuB,GAC/B,4BAA4B,GAC5B,4BAA4B,GAC5B,2BAA2B,GAC3B,2BAA2B,GAC3B,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,mBAAmB;IAC7B,0BAA0B,+BAA+B;IACzD,0BAA0B,+BAA+B;IACzD,yBAAyB,8BAA8B;IACvD,yBAAyB,8BAA8B;IACvD,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB"}
+{"version":3,"file":"phases.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,YAAY,GACZ,WAAW,GACX,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,qBAAqB,GACrB,mBAAmB,GACnB,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,iBAAiB,sBAAsB;IACvC,gBAAgB,qBAAqB;IACrC,eAAe,oBAAoB;IACnC,SAAS,cAAc;IACvB,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,mBAAmB,wBAAwB;IAC3C,6FAA6F;IAC7F,iBAAiB,sBAAsB;IACvC,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,MAAM,MAAM,0BAA0B,GAClC,YAAY,GACZ,SAAS,GACT,aAAa,GACb,iBAAiB,GACjB,aAAa,GACb,oBAAoB,GACpB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,oBAAoB,GACpB,qBAAqB,GACrB,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,sBAAsB;IAChC,UAAU,eAAe;IACzB,OAAO,YAAY;IACnB,WAAW,gBAAgB;IAC3B,eAAe,oBAAoB;IACnC,+FAA+F;IAC/F,WAAW,gBAAgB;IAC3B,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;IACzC,2FAA2F;IAC3F,mBAAmB,wBAAwB;IAC3C,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,MAAM,MAAM,uBAAuB,GAC/B,4BAA4B,GAC5B,4BAA4B,GAC5B,2BAA2B,GAC3B,2BAA2B,GAC3B,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,mBAAmB;IAC7B,0BAA0B,+BAA+B;IACzD,0BAA0B,+BAA+B;IACzD,yBAAyB,8BAA8B;IACvD,yBAAyB,8BAA8B;IACvD,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB"}

package/dist/types/core/aggregation/recovery-policy.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Recovery policy for aggregate beacon outputs.
+ *
+ * An aggregate beacon UTXO is a Taproot output whose key path is the cohort's
+ * n-of-n MuSig2 aggregate key. A key-path-only output can be spent only with a
+ * signature from every cohort member, so a single missing signer would lock the
+ * funds forever. To prevent that, the output commits to a script tree with two
+ * leaves:
+ * - a k-of-n fallback leaf (`p2tr_ms`, BIP-342 CHECKSIGADD): any k cohort members
+ *   can still push the announcement through if some signers go missing, so the
+ *   beacon stays live without waiting out the timelock.
+ * - a CSV recovery leaf: after a relative-timelock delay the funder can reclaim
+ *   the UTXO unilaterally with its own recovery key, so funds are never
+ *   permanently stranded even if fewer than k members remain.
+ *
+ * This module is the seam between the funding model and the concrete script
+ * leaves. Only `operator-funded` is implemented today (the k-of-n fallback leaf
+ * plus one CSV leaf keyed to the operator's recovery key). A future
+ * `participant-funded` model can be added as another case returning
+ * per-participant refund leaves, without touching the cohort, service, or
+ * signing code. See ADR 042.
+ */
+/**
+ * Who funds the beacon UTXO and holds the recovery path.
+ * - `operator-funded`: the service operator funds the UTXO and holds a single
+ *   CSV recovery key. Implemented.
+ * - `participant-funded`: reserved for per-participant funding with
+ *   per-participant refund leaves. Not implemented.
+ */
+export type FundingModel = 'operator-funded' | 'participant-funded';
+/** Default funding model when an advert/config leaves it unspecified. */
+export declare const DEFAULT_FUNDING_MODEL: FundingModel;
+/**
+ * Default relative-timelock (in blocks) before operator recovery is spendable.
+ * About one day at 10-minute blocks. Operators set their own per-cohort value;
+ * this is only a convenience default for callers.
+ */
+export declare const DEFAULT_RECOVERY_SEQUENCE = 144;
+/**
+ * Maximum allowed `recoverySequence`, 0xffff (65535 blocks, about 455 days).
+ *
+ * The value is a BIP-68 block-based relative timelock and is placed directly in
+ * the spending input's nSequence. BIP-68 only uses the low 16 bits as the value
+ * when the type flag (bit 22) is clear, so constraining to [1, 0xffff] keeps the
+ * timelock block-based and, critically, leaves the disable flag (bit 31) clear.
+ * A value with bit 31 set would disable CHECKSEQUENCEVERIFY entirely, letting the
+ * recovery key spend with no delay; an upper bound of 0xffff makes that
+ * unrepresentable.
+ */
+export declare const MAX_RECOVERY_SEQUENCE = 65535;
+/** Inputs needed to build the CSV recovery leaf. */
+export interface RecoveryPolicyParams {
+    /** Operator recovery key, x-only (32 bytes). Spends the recovery leaf via CHECKSIG. */
+    recoveryKey: Uint8Array;
+    /**
+     * Relative-timelock value (BIP-68 nSequence) the recovery spend must wait,
+     * encoded into the leaf as `<recoverySequence> CHECKSEQUENCEVERIFY`.
+     */
+    recoverySequence: number;
+}
+/** Inputs needed to build the k-of-n fallback leaf. */
+export interface FallbackPolicyParams {
+    /**
+     * The cohort's participant public keys (compressed secp256k1, 33 bytes each).
+     * Sorted internally per BIP-327 and reduced to x-only so the leaf is
+     * deterministic regardless of the order keys are supplied in.
+     */
+    cohortKeys: Uint8Array[];
+    /**
+     * Number of signers (k) the fallback leaf requires, 1..n. This is the
+     * resolved threshold; callers that carry an advertised-or-default value should
+     * resolve it with {@link resolveFallbackThreshold} first.
+     */
+    fallbackThreshold: number;
+}
+/** All inputs the beacon output's script tree commits to (fallback leaf + recovery leaf). */
+export interface BeaconLeafParams extends RecoveryPolicyParams, FallbackPolicyParams {
+}
+/** A single Taproot script-tree leaf, spent at the default tapscript leaf version (0xc0). */
+export interface TaprootScriptLeaf {
+    script: Uint8Array;
+}
+/** BIP-341 default tapscript leaf version. */
+export declare const TAPROOT_LEAF_VERSION = 192;
+/**
+ * BIP-341 tapleaf hash: `taggedHash("TapLeaf", leafVersion || compactSize(len) || script)`.
+ * Used to key a script-path signature to its leaf when assembling the witness
+ * for a script-path spend (the fallback and recovery spend builders).
+ */
+export declare function tapLeafHash(script: Uint8Array, leafVersion?: number): Uint8Array;
+/**
+ * Resolve the effective fallback threshold k from an advertised value and the
+ * cohort size n. When unadvertised it defaults to n-1 (tolerate one missing or
+ * defecting signer, the cheapest useful fallback witness), floored at 1. Both
+ * the service and every participant resolve this identically so they derive the
+ * same beacon address.
+ */
+export declare function resolveFallbackThreshold(advertised: number | undefined, n: number): number;
+/**
+ * Build the k-of-n fallback leaf script: a BIP-342 `p2tr_ms` CHECKSIGADD
+ * multisig over the cohort's x-only keys. Any k members can spend this leaf to
+ * push the announcement through when the optimistic n-of-n key path stalls.
+ *
+ * The keys are sorted per BIP-327 (matching the MuSig2 internal-key ordering)
+ * and reduced to x-only, so the leaf is identical for every party that builds it.
+ */
+export declare function buildFallbackLeaf(params: FallbackPolicyParams): Uint8Array;
+/**
+ * Build the CSV recovery leaf script:
+ * `<recoverySequence> CHECKSEQUENCEVERIFY DROP <recoveryKey> CHECKSIG`.
+ *
+ * After `recoverySequence` blocks (relative to the UTXO's confirmation) the
+ * holder of `recoveryKey` can spend the output via the script path.
+ */
+export declare function buildRecoveryScript(params: RecoveryPolicyParams): Uint8Array;
+/**
+ * Build the Taproot script-tree leaves for a funding model. The returned leaves
+ * are the script tree the beacon output key commits to alongside the cohort's
+ * MuSig2 internal key.
+ *
+ * Canonical leaf order is fallback (k-of-n, leaf A) then CSV recovery (leaf B).
+ * For the current two-leaf tree the Merkle root is order-invariant (a TapBranch
+ * sorts its two child hashes), but fixing the order keeps the construction
+ * deterministic and reviewable, and is consensus-affecting should the tree ever
+ * grow past two leaves.
+ *
+ * @throws {AggregationCohortError} when the funding model is reserved (e.g.
+ * `participant-funded`) or unknown, or when the fallback/recovery params are
+ * invalid.
+ */
+export declare function buildRecoveryLeaves(fundingModel: FundingModel, params: BeaconLeafParams): TaprootScriptLeaf[];
+//# sourceMappingURL=recovery-policy.d.ts.map

package/dist/types/core/aggregation/recovery-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-policy.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/recovery-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAEpE,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,EAAE,YAAgC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,WAAW,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,6FAA6F;AAC7F,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB,EAAE,oBAAoB;CAAG;AAEvF,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB,MAAO,CAAC;AASzC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,GAAE,MAA6B,GAAG,UAAU,CAKtG;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1F;AA0BD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,UAAU,CAI1E;AAiBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,UAAU,CAS5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,gBAAgB,GACvB,iBAAiB,EAAE,CAkBrB"}

package/dist/types/core/aggregation/recovery-spend.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Recovery spend builder for aggregate beacon outputs.
+ *
+ * An aggregate beacon UTXO is a Taproot output whose key path is the cohort's
+ * n-of-n MuSig2 aggregate key and whose script path carries a timelocked
+ * recovery leaf (see {@link ./recovery-policy.ts} and ADR 042). When the
+ * optimistic cooperative key-path spend cannot complete (a missing or defecting
+ * signer), the funder reclaims the UTXO via the recovery leaf after the
+ * relative-timelock delay.
+ *
+ * This module builds and signs that script-path spend. It is pure with respect
+ * to the network: it takes a UTXO reference plus the cohort and recovery
+ * parameters and returns a finalized {@link Transaction}; broadcasting and
+ * confirmation are the caller's concern. The recovery key path is a single
+ * BIP-340 Schnorr signature, so unlike the MuSig2 key path it can be driven by
+ * an opaque or HSM-backed signer.
+ *
+ * The relative timelock is enforced by consensus (BIP-68/112): the spend is only
+ * valid once the UTXO has `recoverySequence` confirmations, and the input's
+ * nSequence is set accordingly. The transaction version is 2 so BIP-68 applies.
+ */
+import { Transaction } from '@scure/btc-signer';
+import type { FundingModel } from './recovery-policy.js';
+/** Reference to the beacon UTXO being recovered. */
+export interface BeaconUtxoRef {
+    /** Transaction id (Esplora display-order hex), as returned by the REST UTXO endpoint. */
+    txid: string;
+    /** Output index within that transaction. */
+    vout: number;
+    /** Value of the beacon UTXO in satoshis. */
+    value: bigint;
+}
+/** Inputs to {@link buildRecoverySpend}. */
+export interface RecoverySpendParams {
+    /**
+     * The cohort's participant public keys (compressed secp256k1). Sorted
+     * internally per BIP-327 so the reconstructed internal key matches the one the
+     * beacon address was derived from.
+     */
+    cohortKeys: Uint8Array[];
+    /** Operator recovery secret key (32 bytes). Its x-only public key must equal {@link recoveryKey}. */
+    recoverySecretKey: Uint8Array;
+    /** Operator recovery key, x-only (32 bytes), as committed in the recovery leaf. */
+    recoveryKey: Uint8Array;
+    /** Relative-timelock (BIP-68 nSequence) the recovery leaf enforces. */
+    recoverySequence: number;
+    /**
+     * The advertised k of the k-of-n fallback leaf the beacon output also commits
+     * to, or omit to use the same n-1 default the cohort applies. Resolved against
+     * `cohortKeys.length` exactly as the cohort does, so the reconstructed script
+     * tree and control block match the funded address.
+     */
+    fallbackThreshold?: number;
+    /** Funding model governing the recovery leaves. Defaults to 'operator-funded'. */
+    fundingModel?: FundingModel;
+    /** Bitcoin network name (bitcoin/mainnet, mutinynet, signet, testnet, regtest). */
+    network: string;
+    /**
+     * The beacon UTXO being recovered.
+     *
+     * Precondition: the on-chain output at this `txid:vout` MUST have been funded
+     * to the beacon address derived from these same `cohortKeys`, `recoveryKey`,
+     * `recoverySequence`, and `fundingModel`. If it was funded under different
+     * parameters the reconstructed `witnessUtxo.script` will not match the chain,
+     * the signature will be invalid, and the spend will be rejected. Pass
+     * {@link beaconAddress} to assert this reconstruction up front.
+     */
+    utxo: BeaconUtxoRef;
+    /** Address receiving the recovered funds. */
+    destinationAddress: string;
+    /** Absolute fee (satoshis) deducted from the recovered value. */
+    fee: bigint;
+    /**
+     * Optional: the cohort's funded beacon address. When provided, the builder
+     * asserts that the address it reconstructs from the cohort and recovery params
+     * equals it, catching a caller mismatch before producing an unspendable tx.
+     */
+    beaconAddress?: string;
+}
+/**
+ * Build and sign a script-path recovery spend of an aggregate beacon UTXO.
+ *
+ * Reconstructs the same Taproot output the cohort funded (MuSig2 internal key +
+ * recovery script tree), spends it through the recovery leaf with the operator's
+ * recovery key, and finalizes the witness (signature + leaf script + control
+ * block). The returned transaction is ready to broadcast once the UTXO has
+ * `recoverySequence` confirmations.
+ *
+ * @throws {AggregationCohortError} when the recovery secret key does not match
+ * the committed recovery key, when there are no cohort keys, or when the fee
+ * exceeds the UTXO value.
+ */
+export declare function buildRecoverySpend(params: RecoverySpendParams): Transaction;
+//# sourceMappingURL=recovery-spend.d.ts.map

package/dist/types/core/aggregation/recovery-spend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-spend.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/recovery-spend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAQ,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,qGAAqG;IACrG,iBAAiB,EAAE,UAAU,CAAC;IAC9B,mFAAmF;IACnF,WAAW,EAAE,UAAU,CAAC;IACxB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,IAAI,EAAE,aAAa,CAAC;IACpB,6CAA6C;IAC7C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,WAAW,CA+E3E"}

package/dist/types/core/aggregation/runner/aggregation-runner.d.ts

@@ -13,10 +13,20 @@ export interface SoloCohortOptions {
     service: SoloActor;
     /** The single participant identity (the lone signer of the cohort). */
     participant: SoloActor;
-    /** Bitcoin network and beacon type (`'CASBeacon'` | `'SMTBeacon'`) for the cohort. */
+    /**
+     * Bitcoin network and beacon type (`'CASBeacon'` | `'SMTBeacon'`) for the
+     * cohort. Recovery params are optional here: in a solo run the service actor
+     * is the operator and holds full keys, so when `recoveryKey` is omitted the
+     * service's own x-only key is used as the CSV recovery key (it can actually
+     * perform the recovery), with {@link DEFAULT_RECOVERY_SEQUENCE} as the delay.
+     */
     config: {
         network: string;
         beaconType: string;
+        /** Operator recovery key, x-only (64-hex). Defaults to the service actor's x-only key. */
+        recoveryKey?: string;
+        /** Relative-timelock (BIP-68) before recovery is spendable. Defaults to {@link DEFAULT_RECOVERY_SEQUENCE}. */
+        recoverySequence?: number;
     };
     /** Provide the participant's signed BTCR2 update for the cohort. */
     onProvideUpdate: OnProvideUpdate;
@@ -39,8 +49,8 @@ export declare class AggregationRunner {
      *
      * 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

package/dist/types/core/aggregation/runner/aggregation-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregation-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/aggregation-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,SAAS,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,oEAAoE;IACpE,eAAe,EAAE,eAAe,CAAC;IACjC,6DAA6D;IAC7D,eAAe,EAAE,eAAe,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;;;;;OAiBG;WACU,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAuC1E"}
+{"version":3,"file":"aggregation-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/aggregation-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,SAAS,CAAC;IACvB;;;;;;OAMG;IACH,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,0FAA0F;QAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,8GAA8G;QAC9G,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,oEAAoE;IACpE,eAAe,EAAE,eAAe,CAAC;IACjC,6DAA6D;IAC7D,eAAe,EAAE,eAAe,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;;;;;OAiBG;WACU,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA8C1E"}

package/dist/types/core/aggregation/runner/events.d.ts

@@ -1,6 +1,24 @@
 import type { SerializedSMTProof } from '@did-btcr2/smt';
-import type { CohortAdvert, PendingSigningRequest, PendingValidation } from '../participant.js';
+import type { CohortAdvert, PendingFallbackRequest, PendingSigningRequest, PendingValidation } from '../participant.js';
 import type { AggregationResult, PendingOptIn, Rejection } from '../service.js';
+/**
+ * Sidecar data a participant keeps when a cohort completes from its
+ * perspective: the cohort's beacon coordinates plus the off-chain artifact it
+ * needs for future DID resolution (the CAS Announcement map for CAS beacons, or
+ * the SMT inclusion proof for SMT beacons). Emitted via `cohort-complete` and
+ * returned by the participant runner's join helpers.
+ */
+export interface CohortCompleteInfo {
+    cohortId: string;
+    beaconAddress: string;
+    beaconType: string;
+    /** True if this participant submitted an update; false if it declined (non-inclusion). */
+    included: boolean;
+    /** DID to base64url update hash. Populated only for CAS beacons. */
+    casAnnouncement?: Record<string, string>;
+    /** Inclusion proof (submitter) or non-inclusion proof (decliner) for this slot. Populated only for SMT beacons. */
+    smtProof?: SerializedSMTProof;
+}
 /**
  * AggregationServiceRunner events are emitted by the AggregationServiceRunner to signal important
  * milestones and actions during the aggregation process. They can be listened to by external code
@@ -15,15 +33,17 @@ export type AggregationServiceEvents = {
     'opt-in-received': [PendingOptIn];
     /** A participant has been accepted into the cohort. */
     'participant-accepted': [{
+        cohortId: string;
         participantDid: string;
     }];
-    /** Keygen has been finalized — beacon address is now available. */
+    /** Keygen has been finalized: beacon address is now available. */
     'keygen-complete': [{
         cohortId: string;
         beaconAddress: string;
     }];
     /** A participant has submitted a signed update. */
     'update-received': [{
+        cohortId: string;
         participantDid: string;
     }];
     /**
@@ -40,18 +60,30 @@ export type AggregationServiceEvents = {
     }];
     /** A participant has acknowledged validation (approved or rejected). */
     'validation-received': [{
+        cohortId: string;
         participantDid: string;
         approved: boolean;
     }];
-    /** Signing has started — auth requests sent to participants. */
+    /** Signing has started: auth requests sent to participants. */
     'signing-started': [{
+        cohortId: string;
+        sessionId: string;
+    }];
+    /**
+     * The optimistic n-of-n key path was abandoned and the k-of-n fallback
+     * (script-path) signing round started (ADR 042). After this, the cohort
+     * completes via the fallback once k members sign.
+     */
+    'fallback-started': [{
+        cohortId: string;
         sessionId: string;
     }];
     /** A participant has contributed their MuSig2 nonce. */
     'nonce-received': [{
+        cohortId: string;
         participantDid: string;
     }];
-    /** Signing complete — final aggregated signature is ready to broadcast. */
+    /** Signing complete: final aggregated signature is ready to broadcast. */
     'signing-complete': [AggregationResult];
     /** Cohort transitioned to Failed phase (e.g. a participant rejected validation). */
     'cohort-failed': [{
@@ -74,7 +106,7 @@ export type AggregationParticipantEvents = {
     'cohort-joined': [{
         cohortId: string;
     }];
-    /** Cohort keygen is complete — beacon address is now available. */
+    /** Cohort keygen is complete: beacon address is now available. */
     'cohort-ready': [{
         cohortId: string;
         beaconAddress: string;
@@ -83,27 +115,27 @@ export type AggregationParticipantEvents = {
     'update-submitted': [{
         cohortId: string;
     }];
+    /** Participant declined to submit an update this round (cooperative non-inclusion). */
+    'update-declined': [{
+        cohortId: string;
+    }];
     /** Aggregated data has arrived for validation. Fires before the validate callback. */
     'validation-requested': [PendingValidation];
     /** Signing request has arrived. Fires before the sign approval callback. */
     'signing-requested': [PendingSigningRequest];
+    /**
+     * A fallback (k-of-n script-path) signing request has arrived because the
+     * service abandoned the optimistic key path (ADR 042). Fires before the sign
+     * approval callback; approving signs the fallback spend.
+     */
+    'fallback-requested': [PendingFallbackRequest];
     /**
      * Cohort signing is complete from this participant's perspective.
      * Includes the aggregated sidecar data the participant needs to keep for
      * future DID resolution: the CAS Announcement map (for CAS beacons) or the
      * SMT inclusion proof (for SMT beacons).
      */
-    'cohort-complete': [
-        {
-            cohortId: string;
-            beaconAddress: string;
-            beaconType: string;
-            /** DID → base64url update hash. Populated only for CAS beacons. */
-            casAnnouncement?: Record<string, string>;
-            /** Merkle inclusion proof for this participant's slot. Populated only for SMT beacons. */
-            smtProof?: SerializedSMTProof;
-        }
-    ];
+    'cohort-complete': [CohortCompleteInfo];
     /** Cohort failed (rejected validation, signing error, etc.). */
     'cohort-failed': [{
         cohortId: string;

package/dist/types/core/aggregation/runner/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/events.ts"],"names":[],"mappings":"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"}