@did-btcr2/method 0.27.0 → 0.29.0

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

@@ -1,5 +1,6 @@
 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,
@@ -87,7 +88,7 @@ export interface AggregationParticipantRunnerOptions {
  *   keys: myKeys,
  *   shouldJoin: async (advert) => advert.beaconType === 'CASBeacon',
  *   onProvideUpdate: async ({ beaconAddress }) => {
- *     return Update.sign(myDid, unsigned, vm, secretKey);
+ *     return Updater.sign(myDid, unsigned, vm, secretKey);
  *   },
  * });
  *
@@ -139,9 +140,29 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
     this.#registerHandlers();
   }
 
-  /** Stop the runner. Does not unregister transport handlers. */
+  /** Stop the runner and detach transport handlers. Safe to call repeatedly. */
   stop(): void {
     this.#stopped = true;
+    this.#unregisterHandlers();
+  }
+
+  /** Message types this runner listens for on the transport. */
+  static readonly #HANDLED_MESSAGE_TYPES: readonly string[] = [
+    COHORT_ADVERT,
+    COHORT_OPT_IN_ACCEPT,
+    COHORT_READY,
+    DISTRIBUTE_AGGREGATED_DATA,
+    AUTHORIZATION_REQUEST,
+    AGGREGATED_NONCE,
+  ];
+
+  /** Internal: detach from the transport. Safe to call repeatedly. */
+  #unregisterHandlers(): void {
+    if(!this.#handlersRegistered) return;
+    this.#handlersRegistered = false;
+    for(const type of AggregationParticipantRunner.#HANDLED_MESSAGE_TYPES) {
+      this.#transport.unregisterMessageHandler(this.#did, type);
+    }
   }
 
   /**
@@ -150,7 +171,15 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
    */
   static async joinFirst(
     options: AggregationParticipantRunnerOptions
-  ): Promise<{ cohortId: string; beaconAddress: string }> {
+  ): 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;
+  }> {
     return new Promise((resolve, reject) => {
       const runner = new AggregationParticipantRunner(options);
       runner.once('cohort-complete', (info) => {
@@ -337,7 +366,16 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
       if (this.session.getCohortPhase(cohortId) === ParticipantCohortPhase.Complete) {
         const info = this.session.joinedCohorts.get(cohortId);
         if (info) {
-          this.emit('cohort-complete', { cohortId, beaconAddress: info.beaconAddress });
+          // 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,
+          });
         }
       }
     } catch (err) {

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

@@ -65,8 +65,44 @@ export interface AggregationServiceRunnerOptions {
    * REQUIRED — no sensible default.
    */
   onProvideTxData: OnProvideTxData;
+
+  /**
+   * Maximum canonicalized byte-length of a signed update body. Submissions
+   * above this cap are rejected and surfaced via the `message-rejected` event.
+   * Defaults to {@link DEFAULT_MAX_UPDATE_SIZE_BYTES} (256 KiB).
+   */
+  maxUpdateSizeBytes?: number;
+
+  /**
+   * Overall wall-clock budget for the cohort, from run() to signing-complete.
+   * On expiry the cohort is dropped, `cohort-failed` is emitted, and run()
+   * rejects with a timeout error. Leave undefined to disable.
+   */
+  cohortTtlMs?: number;
+
+  /**
+   * Maximum time allowed between phase transitions. Protects against stalled
+   * cohorts (e.g. a participant vanishing mid-protocol). Reset automatically
+   * on every observed phase change. Leave undefined to disable.
+   */
+  phaseTimeoutMs?: number;
+
+  /**
+   * Re-publish COHORT_ADVERT on this interval until 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
+   * advert without protocol changes. The first publish is immediate;
+   * subsequent publishes fire every `advertRepeatIntervalMs` until
+   * keygen-complete, fail, or stop(). Defaults to
+   * {@link DEFAULT_ADVERT_REPEAT_INTERVAL_MS} (60 s). Set to 0 to publish
+   * once and never retry.
+   */
+  advertRepeatIntervalMs?: number;
 }
 
+/** Default cadence for re-publishing COHORT_ADVERT until keygen completes: 60 seconds. */
+export const DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 60_000;
+
 /**
  * High-level facade for running an Aggregation Service over a Transport.
  *
@@ -111,12 +147,27 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
   readonly #onOptInReceived: OnOptInReceived;
   readonly #onReadyToFinalize: OnReadyToFinalize;
   readonly #onProvideTxData: OnProvideTxData;
+  readonly #cohortTtlMs?: number;
+  readonly #phaseTimeoutMs?: number;
+  readonly #advertRepeatIntervalMs: number;
 
   #cohortId?: string;
   #handlersRegistered = false;
   #stopped = false;
+  /**
+   * Guard against the async race where two concurrent #handleOptIn invocations
+   * both pass the `participants.length >= minParticipants` check before either
+   * mutates the cohort phase. Set synchronously before any `await` so subsequent
+   * handlers observe it on their next resumption.
+   */
+  #finalizing = false;
   #resolveRun?: (result: AggregationResult) => void;
   #rejectRun?: (err: Error) => void;
+  #cohortTtlTimer?: ReturnType<typeof setTimeout>;
+  #phaseTimer?: ReturnType<typeof setTimeout>;
+  #lastObservedPhase?: string;
+  /** Stop handle for the repeating COHORT_ADVERT publish loop. */
+  #stopAdvertRepeat?: () => void;
 
   constructor(options: AggregationServiceRunnerOptions) {
     super();
@@ -128,8 +179,27 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
       finalize : acceptedCount >= minRequired,
     }));
     this.#onProvideTxData = options.onProvideTxData;
+    this.#cohortTtlMs = options.cohortTtlMs;
+    this.#phaseTimeoutMs = options.phaseTimeoutMs;
+    this.#advertRepeatIntervalMs = options.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+
+    this.session = new AggregationService({
+      did                : options.did,
+      keys               : options.keys,
+      maxUpdateSizeBytes : options.maxUpdateSizeBytes,
+    });
+  }
 
-    this.session = new AggregationService({ did: options.did, keys: options.keys });
+  /**
+   * Drain any silent rejections the state machine recorded during the most
+   * recent receive() and surface them as `message-rejected` events. Safe to
+   * call even before a cohortId is assigned.
+   */
+  #drainRejections(): void {
+    if(!this.#cohortId) return;
+    for(const r of this.session.drainRejections(this.#cohortId)) {
+      this.emit('message-rejected', { cohortId: this.#cohortId, ...r });
+    }
   }
 
   /**
@@ -146,10 +216,20 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
       try {
         this.#registerHandlers();
         this.#cohortId = this.session.createCohort(this.#config);
+        this.#startTimers();
         // Emit cohort-advertised BEFORE the send so the event fires before any downstream cascade
         const advertMsgs = this.session.advertise(this.#cohortId);
+        this.#onPhaseMaybeChanged();
         this.emit('cohort-advertised', { cohortId: this.#cohortId });
-        this.#sendAll(advertMsgs).catch(err => this.#fail(err));
+        // Publish the advert. If advertRepeatIntervalMs > 0 we republish on
+        // that cadence until 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) {
+          this.#startAdvertRepeat(advertMsgs);
+        } else {
+          this.#sendAll(advertMsgs).catch(err => this.#fail(err));
+        }
       } catch(err) {
         this.#fail(err as Error);
       }
@@ -157,14 +237,95 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
   }
 
   /**
-   * Stop the runner early. Cleans up internal state.
-   * Note: does not unregister transport handlers (the transport interface
-   * does not currently expose unregister).
+   * Begin publishing the cohort advert immediately and on a repeating interval
+   * until {@link #stopAdvertRepeating} is called. Each advert is broadcast
+   * (no recipient) via the transport's `publishRepeating` primitive.
+   */
+  #startAdvertRepeat(advertMsgs: BaseMessage[]): void {
+    // COHORT_ADVERT is always a single broadcast message in the current
+    // protocol, but iterate for generality.
+    const stops: Array<() => void> = [];
+    for(const msg of advertMsgs) {
+      stops.push(this.#transport.publishRepeating(msg, this.#did, this.#advertRepeatIntervalMs));
+    }
+    this.#stopAdvertRepeat = () => {
+      for(const stop of stops) {
+        try { stop(); } catch { /* ignore */ }
+      }
+    };
+  }
+
+  /** Stop the advert republish loop. Idempotent. */
+  #stopAdvertRepeating(): void {
+    if(!this.#stopAdvertRepeat) return;
+    const stop = this.#stopAdvertRepeat;
+    this.#stopAdvertRepeat = undefined;
+    stop();
+  }
+
+  /** Schedule cohort TTL + phase timeout at the start of a run. */
+  #startTimers(): void {
+    if(this.#cohortTtlMs !== undefined) {
+      this.#cohortTtlTimer = setTimeout(() => {
+        const reason = `Cohort ${this.#cohortId ?? ''} exceeded TTL of ${this.#cohortTtlMs}ms`;
+        this.emit('cohort-failed', { cohortId: this.#cohortId ?? '', reason });
+        this.#fail(new Error(reason));
+      }, this.#cohortTtlMs);
+    }
+    this.#resetPhaseTimer();
+  }
+
+  /** Reset the per-phase stall timer. Called when a phase transition is observed. */
+  #resetPhaseTimer(): void {
+    if(this.#phaseTimer) clearTimeout(this.#phaseTimer);
+    this.#phaseTimer = undefined;
+    if(this.#phaseTimeoutMs === undefined) return;
+    this.#phaseTimer = setTimeout(() => {
+      const reason = `Cohort ${this.#cohortId ?? ''} stalled in phase ${this.#lastObservedPhase ?? '?'} for ${this.#phaseTimeoutMs}ms`;
+      this.emit('cohort-failed', { cohortId: this.#cohortId ?? '', reason });
+      this.#fail(new Error(reason));
+    }, this.#phaseTimeoutMs);
+  }
+
+  /** Detect a phase change since the last observation and reset the phase timer. */
+  #onPhaseMaybeChanged(): void {
+    if(!this.#cohortId) return;
+    const phase = this.session.getCohortPhase(this.#cohortId);
+    if(phase !== this.#lastObservedPhase) {
+      this.#lastObservedPhase = phase;
+      this.#resetPhaseTimer();
+    }
+  }
+
+  /** Clear both timers. Called on successful completion, stop(), and #fail. */
+  #clearTimers(): void {
+    if(this.#cohortTtlTimer) clearTimeout(this.#cohortTtlTimer);
+    if(this.#phaseTimer) clearTimeout(this.#phaseTimer);
+    this.#cohortTtlTimer = undefined;
+    this.#phaseTimer = undefined;
+  }
+
+  /**
+   * Stop the runner early. Marks the runner stopped and detaches transport
+   * handlers so a restart or a new runner doesn't inherit stale dispatch.
    */
   stop(): void {
     this.#stopped = true;
+    this.#stopAdvertRepeating();
+    this.#clearTimers();
+    this.#unregisterHandlers();
+    if(this.#cohortId) this.session.removeCohort(this.#cohortId);
   }
 
+  /** Message types this runner listens for on the transport. */
+  static readonly #HANDLED_MESSAGE_TYPES: readonly string[] = [
+    COHORT_OPT_IN,
+    SUBMIT_UPDATE,
+    VALIDATION_ACK,
+    NONCE_CONTRIBUTION,
+    SIGNATURE_AUTHORIZATION,
+  ];
+
   /**
    * Internal: handler registration with the transport. Idempotent.
    */
@@ -179,6 +340,15 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     this.#transport.registerMessageHandler(this.#did, SIGNATURE_AUTHORIZATION, this.#handleSignatureAuthorization.bind(this));
   }
 
+  /** Internal: detach from the transport. Safe to call repeatedly. */
+  #unregisterHandlers(): void {
+    if(!this.#handlersRegistered) return;
+    this.#handlersRegistered = false;
+    for(const type of AggregationServiceRunner.#HANDLED_MESSAGE_TYPES) {
+      this.#transport.unregisterMessageHandler(this.#did, type);
+    }
+  }
+
   /**
    * Internal: message handlers for each protocol step. Each handler:
    * 1) feeds the message into the state machine via session.receive()
@@ -195,6 +365,8 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     if(this.#stopped) return;
     try {
       this.session.receive(msg);
+      this.#drainRejections();
+      this.#onPhaseMaybeChanged();
 
       const optIn = this.session.pendingOptIns(this.#cohortId!).get(msg.from);
       if(!optIn) return;
@@ -211,25 +383,35 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
       await this.#sendAll(this.session.acceptParticipant(this.#cohortId!, msg.from));
       this.emit('participant-accepted', { participantDid: msg.from });
 
-      // Check if it's time to finalize
+      // Check if it's time to finalize. The `#finalizing` flag is set synchronously
+      // before the first await so concurrent opt-in handlers 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(this.#cohortId!)!;
-      if(cohort.participants.length >= this.#config.minParticipants) {
+      if(cohort.participants.length >= this.#config.minParticipants && !this.#finalizing) {
+        this.#finalizing = true;
         const finalizeDecision = await this.#onReadyToFinalize({
           acceptedCount : cohort.participants.length,
           minRequired   : this.#config.minParticipants,
         });
-        if(finalizeDecision.finalize) {
-          // finalizeKeygen() computes the beacon address synchronously
-          // emit BEFORE awaiting sendAll. Otherwise the downstream cascade
-          // (which can run all the way to signing-complete) would resolve the
-          // run() promise before this event fires.
-          const readyMsgs = this.session.finalizeKeygen(this.#cohortId!);
-          this.emit('keygen-complete', {
-            cohortId      : this.#cohortId!,
-            beaconAddress : cohort.beaconAddress,
-          });
-          await this.#sendAll(readyMsgs);
+        if(!finalizeDecision.finalize) {
+          // Operator declined — reset the flag so a later opt-in can retry.
+          this.#finalizing = false;
+          return;
         }
+        // finalizeKeygen() computes the beacon address synchronously
+        // emit BEFORE awaiting sendAll. Otherwise the downstream cascade
+        // (which can run all the way to signing-complete) would resolve the
+        // run() promise before this event fires.
+        const readyMsgs = this.session.finalizeKeygen(this.#cohortId!);
+        // Keygen done — stop re-advertising the cohort. New participants
+        // arriving after this point would be rejected anyway.
+        this.#stopAdvertRepeating();
+        this.emit('keygen-complete', {
+          cohortId      : this.#cohortId!,
+          beaconAddress : cohort.beaconAddress,
+        });
+        await this.#sendAll(readyMsgs);
       }
     } catch(err) {
       this.#fail(err as Error);
@@ -248,6 +430,8 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     if(this.#stopped) return;
     try {
       this.session.receive(msg);
+      this.#drainRejections();
+      this.#onPhaseMaybeChanged();
       this.emit('update-received', { participantDid: msg.from });
 
       // When all updates collected, build and distribute
@@ -273,11 +457,25 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     if(this.#stopped) return;
     try {
       this.session.receive(msg);
+      this.#drainRejections();
+      this.#onPhaseMaybeChanged();
       const approved = !!msg.body?.approved;
       this.emit('validation-received', { participantDid: msg.from, approved });
 
+      const phase = this.session.getCohortPhase(this.#cohortId!);
+
+      // A participant rejection flips the cohort to Failed. Emit a structured
+      // event so the runner/caller sees the failure instead of the cohort
+      // silently stalling.
+      if(phase === ServiceCohortPhase.Failed) {
+        const reason = `Validation rejected by participant ${msg.from}`;
+        this.emit('cohort-failed', { cohortId: this.#cohortId!, reason });
+        this.#fail(new Error(reason));
+        return;
+      }
+
       // When all validations received, request tx data and start signing
-      if(this.session.getCohortPhase(this.#cohortId!) === ServiceCohortPhase.Validated) {
+      if(phase === ServiceCohortPhase.Validated) {
         const cohort = this.session.getCohort(this.#cohortId!)!;
         const txData = await this.#onProvideTxData({
           cohortId      : this.#cohortId!,
@@ -306,6 +504,8 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     if(this.#stopped) return;
     try {
       this.session.receive(msg);
+      this.#drainRejections();
+      this.#onPhaseMaybeChanged();
       this.emit('nonce-received', { participantDid: msg.from });
 
       // When all nonces collected, send aggregated nonce
@@ -329,10 +529,14 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     if(this.#stopped) return;
     try {
       this.session.receive(msg);
+      this.#drainRejections();
+      this.#onPhaseMaybeChanged();
 
       // The state machine auto-completes when all partial sigs received
       const result = this.session.getResult(this.#cohortId!);
       if(result) {
+        this.#clearTimers();
+        this.#unregisterHandlers();
         this.emit('signing-complete', result);
         this.#resolveRun?.(result);
       }
@@ -359,6 +563,10 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
    * @param {Error} err - The error to handle.
    */
   #fail(err: Error): void {
+    this.#stopAdvertRepeating();
+    this.#clearTimers();
+    this.#unregisterHandlers();
+    if(this.#cohortId) this.session.removeCohort(this.#cohortId);
     this.emit('error', err);
     this.#rejectRun?.(err);
   }