@did-btcr2/method 0.27.0 → 0.29.0

package/src/core/aggregation/cohort.ts

@@ -2,9 +2,10 @@ import { canonicalHash, canonicalize, hash } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import type { SerializedSMTProof, TreeEntry } from '@did-btcr2/smt';
 import { BTCR2MerkleTree } from '@did-btcr2/smt';
+import { schnorr } from '@noble/curves/secp256k1.js';
 import { hexToBytes, randomBytes } from '@noble/hashes/utils';
+import { p2tr } from '@scure/btc-signer';
 import { keyAggExport, keyAggregate, sortKeys } from '@scure/btc-signer/musig2';
-import { crypto as btcCrypto, payments } from 'bitcoinjs-lib';
 import type { CASAnnouncement } from '../types.js';
 import { AggregationCohortError } from './errors.js';
 
@@ -48,11 +49,23 @@ export class AggregationCohort {
   /** List of participant DIDs that have been accepted into the cohort. */
   participants: Array<string> = [];
 
+  /**
+   * Mapping from participant DID → their compressed secp256k1 public key.
+   * Distinct from {@link cohortKeys} (which is sorted per BIP-327) — this lets
+   * callers look up a participant's key without knowing their position in the
+   * sorted array. Populated by the service at `acceptParticipant` time.
+   */
+  participantKeys: Map<string, Uint8Array> = new Map();
+
   /** Sorted list of cohort participants' compressed public keys. */
   #cohortKeys: Array<Uint8Array> = [];
 
-  /** Taproot tweak (BIP-341 key-path-only). */
-  trMerkleRoot: Uint8Array = new Uint8Array();
+  /**
+   * BIP-341 TapTweak — `taggedHash("TapTweak", internalPubkey)` for a key-path-only
+   * Taproot output. Despite prior naming, this is NOT a Merkle root: key-path-only
+   * spends have no script tree.
+   */
+  tapTweak: Uint8Array = new Uint8Array();
 
   /** The n-of-n MuSig2 Taproot beacon address. */
   beaconAddress: string = '';
@@ -94,7 +107,7 @@ export class AggregationCohort {
 
   /**
    * Computes the n-of-n MuSig2 Taproot beacon address from cohort keys.
-   * Sets `trMerkleRoot` to the BIP-341 key-path-only tweak.
+   * Sets `tapTweak` to the BIP-341 key-path-only tweak.
    */
   public computeBeaconAddress(): string {
     if(this.#cohortKeys.length === 0) {
@@ -105,11 +118,11 @@ export class AggregationCohort {
     }
     const keyAggContext = keyAggregate(this.#cohortKeys);
     const aggPubkey = keyAggExport(keyAggContext);
-    const payment = payments.p2tr({ internalPubkey: aggPubkey });
+    const payment = p2tr(aggPubkey);
 
-    // BIP-341: key-path-only P2TR has no script tree, so payment.hash is null.
-    // Compute the tweak: taggedHash("TapTweak", internalPubkey).
-    this.trMerkleRoot = payment.hash ?? btcCrypto.taggedHash('TapTweak', aggPubkey);
+    // BIP-341: key-path-only P2TR has no script tree. Compute the tweak:
+    // taggedHash("TapTweak", internalPubkey).
+    this.tapTweak = schnorr.utils.taggedHash('TapTweak', aggPubkey);
 
     if(!payment.address) {
       throw new AggregationCohortError(
@@ -147,6 +160,19 @@ export class AggregationCohort {
     }
   }
 
+  /**
+   * Returns the position of a participant's public key in the sorted
+   * {@link cohortKeys} array, or -1 if the participant is not in the cohort.
+   * Required by MuSig2 partial-sig verification which indexes by signer position.
+   */
+  public indexOfParticipant(did: string): number {
+    const pk = this.participantKeys.get(did);
+    if(!pk) return -1;
+    return this.#cohortKeys.findIndex(k =>
+      k.length === pk.length && k.every((b, i) => b === pk[i])
+    );
+  }
+
   public addUpdate(participantDid: string, signedUpdate: SignedBTCR2Update): void {
     if(!this.participants.includes(participantDid)) {
       throw new AggregationCohortError(

package/src/core/aggregation/logger.ts

@@ -0,0 +1,33 @@
+/**
+ * Minimal injectable logger for the aggregation subsystem.
+ *
+ * Each runner and transport adapter accepts a `Logger` option; the default is
+ * {@link CONSOLE_LOGGER}, which forwards to `console.*`. Pass
+ * {@link SILENT_LOGGER} to suppress output (useful for tests) or a custom
+ * implementation to route logs to pino, winston, Sentry, etc.
+ *
+ * The interface is intentionally small — we don't want production code taking
+ * a hard dependency on any specific logger library.
+ */
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+/** Console-backed logger. Default for runners and transports. */
+export const CONSOLE_LOGGER: Logger = {
+  debug : (msg, ...args) => console.debug(msg, ...args),
+  info  : (msg, ...args) => console.info(msg, ...args),
+  warn  : (msg, ...args) => console.warn(msg, ...args),
+  error : (msg, ...args) => console.error(msg, ...args),
+};
+
+/** No-op logger. Useful for tests and production environments with own logging pipeline. */
+export const SILENT_LOGGER: Logger = {
+  debug : () => {},
+  info  : () => {},
+  warn  : () => {},
+  error : () => {},
+};

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

@@ -1,3 +1,12 @@
+/**
+ * Current on-the-wire protocol version.
+ *
+ * Receivers reject messages with an unknown (mismatched) version. Bumping this
+ * requires coordinated updates across all participants and any intermediate
+ * relays that inspect message content.
+ */
+export const AGGREGATION_WIRE_VERSION = 1;
+
 export type BaseBody = {
   cohortId: string;
   cohortSize?: number;
@@ -10,6 +19,8 @@ export type BaseBody = {
   nonceContribution?: Uint8Array;
   partialSignature?: Uint8Array;
   pendingTx?: string;
+  /** Hex-encoded scriptPubKey of the UTXO being spent. Required for BIP-341 sighash. */
+  prevOutScriptHex?: string;
   prevOutValue?: string;
   communicationPk?: Uint8Array;
   beaconType?: string;
@@ -23,6 +34,7 @@ export type BaseBody = {
 
 export type Base = {
   type: string;
+  version?: number;
   to?: string;
   from: string;
   body?: BaseBody;
@@ -30,12 +42,14 @@ export type Base = {
 
 export class BaseMessage {
   public type: string;
+  public version: number;
   public to?: string;
   public from: string;
   public body?: BaseBody;
 
-  constructor({ type, to, from, body }: Base) {
+  constructor({ type, version, to, from, body }: Base) {
     this.type = type;
+    this.version = version ?? AGGREGATION_WIRE_VERSION;
     this.to = to;
     this.from = from;
     this.body = body;
@@ -47,10 +61,11 @@ export class BaseMessage {
    */
   public toJSON(): Base {
     return {
-      type : this.type,
-      to   : this.to,
-      from : this.from,
-      body : this.body
+      type    : this.type,
+      version : this.version,
+      to      : this.to,
+      from    : this.from,
+      body    : this.body
     };
   }
 }

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

@@ -0,0 +1,223 @@
+/**
+ * Per-message-type body interfaces and a discriminated {@link AggregationMessage}
+ * union.
+ *
+ * {@link BaseBody} remains the superset-of-all-fields body type used by the
+ * raw {@link BaseMessage} class (see `base.ts`). The narrow interfaces here
+ * describe what each specific message type is *required* to carry and are
+ * exposed alongside type guards for consumers who want compile-time narrowing.
+ *
+ * Guards validate both `type` and the presence of required body fields so they
+ * are safe to use on messages that have round-tripped through JSON / a relay.
+ */
+
+import type { SerializedSMTProof } from '@did-btcr2/smt';
+import type { BaseMessage } from './base.js';
+import {
+  AGGREGATED_NONCE,
+  AUTHORIZATION_REQUEST,
+  COHORT_ADVERT,
+  COHORT_OPT_IN,
+  COHORT_OPT_IN_ACCEPT,
+  COHORT_READY,
+  DISTRIBUTE_AGGREGATED_DATA,
+  NONCE_CONTRIBUTION,
+  SIGNATURE_AUTHORIZATION,
+  SUBMIT_UPDATE,
+  VALIDATION_ACK,
+} from './constants.js';
+
+// ── Cohort formation (Step 1) ─────────────────────────────────────────────
+
+export interface CohortAdvertBody {
+  cohortId: string;
+  cohortSize: number;
+  beaconType: string;
+  network: string;
+  communicationPk: Uint8Array;
+}
+
+export interface CohortOptInBody {
+  cohortId: string;
+  participantPk: Uint8Array;
+  communicationPk: Uint8Array;
+}
+
+export interface CohortOptInAcceptBody {
+  cohortId: string;
+}
+
+export interface CohortReadyBody {
+  cohortId: string;
+  beaconAddress: string;
+  cohortKeys: Array<Uint8Array>;
+}
+
+// ── Update / aggregation (Steps 2-3) ──────────────────────────────────────
+
+export interface SubmitUpdateBody {
+  cohortId: string;
+  signedUpdate: Record<string, unknown>;
+}
+
+export interface DistributeAggregatedDataBody {
+  cohortId: string;
+  beaconType: string;
+  signalBytesHex: string;
+  casAnnouncement?: Record<string, string>;
+  smtProof?: Record<string, unknown> | SerializedSMTProof;
+}
+
+export interface ValidationAckBody {
+  cohortId: string;
+  approved: boolean;
+}
+
+// ── Signing (Step 4) ──────────────────────────────────────────────────────
+
+export interface AuthorizationRequestBody {
+  cohortId: string;
+  sessionId: string;
+  pendingTx: string;
+  prevOutScriptHex: string;
+  prevOutValue: string;
+}
+
+export interface NonceContributionBody {
+  cohortId: string;
+  sessionId: string;
+  nonceContribution: Uint8Array;
+}
+
+export interface AggregatedNonceBody {
+  cohortId: string;
+  sessionId: string;
+  aggregatedNonce: Uint8Array;
+}
+
+export interface SignatureAuthorizationBody {
+  cohortId: string;
+  sessionId: string;
+  partialSignature: Uint8Array;
+}
+
+// ── Narrow message types (BaseMessage & { type, body }) ──────────────────
+
+export type CohortAdvertMessage = BaseMessage & { type: typeof COHORT_ADVERT; body: CohortAdvertBody };
+export type CohortOptInMessage = BaseMessage & { type: typeof COHORT_OPT_IN; body: CohortOptInBody };
+export type CohortOptInAcceptMessage = BaseMessage & { type: typeof COHORT_OPT_IN_ACCEPT; body: CohortOptInAcceptBody };
+export type CohortReadyMessage = BaseMessage & { type: typeof COHORT_READY; body: CohortReadyBody };
+export type SubmitUpdateMessage = BaseMessage & { type: typeof SUBMIT_UPDATE; body: SubmitUpdateBody };
+export type DistributeAggregatedDataMessage = BaseMessage & { type: typeof DISTRIBUTE_AGGREGATED_DATA; body: DistributeAggregatedDataBody };
+export type ValidationAckMessage = BaseMessage & { type: typeof VALIDATION_ACK; body: ValidationAckBody };
+export type AuthorizationRequestMessage = BaseMessage & { type: typeof AUTHORIZATION_REQUEST; body: AuthorizationRequestBody };
+export type NonceContributionMessage = BaseMessage & { type: typeof NONCE_CONTRIBUTION; body: NonceContributionBody };
+export type AggregatedNonceMessage = BaseMessage & { type: typeof AGGREGATED_NONCE; body: AggregatedNonceBody };
+export type SignatureAuthorizationMessage = BaseMessage & { type: typeof SIGNATURE_AUTHORIZATION; body: SignatureAuthorizationBody };
+
+/** Discriminated union of every well-formed aggregation message. */
+export type AggregationMessage =
+  | CohortAdvertMessage
+  | CohortOptInMessage
+  | CohortOptInAcceptMessage
+  | CohortReadyMessage
+  | SubmitUpdateMessage
+  | DistributeAggregatedDataMessage
+  | ValidationAckMessage
+  | AuthorizationRequestMessage
+  | NonceContributionMessage
+  | AggregatedNonceMessage
+  | SignatureAuthorizationMessage;
+
+// ── Type guards ───────────────────────────────────────────────────────────
+// Each guard validates `type` plus required body fields so it's safe to use
+// on messages that have round-tripped through JSON / a relay.
+
+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';
+const hasBool = (b: unknown, k: string): boolean =>
+  !!b && typeof (b as Record<string, unknown>)[k] === 'boolean';
+const hasBytes = (b: unknown, k: string): boolean =>
+  !!b && (b as Record<string, unknown>)[k] instanceof Uint8Array;
+const hasBytesArray = (b: unknown, k: string): boolean => {
+  const v = b ? (b as Record<string, unknown>)[k] : undefined;
+  return Array.isArray(v) && v.every(x => x instanceof Uint8Array);
+};
+
+export function isCohortAdvertMessage(m: BaseMessage): m is CohortAdvertMessage {
+  return m.type === COHORT_ADVERT
+    && hasStr(m.body, 'cohortId')
+    && hasNum(m.body, 'cohortSize')
+    && hasStr(m.body, 'beaconType')
+    && hasStr(m.body, 'network')
+    && hasBytes(m.body, 'communicationPk');
+}
+
+export function isCohortOptInMessage(m: BaseMessage): m is CohortOptInMessage {
+  return m.type === COHORT_OPT_IN
+    && hasStr(m.body, 'cohortId')
+    && hasBytes(m.body, 'participantPk')
+    && hasBytes(m.body, 'communicationPk');
+}
+
+export function isCohortOptInAcceptMessage(m: BaseMessage): m is CohortOptInAcceptMessage {
+  return m.type === COHORT_OPT_IN_ACCEPT && hasStr(m.body, 'cohortId');
+}
+
+export function isCohortReadyMessage(m: BaseMessage): m is CohortReadyMessage {
+  return m.type === COHORT_READY
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'beaconAddress')
+    && hasBytesArray(m.body, 'cohortKeys');
+}
+
+export function isSubmitUpdateMessage(m: BaseMessage): m is SubmitUpdateMessage {
+  return m.type === SUBMIT_UPDATE
+    && hasStr(m.body, 'cohortId')
+    && !!m.body && typeof (m.body as Record<string, unknown>).signedUpdate === 'object';
+}
+
+export function isDistributeAggregatedDataMessage(m: BaseMessage): m is DistributeAggregatedDataMessage {
+  return m.type === DISTRIBUTE_AGGREGATED_DATA
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'beaconType')
+    && hasStr(m.body, 'signalBytesHex');
+}
+
+export function isValidationAckMessage(m: BaseMessage): m is ValidationAckMessage {
+  return m.type === VALIDATION_ACK
+    && hasStr(m.body, 'cohortId')
+    && hasBool(m.body, 'approved');
+}
+
+export function isAuthorizationRequestMessage(m: BaseMessage): m is AuthorizationRequestMessage {
+  return m.type === AUTHORIZATION_REQUEST
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'sessionId')
+    && hasStr(m.body, 'pendingTx')
+    && hasStr(m.body, 'prevOutScriptHex')
+    && hasStr(m.body, 'prevOutValue');
+}
+
+export function isNonceContributionMessage(m: BaseMessage): m is NonceContributionMessage {
+  return m.type === NONCE_CONTRIBUTION
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'sessionId')
+    && hasBytes(m.body, 'nonceContribution');
+}
+
+export function isAggregatedNonceMessage(m: BaseMessage): m is AggregatedNonceMessage {
+  return m.type === AGGREGATED_NONCE
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'sessionId')
+    && hasBytes(m.body, 'aggregatedNonce');
+}
+
+export function isSignatureAuthorizationMessage(m: BaseMessage): m is SignatureAuthorizationMessage {
+  return m.type === SIGNATURE_AUTHORIZATION
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'sessionId')
+    && hasBytes(m.body, 'partialSignature');
+}

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

@@ -164,6 +164,7 @@ type AuthorizationRequestMessage = {
   cohortId: string;
   sessionId: string;
   pendingTx: string;
+  prevOutScriptHex: string;
   prevOutValue: string;
 };
 type NonceContributionMessage = {

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

@@ -1,4 +1,5 @@
 export * from './base.js';
+export * from './bodies.js';
 export * from './constants.js';
 export * from './factories.js';
 export * from './guards.js';

package/src/core/aggregation/participant.ts

@@ -1,13 +1,14 @@
-import { canonicalHash, canonicalize } from '@did-btcr2/common';
+import { canonicalHash } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import type { SchnorrKeyPair } from '@did-btcr2/keypair';
 import type { SerializedSMTProof} from '@did-btcr2/smt';
-import { blockHash, didToIndex, hashToHex, hexToHash, verifySerializedProof } from '@did-btcr2/smt';
-import { bytesToHex } from '@noble/hashes/utils';
-import { Transaction } from 'bitcoinjs-lib';
+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 { AggregationParticipantError } from './errors.js';
 import type { BaseMessage } from './messages/base.js';
+import { AGGREGATION_WIRE_VERSION } from './messages/base.js';
 import {
   AGGREGATED_NONCE,
   AUTHORIZATION_REQUEST,
@@ -61,6 +62,8 @@ export interface PendingSigningRequest {
   cohortId: string;
   sessionId: string;
   pendingTxHex: string;
+  /** Hex-encoded scriptPubKey of the UTXO being spent. Required for BIP-341 sighash. */
+  prevOutScriptHex: string;
   prevOutValue: string;
 }
 
@@ -110,6 +113,10 @@ export class AggregationParticipant {
    * outgoing messages — those come exclusively from action methods.
    */
   public receive(message: BaseMessage): void {
+    // Reject messages whose wire version doesn't match what this build speaks.
+    if(message.version === undefined || message.version !== AGGREGATION_WIRE_VERSION) {
+      return;
+    }
     const type = message.type;
     switch(type) {
       case COHORT_ADVERT:
@@ -291,46 +298,28 @@ export class AggregationParticipant {
     if(!state.submittedUpdate) return;
 
     const beaconType = message.body?.beaconType;
+    if(!beaconType) return;
+    const strategy = getBeaconStrategy(beaconType);
+    if(!strategy) return;
+
     const signalBytesHex = message.body?.signalBytesHex ?? '';
     const expectedHash = canonicalHash(state.submittedUpdate);
-    let matches = false;
-
-    if(beaconType === 'CASBeacon') {
-      const casAnnouncement = message.body?.casAnnouncement;
-      if(casAnnouncement) {
-        matches = casAnnouncement[this.did] === expectedHash;
-        state.validation = {
-          cohortId,
-          beaconType,
-          signalBytesHex,
-          casAnnouncement,
-          expectedHash,
-          matches,
-        };
-      }
-    } else if(beaconType === 'SMTBeacon') {
-      const smtProof = message.body?.smtProof as unknown as SerializedSMTProof | undefined;
-      if(smtProof?.updateId && smtProof?.nonce) {
-        // Verify updateId matches the canonicalized update hash
-        const canonicalBytes = new TextEncoder().encode(canonicalize(state.submittedUpdate));
-        const expectedUpdateId = hashToHex(blockHash(canonicalBytes));
-        if(smtProof.updateId === expectedUpdateId) {
-          // Verify Merkle inclusion
-          const index = didToIndex(this.did);
-          const candidateHash = blockHash(blockHash(hexToHash(smtProof.nonce)), hexToHash(smtProof.updateId));
-          matches = verifySerializedProof(smtProof, index, candidateHash);
-        }
-        state.validation = {
-          cohortId,
-          beaconType,
-          signalBytesHex,
-          smtProof,
-          expectedHash,
-          matches,
-        };
-      }
-    }
+    const result = strategy.validateParticipantView({
+      participantDid  : this.did,
+      submittedUpdate : state.submittedUpdate,
+      expectedHash,
+      body            : message.body!,
+    });
 
+    state.validation = {
+      cohortId,
+      beaconType,
+      signalBytesHex,
+      expectedHash,
+      matches         : result.matches,
+      casAnnouncement : result.casAnnouncement,
+      smtProof        : result.smtProof,
+    };
     state.phase = ParticipantCohortPhase.AwaitingValidation;
   }
 
@@ -395,13 +384,15 @@ export class AggregationParticipant {
 
     const sessionId = message.body?.sessionId;
     const pendingTxHex = message.body?.pendingTx;
+    const prevOutScriptHex = message.body?.prevOutScriptHex;
     const prevOutValue = message.body?.prevOutValue;
-    if(!sessionId || !pendingTxHex || !prevOutValue) return;
+    if(!sessionId || !pendingTxHex || !prevOutScriptHex || !prevOutValue) return;
 
     state.signingRequest = {
       cohortId,
       sessionId,
       pendingTxHex,
+      prevOutScriptHex,
       prevOutValue,
     };
     state.phase = ParticipantCohortPhase.AwaitingSigning;
@@ -425,11 +416,14 @@ export class AggregationParticipant {
       );
     }
 
-    const tx = Transaction.fromHex(state.signingRequest.pendingTxHex);
+    const tx = Transaction.fromRaw(hexToBytes(state.signingRequest.pendingTxHex));
 
-    // Derive UTXO metadata for Taproot sighash (BIP-341).
-    // The beacon TX's change output (index 0) uses the same Taproot address as the input.
-    const prevOutScripts = tx.outs.length > 0 ? [tx.outs[0].script] : [];
+    // Derive UTXO metadata for Taproot sighash (BIP-341). Use the script
+    // supplied by the service in AUTHORIZATION_REQUEST rather than reading
+    // the change output: input and change may use different scripts in future
+    // beacon designs, and the prevOutScript must be the UTXO script, not the
+    // change script.
+    const prevOutScripts = [hexToBytes(state.signingRequest.prevOutScriptHex)];
     const prevOutValues = [BigInt(state.signingRequest.prevOutValue)];
 
     const session = new BeaconSigningSession({

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

@@ -1,5 +1,6 @@
+import type { SerializedSMTProof } from '@did-btcr2/smt';
 import type { CohortAdvert, PendingSigningRequest, PendingValidation } from '../participant.js';
-import type { AggregationResult, PendingOptIn } from '../service.js';
+import type { AggregationResult, PendingOptIn, Rejection } from '../service.js';
 
 /**
  * AggregationServiceRunner events are emitted by the AggregationServiceRunner to signal important
@@ -22,6 +23,13 @@ export type AggregationServiceEvents = {
   /** A participant has submitted a signed update. */
   'update-received': [{ participantDid: string }];
 
+  /**
+   * An inbound message was silently dropped by the state machine (bad proof,
+   * oversized payload, wrong wire version, etc.). Fires for *any* rejection,
+   * not just SUBMIT_UPDATE.
+   */
+  'message-rejected': [Rejection & { cohortId: string }];
+
   /** Aggregated data has been distributed to all participants for validation. */
   'data-distributed': [{ cohortId: string }];
 
@@ -37,6 +45,9 @@ export type AggregationServiceEvents = {
   /** Signing complete — final aggregated signature is ready to broadcast. */
   'signing-complete': [AggregationResult];
 
+  /** Cohort transitioned to Failed phase (e.g. a participant rejected validation). */
+  'cohort-failed': [{ cohortId: string; reason: string }];
+
   /** A non-fatal error occurred. Fatal errors reject the run() promise. */
   'error': [Error];
 };
@@ -66,8 +77,21 @@ export type AggregationParticipantEvents = {
   /** Signing request has arrived. Fires before the sign approval callback. */
   'signing-requested': [PendingSigningRequest];
 
-  /** Cohort signing is complete from this participant's perspective. */
-  'cohort-complete': [{ cohortId: string; beaconAddress: string }];
+  /**
+   * Cohort signing is complete from this participant's perspective.
+   * Includes the aggregated sidecar data the participant needs to keep for
+   * 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 failed (rejected validation, signing error, etc.). */
   'cohort-failed': [{ cohortId: string; reason: string }];