@did-btcr2/method 0.36.1 → 0.37.0

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,
 ]);
 
 /**