@did-btcr2/method 0.36.0 → 0.37.0

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

@@ -1,6 +1,5 @@
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import type { SchnorrKeyPair } from '@did-btcr2/keypair';
-import type { SerializedSMTProof } from '@did-btcr2/smt';
 import type { BaseMessage } from '../messages/base.js';
 import {
   AGGREGATED_NONCE,
@@ -9,6 +8,7 @@ import {
   COHORT_OPT_IN_ACCEPT,
   COHORT_READY,
   DISTRIBUTE_AGGREGATED_DATA,
+  FALLBACK_AUTHORIZATION_REQUEST,
 } from '../messages/constants.js';
 import type {
   CohortAdvert,
@@ -20,7 +20,7 @@ import {
 import { ParticipantCohortPhase } from '../phases.js';
 import { KeyPairAggregationSigner } from '../signer.js';
 import type { Transport } from '../transport/transport.js';
-import type { AggregationParticipantEvents } from './events.js';
+import type { AggregationParticipantEvents, CohortCompleteInfo } from './events.js';
 import { TypedEventEmitter } from './typed-emitter.js';
 
 /** Decision callback: filter discovered cohorts. Default rejects all. */
@@ -30,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 }>;
@@ -54,7 +54,7 @@ export interface AggregationParticipantRunnerOptions {
 
   /**
    * Provide a signed BTCR2 update for the cohort.
-   * REQUIRED — no sensible default.
+   * REQUIRED - no sensible default.
    */
   onProvideUpdate: OnProvideUpdate;
 
@@ -162,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. */
@@ -175,19 +176,12 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
 
   /**
    * Single-shot helper: start, join the first cohort that passes `shouldJoin`,
-   * drive it to completion, and resolve. Convenient for tests and demos.
+   * drive it to completion, and resolve. Convenient for tests and demos. The
+   * single-cohort special case of {@link joinMatching} (count = 1).
    */
   static async joinFirst(
     options: AggregationParticipantRunnerOptions
-  ): Promise<{
-    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;
-  }> {
+  ): Promise<CohortCompleteInfo> {
     return new Promise((resolve, reject) => {
       const runner = new AggregationParticipantRunner(options);
       runner.once('cohort-complete', (info) => {
@@ -199,6 +193,41 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
     });
   }
 
+  /**
+   * Multi-cohort helper: start, join EVERY cohort whose advert passes
+   * `shouldJoin`, drive each to completion in parallel, and resolve once
+   * `count` cohorts have completed (the runner stops at that point). The
+   * N-cohort generalization of {@link joinFirst}, for a participant that joins
+   * several cohorts advertised by one service.
+   *
+   * 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
+   * any number of cohorts concurrently.
+   *
+   * @param options Participant runner options (set `shouldJoin` to select cohorts).
+   * @param count Number of completed cohorts to collect before resolving.
+   * @returns The {@link CohortCompleteInfo} for each completed cohort, in completion order.
+   */
+  static async joinMatching(
+    options: AggregationParticipantRunnerOptions,
+    count: number,
+  ): Promise<CohortCompleteInfo[]> {
+    return new Promise((resolve, reject) => {
+      const runner = new AggregationParticipantRunner(options);
+      const completed: CohortCompleteInfo[] = [];
+      runner.on('cohort-complete', (info) => {
+        completed.push(info);
+        if(completed.length >= count) {
+          runner.stop();
+          resolve(completed);
+        }
+      });
+      runner.on('error', reject);
+      runner.start().catch(reject);
+    });
+  }
+
   /**
    * Internal: handler registration with the transport. Idempotent and safe to call multiple times,
    * but only registers handlers once.
@@ -213,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));
   }
 
   /**
@@ -275,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);
     }
@@ -371,26 +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.
-          const validation = this.session.pendingValidations.get(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.