@did-btcr2/aggregation 0.1.0

package/src/fallback-spend.ts

@@ -0,0 +1,223 @@
+/**
+ * Fallback spend builder for aggregate beacon outputs.
+ *
+ * An aggregate beacon UTXO is a Taproot output whose key path is the cohort's
+ * n-of-n MuSig2 aggregate key and whose script path carries a k-of-n fallback
+ * leaf (`p2tr_ms` CHECKSIGADD) plus a CSV recovery leaf (see
+ * {@link ./recovery-policy.ts} and ADR 042). When the optimistic n-of-n key path
+ * stalls (a missing or defecting signer), the cohort can still push the SAME
+ * announcement transaction through the fallback leaf with any k members'
+ * signatures, instead of abandoning the round or waiting out the recovery
+ * timelock.
+ *
+ * Unlike the MuSig2 key path, the fallback is a plain k-of-n script-path spend:
+ * each signer produces a standalone BIP-340 signature over the script-path
+ * sighash (no nonce round), and the coordinator assembles k of them into the
+ * witness. The coordinator never holds a participant secret - it injects the
+ * collected signatures and finalizes.
+ *
+ * This module is pure with respect to the network: it takes the beacon
+ * transaction, the cohort and recovery parameters, the spent output, and the
+ * collected signatures, and returns a finalized {@link Transaction}.
+ * Broadcasting is the caller's concern.
+ */
+
+import { getNetwork } from '@did-btcr2/bitcoin';
+import { schnorr } from '@noble/curves/secp256k1.js';
+import type { Transaction} from '@scure/btc-signer';
+import { SigHash, p2tr } from '@scure/btc-signer';
+import { keyAggExport, keyAggregate, sortKeys } from '@scure/btc-signer/musig2';
+import { AggregationCohortError } from './errors.js';
+import type { FundingModel } from './recovery-policy.js';
+import {
+  DEFAULT_FUNDING_MODEL,
+  TAPROOT_LEAF_VERSION,
+  buildFallbackLeaf,
+  buildRecoveryLeaves,
+  resolveFallbackThreshold,
+  tapLeafHash,
+} from './recovery-policy.js';
+
+/** A single member's standalone signature over the fallback script-path sighash. */
+export interface FallbackSignature {
+  /** Signer's x-only public key (32 bytes). Must be one of the cohort's keys. */
+  pubKey: Uint8Array;
+  /** 64-byte BIP-340 Schnorr signature over the script-path sighash. */
+  signature: Uint8Array;
+}
+
+/** Inputs to {@link buildFallbackSpend}. */
+export interface FallbackSpendParams {
+  /**
+   * The beacon announcement transaction to finalize. Input {@link inputIndex}
+   * spends the beacon UTXO; its key-path witness must not be set (the fallback
+   * assembles a script-path witness instead).
+   */
+  pendingTx: Transaction;
+  /** Index of the beacon input within {@link pendingTx}. Defaults to 0. */
+  inputIndex?: number;
+  /**
+   * The cohort's participant public keys (compressed secp256k1, 33 bytes).
+   * Sorted internally per BIP-327 so the reconstructed tree matches the funded
+   * output.
+   */
+  cohortKeys: Uint8Array[];
+  /**
+   * The advertised k of the k-of-n fallback leaf, or omit for the cohort's n-1
+   * default. Resolved against `cohortKeys.length` exactly as the cohort does.
+   */
+  fallbackThreshold?: number;
+  /** Operator recovery key, x-only (32 bytes). Needed to reconstruct the script tree. */
+  recoveryKey: Uint8Array;
+  /** Relative-timelock (BIP-68) the recovery leaf enforces. Needed to reconstruct the script tree. */
+  recoverySequence: number;
+  /** Funding model governing the leaves. Defaults to 'operator-funded'. */
+  fundingModel?: FundingModel;
+  /** Bitcoin network name (bitcoin/mainnet, mutinynet, signet, testnet, regtest). */
+  network: string;
+  /** scriptPubKey of the beacon UTXO being spent. Must equal the reconstructed tree output script. */
+  prevOutScript: Uint8Array;
+  /** Value of the beacon UTXO in satoshis. */
+  prevOutValue: bigint;
+  /**
+   * Standalone signatures collected from cohort members. At least
+   * {@link fallbackThreshold} valid, distinct-by-key signatures are required;
+   * exactly k are injected (a k-of-n CHECKSIGADD leaf demands exactly k).
+   */
+  signatures: FallbackSignature[];
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+
+/**
+ * Compute the BIP-341 script-path sighash a cohort member must sign to authorize
+ * the fallback spend. The leaf is the k-of-n fallback leaf; signers produce a
+ * standalone BIP-340 signature over this digest with SIGHASH_DEFAULT.
+ */
+export function fallbackSighash(
+  tx: Transaction,
+  inputIndex: number,
+  prevOutScript: Uint8Array,
+  prevOutValue: bigint,
+  fallbackLeafScript: Uint8Array,
+): Uint8Array {
+  return tx.preimageWitnessV1(
+    inputIndex,
+    [ prevOutScript ],
+    SigHash.DEFAULT,
+    [ prevOutValue ],
+    undefined,
+    fallbackLeafScript,
+    TAPROOT_LEAF_VERSION,
+  );
+}
+
+/**
+ * Assemble and finalize a k-of-n fallback spend of an aggregate beacon UTXO.
+ *
+ * Reconstructs the funded Taproot output (MuSig2 internal key + fallback/recovery
+ * script tree), verifies each collected signature against the script-path
+ * sighash and a cohort key, injects exactly k distinct valid signatures into the
+ * fallback leaf, and finalizes the witness. The returned transaction is the same
+ * announcement the optimistic path would have produced, signed via the script
+ * path instead of the key path.
+ *
+ * @throws {AggregationCohortError} when there are no cohort keys, the spent
+ * script does not match the reconstructed tree output, or fewer than k valid
+ * distinct signatures were supplied.
+ */
+export function buildFallbackSpend(params: FallbackSpendParams): Transaction {
+  const {
+    pendingTx, cohortKeys, recoveryKey, recoverySequence,
+    fundingModel, network, prevOutScript, prevOutValue, signatures,
+  } = params;
+  const inputIndex = params.inputIndex ?? 0;
+
+  if(cohortKeys.length === 0) {
+    throw new AggregationCohortError(
+      'Cannot build fallback spend: no cohort keys.',
+      'NO_COHORT_KEYS'
+    );
+  }
+
+  // Resolve k the same way the cohort did, so the reconstructed leaf matches.
+  const fallbackThreshold = resolveFallbackThreshold(params.fallbackThreshold, cohortKeys.length);
+
+  // Reconstruct the funded output the same way the cohort derived its address.
+  const internalKey = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey, recoverySequence, cohortKeys, fallbackThreshold,
+  });
+  const net = getNetwork(network);
+  // allowUnknownOutputs: the CSV recovery leaf is a custom script (see cohort.ts).
+  const payment = p2tr(internalKey, leaves, net, true);
+
+  // The output we are spending must be the cohort's funded beacon output; if the
+  // reconstructed tree script differs, the witness would not match the chain.
+  if(!bytesEqual(payment.script, prevOutScript)) {
+    throw new AggregationCohortError(
+      'Reconstructed beacon output script does not match the spent prevout script.',
+      'PREVOUT_SCRIPT_MISMATCH'
+    );
+  }
+
+  const fallbackLeaf = buildFallbackLeaf({ cohortKeys, fallbackThreshold });
+  // Locate the fallback leaf's tapLeafScript entry: each entry is
+  // [controlBlock, script || leafVersion]; strip the trailing version byte to
+  // compare the script.
+  const leafEntry = payment.tapLeafScript?.find(([ , scriptVer ]) => {
+    const script = scriptVer.slice(0, scriptVer.length - 1);
+    return bytesEqual(script, fallbackLeaf);
+  });
+  if(!leafEntry) {
+    throw new AggregationCohortError(
+      'Could not locate the fallback leaf in the reconstructed beacon output.',
+      'FALLBACK_LEAF_NOT_FOUND'
+    );
+  }
+
+  // Validate the collected signatures against the script-path sighash. The leaf
+  // is keyed by x-only cohort keys, so a valid signature must verify against one
+  // of them. Keep only distinct, valid signatures (first occurrence per key).
+  const cohortXOnly = sortKeys(cohortKeys).map(k => k.slice(1));
+  const tx = pendingTx;
+  const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+
+  const leafHash = tapLeafHash(fallbackLeaf);
+  const accepted = new Map<string, Uint8Array>(); // x-only hex to signature
+  for(const { pubKey, signature } of signatures) {
+    if(pubKey.length !== 32 || signature.length !== 64) continue;
+    const isCohortKey = cohortXOnly.some(k => bytesEqual(k, pubKey));
+    if(!isCohortKey) continue;
+    const hex = Array.from(pubKey, b => b.toString(16).padStart(2, '0')).join('');
+    if(accepted.has(hex)) continue;
+    let ok = false;
+    try { ok = schnorr.verify(signature, sighash, pubKey); } catch { ok = false; }
+    if(ok) accepted.set(hex, signature);
+  }
+
+  if(accepted.size < fallbackThreshold) {
+    throw new AggregationCohortError(
+      `Not enough valid fallback signatures: have ${accepted.size}, need ${fallbackThreshold}.`,
+      'NOT_ENOUGH_FALLBACK_SIGNATURES', { have: accepted.size, need: fallbackThreshold }
+    );
+  }
+
+  // A k-of-n CHECKSIGADD leaf demands EXACTLY k satisfied signatures (the final
+  // <k> NUMEQUAL fails if the running count differs), so inject exactly k.
+  const chosen = cohortXOnly
+    .filter(k => accepted.has(Array.from(k, b => b.toString(16).padStart(2, '0')).join('')))
+    .slice(0, fallbackThreshold);
+
+  tx.updateInput(inputIndex, {
+    tapLeafScript : [ leafEntry ],
+    tapScriptSig  : chosen.map(pubKey => {
+      const hex = Array.from(pubKey, b => b.toString(16).padStart(2, '0')).join('');
+      return [ { pubKey, leafHash }, accepted.get(hex)! ];
+    }),
+  });
+  tx.finalize();
+  return tx;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// State machines + core data
+export * from './service.js';
+export * from './participant.js';
+export * from './signer.js';
+export * from './conditions.js';
+export * from './recovery-policy.js';
+export * from './recovery-spend.js';
+export * from './fallback-spend.js';
+export * from './cohort.js';
+export * from './signing-session.js';
+export * from './phases.js';
+export * from './errors.js';
+export * from './beacon-strategy.js';
+export * from './logger.js';
+
+// Messages
+export * from './messages/index.js';
+
+// Transport
+export * from './transport/index.js';
+
+// Runner facades
+export * from './runner/index.js';

package/src/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/messages/base.ts

@@ -0,0 +1,80 @@
+import type { CohortConditions } from '../conditions.js';
+
+/**
+ * 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;
+
+// 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;
+  network?: string;
+  participantPk?: Uint8Array;
+  beaconAddress?: string;
+  cohortKeys?: Array<Uint8Array>;
+  sessionId?: string;
+  aggregatedNonce?: Uint8Array;
+  nonceContribution?: Uint8Array;
+  partialSignature?: Uint8Array;
+  /** Fallback (k-of-n script-path) leaf script, hex. Carried on FALLBACK_AUTHORIZATION_REQUEST. */
+  fallbackLeafScriptHex?: string;
+  /** Signer's x-only key for a fallback signature (which CHECKSIGADD slot it satisfies). */
+  signerPk?: Uint8Array;
+  /** A member's standalone BIP-340 fallback script-path signature (64 bytes). */
+  fallbackSignature?: Uint8Array;
+  pendingTx?: string;
+  /** Hex-encoded scriptPubKey of the UTXO being spent. Required for BIP-341 sighash. */
+  prevOutScriptHex?: string;
+  prevOutValue?: string;
+  communicationPk?: Uint8Array;
+  data?: string;
+  signedUpdate?: Record<string, unknown>;
+  casAnnouncement?: Record<string, string>;
+  smtProof?: Record<string, unknown>;
+  signalBytesHex?: string;
+  approved?: boolean;
+};
+
+export type Base = {
+  type: string;
+  version?: number;
+  to?: string;
+  from: string;
+  body?: BaseBody;
+};
+
+export class BaseMessage {
+  public type: string;
+  public version: number;
+  public to?: string;
+  public from: string;
+  public body?: BaseBody;
+
+  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;
+  }
+
+  /**
+   * Converts a BaseMessage to a JSON object.
+   * @returns {Base} The JSON representation of the BaseMessage.
+   */
+  public toJSON(): Base {
+    return {
+      type    : this.type,
+      version : this.version,
+      to      : this.to,
+      from    : this.from,
+      body    : this.body
+    };
+  }
+}

package/src/messages/bodies.ts

@@ -0,0 +1,328 @@
+/**
+ * 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 { CohortConditions } from '../conditions.js';
+import { KNOWN_FUNDING_MODELS } from '../conditions.js';
+import { MAX_RECOVERY_SEQUENCE } from '../recovery-policy.js';
+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,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE,
+  NONCE_CONTRIBUTION,
+  SIGNATURE_AUTHORIZATION,
+  SUBMIT_NONINCLUDED,
+  SUBMIT_UPDATE,
+  VALIDATION_ACK,
+} from './constants.js';
+
+// ── Cohort formation (Step 1) ─────────────────────────────────────────────
+
+export interface CohortAdvertBody extends CohortConditions {
+  cohortId: 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>;
+}
+
+/**
+ * A member declines to submit an update this round (cooperative non-inclusion).
+ * Carries only the cohortId; membership is proven by the signed transport
+ * envelope (the sender DID), so no payload is needed.
+ */
+export interface SubmitNonIncludedBody {
+  cohortId: string;
+}
+
+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;
+}
+
+/**
+ * Service asks members to authorize the k-of-n fallback (script-path) spend of
+ * the SAME beacon transaction (ADR 042). Carries the unsigned tx and the spent
+ * output so each member recomputes the script-path sighash itself. The fallback
+ * leaf script is included for cross-check; members recompute it from their own
+ * cohort state.
+ */
+export interface FallbackAuthorizationRequestBody {
+  cohortId: string;
+  sessionId: string;
+  pendingTx: string;
+  prevOutScriptHex: string;
+  prevOutValue: string;
+  fallbackLeafScriptHex: string;
+}
+
+/**
+ * A member's standalone BIP-340 signature over the fallback script-path sighash.
+ * `signerPk` is the member's x-only key (which CHECKSIGADD slot it satisfies).
+ */
+export interface FallbackSignatureBody {
+  cohortId: string;
+  sessionId: string;
+  signerPk: Uint8Array;
+  fallbackSignature: 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 SubmitNonIncludedMessage = BaseMessage & { type: typeof SUBMIT_NONINCLUDED; body: SubmitNonIncludedBody };
+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 };
+export type FallbackAuthorizationRequestMessage = BaseMessage & { type: typeof FALLBACK_AUTHORIZATION_REQUEST; body: FallbackAuthorizationRequestBody };
+export type FallbackSignatureMessage = BaseMessage & { type: typeof FALLBACK_SIGNATURE; body: FallbackSignatureBody };
+
+/** Discriminated union of every well-formed aggregation message. */
+export type AggregationMessage =
+  | CohortAdvertMessage
+  | CohortOptInMessage
+  | CohortOptInAcceptMessage
+  | CohortReadyMessage
+  | SubmitUpdateMessage
+  | SubmitNonIncludedMessage
+  | DistributeAggregatedDataMessage
+  | ValidationAckMessage
+  | AuthorizationRequestMessage
+  | NonceContributionMessage
+  | AggregatedNonceMessage
+  | SignatureAuthorizationMessage
+  | FallbackAuthorizationRequestMessage
+  | FallbackSignatureMessage;
+
+// ── 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';
+/** 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);
+};
+/** Present, an integer, and within [min, max] inclusive. */
+const intInRange = (b: unknown, k: string, min: number, max: number): boolean => {
+  const v = b ? (b as Record<string, unknown>)[k] : undefined;
+  return typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
+};
+/** Absent, or present as a string in the allowed set. */
+const optStrOneOf = (b: unknown, k: string, allowed: readonly string[]): boolean => {
+  const v = b ? (b as Record<string, unknown>)[k] : undefined;
+  return v === undefined || (typeof v === 'string' && allowed.includes(v));
+};
+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 {
+  // 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')
+    && hasIntMin(m.body, 'minParticipants', 1)
+    && optIntMin(m.body, 'maxParticipants', 1)
+    && hasStr(m.body, 'beaconType')
+    && hasStr(m.body, 'network')
+    // Recovery params are mandatory: a participant must see the recovery terms
+    // (key + timelock) before funding the beacon UTXO (ADR 042). recoverySequence
+    // is range-checked here because the participant funds based on the advert and
+    // does not separately run validateCohortConditions: an out-of-range value
+    // (e.g. one with the BIP-68 disable bit set) must be rejected before funding.
+    && hasStr(m.body, 'recoveryKey')
+    && intInRange(m.body, 'recoverySequence', 1, MAX_RECOVERY_SEQUENCE)
+    // fundingModel is optional on the wire (absent means the operator-funded
+    // default), but when present it must name a known model.
+    && optStrOneOf(m.body, 'fundingModel', KNOWN_FUNDING_MODELS)
+    // fallbackThreshold is optional (absent means n-1 at keygen); when present it
+    // must be a positive integer. The upper bound against the cohort size is
+    // checked when the participant recomputes the beacon address.
+    && optIntMin(m.body, 'fallbackThreshold', 1)
+    && 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 isSubmitNonIncludedMessage(m: BaseMessage): m is SubmitNonIncludedMessage {
+  return m.type === SUBMIT_NONINCLUDED && hasStr(m.body, 'cohortId');
+}
+
+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');
+}
+
+export function isFallbackAuthorizationRequestMessage(m: BaseMessage): m is FallbackAuthorizationRequestMessage {
+  return m.type === FALLBACK_AUTHORIZATION_REQUEST
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'sessionId')
+    && hasStr(m.body, 'pendingTx')
+    && hasStr(m.body, 'prevOutScriptHex')
+    && hasStr(m.body, 'prevOutValue')
+    && hasStr(m.body, 'fallbackLeafScriptHex');
+}
+
+export function isFallbackSignatureMessage(m: BaseMessage): m is FallbackSignatureMessage {
+  return m.type === FALLBACK_SIGNATURE
+    && hasStr(m.body, 'cohortId')
+    && hasStr(m.body, 'sessionId')
+    && hasBytes(m.body, 'signerPk')
+    && hasBytes(m.body, 'fallbackSignature');
+}