@did-btcr2/aggregation 0.1.0

package/src/messages/constants.ts

@@ -0,0 +1,40 @@
+/**
+ * Message type URLs for the did:btcr2 Aggregate Beacon protocol.
+ *
+ * Naming follows the spec (https://dcdpr.github.io/did-btcr2/beacons/aggregate-beacons.html):
+ * - Step 1 (Cohort Formation): COHORT_ADVERT, COHORT_OPT_IN, COHORT_OPT_IN_ACCEPT, COHORT_READY
+ * - Step 2 (Update Submission): SUBMIT_UPDATE
+ * - 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';
+
+// Step 1: Cohort Formation
+export const COHORT_ADVERT = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_advert`;
+export const COHORT_OPT_IN = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in`;
+export const COHORT_OPT_IN_ACCEPT = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in_accept`;
+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`;
+
+// Step 4: Signing
+export const AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/authorization_request`;
+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/messages/factories.ts

@@ -0,0 +1,297 @@
+import type { CohortConditions } from '../conditions.js';
+import { 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';
+
+/**
+ * Step 1: Cohort Formation
+ * 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 = CohortConditions & {
+  from: string;
+  cohortId: string;
+  network: string;
+  communicationPk: Uint8Array;
+};
+type CohortOptInMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  participantPk: Uint8Array;
+  communicationPk: Uint8Array;
+};
+type CohortOptInAcceptMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+};
+type CohortReadyMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  beaconAddress: string;
+  cohortKeys: Array<Uint8Array>;
+};
+
+/**
+ * Factory function for creating a Cohort Advert message, which is used to announce the formation of
+ * a new cohort and invite participants to join.
+ * @param {CohortAdvertMessage} fields - The fields required to create a Cohort Advert message.
+ * @returns {BaseMessage} The created Cohort Advert message.
+ */
+export function createCohortAdvertMessage(fields: CohortAdvertMessage): BaseMessage {
+  const { from, ...body } = fields;
+  return new BaseMessage({ type: COHORT_ADVERT, from, body });
+}
+
+/**
+ * Factory function for creating a Cohort Opt-In message, which is sent by a participant to express
+ * interest in joining a cohort.
+ * @param {CohortOptInMessage} fields - The fields required to create a Cohort Opt-In message, which
+ * is sent by a participant to express interest in joining a cohort.
+ * @returns {BaseMessage} The created Cohort Opt-In message.
+ */
+export function createCohortOptInMessage(fields: CohortOptInMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: COHORT_OPT_IN, from, to, body });
+}
+
+export function createCohortOptInAcceptMessage(fields: CohortOptInAcceptMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: COHORT_OPT_IN_ACCEPT, from, to, body });
+}
+
+export function createCohortReadyMessage(fields: CohortReadyMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: COHORT_READY, from, to, body });
+}
+
+/**
+ * Step 2: Update Submission
+ * Factory functions for creating messages related to the update submission step, where participants
+ * submit their signed updates for aggregation.
+ */
+type SubmitUpdateMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  signedUpdate: Record<string, unknown>;
+};
+
+/**
+ * Factory function for creating a Submit Update message, which is sent by a participant to submit
+ * their signed update for aggregation.
+ * @param {SubmitUpdateMessage} fields - The fields required to create a Submit Update message,
+ * which is sent by a participant to submit their signed update for aggregation.
+ * @returns {BaseMessage} The created Submit Update message.
+ */
+export function createSubmitUpdateMessage(fields: SubmitUpdateMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  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
+ * participants aggregate their updates and validate the aggregated data.
+ */
+
+type DistributeAggregatedDataMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  beaconType: string;
+  signalBytesHex: string;
+  casAnnouncement?: Record<string, string>;
+  smtProof?: Record<string, unknown>;
+};
+type ValidationAckMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  approved: boolean;
+};
+
+/**
+ * Factory function for creating a Distribute Aggregated Data message, which is sent by the
+ * aggregator to distribute the aggregated data to participants for validation.
+ * @param {DistributeAggregatedDataMessage} fields - The fields required to create a Distribute
+ * Aggregated Data message, which is sent by the aggregator to distribute the aggregated data to
+ * participants for validation.
+ * @returns {BaseMessage} The created Distribute Aggregated Data message.
+ */
+export function createDistributeAggregatedDataMessage(
+  fields: DistributeAggregatedDataMessage
+): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: DISTRIBUTE_AGGREGATED_DATA, from, to, body });
+}
+
+/**
+ * Factory function for creating a Validation Acknowledgment message, which is sent by a participant
+ * to acknowledge.
+ * @param {ValidationAckMessage} fields - The fields required to create a Validation Acknowledgment
+ * message, which is sent by a participant to acknowledge the validation of the aggregated data.
+ * @returns {BaseMessage} The created Validation Acknowledgment message.
+ */
+export function createValidationAckMessage(fields: ValidationAckMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: VALIDATION_ACK, from, to, body });
+}
+
+/**
+ * Step 4: Signing
+ * Factory functions for creating messages related to the signing step, where participants request
+ * signatures, contribute nonces, and authorize signatures.
+ */
+
+type AuthorizationRequestMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  sessionId: string;
+  pendingTx: string;
+  prevOutScriptHex: string;
+  prevOutValue: string;
+};
+type NonceContributionMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  sessionId: string;
+  nonceContribution: Uint8Array;
+};
+type AggregatedNonceMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  sessionId: string;
+  aggregatedNonce: Uint8Array;
+};
+type SignatureAuthorizationMessage = {
+  from: string;
+  to: string;
+  cohortId: string;
+  sessionId: string;
+  partialSignature: Uint8Array;
+};
+
+/**
+ * Factory function for creating an Authorization Request message, which is sent by a participant to
+ * request authorization for their signature.
+ * @param {AuthorizationRequestMessage} fields - The fields required to create an Authorization
+ * Request message, which is sent by a participant to request authorization for their signature.
+ * @returns {BaseMessage} The created Authorization Request message.
+ */
+export function createAuthorizationRequestMessage(fields: AuthorizationRequestMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: AUTHORIZATION_REQUEST, from, to, body });
+}
+
+/**
+ * Factory function for creating a Nonce Contribution message, which is sent by a participant to
+ * contribute their nonce for the signature aggregation process.
+ * @param {NonceContributionMessage} fields - The fields required to create a Nonce Contribution
+ * message, which is sent by a participant to contribute their nonce for the signature aggregation
+ * process.
+ * @returns {BaseMessage} The created Nonce Contribution message.
+ */
+export function createNonceContributionMessage(fields: NonceContributionMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: NONCE_CONTRIBUTION, from, to, body });
+}
+
+/**
+ * Factory function for creating an Aggregated Nonce message, which is sent by the aggregator to
+ * distribute the aggregated nonce to participants for the signature aggregation process.
+ * @param {AggregatedNonceMessage} fields - The fields required to create an Aggregated Nonce
+ * message, which is sent by the aggregator to distribute the aggregated nonce to participants for
+ * the signature aggregation process.
+ * @returns {BaseMessage} The created Aggregated Nonce message.
+ */
+export function createAggregatedNonceMessage(fields: AggregatedNonceMessage): BaseMessage {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: AGGREGATED_NONCE, from, to, body });
+}
+
+/**
+ * Factory function for creating a Signature Authorization message, which is sent by a participant
+ * to authorize their partial signature for the signature aggregation process.
+ * @param {SignatureAuthorizationMessage} fields - The fields required to create a Signature
+ * Authorization message, which is sent by a participant to authorize their partial signature for
+ * the signature aggregation process.
+ * @returns {BaseMessage} The created Signature Authorization message.
+ */
+export function createSignatureAuthorizationMessage(fields: SignatureAuthorizationMessage): BaseMessage {
+  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/messages/guards.ts

@@ -0,0 +1,61 @@
+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';
+
+const KEYGEN_VALUES: Set<string> = new Set([
+  COHORT_ADVERT,
+  COHORT_OPT_IN,
+  COHORT_OPT_IN_ACCEPT,
+  COHORT_READY,
+]);
+
+const UPDATE_VALUES: Set<string> = new Set([
+  SUBMIT_UPDATE,
+  SUBMIT_NONINCLUDED,
+  DISTRIBUTE_AGGREGATED_DATA,
+  VALIDATION_ACK,
+]);
+
+const SIGN_VALUES: Set<string> = new Set([
+  AUTHORIZATION_REQUEST,
+  NONCE_CONTRIBUTION,
+  AGGREGATED_NONCE,
+  SIGNATURE_AUTHORIZATION,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE,
+]);
+
+/**
+ * Checks if the provided type is a valid aggregation message type.
+ */
+export function isAggregationMessageType(type: string): boolean {
+  return KEYGEN_VALUES.has(type) || UPDATE_VALUES.has(type) || SIGN_VALUES.has(type);
+}
+
+/** Checks if the message type belongs to the keygen phase. */
+export function isKeygenMessageType(type: string): boolean {
+  return KEYGEN_VALUES.has(type);
+}
+
+/** Checks if the message type belongs to the update phase. */
+export function isUpdateMessageType(type: string): boolean {
+  return UPDATE_VALUES.has(type);
+}
+
+/** Checks if the message type belongs to the signing phase. */
+export function isSignMessageType(type: string): boolean {
+  return SIGN_VALUES.has(type);
+}

package/src/messages/index.ts

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