@did-btcr2/method 0.35.0 → 0.36.0

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,
     });

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

@@ -383,6 +383,15 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
       const decision = await this.#onOptInReceived(optIn);
       if(!decision.accepted) return;
 
+      // Don't accept past the advertised maxParticipants: acceptParticipant
+      // would throw COHORT_FULL and fail the run. Silently ignore the surplus
+      // opt-in (the cohort is full).
+      const maxParticipants = this.#config.maxParticipants;
+      const cohortNow = this.session.getCohort(this.#cohortId!);
+      if(maxParticipants !== undefined && cohortNow && cohortNow.participants.length >= maxParticipants) {
+        return;
+      }
+
       await this.#sendAll(this.session.acceptParticipant(this.#cohortId!, msg.from));
       this.emit('participant-accepted', { participantDid: msg.from });
 

package/src/core/aggregation/service.ts

@@ -6,6 +6,7 @@ import { bytesToHex } from '@noble/hashes/utils';
 import type { Transaction } from '@scure/btc-signer';
 import { getBeaconStrategy } from './beacon-strategy.js';
 import { AggregationCohort } from './cohort.js';
+import { validateCohortConditions, type CohortConditions } from './conditions.js';
 import { AggregationServiceError } from './errors.js';
 import type { BaseMessage } from './messages/base.js';
 import { AGGREGATION_WIRE_VERSION } from './messages/base.js';
@@ -28,11 +29,14 @@ import type { ServiceCohortPhaseType } from './phases.js';
 import { ServiceCohortPhase } from './phases.js';
 import { BeaconSigningSession } from './signing-session.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. */
@@ -201,6 +205,14 @@ export class AggregationService {
    * Cohort starts in `Created` phase — call `advertise()` to broadcast.
    */
   createCohort(config: CohortConfig): string {
+    // Fail fast on invalid conditions rather than discovering them at finalize.
+    const problems = validateCohortConditions(config);
+    if(problems.length > 0) {
+      throw new AggregationServiceError(
+        `Invalid cohort conditions: ${problems.join('; ')}`,
+        'INVALID_COHORT_CONDITIONS', { problems }
+      );
+    }
     const cohort = new AggregationCohort({
       serviceDid      : this.did,
       minParticipants : config.minParticipants,
@@ -234,13 +246,15 @@ export class AggregationService {
       );
     }
 
+    // Advertise the full condition set (flat fields, per ADR 039). network is
+    // a separate cohort parameter; everything else in config is a condition.
+    const { network, ...conditions } = state.config;
     const message = createCohortAdvertMessage({
       from            : this.did,
       cohortId,
-      cohortSize      : state.config.minParticipants,
-      beaconType      : state.config.beaconType,
-      network         : state.config.network,
+      network,
       communicationPk : this.publicKey.compressed,
+      ...conditions,
     });
 
     state.phase = ServiceCohortPhase.Advertised;
@@ -310,6 +324,15 @@ export class AggregationService {
         'ALREADY_ACCEPTED', { cohortId, participantDid }
       );
     }
+    // Enforce the maxParticipants condition: a cohort cannot grow past its
+    // advertised ceiling (closes the unbounded-growth path; see ADR 039).
+    const maxParticipants = state.config.maxParticipants;
+    if(maxParticipants !== undefined && state.acceptedParticipants.size >= maxParticipants) {
+      throw new AggregationServiceError(
+        `Cohort ${cohortId} is full: ${maxParticipants} participants already accepted.`,
+        'COHORT_FULL', { cohortId, maxParticipants }
+      );
+    }
 
     state.acceptedParticipants.add(participantDid);
     state.cohort.participants.push(participantDid);
@@ -344,6 +367,15 @@ export class AggregationService {
         'NOT_ENOUGH_PARTICIPANTS', { cohortId }
       );
     }
+    // Ceiling defense: acceptParticipant already rejects past max, so reaching
+    // here over max means state was mutated out-of-band.
+    const maxParticipants = state.config.maxParticipants;
+    if(maxParticipants !== undefined && state.acceptedParticipants.size > maxParticipants) {
+      throw new AggregationServiceError(
+        `Cohort ${cohortId} has ${state.acceptedParticipants.size} accepted participants, exceeds max ${maxParticipants}.`,
+        'TOO_MANY_PARTICIPANTS', { cohortId, maxParticipants }
+      );
+    }
 
     const beaconAddress = state.cohort.computeBeaconAddress();
     state.phase = ServiceCohortPhase.CohortSet;

package/src/index.ts

@@ -2,6 +2,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';