@did-btcr2/method 0.36.1 → 0.37.0

package/src/core/aggregation/runner/participant-runner.ts

@@ -8,6 +8,7 @@ import {
   COHORT_OPT_IN_ACCEPT,
   COHORT_READY,
   DISTRIBUTE_AGGREGATED_DATA,
+  FALLBACK_AUTHORIZATION_REQUEST,
 } from '../messages/constants.js';
 import type {
   CohortAdvert,
@@ -29,7 +30,7 @@ export type ShouldJoin = (advert: CohortAdvert) => Promise<boolean>;
 export type OnProvideUpdate = (info: {
   cohortId: string;
   beaconAddress: string;
-}) => Promise<SignedBTCR2Update>;
+}) => Promise<SignedBTCR2Update | null>;
 
 /** Decision callback: approve or reject aggregated data. */
 export type OnValidateData = (info: PendingValidation) => Promise<{ approved: boolean }>;
@@ -53,7 +54,7 @@ export interface AggregationParticipantRunnerOptions {
 
   /**
    * Provide a signed BTCR2 update for the cohort.
-   * REQUIRED — no sensible default.
+   * REQUIRED - no sensible default.
    */
   onProvideUpdate: OnProvideUpdate;
 
@@ -161,6 +162,7 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
     DISTRIBUTE_AGGREGATED_DATA,
     AUTHORIZATION_REQUEST,
     AGGREGATED_NONCE,
+    FALLBACK_AUTHORIZATION_REQUEST,
   ];
 
   /** Internal: detach from the transport. Safe to call repeatedly. */
@@ -200,7 +202,7 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
    *
    * 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).
@@ -240,6 +242,7 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
     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));
   }
 
   /**
@@ -302,13 +305,20 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
       if (!info) return;
       this.emit('cohort-ready', { cohortId, beaconAddress: info.beaconAddress });
 
-      // Construct the signed update via caller callback and submit
+      // Construct the signed update via caller callback and submit. A null return
+      // means the member has no update this round: it declines (cooperative
+      // non-inclusion) but stays in the cohort and still signs.
       const signedUpdate = await this.#onProvideUpdate({
         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 as Error);
     }
@@ -398,29 +408,71 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
       await this.#sendAll(this.session.generatePartialSignature(cohortId));
 
       // Check if we've reached completion
-      if (this.session.getCohortPhase(cohortId) === ParticipantCohortPhase.Complete) {
-        const info = this.session.joinedCohorts.get(cohortId);
-        if (info) {
-          // Surface the sidecar data the participant will need for future resolutions:
-          // the CAS Announcement map (CAS beacons) or their SMT inclusion proof.
-          // Read via getValidation (not pendingValidations, which lists only the
-          // AwaitingValidation phase) so the sidecar is still available now that
-          // the cohort has reached Complete.
-          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 as Error);
+    }
+  }
+
+  /**
+   * 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: BaseMessage): Promise<void> {
+    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));
+      // The member has contributed its fallback signature and is done from its
+      // own perspective, regardless of whether the service has yet collected k.
+      this.#emitCohortCompleteIfDone(cohortId);
     } catch (err) {
       this.emit('error', err as Error);
     }
   }
 
+  /**
+   * 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: string): void {
+    if (this.session.getCohortPhase(cohortId) !== ParticipantCohortPhase.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.

package/src/core/aggregation/runner/service-runner.ts

@@ -3,12 +3,15 @@ import { AggregationServiceError } from '../errors.js';
 import type { BaseMessage } from '../messages/base.js';
 import {
   COHORT_OPT_IN,
+  FALLBACK_SIGNATURE,
   NONCE_CONTRIBUTION,
   SIGNATURE_AUTHORIZATION,
+  SUBMIT_NONINCLUDED,
   SUBMIT_UPDATE,
   VALIDATION_ACK,
 } from '../messages/constants.js';
 import { ServiceCohortPhase } from '../phases.js';
+import type { ServiceCohortPhaseType } from '../phases.js';
 import type {
   AggregationResult,
   CohortConfig,
@@ -68,7 +71,7 @@ export interface AggregationServiceRunnerOptions {
 
   /**
    * Provide the Bitcoin transaction data to sign.
-   * REQUIRED — no sensible default.
+   * REQUIRED - no sensible default.
    */
   onProvideTxData: OnProvideTxData;
 
@@ -98,7 +101,7 @@ export interface AggregationServiceRunnerOptions {
   /**
    * Re-publish COHORT_ADVERT on this interval until a cohort's keygen is
    * finalized. Works around relays that don't backfill historical events to
-   * late subscribers — a republish gives late joiners a window to discover the
+   * late subscribers - a republish gives late joiners a window to discover the
    * advert without protocol changes. The first publish is immediate;
    * subsequent publishes fire every `advertRepeatIntervalMs` until that
    * cohort's keygen completes, fails, or is stopped. Defaults to
@@ -106,6 +109,17 @@ export interface AggregationServiceRunnerOptions {
    * once and never retry.
    */
   advertRepeatIntervalMs?: number;
+
+  /**
+   * When a cohort stalls (phase timeout) while the optimistic n-of-n signing
+   * round is in flight, fall back to the k-of-n script path instead of failing
+   * the cohort (graceful liveness, ADR 042). Off by default: enabling it trades a
+   * cheaper/private key-path spend for a larger script-path spend whenever the
+   * optimistic round does not complete in time. A stall outside the signing
+   * phases still fails the cohort. Operators can also drive the fallback
+   * explicitly via {@link AggregationServiceRunner.triggerFallback}.
+   */
+  autoFallbackOnStall?: boolean;
 }
 
 /** Default cadence for re-publishing COHORT_ADVERT until keygen completes: 60 seconds. */
@@ -139,6 +153,14 @@ interface RunContext {
   finalizing: boolean;
   /** Once settled (resolved or rejected), late timers/messages must not re-settle. */
   settled: boolean;
+  /**
+   * The spend path this cohort is committed to once signing reaches a decision:
+   * `optimistic` (n-of-n key path) or `fallback` (k-of-n script path). A cohort
+   * spends its single beacon UTXO exactly once, so this latch (set synchronously
+   * before any await) ensures the optimistic completion and the fallback never
+   * both finalize and broadcast the same UTXO (the ADR-042 double-spend hazard).
+   */
+  committedPath?: 'optimistic' | 'fallback';
   cohortTtlTimer?: ReturnType<typeof setTimeout>;
   phaseTimer?: ReturnType<typeof setTimeout>;
   lastObservedPhase?: string;
@@ -155,7 +177,7 @@ interface RunContext {
  *
  * A single runner is a long-lived multiplexer: it advertises and drives many
  * cohorts concurrently over one transport. Each advertised cohort owns an
- * independent completion promise and fails in isolation — a stalled or failed
+ * independent completion promise and fails in isolation - a stalled or failed
  * cohort never settles its siblings (see ADR 040). Use
  * {@link AggregationServiceRunner.advertiseCohort} for the multi-cohort path;
  * {@link AggregationServiceRunner.run} is a thin single-cohort convenience over
@@ -206,6 +228,14 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
   readonly #cohortTtlMs?: number;
   readonly #phaseTimeoutMs?: number;
   readonly #advertRepeatIntervalMs: number;
+  readonly #autoFallbackOnStall: boolean;
+
+  /** Phases during which a stall can be salvaged by the k-of-n fallback (ADR 042). */
+  static readonly #SIGNING_PHASES: readonly ServiceCohortPhaseType[] = [
+    ServiceCohortPhase.SigningStarted,
+    ServiceCohortPhase.NoncesCollected,
+    ServiceCohortPhase.AwaitingPartialSigs,
+  ];
 
   /** Per-cohort run state, keyed by cohortId. */
   readonly #contexts: Map<string, RunContext> = new Map();
@@ -225,6 +255,7 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     this.#cohortTtlMs = options.cohortTtlMs;
     this.#phaseTimeoutMs = options.phaseTimeoutMs;
     this.#advertRepeatIntervalMs = options.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+    this.#autoFallbackOnStall = options.autoFallbackOnStall ?? false;
 
     this.session = new AggregationService({
       // The coordinator never signs, so the state machine receives only the
@@ -269,7 +300,7 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     }
     this.#registerHandlers();
     // createCohort validates the conditions and throws on a bad config before
-    // any context exists — fail-fast, nothing to clean up.
+    // any context exists - fail-fast, nothing to clean up.
     const cohortId = this.session.createCohort(config);
 
     let resolve!: (result: AggregationResult) => void;
@@ -293,7 +324,7 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
       this.#onPhaseMaybeChanged(ctx);
       this.emit('cohort-advertised', { cohortId });
       // Publish the advert. If advertRepeatIntervalMs > 0 we republish on that
-      // cadence until this cohort's keygen-complete / fail / stop — works around
+      // cadence until this cohort's keygen-complete / fail / stop - works around
       // relays that don't backfill historical events to late subscribers.
       // Otherwise fall back to a single send.
       if(this.#advertRepeatIntervalMs > 0) {
@@ -404,12 +435,53 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     ctx.phaseTimer = undefined;
     if(this.#phaseTimeoutMs === undefined) return;
     ctx.phaseTimer = setTimeout(() => {
+      // A stall during the optimistic signing round can be salvaged by the k-of-n
+      // fallback rather than failing the whole cohort (graceful liveness, ADR
+      // 042) - but only if enabled and not already committed to a path.
+      const phase = this.session.getCohortPhase(ctx.cohortId);
+      const inSigning = phase !== undefined && AggregationServiceRunner.#SIGNING_PHASES.includes(phase);
+      if(this.#autoFallbackOnStall && inSigning && !ctx.committedPath && !ctx.settled) {
+        this.triggerFallback(ctx.cohortId).catch(err => this.#failCohort(ctx, err as Error));
+        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: string): Promise<void> {
+    const ctx = this.#contexts.get(cohortId);
+    if(!ctx || ctx.settled || ctx.committedPath) return;
+    // startFallbackSigning is synchronous and throws if the cohort is not in a
+    // signing phase (e.g. a premature operator call). Run it FIRST so a rejected
+    // transition cannot poison the latch: only after it commits the state machine
+    // to the fallback do we set committedPath. This still happens synchronously
+    // before any await, so a concurrent optimistic completion observes the latch
+    // and stands down - but a bad-phase call leaves the optimistic path intact.
+    const messages = this.session.startFallbackSigning(cohortId);
+    ctx.committedPath = 'fallback';
+    this.#stopAdvertRepeating(ctx);
+    this.#onPhaseMaybeChanged(ctx);
+    const sessionId = this.session.getSigningSessionId(cohortId) ?? '';
+    this.emit('fallback-started', { cohortId, sessionId });
+    await this.#sendAll(messages);
+  }
+
   /** Detect a phase change for a cohort since the last observation and reset its phase timer. */
   #onPhaseMaybeChanged(ctx: RunContext): void {
     const phase = this.session.getCohortPhase(ctx.cohortId);
@@ -505,14 +577,16 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
   static readonly #HANDLED_MESSAGE_TYPES: readonly string[] = [
     COHORT_OPT_IN,
     SUBMIT_UPDATE,
+    SUBMIT_NONINCLUDED,
     VALIDATION_ACK,
     NONCE_CONTRIBUTION,
     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.
    */
@@ -522,9 +596,14 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
 
     this.#transport.registerMessageHandler(this.#did, COHORT_OPT_IN, this.#handleOptIn.bind(this));
     this.#transport.registerMessageHandler(this.#did, SUBMIT_UPDATE, this.#handleSubmitUpdate.bind(this));
+    // A non-inclusion (decline) is an update-phase response handled identically:
+    // session.receive() routes by type, and the response gate + distribute
+    // trigger are shared with SUBMIT_UPDATE.
+    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. */
@@ -584,7 +663,7 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
 
       // Check if it's time to finalize. The per-cohort `finalizing` flag is set
       // synchronously before the first await so concurrent opt-in handlers for
-      // the same cohort observe it and skip — otherwise two handlers could both
+      // the same cohort observe it and skip - otherwise two handlers could both
       // pass the minParticipants check and both call finalizeKeygen, the second
       // of which would throw (phase mismatch).
       const cohort = this.session.getCohort(ctx.cohortId)!;
@@ -595,7 +674,7 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
           minRequired   : ctx.config.minParticipants,
         });
         if(!finalizeDecision.finalize) {
-          // Operator declined — reset the flag so a later opt-in can retry.
+          // Operator declined - reset the flag so a later opt-in can retry.
           ctx.finalizing = false;
           return;
         }
@@ -604,7 +683,7 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
         // (which can run all the way to signing-complete) would resolve the
         // cohort's completion promise before this event fires.
         const readyMsgs = this.session.finalizeKeygen(ctx.cohortId);
-        // Keygen done — stop re-advertising the cohort. New participants
+        // Keygen done - stop re-advertising the cohort. New participants
         // arriving after this point would be rejected anyway.
         this.#stopAdvertRepeating(ctx);
         this.emit('keygen-complete', {
@@ -733,7 +812,38 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
       this.#drainRejections(ctx);
       this.#onPhaseMaybeChanged(ctx);
 
-      // The state machine auto-completes when all partial sigs received
+      // If the cohort already committed to the fallback path, ignore a late
+      // optimistic completion: only one path may finalize the single beacon UTXO.
+      if(ctx.committedPath === 'fallback') return;
+
+      // The state machine auto-completes when all partial sigs received.
+      const result = this.session.getResult(ctx.cohortId);
+      if(result) {
+        ctx.committedPath = 'optimistic';
+        this.#completeCohort(ctx, result);
+      }
+    } catch(err) {
+      this.#failCohort(ctx, err as Error);
+    }
+  }
+
+  /**
+   * 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: BaseMessage): Promise<void> {
+    if(this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if(!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+
       const result = this.session.getResult(ctx.cohortId);
       if(result) {
         this.#completeCohort(ctx, result);