@did-btcr2/aggregation 0.1.0

package/dist/types/cohort.d.ts

@@ -0,0 +1,188 @@
+import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SerializedSMTProof } from '@did-btcr2/smt';
+import type { FundingModel } from './recovery-policy.js';
+/**
+ * The CAS Beacon Announcement Map a cohort produces: a record of DID to update hash.
+ * Defined locally so the aggregation package does not depend on method; it is
+ * structurally compatible with method's resolution-side `CASAnnouncement` type, which
+ * the resolver consumes when reading the announcement off the content-addressed store.
+ */
+export type CASAnnouncementMap = Record<string, string>;
+export type AggregationCohortParams = {
+    id?: string;
+    serviceDid?: string;
+    minParticipants?: number;
+    network: string;
+    beaconType?: string;
+    /** Operator recovery key, x-only (32 bytes). Required to compute the beacon address. */
+    recoveryKey?: Uint8Array;
+    /** Relative-timelock (BIP-68 nSequence) before recovery is spendable. Required to compute the beacon address. */
+    recoverySequence?: number;
+    /** Funding model governing the recovery leaves. Defaults to 'operator-funded'. */
+    fundingModel?: FundingModel;
+    /** Advertised k of the k-of-n fallback leaf. Absent defaults to n-1 at address computation. */
+    fallbackThreshold?: number;
+};
+/**
+ * Represents an Aggregation Cohort: a set of Aggregation Participants who
+ * submitted cryptographic material to an Aggregation Service to coordinate
+ * signing of a shared n-of-n MuSig2 Bitcoin transaction.
+ *
+ * This is a pure data class: it holds cohort state and provides computation
+ * helpers (key aggregation, CAS Announcement building, SMT tree building).
+ * It performs no I/O and emits no messages. Both AggregationService and
+ * AggregationParticipant create their own AggregationCohort instances to
+ * track their respective views of the cohort state.
+ *
+ * @class AggregationCohort
+ */
+export declare class AggregationCohort {
+    #private;
+    /** Unique identifier for the cohort. */
+    id: string;
+    /** DID of the Aggregation Service managing this cohort. */
+    serviceDid: string;
+    /** Minimum number of participants required to finalize the cohort. */
+    minParticipants: number;
+    /** Network on which the cohort operates (mainnet, mutinynet, etc.). */
+    network: string;
+    /** Type of beacon used in the cohort: 'CASBeacon' or 'SMTBeacon'. */
+    beaconType: string;
+    /** List of participant DIDs that have been accepted into the cohort. */
+    participants: Array<string>;
+    /**
+     * Mapping from participant DID to 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>;
+    /**
+     * BIP-341 TapTweak scalar: `taggedHash("TapTweak", internalPubkey || tapMerkleRoot)`.
+     * The beacon output is an internal key (the MuSig2 aggregate) plus a script
+     * tree (the recovery leaves), so the tweak commits to the tree's Merkle root.
+     * The MuSig2 signing session applies this as an x-only tweak; a value that does
+     * not match the root the funded address was derived from silently yields an
+     * invalid key-path signature.
+     */
+    tapTweak: Uint8Array;
+    /** The n-of-n MuSig2 aggregate internal key, x-only (32 bytes), set by computeBeaconAddress(). */
+    internalKey: Uint8Array;
+    /** BIP-341 Taproot Merkle root of the recovery script tree, set by computeBeaconAddress(). */
+    tapMerkleRoot: Uint8Array;
+    /** Operator recovery key, x-only (32 bytes). Used to build the CSV recovery leaf. */
+    recoveryKey?: Uint8Array;
+    /** Relative-timelock (BIP-68 nSequence) before the recovery leaf is spendable. */
+    recoverySequence?: number;
+    /** Funding model governing the recovery leaves (default 'operator-funded'). */
+    fundingModel: FundingModel;
+    /**
+     * Advertised k of the k-of-n fallback leaf, or undefined to default to n-1 at
+     * address computation. Read the resolved value via {@link effectiveFallbackThreshold}.
+     */
+    fallbackThreshold?: number;
+    /** The Taproot beacon address: key path is the MuSig2 aggregate, script path is fallback + recovery. */
+    beaconAddress: string;
+    /** Pending DID updates submitted by participants, keyed by DID. */
+    pendingUpdates: Map<string, SignedBTCR2Update>;
+    /**
+     * Participant DIDs that explicitly declined to submit an update this round
+     * (cooperative non-inclusion). A decliner is absent from the CAS Announcement
+     * Map and carries a non-inclusion leaf in the SMT, yet still signs. Kept
+     * disjoint from {@link pendingUpdates} so CAS correctness holds by construction.
+     */
+    nonIncluded: Set<string>;
+    /** CAS Beacon Announcement Map (DID to updateHash), set by buildCASAnnouncement(). */
+    casAnnouncement?: CASAnnouncementMap;
+    /** Per-participant SMT proofs, set by buildSMTTree(). */
+    smtProofs?: Map<string, SerializedSMTProof>;
+    /** Signal bytes (32 bytes) for OP_RETURN: SHA-256 of CAS announcement OR SMT root. */
+    signalBytes?: Uint8Array;
+    /** Set of participant DIDs that have approved the aggregated data. */
+    validationAcks: Set<string>;
+    /** Set of participant DIDs that have rejected the aggregated data. */
+    validationRejections: Set<string>;
+    constructor({ id, minParticipants, serviceDid, network, beaconType, recoveryKey, recoverySequence, fundingModel, fallbackThreshold }: AggregationCohortParams);
+    /** Sorted cohort keys (sorted on assignment per BIP-327). */
+    get cohortKeys(): Array<Uint8Array>;
+    set cohortKeys(keys: Array<Uint8Array>);
+    /**
+     * The resolved k of the k-of-n fallback leaf: the advertised
+     * {@link fallbackThreshold}, or n-1 (floored at 1) when unadvertised, where n is
+     * the current cohort size. This is the value the beacon address commits to and
+     * the spend builders must reproduce. Returns 0 before any cohort keys are set.
+     */
+    get effectiveFallbackThreshold(): number;
+    /**
+     * Computes the Taproot beacon address from the cohort keys and recovery params.
+     *
+     * The output's key path is the n-of-n MuSig2 aggregate of the cohort keys; its
+     * script path is the recovery tree (a CSV recovery leaf so a missing signer
+     * cannot permanently lock the UTXO). Sets `internalKey`, `tapMerkleRoot`, and
+     * the `tapTweak` the MuSig2 session must apply for the key-path spend.
+     *
+     * The tweak is derived from the Merkle root the address was built with (read
+     * back from the payment), never recomputed by hand, so the MuSig2 key-path
+     * signature is guaranteed to validate against the funded address.
+     */
+    computeBeaconAddress(): string;
+    /**
+     * Validates that the participant's key is in the cohort and the beacon address
+     * matches the locally-computed one. Used by participants to verify cohort ready
+     * messages from the service.
+     */
+    validateMembership(participantPkHex: string, cohortKeysHex: Array<string>, expectedBeaconAddress: string): void;
+    /**
+     * 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.
+     */
+    indexOfParticipant(did: string): number;
+    addUpdate(participantDid: string, signedUpdate: SignedBTCR2Update): void;
+    /**
+     * Record that a participant declined to submit an update this round
+     * (cooperative non-inclusion). The member stays in the cohort and still signs.
+     */
+    addNonInclusion(participantDid: string): void;
+    hasAllUpdates(): boolean;
+    /**
+     * True when every participant has responded for this round, either with an
+     * update or with an explicit non-inclusion. This is the aggregation gate when
+     * non-inclusion is in play; it generalizes {@link hasAllUpdates} the same way
+     * {@link hasAllValidationResponses} generalizes a unanimous ack.
+     */
+    hasAllResponses(): boolean;
+    /**
+     * Builds a CAS Announcement Map from collected updates.
+     * Maps each participant DID to base64url canonical hash of their signed update.
+     * Computes signal bytes as SHA-256 of canonicalized announcement.
+     *
+     * Members who declined (cooperative non-inclusion) are naturally absent from
+     * the map: the body iterates {@link pendingUpdates}, which never holds a
+     * decliner. Absence from the map is exactly the CAS non-inclusion signal.
+     */
+    buildCASAnnouncement(): CASAnnouncementMap;
+    /**
+     * Builds an SMT tree with one leaf per participant.
+     *
+     * A member who submitted an update gets an inclusion leaf
+     * (SHA-256(SHA-256(nonce) || SHA-256(update))); a member who declined gets a
+     * non-inclusion leaf (SHA-256(SHA-256(nonce)), the `signedUpdate` entry field
+     * omitted). The cohort mints each member's nonce and returns it inside that
+     * member's serialized proof, so a decliner can self-validate its own
+     * non-inclusion slot and the resolver can recompute the leaf. Stores
+     * per-participant proofs and the SMT root as signalBytes.
+     */
+    buildSMTTree(): Map<string, SerializedSMTProof>;
+    addValidation(participantDid: string, approved: boolean): void;
+    /**
+     * True when every participant has either approved or rejected the aggregated data.
+     */
+    hasAllValidationResponses(): boolean;
+    /**
+     * True when all participants approved. Note: differs from {@link hasAllValidationResponses},
+     * this returns false if any participant rejected, even if all responses are in.
+     */
+    isFullyValidated(): boolean;
+}
+//# sourceMappingURL=cohort.d.ts.map

package/dist/types/cohort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohort.d.ts","sourceRoot":"","sources":["../../src/cohort.ts"],"names":[],"mappings":"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"}

package/dist/types/conditions.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cohort conditions: the constraints an Aggregation Service advertises for a
+ * cohort (did:btcr2 spec, "Step 1: Create Aggregation Cohort"). See ADR 039.
+ *
+ * The spec frames these as an optional menu ("the Aggregation Service can define
+ * conditions such as ..."), so only `beaconType` and `minParticipants` are
+ * required here; every other condition is optional and, when absent, means
+ * unconstrained.
+ *
+ * Enforcement is staged (ADR 039): `beaconType` and the participant bounds are
+ * enforced by the state machine now; DIDs-per-participant, timing/cadence, and
+ * the pending-update trigger are modeled and advertised here but enforced when
+ * the multi-cohort (AGG-4) and non-inclusion (AGG-5) tracks land. The two cost
+ * conditions are advertised metadata only - the protocol performs no payment or
+ * settlement (consistent with ADR 008).
+ */
+import type { FundingModel } from './recovery-policy.js';
+/** Beacon types that support aggregation (singleton is single-party only, per ADR 037). */
+export declare const KNOWN_BEACON_TYPES: readonly ["CASBeacon", "SMTBeacon"];
+/** Funding models an operator may advertise. Only 'operator-funded' is implemented (ADR 042). */
+export declare const KNOWN_FUNDING_MODELS: readonly ["operator-funded", "participant-funded"];
+/**
+ * An advertised price. `unit` is operator-defined (the spec does not specify a
+ * currency); `basis` distinguishes a per-DID from a per-participant charge for
+ * "cost per announcement". Advertised only - never settled by the protocol.
+ */
+export interface CohortCost {
+    amount: number;
+    unit: string;
+    basis?: 'per-did' | 'per-participant';
+}
+/** The seven spec cohort conditions. Only beaconType + minParticipants are required. */
+export interface CohortConditions {
+    /** 1. Beacon mechanism: 'CASBeacon' or 'SMTBeacon'. Enforced. */
+    beaconType: string;
+    /** 2. Lower bound on cohort size. Enforced (finalize floor). */
+    minParticipants: number;
+    /** 2. Upper bound on cohort size. Enforced (accept/finalize ceiling). */
+    maxParticipants?: number;
+    /** 3. Lower bound on DIDs a participant may register. Advertised; enforcement staged (AGG-5). */
+    minDidsPerParticipant?: number;
+    /** 3. Upper bound on DIDs a participant may register. Advertised; enforcement staged (AGG-5). */
+    maxDidsPerParticipant?: number;
+    /** 4. One-time enrollment price. Advertised only - no settlement. */
+    costOfEnrollment?: CohortCost;
+    /** 5. Recurring per-announcement price. Advertised only - no settlement. */
+    costPerAnnouncement?: CohortCost;
+    /** 6. Floor on time between announcements (seconds). Advertised; enforcement staged (AGG-4/5). */
+    minSecondsBetweenAnnouncements?: number;
+    /** 6. Ceiling on time between announcements (seconds). Advertised; enforcement staged - generalizes the ADR 027 Cohort TTL. */
+    maxSecondsBetweenAnnouncements?: number;
+    /** 7. Pending-update count that triggers an announcement. Advertised; enforcement staged (AGG-5) - generalizes hasAllUpdates(). */
+    pendingUpdateTrigger?: number;
+    /**
+     * Who funds the beacon UTXO and holds the recovery path. Defaults to
+     * 'operator-funded' when absent. See ADR 042.
+     */
+    fundingModel?: FundingModel;
+    /**
+     * Operator recovery key, x-only (64-character hex / 32 bytes). The beacon
+     * output commits to a CSV recovery leaf keyed to this key, so a missing signer
+     * can never permanently lock the funded UTXO. Required (ADR 042).
+     */
+    recoveryKey: string;
+    /**
+     * Relative-timelock (BIP-68 nSequence, in blocks) before the recovery leaf is
+     * spendable. Required, >= 1 (ADR 042).
+     */
+    recoverySequence: number;
+    /**
+     * Number of signers (k) the k-of-n fallback leaf requires, so any k cohort
+     * members can still announce when the optimistic n-of-n key path stalls
+     * (graceful liveness, ADR 042). Optional: when absent it defaults to n-1 at
+     * keygen, where n is the finalized participant count. When advertised it must
+     * be an integer >= 1 (and <= maxParticipants when that is set); the upper bound
+     * against the actual cohort size n is enforced at keygen.
+     */
+    fallbackThreshold?: number;
+}
+/**
+ * Validate a set of cohort conditions. Returns a list of human-readable problems
+ * (empty when valid) so the caller can decide how to surface them. Used by
+ * `createCohort()` to fail fast instead of discovering invalidity at finalize.
+ */
+export declare function validateCohortConditions(c: CohortConditions): string[];
+//# sourceMappingURL=conditions.d.ts.map

package/dist/types/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../src/conditions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,qCAAsC,CAAC;AAEtE,iGAAiG;AACjG,eAAO,MAAM,oBAAoB,oDAAqD,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,GAAG,iBAAiB,CAAC;CACvC;AAED,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,UAAU,CAAC;IAC9B,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,UAAU,CAAC;IACjC,kGAAkG;IAClG,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,+HAA+H;IAC/H,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mIAAmI;IACnI,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AA6BD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAqDtE"}

package/dist/types/errors.d.ts

@@ -0,0 +1,14 @@
+import { MethodError } from '@did-btcr2/common';
+export declare class AggregationServiceError extends MethodError {
+    constructor(message: string, type?: string, data?: Record<string, any>);
+}
+export declare class AggregationParticipantError extends MethodError {
+    constructor(message: string, type?: string, data?: Record<string, any>);
+}
+export declare class AggregationCohortError extends MethodError {
+    constructor(message: string, type?: string, data?: Record<string, any>);
+}
+export declare class SigningSessionError extends MethodError {
+    constructor(message: string, type?: string, data?: Record<string, any>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,qBAAa,uBAAwB,SAAQ,WAAW;gBAC1C,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAGlG;AAED,qBAAa,2BAA4B,SAAQ,WAAW;gBAC9C,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAsC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAGtG;AAED,qBAAa,sBAAuB,SAAQ,WAAW;gBACzC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAiC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAGjG;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAA8B,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAG9F"}

package/dist/types/fallback-spend.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 type { Transaction } from '@scure/btc-signer';
+import type { FundingModel } 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[];
+}
+/**
+ * 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 declare function fallbackSighash(tx: Transaction, inputIndex: number, prevOutScript: Uint8Array, prevOutValue: bigint, fallbackLeafScript: Uint8Array): Uint8Array;
+/**
+ * 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 declare function buildFallbackSpend(params: FallbackSpendParams): Transaction;
+//# sourceMappingURL=fallback-spend.d.ts.map

package/dist/types/fallback-spend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-spend.d.ts","sourceRoot":"","sources":["../../src/fallback-spend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAIpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAUzD,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,MAAM,EAAE,UAAU,CAAC;IACnB,sEAAsE;IACtE,SAAS,EAAE,UAAU,CAAC;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,EAAE,WAAW,CAAC;IACvB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,WAAW,EAAE,UAAU,CAAC;IACxB,oGAAoG;IACpG,gBAAgB,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,aAAa,EAAE,UAAU,CAAC;IAC1B,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,WAAW,EACf,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,UAAU,EACzB,YAAY,EAAE,MAAM,EACpB,kBAAkB,EAAE,UAAU,GAC7B,UAAU,CAUZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,WAAW,CA4F3E"}

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+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';
+export * from './messages/index.js';
+export * from './transport/index.js';
+export * from './runner/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAG5B,cAAc,qBAAqB,CAAC;AAGpC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,mBAAmB,CAAC"}

package/dist/types/logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare const CONSOLE_LOGGER: Logger;
+/** No-op logger. Useful for tests and production environments with own logging pipeline. */
+export declare const SILENT_LOGGER: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/types/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAED,iEAAiE;AACjE,eAAO,MAAM,cAAc,EAAE,MAK5B,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,aAAa,EAAE,MAK3B,CAAC"}

package/dist/types/messages/base.d.ts

@@ -0,0 +1,58 @@
+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 declare const AGGREGATION_WIRE_VERSION = 1;
+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 declare class BaseMessage {
+    type: string;
+    version: number;
+    to?: string;
+    from: string;
+    body?: BaseBody;
+    constructor({ type, version, to, from, body }: Base);
+    /**
+     * Converts a BaseMessage to a JSON object.
+     * @returns {Base} The JSON representation of the BaseMessage.
+     */
+    toJSON(): Base;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/types/messages/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/messages/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAK1C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,GAAG;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,UAAU,CAAC;IAC7B,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,gBAAgB,CAAC,EAAE,UAAU,CAAC;IAC9B,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,IAAI,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB,CAAC;AAEF,qBAAa,WAAW;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,CAAC;gBAEX,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,IAAI;IAQnD;;;OAGG;IACI,MAAM,IAAI,IAAI;CAStB"}