@did-btcr2/method 0.35.0 → 0.36.1

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

@@ -1 +1 @@
-{"version":3,"file":"participant-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/participant-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAUzD,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpE,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEjC,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEzF,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE/F,MAAM,WAAW,mCAAmC;IAClD,4BAA4B;IAC5B,SAAS,EAAE,SAAS,CAAC;IAErB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB,CAAC,4BAA4B,CAAC;;IAC/F,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;gBAY7B,OAAO,EAAE,mCAAmC;IAexD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,8EAA8E;IAC9E,IAAI,IAAI,IAAI;IA4BZ;;;OAGG;WACU,SAAS,CACpB,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,mEAAmE;QACnE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,0FAA0F;QAC1F,QAAQ,CAAC,EAAE,kBAAkB,CAAC;KAC/B,CAAC;CAwNH"}
+{"version":3,"file":"participant-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/participant-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAUzD,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpE,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEjC,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEzF,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE/F,MAAM,WAAW,mCAAmC;IAClD,4BAA4B;IAC5B,SAAS,EAAE,SAAS,CAAC;IAErB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB,CAAC,4BAA4B,CAAC;;IAC/F,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;gBAY7B,OAAO,EAAE,mCAAmC;IAexD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,8EAA8E;IAC9E,IAAI,IAAI,IAAI;IA4BZ;;;;OAIG;WACU,SAAS,CACpB,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,kBAAkB,CAAC;IAY9B;;;;;;;;;;;;;;;OAeG;WACU,YAAY,CACvB,OAAO,EAAE,mCAAmC,EAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,EAAE,CAAC;CA+NjC"}

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

@@ -27,8 +27,13 @@ export interface AggregationServiceRunnerOptions {
     /** This service's identity. */
     did: string;
     keys: SchnorrKeyPair;
-    /** Cohort configuration. */
-    config: CohortConfig;
+    /**
+     * Default cohort configuration for the {@link AggregationServiceRunner.run}
+     * convenience path. Optional: omit it when driving the runner with
+     * {@link AggregationServiceRunner.advertiseCohort}, which takes a per-cohort
+     * config and can be called many times on one runner.
+     */
+    config?: CohortConfig;
     /**
      * Decide whether to accept a participant's opt-in.
      * Default: auto-accept all opt-ins.
@@ -52,24 +57,26 @@ export interface AggregationServiceRunnerOptions {
      */
     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.
+     * Overall wall-clock budget for each cohort, from advertise to
+     * signing-complete. On expiry the cohort is dropped, `cohort-failed` is
+     * emitted, and that cohort's completion rejects with a timeout error. Other
+     * cohorts on the same runner are unaffected. 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.
+     * Maximum time allowed between phase transitions for a cohort. Protects
+     * against stalled cohorts (e.g. a participant vanishing mid-protocol). Reset
+     * automatically on every observed phase change. Applied per cohort. 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
+     * 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
      * advert without protocol changes. The first publish is immediate;
-     * subsequent publishes fire every `advertRepeatIntervalMs` until
-     * keygen-complete, fail, or stop(). Defaults to
+     * subsequent publishes fire every `advertRepeatIntervalMs` until that
+     * cohort's keygen completes, fails, or is stopped. Defaults to
      * {@link DEFAULT_ADVERT_REPEAT_INTERVAL_MS} (60 s). Set to 0 to publish
      * once and never retry.
      */
@@ -84,6 +91,14 @@ export declare const DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 60000;
  * encapsulating message handler registration, outgoing message dispatch,
  * and decision callback orchestration.
  *
+ * 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
+ * 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
+ * it.
+ *
  * @example
  * ```typescript
  * const transport = new NostrTransport({ relays: [RELAY] });
@@ -93,16 +108,21 @@ export declare const DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 60000;
  *   transport,
  *   did: serviceDid,
  *   keys: serviceKeys,
- *   config: { minParticipants: 2, network: 'mutinynet', beaconType: 'CASBeacon' },
- *   onProvideTxData: async ({ beaconAddress, signalBytes }) => {
+ *   onProvideTxData: async ({ cohortId, beaconAddress, signalBytes }) => {
  *     return await buildBeaconTransaction(beaconAddress, signalBytes, bitcoin);
  *   },
  * });
  *
- * runner.on('keygen-complete', ({ beaconAddress }) => console.log(beaconAddress));
- * runner.on('signing-complete', ({ signature }) => console.log('done'));
+ * runner.on('keygen-complete', ({ cohortId, beaconAddress }) => console.log(beaconAddress));
+ * runner.on('signing-complete', ({ cohortId, signature }) => console.log('done', cohortId));
  *
- * const result = await runner.run();
+ * // Multi-cohort: advertise several cohorts; each completion resolves independently.
+ * const a = runner.advertiseCohort({ minParticipants: 2, network: 'mutinynet', beaconType: 'CASBeacon' });
+ * const b = runner.advertiseCohort({ minParticipants: 3, network: 'mutinynet', beaconType: 'SMTBeacon' });
+ * const [ra, rb] = await Promise.all([a.completion, b.completion]);
+ *
+ * // Single-cohort convenience (requires `config` in the options):
+ * // const result = await runner.run();
  * ```
  *
  * For full manual control, drop down to the underlying state machine via
@@ -117,15 +137,49 @@ export declare class AggregationServiceRunner extends TypedEventEmitter<Aggregat
     readonly session: AggregationService;
     constructor(options: AggregationServiceRunnerOptions);
     /**
-     * Run the protocol to completion. Resolves with the final aggregation result
-     * (signature + signed transaction) once signing is complete.
+     * Advertise a new cohort and begin driving it to completion. Callable many
+     * times on one runner; each cohort runs concurrently and independently.
+     *
+     * @param config Per-cohort conditions + network (see {@link CohortConfig}).
+     * @returns The new cohort's id and a `completion` promise that resolves with
+     *   that cohort's {@link AggregationResult} (or rejects if it fails/stalls).
+     * @throws If the runner has been stopped, or the config is invalid
+     *   (fail-fast via `createCohort`).
+     */
+    advertiseCohort(config: CohortConfig): {
+        cohortId: string;
+        completion: Promise<AggregationResult>;
+    };
+    /**
+     * Run a single cohort to completion using the `config` supplied in the
+     * runner options. Thin convenience over {@link advertiseCohort} for the
+     * single-cohort case (and the path {@link AggregationRunner.solo} rides).
      *
      * @returns {Promise<AggregationResult>} The final result with signature and signed tx.
      */
     run(): Promise<AggregationResult>;
     /**
-     * Stop the runner early. Marks the runner stopped and detaches transport
-     * handlers so a restart or a new runner doesn't inherit stale dispatch.
+     * Wait for every currently-outstanding cohort to settle and return the
+     * successful results. Dynamic drain: cohorts advertised while this is pending
+     * are included, and it resolves only once no cohorts remain. Failed cohorts
+     * are surfaced via `error` / `cohort-failed` events and their rejected
+     * `completion` promises; they are omitted from the returned array (this
+     * method does not throw). Bound long-running cohorts with `cohortTtlMs` /
+     * `phaseTimeoutMs` or this may never resolve.
+     *
+     * @returns {Promise<AggregationResult[]>} Results of the cohorts that completed.
+     */
+    runAll(): Promise<AggregationResult[]>;
+    /**
+     * Stop a single cohort early without affecting the rest of the runner. Drops
+     * the cohort's state machine state; its `completion` promise rejects with a
+     * stopped error.
+     */
+    stopCohort(cohortId: string): void;
+    /**
+     * Stop the whole runner. Fails every outstanding cohort, then detaches the
+     * shared transport handlers so a restart or a new runner doesn't inherit
+     * stale dispatch. Safe to call repeatedly.
      */
     stop(): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"service-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/service-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAUzD,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,aAAa,EAAC,MAAM,eAAe,CAAC;AACtC,OAAO,EACL,kBAAkB,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEtF,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAErC,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,UAAU,CAAC;CACzB,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE7B,MAAM,WAAW,+BAA+B;IAC9C,kEAAkE;IAClE,SAAS,EAAE,SAAS,CAAC;IAErB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IAErB,4BAA4B;IAC5B,MAAM,EAAE,YAAY,CAAC;IAErB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,0FAA0F;AAC1F,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,wBAAyB,SAAQ,iBAAiB,CAAC,wBAAwB,CAAC;;IACvF,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBA8BzB,OAAO,EAAE,+BAA+B;IAoCpD;;;;;OAKG;IACH,GAAG,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAiGjC;;;OAGG;IACH,IAAI,IAAI,IAAI;CAqQb"}
+{"version":3,"file":"service-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/service-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAWzD,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,aAAa,EAAC,MAAM,eAAe,CAAC;AACtC,OAAO,EACL,kBAAkB,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEtF,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAErC,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,UAAU,CAAC;CACzB,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE7B,MAAM,WAAW,+BAA+B;IAC9C,kEAAkE;IAClE,SAAS,EAAE,SAAS,CAAC;IAErB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IAErB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,0FAA0F;AAC1F,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAqCxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,wBAAyB,SAAQ,iBAAiB,CAAC,wBAAwB,CAAC;;IACvF,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAiBzB,OAAO,EAAE,+BAA+B;IAyCpD;;;;;;;;;OASG;IACH,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;KAAE;IA6CnG;;;;;;OAMG;IACH,GAAG,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAcjC;;;;;;;;;;OAUG;IACG,MAAM,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAiI5C;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IASlC;;;;OAIG;IACH,IAAI,IAAI,IAAI;CAyQb"}

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

@@ -2,13 +2,17 @@ import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import type { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
 import type { Transaction } from '@scure/btc-signer';
 import { AggregationCohort } from './cohort.js';
+import { type CohortConditions } from './conditions.js';
 import type { BaseMessage } from './messages/base.js';
 import type { ServiceCohortPhaseType } from './phases.js';
-/** Cohort configuration set by the service operator. */
-export interface CohortConfig {
-    minParticipants: number;
+/**
+ * Cohort configuration set by the service operator: the advertised cohort
+ * {@link CohortConditions} plus the Bitcoin network. `beaconType` and
+ * `minParticipants` are required; the other conditions are optional (absent =
+ * unconstrained). See ADR 039.
+ */
+export interface CohortConfig extends CohortConditions {
     network: string;
-    beaconType: string;
 }
 /** Pending opt-in awaiting service operator approval. */
 export interface PendingOptIn {

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

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAiBtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,UAAU,CAAC;IAC1B,eAAe,EAAE,UAAU,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,UAAU,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,kBAAkB,GAClB,4BAA4B,GAC5B,kBAAkB,CAAC;AAEvB,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,EAAE,eAAe,CAAC;IACtB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAeD,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,QAAa,CAAC;AAExD,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,SAAS,EAAE,4BAA4B,CAAC;IACxC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAkB;;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,4BAA4B,CAAC;IACjD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;gBAKxB,EAAE,GAAG,EAAE,SAAS,EAAE,kBAAkB,EAAE,EAAE,wBAAwB;IAO5E,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAyCnC;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC;IASnD;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAkB1C;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAyB1C,kDAAkD;IAClD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAwClE;;;OAGG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,WAAW,EAAE;IA+B1E;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAmC/C,6CAA6C;IAC7C,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC;IA2G1E;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAwCnD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB;IAwCxD;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,EAAE;IAgEpE;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IA4DpD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAI1D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS;IAIpE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAI1D;;;;OAIG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzD,IAAI,OAAO,IAAI,aAAa,CAAC,iBAAiB,CAAC,CAE9C;IAED;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAGrC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/service.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export * from './core/aggregation/service.js';
 export * from './core/aggregation/participant.js';
 export * from './core/aggregation/signer.js';
+export * from './core/aggregation/conditions.js';
 export * from './core/aggregation/cohort.js';
 export * from './core/aggregation/signing-session.js';
 export * from './core/aggregation/phases.js';

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "type": "module",
   "description": "Reference implementation for the did:btcr2 DID method written in TypeScript and JavaScript. did:btcr2 is a censorship resistant DID Method using the Bitcoin blockchain as a Verifiable Data Registry to announce changes to the DID document. This is the core method implementation for the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -80,11 +80,11 @@
     "helia": "^5.5.1",
     "multiformats": "^13.4.2",
     "nostr-tools": "^2.23.3",
-    "@did-btcr2/common": "^9.1.0",
     "@did-btcr2/bitcoin": "^0.6.0",
-    "@did-btcr2/cryptosuite": "^8.0.0",
+    "@did-btcr2/keypair": "^0.13.1",
     "@did-btcr2/smt": "^0.3.0",
-    "@did-btcr2/keypair": "^0.13.1"
+    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/cryptosuite": "^8.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/aggregation/cohort.ts

@@ -91,7 +91,9 @@ export class AggregationCohort {
 
   constructor({ id, minParticipants, serviceDid, network, beaconType }: AggregationCohortParams) {
     this.id = id || crypto.randomUUID();
-    this.minParticipants = minParticipants || 2;
+    // `?? 2` (not `|| 2`) so a deliberately-passed 0 is preserved rather than
+    // silently coerced; the service rejects an invalid count at createCohort.
+    this.minParticipants = minParticipants ?? 2;
     this.serviceDid = serviceDid || '';
     this.network = network;
     this.beaconType = beaconType || 'CASBeacon';

package/src/core/aggregation/conditions.ts

@@ -0,0 +1,116 @@
+/**
+ * Cohort conditions: the constraints an Aggregation Service advertises for a
+ * cohort (did:btcr2 spec, "Step 1: Create Aggregation Cohort"). See ADR 039.
+ *
+ * The spec frames these as an optional menu ("the Aggregation Service can define
+ * conditions such as ..."), so only `beaconType` and `minParticipants` are
+ * required here; every other condition is optional and, when absent, means
+ * unconstrained.
+ *
+ * Enforcement is staged (ADR 039): `beaconType` and the participant bounds are
+ * enforced by the state machine now; DIDs-per-participant, timing/cadence, and
+ * the pending-update trigger are modeled and advertised here but enforced when
+ * the multi-cohort (AGG-4) and non-inclusion (AGG-5) tracks land. The two cost
+ * conditions are advertised metadata only - the protocol performs no payment or
+ * settlement (consistent with ADR 008).
+ */
+
+/** Beacon types that support aggregation (singleton is single-party only, per ADR 037). */
+export const KNOWN_BEACON_TYPES = ['CASBeacon', 'SMTBeacon'] as const;
+
+/**
+ * An advertised price. `unit` is operator-defined (the spec does not specify a
+ * currency); `basis` distinguishes a per-DID from a per-participant charge for
+ * "cost per announcement". Advertised only - never settled by the protocol.
+ */
+export interface CohortCost {
+  amount: number;
+  unit: string;
+  basis?: 'per-did' | 'per-participant';
+}
+
+/** The seven spec cohort conditions. Only beaconType + minParticipants are required. */
+export interface CohortConditions {
+  /** 1. Beacon mechanism: 'CASBeacon' or 'SMTBeacon'. Enforced. */
+  beaconType: string;
+  /** 2. Lower bound on cohort size. Enforced (finalize floor). */
+  minParticipants: number;
+  /** 2. Upper bound on cohort size. Enforced (accept/finalize ceiling). */
+  maxParticipants?: number;
+  /** 3. Lower bound on DIDs a participant may register. Advertised; enforcement staged (AGG-5). */
+  minDidsPerParticipant?: number;
+  /** 3. Upper bound on DIDs a participant may register. Advertised; enforcement staged (AGG-5). */
+  maxDidsPerParticipant?: number;
+  /** 4. One-time enrollment price. Advertised only - no settlement. */
+  costOfEnrollment?: CohortCost;
+  /** 5. Recurring per-announcement price. Advertised only - no settlement. */
+  costPerAnnouncement?: CohortCost;
+  /** 6. Floor on time between announcements (seconds). Advertised; enforcement staged (AGG-4/5). */
+  minSecondsBetweenAnnouncements?: number;
+  /** 6. Ceiling on time between announcements (seconds). Advertised; enforcement staged - generalizes the ADR 027 Cohort TTL. */
+  maxSecondsBetweenAnnouncements?: number;
+  /** 7. Pending-update count that triggers an announcement. Advertised; enforcement staged (AGG-5) - generalizes hasAllUpdates(). */
+  pendingUpdateTrigger?: number;
+}
+
+/** Validate an optional [min, max] integer pair. */
+function checkPair(problems: string[], label: string, min?: number, max?: number): void {
+  if(min !== undefined && (!Number.isInteger(min) || min < 0)) {
+    problems.push(`min${label} must be an integer >= 0`);
+  }
+  if(max !== undefined && (!Number.isInteger(max) || max < 0)) {
+    problems.push(`max${label} must be an integer >= 0`);
+  }
+  if(min !== undefined && max !== undefined && Number.isInteger(min) && Number.isInteger(max) && max < min) {
+    problems.push(`max${label} must be >= min${label}`);
+  }
+}
+
+/** Validate an optional advertised cost. */
+function checkCost(problems: string[], label: string, cost?: CohortCost): void {
+  if(cost === undefined) return;
+  if(typeof cost.amount !== 'number' || !Number.isFinite(cost.amount) || cost.amount < 0) {
+    problems.push(`${label}.amount must be a finite number >= 0`);
+  }
+  if(typeof cost.unit !== 'string' || cost.unit.length === 0) {
+    problems.push(`${label}.unit must be a non-empty string`);
+  }
+  if(cost.basis !== undefined && cost.basis !== 'per-did' && cost.basis !== 'per-participant') {
+    problems.push(`${label}.basis must be 'per-did' or 'per-participant'`);
+  }
+}
+
+/**
+ * Validate a set of cohort conditions. Returns a list of human-readable problems
+ * (empty when valid) so the caller can decide how to surface them. Used by
+ * `createCohort()` to fail fast instead of discovering invalidity at finalize.
+ */
+export function validateCohortConditions(c: CohortConditions): string[] {
+  const problems: string[] = [];
+
+  if(!(KNOWN_BEACON_TYPES as readonly string[]).includes(c.beaconType)) {
+    problems.push(`beaconType must be one of ${KNOWN_BEACON_TYPES.join(', ')}`);
+  }
+  if(!Number.isInteger(c.minParticipants) || c.minParticipants < 1) {
+    problems.push('minParticipants must be an integer >= 1');
+  }
+  if(c.maxParticipants !== undefined) {
+    if(!Number.isInteger(c.maxParticipants) || c.maxParticipants < 1) {
+      problems.push('maxParticipants must be an integer >= 1');
+    } else if(Number.isInteger(c.minParticipants) && c.maxParticipants < c.minParticipants) {
+      problems.push('maxParticipants must be >= minParticipants');
+    }
+  }
+
+  checkPair(problems, 'DidsPerParticipant', c.minDidsPerParticipant, c.maxDidsPerParticipant);
+  checkPair(problems, 'SecondsBetweenAnnouncements', c.minSecondsBetweenAnnouncements, c.maxSecondsBetweenAnnouncements);
+
+  if(c.pendingUpdateTrigger !== undefined && (!Number.isInteger(c.pendingUpdateTrigger) || c.pendingUpdateTrigger < 1)) {
+    problems.push('pendingUpdateTrigger must be an integer >= 1');
+  }
+
+  checkCost(problems, 'costOfEnrollment', c.costOfEnrollment);
+  checkCost(problems, 'costPerAnnouncement', c.costPerAnnouncement);
+
+  return problems;
+}

package/src/core/aggregation/messages/base.ts

@@ -1,3 +1,5 @@
+import type { CohortConditions } from '../conditions.js';
+
 /**
  * Current on-the-wire protocol version.
  *
@@ -7,9 +9,11 @@
  */
 export const AGGREGATION_WIRE_VERSION = 1;
 
-export type BaseBody = {
+// Cohort conditions (beaconType, minParticipants, maxParticipants, ...) ride on
+// the wire as flat optional body fields, supplied via `Partial<CohortConditions>`
+// below so the bag stays a single source of truth for the advertised conditions.
+export type BaseBody = Partial<CohortConditions> & {
   cohortId: string;
-  cohortSize?: number;
   network?: string;
   participantPk?: Uint8Array;
   beaconAddress?: string;
@@ -23,7 +27,6 @@ export type BaseBody = {
   prevOutScriptHex?: string;
   prevOutValue?: string;
   communicationPk?: Uint8Array;
-  beaconType?: string;
   data?: string;
   signedUpdate?: Record<string, unknown>;
   casAnnouncement?: Record<string, string>;

package/src/core/aggregation/messages/bodies.ts

@@ -12,6 +12,7 @@
  */
 
 import type { SerializedSMTProof } from '@did-btcr2/smt';
+import type { CohortConditions } from '../conditions.js';
 import type { BaseMessage } from './base.js';
 import {
   AGGREGATED_NONCE,
@@ -29,10 +30,8 @@ import {
 
 // ── Cohort formation (Step 1) ─────────────────────────────────────────────
 
-export interface CohortAdvertBody {
+export interface CohortAdvertBody extends CohortConditions {
   cohortId: string;
-  cohortSize: number;
-  beaconType: string;
   network: string;
   communicationPk: Uint8Array;
 }
@@ -135,8 +134,16 @@ export type AggregationMessage =
 
 const hasStr = (b: unknown, k: string): boolean =>
   !!b && typeof (b as Record<string, unknown>)[k] === 'string';
-const hasNum = (b: unknown, k: string): boolean =>
-  !!b && typeof (b as Record<string, unknown>)[k] === 'number';
+/** Present, an integer, and >= min. */
+const hasIntMin = (b: unknown, k: string, min: number): boolean => {
+  const v = b ? (b as Record<string, unknown>)[k] : undefined;
+  return typeof v === 'number' && Number.isInteger(v) && v >= min;
+};
+/** Absent, or present as an integer >= min. */
+const optIntMin = (b: unknown, k: string, min: number): boolean => {
+  const v = b ? (b as Record<string, unknown>)[k] : undefined;
+  return v === undefined || (typeof v === 'number' && Number.isInteger(v) && v >= min);
+};
 const hasBool = (b: unknown, k: string): boolean =>
   !!b && typeof (b as Record<string, unknown>)[k] === 'boolean';
 const hasBytes = (b: unknown, k: string): boolean =>
@@ -147,9 +154,14 @@ const hasBytesArray = (b: unknown, k: string): boolean => {
 };
 
 export function isCohortAdvertMessage(m: BaseMessage): m is CohortAdvertMessage {
+  // Range-check the participant bounds so a malformed advert (missing or
+  // zero/negative minParticipants) is rejected rather than silently accepted as
+  // a zero-floor cohort. The service does the full cross-field validation at
+  // createCohort (see validateCohortConditions); here we guard the wire shape.
   return m.type === COHORT_ADVERT
     && hasStr(m.body, 'cohortId')
-    && hasNum(m.body, 'cohortSize')
+    && hasIntMin(m.body, 'minParticipants', 1)
+    && optIntMin(m.body, 'maxParticipants', 1)
     && hasStr(m.body, 'beaconType')
     && hasStr(m.body, 'network')
     && hasBytes(m.body, 'communicationPk');

package/src/core/aggregation/messages/factories.ts

@@ -1,3 +1,4 @@
+import type { CohortConditions } from '../conditions.js';
 import { BaseMessage } from './base.js';
 import {
   AGGREGATED_NONCE,
@@ -18,11 +19,9 @@ import {
  * Factory functions for creating messages related to the cohort formation step, where cohorts are
  * formed and participants opt in to join the cohort.
  */
-type CohortAdvertMessage = {
+type CohortAdvertMessage = CohortConditions & {
   from: string;
   cohortId: string;
-  cohortSize: number;
-  beaconType: string;
   network: string;
   communicationPk: Uint8Array;
 };

package/src/core/aggregation/participant.ts

@@ -5,8 +5,10 @@ import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
 import { Transaction } from '@scure/btc-signer';
 import { getBeaconStrategy } from './beacon-strategy.js';
 import { AggregationCohort } from './cohort.js';
+import type { CohortConditions } from './conditions.js';
 import { AggregationParticipantError } from './errors.js';
 import type { BaseMessage } from './messages/base.js';
+import { isCohortAdvertMessage } from './messages/bodies.js';
 import { AGGREGATION_WIRE_VERSION } from './messages/base.js';
 import {
   AGGREGATED_NONCE,
@@ -28,13 +30,15 @@ import { ParticipantCohortPhase } from './phases.js';
 import type { AggregationSigner } from './signer.js';
 import { BeaconSigningSession } from './signing-session.js';
 
-/** Cohort advert as discovered by the participant (UI: list of joinable cohorts). */
-export interface CohortAdvert {
+/**
+ * Cohort advert as discovered by the participant (UI: list of joinable cohorts).
+ * Carries the advertised {@link CohortConditions} (beaconType, minParticipants,
+ * maxParticipants, costs, ...) so a `shouldJoin` decision can inspect them.
+ */
+export interface CohortAdvert extends CohortConditions {
   cohortId: string;
   serviceDid: string;
-  cohortSize: number;
   network: string;
-  beaconType: string;
   serviceCommunicationPk: Uint8Array;
 }
 
@@ -168,17 +172,18 @@ export class AggregationParticipant {
   }
 
   #handleCohortAdvert(message: BaseMessage): void {
-    const cohortId = message.body?.cohortId;
-    if(!cohortId) return;
+    // Validate the wire shape (incl. minParticipants range) before trusting it,
+    // rather than reading fields with `?? 0` fallbacks (see ADR 039).
+    if(!isCohortAdvertMessage(message)) return;
+    const { cohortId, network, communicationPk, ...conditions } = message.body;
     if(this.#cohortStates.has(cohortId)) return;  // Already known
 
     const advert: CohortAdvert = {
       cohortId,
       serviceDid             : message.from,
-      cohortSize             : message.body?.cohortSize ?? 0,
-      network                : message.body?.network ?? '',
-      beaconType             : message.body?.beaconType ?? 'CASBeacon',
-      serviceCommunicationPk : message.body?.communicationPk ?? new Uint8Array(),
+      network,
+      serviceCommunicationPk : communicationPk,
+      ...conditions,
     };
 
     this.#cohortStates.set(cohortId, {
@@ -206,7 +211,7 @@ export class AggregationParticipant {
     const cohort = new AggregationCohort({
       id              : cohortId,
       serviceDid      : state.serviceDid,
-      minParticipants : state.advert!.cohortSize,
+      minParticipants : state.advert!.minParticipants,
       network         : state.advert!.network,
       beaconType      : state.advert!.beaconType,
     });
@@ -302,6 +307,18 @@ export class AggregationParticipant {
     return map;
   }
 
+  /**
+   * 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.
+   */
+  public getValidation(cohortId: string): PendingValidation | undefined {
+    return this.#cohortStates.get(cohortId)?.validation;
+  }
+
   #handleDistributeAggregatedData(message: BaseMessage): void {
     const cohortId = message.body?.cohortId;
     if(!cohortId) return;

package/src/core/aggregation/runner/events.ts

@@ -2,6 +2,23 @@ import type { SerializedSMTProof } from '@did-btcr2/smt';
 import type { CohortAdvert, 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;
+  /** 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;
+}
+
 /**
  * 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,13 +32,13 @@ export type AggregationServiceEvents = {
   'opt-in-received': [PendingOptIn];
 
   /** A participant has been accepted into the cohort. */
-  'participant-accepted': [{ participantDid: string }];
+  'participant-accepted': [{ cohortId: string; participantDid: string }];
 
   /** Keygen has been finalized — beacon address is now available. */
   'keygen-complete': [{ cohortId: string; beaconAddress: string }];
 
   /** A participant has submitted a signed update. */
-  'update-received': [{ participantDid: string }];
+  'update-received': [{ cohortId: string; participantDid: string }];
 
   /**
    * An inbound message was silently dropped by the state machine (bad proof,
@@ -34,13 +51,13 @@ export type AggregationServiceEvents = {
   'data-distributed': [{ cohortId: string }];
 
   /** A participant has acknowledged validation (approved or rejected). */
-  'validation-received': [{ participantDid: string; approved: boolean }];
+  'validation-received': [{ cohortId: string; participantDid: string; approved: boolean }];
 
   /** Signing has started — auth requests sent to participants. */
-  'signing-started': [{ sessionId: string }];
+  'signing-started': [{ cohortId: string; sessionId: string }];
 
   /** A participant has contributed their MuSig2 nonce. */
-  'nonce-received': [{ participantDid: string }];
+  'nonce-received': [{ cohortId: string; participantDid: string }];
 
   /** Signing complete — final aggregated signature is ready to broadcast. */
   'signing-complete': [AggregationResult];
@@ -83,15 +100,7 @@ export type AggregationParticipantEvents = {
    * 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; reason: string }];