@did-btcr2/method 0.36.0 → 0.37.0

package/src/core/aggregation/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/core/aggregation/logger.ts

@@ -6,7 +6,7 @@
  * {@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
+ * The interface is intentionally small: we don't want production code taking
  * a hard dependency on any specific logger library.
  */
 export interface Logger {

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

@@ -22,6 +22,12 @@ export type BaseBody = Partial<CohortConditions> & {
   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;

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

@@ -13,6 +13,8 @@
 
 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,
@@ -22,8 +24,11 @@ import {
   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';
@@ -59,6 +64,15 @@ export interface SubmitUpdateBody {
   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;
@@ -100,6 +114,33 @@ export interface SignatureAuthorizationBody {
   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 };
@@ -107,12 +148,15 @@ export type CohortOptInMessage = BaseMessage & { type: typeof COHORT_OPT_IN; bod
 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 =
@@ -121,12 +165,15 @@ export type AggregationMessage =
   | CohortOptInAcceptMessage
   | CohortReadyMessage
   | SubmitUpdateMessage
+  | SubmitNonIncludedMessage
   | DistributeAggregatedDataMessage
   | ValidationAckMessage
   | AuthorizationRequestMessage
   | NonceContributionMessage
   | AggregatedNonceMessage
-  | SignatureAuthorizationMessage;
+  | SignatureAuthorizationMessage
+  | FallbackAuthorizationRequestMessage
+  | FallbackSignatureMessage;
 
 // ── Type guards ───────────────────────────────────────────────────────────
 // Each guard validates `type` plus required body fields so it's safe to use
@@ -144,6 +191,16 @@ 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 =>
@@ -164,6 +221,20 @@ export function isCohortAdvertMessage(m: BaseMessage): m is CohortAdvertMessage
     && 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');
 }
 
@@ -191,6 +262,10 @@ export function isSubmitUpdateMessage(m: BaseMessage): m is SubmitUpdateMessage
     && !!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')
@@ -233,3 +308,21 @@ export function isSignatureAuthorizationMessage(m: BaseMessage): m is SignatureA
     && 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');
+}

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

@@ -7,6 +7,8 @@
  * - Step 3 (Aggregate & Validate): DISTRIBUTE_AGGREGATED_DATA, VALIDATION_ACK
  * - Step 4 (Sign & Broadcast): AUTHORIZATION_REQUEST, NONCE_CONTRIBUTION,
  *   AGGREGATED_NONCE, SIGNATURE_AUTHORIZATION
+ * - Step 4 fallback (k-of-n script path, ADR 042): FALLBACK_AUTHORIZATION_REQUEST,
+ *   FALLBACK_SIGNATURE
  */
 export const AGGREGATION_MESSAGE_PREFIX = 'https://btcr2.dev/aggregation';
 
@@ -18,6 +20,8 @@ export const COHORT_READY = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_ready`;
 
 // Step 2 + 3: Update Submission, Aggregation, Validation
 export const SUBMIT_UPDATE = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_update`;
+/** A member with no update this round declines explicitly (cooperative non-inclusion). */
+export const SUBMIT_NONINCLUDED = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_nonincluded`;
 export const DISTRIBUTE_AGGREGATED_DATA = `${AGGREGATION_MESSAGE_PREFIX}/update/distribute_aggregated_data`;
 export const VALIDATION_ACK = `${AGGREGATION_MESSAGE_PREFIX}/update/validation_ack`;
 
@@ -26,3 +30,11 @@ export const AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/authori
 export const NONCE_CONTRIBUTION = `${AGGREGATION_MESSAGE_PREFIX}/sign/nonce_contribution`;
 export const AGGREGATED_NONCE = `${AGGREGATION_MESSAGE_PREFIX}/sign/aggregated_nonce`;
 export const SIGNATURE_AUTHORIZATION = `${AGGREGATION_MESSAGE_PREFIX}/sign/signature_authorization`;
+
+// Step 4 fallback: k-of-n script-path signing when the optimistic n-of-n key
+// path stalls (graceful liveness, ADR 042). A single standalone BIP-340
+// signature per member, no nonce round.
+/** Service asks members to sign the fallback (k-of-n) script path of the beacon tx. */
+export const FALLBACK_AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_authorization_request`;
+/** A member returns a standalone BIP-340 signature over the fallback script-path sighash. */
+export const FALLBACK_SIGNATURE = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_signature`;

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

@@ -8,8 +8,11 @@ import {
   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';
@@ -102,6 +105,22 @@ export function createSubmitUpdateMessage(fields: SubmitUpdateMessage): BaseMess
   return new BaseMessage({ type: SUBMIT_UPDATE, from, to, body });
 }
 
+type SubmitNonIncludedMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+};
+
+/**
+ * Factory for a Submit Non-Included message: a member declares it has no update
+ * this round (cooperative non-inclusion). Membership is proven by the signed
+ * envelope, so the body carries only the cohortId.
+ */
+export function createSubmitNonIncludedMessage(fields: SubmitNonIncludedMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: SUBMIT_NONINCLUDED, from, to, body });
+}
+
 /**
  * Step 3: Aggregate & Validate
  * Factory functions for creating messages related to the aggregate and validate step, where
@@ -238,3 +257,41 @@ export function createSignatureAuthorizationMessage(fields: SignatureAuthorizati
   const { from, to, ...body } = fields;
   return new BaseMessage({ type: SIGNATURE_AUTHORIZATION, from, to, body });
 }
+
+type FallbackAuthorizationRequestMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  sessionId: string;
+  pendingTx: string;
+  prevOutScriptHex: string;
+  prevOutValue: string;
+  fallbackLeafScriptHex: string;
+};
+type FallbackSignatureMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  sessionId: string;
+  signerPk: Uint8Array;
+  fallbackSignature: Uint8Array;
+};
+
+/**
+ * Factory for a Fallback Authorization Request: the service asks members to
+ * authorize the k-of-n script-path spend of the beacon transaction when the
+ * optimistic n-of-n key path stalls (ADR 042).
+ */
+export function createFallbackAuthorizationRequestMessage(fields: FallbackAuthorizationRequestMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_AUTHORIZATION_REQUEST, from, to, body });
+}
+
+/**
+ * Factory for a Fallback Signature: a member's standalone BIP-340 signature over
+ * the fallback script-path sighash (no nonce round).
+ */
+export function createFallbackSignatureMessage(fields: FallbackSignatureMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_SIGNATURE, from, to, body });
+}

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

@@ -6,8 +6,11 @@ import {
   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';
@@ -21,6 +24,7 @@ const KEYGEN_VALUES: Set<string> = new Set([
 
 const UPDATE_VALUES: Set<string> = new Set([
   SUBMIT_UPDATE,
+  SUBMIT_NONINCLUDED,
   DISTRIBUTE_AGGREGATED_DATA,
   VALIDATION_ACK,
 ]);
@@ -30,6 +34,8 @@ const SIGN_VALUES: Set<string> = new Set([
   NONCE_CONTRIBUTION,
   AGGREGATED_NONCE,
   SIGNATURE_AUTHORIZATION,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE,
 ]);
 
 /**