@did-btcr2/aggregation 0.1.0

package/dist/types/phases.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Phases for the did:btcr2 Aggregate Beacon protocol.
+ *
+ * The protocol has two roles (AggregationService and AggregationParticipant)
+ * which experience different phases for the same cohort. Each role has its own
+ * phase enum.
+ *
+ * The signing session has its own phase enum because MuSig2 signing is a
+ * sub-protocol within the larger aggregation protocol.
+ */
+export type ServiceCohortPhaseType = 'Created' | 'Advertised' | 'CohortSet' | 'CollectingUpdates' | 'UpdatesCollected' | 'DataDistributed' | 'Validated' | 'SigningStarted' | 'NoncesCollected' | 'AwaitingPartialSigs' | 'FallbackRequested' | 'Complete' | 'Failed';
+export declare enum ServiceCohortPhase {
+    Created = "Created",
+    Advertised = "Advertised",
+    CohortSet = "CohortSet",
+    CollectingUpdates = "CollectingUpdates",
+    UpdatesCollected = "UpdatesCollected",
+    DataDistributed = "DataDistributed",
+    Validated = "Validated",
+    SigningStarted = "SigningStarted",
+    NoncesCollected = "NoncesCollected",
+    AwaitingPartialSigs = "AwaitingPartialSigs",
+    /** Optimistic n-of-n key path abandoned; collecting k-of-n fallback signatures (ADR 042). */
+    FallbackRequested = "FallbackRequested",
+    Complete = "Complete",
+    Failed = "Failed"
+}
+export type ParticipantCohortPhaseType = 'Discovered' | 'OptedIn' | 'CohortReady' | 'UpdateSubmitted' | 'NonIncluded' | 'AwaitingValidation' | 'ValidationSent' | 'AwaitingSigning' | 'NonceSent' | 'AwaitingPartialSig' | 'AwaitingFallbackSig' | 'Complete' | 'Failed';
+export declare enum ParticipantCohortPhase {
+    Discovered = "Discovered",
+    OptedIn = "OptedIn",
+    CohortReady = "CohortReady",
+    UpdateSubmitted = "UpdateSubmitted",
+    /** Member declined to submit an update this round (cooperative non-inclusion); still signs. */
+    NonIncluded = "NonIncluded",
+    AwaitingValidation = "AwaitingValidation",
+    ValidationSent = "ValidationSent",
+    AwaitingSigning = "AwaitingSigning",
+    NonceSent = "NonceSent",
+    AwaitingPartialSig = "AwaitingPartialSig",
+    /** Service fell back to the k-of-n script path; member can sign the fallback (ADR 042). */
+    AwaitingFallbackSig = "AwaitingFallbackSig",
+    Complete = "Complete",
+    Failed = "Failed"
+}
+export type SigningSessionPhaseType = 'AwaitingNonceContributions' | 'NonceContributionsReceived' | 'AwaitingPartialSignatures' | 'PartialSignaturesReceived' | 'Complete' | 'Failed';
+export declare enum SigningSessionPhase {
+    AwaitingNonceContributions = "AwaitingNonceContributions",
+    NonceContributionsReceived = "NonceContributionsReceived",
+    AwaitingPartialSignatures = "AwaitingPartialSignatures",
+    PartialSignaturesReceived = "PartialSignaturesReceived",
+    Complete = "Complete",
+    Failed = "Failed"
+}
+//# sourceMappingURL=phases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"phases.d.ts","sourceRoot":"","sources":["../../src/phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,YAAY,GACZ,WAAW,GACX,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,qBAAqB,GACrB,mBAAmB,GACnB,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,iBAAiB,sBAAsB;IACvC,gBAAgB,qBAAqB;IACrC,eAAe,oBAAoB;IACnC,SAAS,cAAc;IACvB,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,mBAAmB,wBAAwB;IAC3C,6FAA6F;IAC7F,iBAAiB,sBAAsB;IACvC,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,MAAM,MAAM,0BAA0B,GAClC,YAAY,GACZ,SAAS,GACT,aAAa,GACb,iBAAiB,GACjB,aAAa,GACb,oBAAoB,GACpB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,oBAAoB,GACpB,qBAAqB,GACrB,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,sBAAsB;IAChC,UAAU,eAAe;IACzB,OAAO,YAAY;IACnB,WAAW,gBAAgB;IAC3B,eAAe,oBAAoB;IACnC,+FAA+F;IAC/F,WAAW,gBAAgB;IAC3B,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;IACzC,2FAA2F;IAC3F,mBAAmB,wBAAwB;IAC3C,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,MAAM,MAAM,uBAAuB,GAC/B,4BAA4B,GAC5B,4BAA4B,GAC5B,2BAA2B,GAC3B,2BAA2B,GAC3B,UAAU,GACV,QAAQ,CAAC;AAEb,oBAAY,mBAAmB;IAC7B,0BAA0B,+BAA+B;IACzD,0BAA0B,+BAA+B;IACzD,yBAAyB,8BAA8B;IACvD,yBAAyB,8BAA8B;IACvD,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB"}

package/dist/types/recovery-policy.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Recovery policy 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. A key-path-only output can be spent only with a
+ * signature from every cohort member, so a single missing signer would lock the
+ * funds forever. To prevent that, the output commits to a script tree with two
+ * leaves:
+ * - a k-of-n fallback leaf (`p2tr_ms`, BIP-342 CHECKSIGADD): any k cohort members
+ *   can still push the announcement through if some signers go missing, so the
+ *   beacon stays live without waiting out the timelock.
+ * - a CSV recovery leaf: after a relative-timelock delay the funder can reclaim
+ *   the UTXO unilaterally with its own recovery key, so funds are never
+ *   permanently stranded even if fewer than k members remain.
+ *
+ * This module is the seam between the funding model and the concrete script
+ * leaves. Only `operator-funded` is implemented today (the k-of-n fallback leaf
+ * plus one CSV leaf keyed to the operator's recovery key). A future
+ * `participant-funded` model can be added as another case returning
+ * per-participant refund leaves, without touching the cohort, service, or
+ * signing code. See ADR 042.
+ */
+/**
+ * Who funds the beacon UTXO and holds the recovery path.
+ * - `operator-funded`: the service operator funds the UTXO and holds a single
+ *   CSV recovery key. Implemented.
+ * - `participant-funded`: reserved for per-participant funding with
+ *   per-participant refund leaves. Not implemented.
+ */
+export type FundingModel = 'operator-funded' | 'participant-funded';
+/** Default funding model when an advert/config leaves it unspecified. */
+export declare const DEFAULT_FUNDING_MODEL: FundingModel;
+/**
+ * Default relative-timelock (in blocks) before operator recovery is spendable.
+ * About one day at 10-minute blocks. Operators set their own per-cohort value;
+ * this is only a convenience default for callers.
+ */
+export declare const DEFAULT_RECOVERY_SEQUENCE = 144;
+/**
+ * Maximum allowed `recoverySequence`, 0xffff (65535 blocks, about 455 days).
+ *
+ * The value is a BIP-68 block-based relative timelock and is placed directly in
+ * the spending input's nSequence. BIP-68 only uses the low 16 bits as the value
+ * when the type flag (bit 22) is clear, so constraining to [1, 0xffff] keeps the
+ * timelock block-based and, critically, leaves the disable flag (bit 31) clear.
+ * A value with bit 31 set would disable CHECKSEQUENCEVERIFY entirely, letting the
+ * recovery key spend with no delay; an upper bound of 0xffff makes that
+ * unrepresentable.
+ */
+export declare const MAX_RECOVERY_SEQUENCE = 65535;
+/** Inputs needed to build the CSV recovery leaf. */
+export interface RecoveryPolicyParams {
+    /** Operator recovery key, x-only (32 bytes). Spends the recovery leaf via CHECKSIG. */
+    recoveryKey: Uint8Array;
+    /**
+     * Relative-timelock value (BIP-68 nSequence) the recovery spend must wait,
+     * encoded into the leaf as `<recoverySequence> CHECKSEQUENCEVERIFY`.
+     */
+    recoverySequence: number;
+}
+/** Inputs needed to build the k-of-n fallback leaf. */
+export interface FallbackPolicyParams {
+    /**
+     * The cohort's participant public keys (compressed secp256k1, 33 bytes each).
+     * Sorted internally per BIP-327 and reduced to x-only so the leaf is
+     * deterministic regardless of the order keys are supplied in.
+     */
+    cohortKeys: Uint8Array[];
+    /**
+     * Number of signers (k) the fallback leaf requires, 1..n. This is the
+     * resolved threshold; callers that carry an advertised-or-default value should
+     * resolve it with {@link resolveFallbackThreshold} first.
+     */
+    fallbackThreshold: number;
+}
+/** All inputs the beacon output's script tree commits to (fallback leaf + recovery leaf). */
+export interface BeaconLeafParams extends RecoveryPolicyParams, FallbackPolicyParams {
+}
+/** A single Taproot script-tree leaf, spent at the default tapscript leaf version (0xc0). */
+export interface TaprootScriptLeaf {
+    script: Uint8Array;
+}
+/** BIP-341 default tapscript leaf version. */
+export declare const TAPROOT_LEAF_VERSION = 192;
+/**
+ * BIP-341 tapleaf hash: `taggedHash("TapLeaf", leafVersion || compactSize(len) || script)`.
+ * Used to key a script-path signature to its leaf when assembling the witness
+ * for a script-path spend (the fallback and recovery spend builders).
+ */
+export declare function tapLeafHash(script: Uint8Array, leafVersion?: number): Uint8Array;
+/**
+ * Resolve the effective fallback threshold k from an advertised value and the
+ * cohort size n. When unadvertised it defaults to n-1 (tolerate one missing or
+ * defecting signer, the cheapest useful fallback witness), floored at 1. Both
+ * the service and every participant resolve this identically so they derive the
+ * same beacon address.
+ */
+export declare function resolveFallbackThreshold(advertised: number | undefined, n: number): number;
+/**
+ * Build the k-of-n fallback leaf script: a BIP-342 `p2tr_ms` CHECKSIGADD
+ * multisig over the cohort's x-only keys. Any k members can spend this leaf to
+ * push the announcement through when the optimistic n-of-n key path stalls.
+ *
+ * The keys are sorted per BIP-327 (matching the MuSig2 internal-key ordering)
+ * and reduced to x-only, so the leaf is identical for every party that builds it.
+ */
+export declare function buildFallbackLeaf(params: FallbackPolicyParams): Uint8Array;
+/**
+ * Build the CSV recovery leaf script:
+ * `<recoverySequence> CHECKSEQUENCEVERIFY DROP <recoveryKey> CHECKSIG`.
+ *
+ * After `recoverySequence` blocks (relative to the UTXO's confirmation) the
+ * holder of `recoveryKey` can spend the output via the script path.
+ */
+export declare function buildRecoveryScript(params: RecoveryPolicyParams): Uint8Array;
+/**
+ * Build the Taproot script-tree leaves for a funding model. The returned leaves
+ * are the script tree the beacon output key commits to alongside the cohort's
+ * MuSig2 internal key.
+ *
+ * Canonical leaf order is fallback (k-of-n, leaf A) then CSV recovery (leaf B).
+ * For the current two-leaf tree the Merkle root is order-invariant (a TapBranch
+ * sorts its two child hashes), but fixing the order keeps the construction
+ * deterministic and reviewable, and is consensus-affecting should the tree ever
+ * grow past two leaves.
+ *
+ * @throws {AggregationCohortError} when the funding model is reserved (e.g.
+ * `participant-funded`) or unknown, or when the fallback/recovery params are
+ * invalid.
+ */
+export declare function buildRecoveryLeaves(fundingModel: FundingModel, params: BeaconLeafParams): TaprootScriptLeaf[];
+//# sourceMappingURL=recovery-policy.d.ts.map

package/dist/types/recovery-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-policy.d.ts","sourceRoot":"","sources":["../../src/recovery-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAEpE,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,EAAE,YAAgC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,WAAW,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,6FAA6F;AAC7F,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB,EAAE,oBAAoB;CAAG;AAEvF,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB,MAAO,CAAC;AASzC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,GAAE,MAA6B,GAAG,UAAU,CAKtG;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1F;AA0BD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,UAAU,CAI1E;AAiBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,UAAU,CAS5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,gBAAgB,GACvB,iBAAiB,EAAE,CAkBrB"}

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

@@ -0,0 +1,94 @@
+/**
+ * Recovery 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 timelocked
+ * recovery leaf (see {@link ./recovery-policy.ts} and ADR 042). When the
+ * optimistic cooperative key-path spend cannot complete (a missing or defecting
+ * signer), the funder reclaims the UTXO via the recovery leaf after the
+ * relative-timelock delay.
+ *
+ * This module builds and signs that script-path spend. It is pure with respect
+ * to the network: it takes a UTXO reference plus the cohort and recovery
+ * parameters and returns a finalized {@link Transaction}; broadcasting and
+ * confirmation are the caller's concern. The recovery key path is a single
+ * BIP-340 Schnorr signature, so unlike the MuSig2 key path it can be driven by
+ * an opaque or HSM-backed signer.
+ *
+ * The relative timelock is enforced by consensus (BIP-68/112): the spend is only
+ * valid once the UTXO has `recoverySequence` confirmations, and the input's
+ * nSequence is set accordingly. The transaction version is 2 so BIP-68 applies.
+ */
+import { Transaction } from '@scure/btc-signer';
+import type { FundingModel } from './recovery-policy.js';
+/** Reference to the beacon UTXO being recovered. */
+export interface BeaconUtxoRef {
+    /** Transaction id (Esplora display-order hex), as returned by the REST UTXO endpoint. */
+    txid: string;
+    /** Output index within that transaction. */
+    vout: number;
+    /** Value of the beacon UTXO in satoshis. */
+    value: bigint;
+}
+/** Inputs to {@link buildRecoverySpend}. */
+export interface RecoverySpendParams {
+    /**
+     * The cohort's participant public keys (compressed secp256k1). Sorted
+     * internally per BIP-327 so the reconstructed internal key matches the one the
+     * beacon address was derived from.
+     */
+    cohortKeys: Uint8Array[];
+    /** Operator recovery secret key (32 bytes). Its x-only public key must equal {@link recoveryKey}. */
+    recoverySecretKey: Uint8Array;
+    /** Operator recovery key, x-only (32 bytes), as committed in the recovery leaf. */
+    recoveryKey: Uint8Array;
+    /** Relative-timelock (BIP-68 nSequence) the recovery leaf enforces. */
+    recoverySequence: number;
+    /**
+     * The advertised k of the k-of-n fallback leaf the beacon output also commits
+     * to, or omit to use the same n-1 default the cohort applies. Resolved against
+     * `cohortKeys.length` exactly as the cohort does, so the reconstructed script
+     * tree and control block match the funded address.
+     */
+    fallbackThreshold?: number;
+    /** Funding model governing the recovery leaves. Defaults to 'operator-funded'. */
+    fundingModel?: FundingModel;
+    /** Bitcoin network name (bitcoin/mainnet, mutinynet, signet, testnet, regtest). */
+    network: string;
+    /**
+     * The beacon UTXO being recovered.
+     *
+     * Precondition: the on-chain output at this `txid:vout` MUST have been funded
+     * to the beacon address derived from these same `cohortKeys`, `recoveryKey`,
+     * `recoverySequence`, and `fundingModel`. If it was funded under different
+     * parameters the reconstructed `witnessUtxo.script` will not match the chain,
+     * the signature will be invalid, and the spend will be rejected. Pass
+     * {@link beaconAddress} to assert this reconstruction up front.
+     */
+    utxo: BeaconUtxoRef;
+    /** Address receiving the recovered funds. */
+    destinationAddress: string;
+    /** Absolute fee (satoshis) deducted from the recovered value. */
+    fee: bigint;
+    /**
+     * Optional: the cohort's funded beacon address. When provided, the builder
+     * asserts that the address it reconstructs from the cohort and recovery params
+     * equals it, catching a caller mismatch before producing an unspendable tx.
+     */
+    beaconAddress?: string;
+}
+/**
+ * Build and sign a script-path recovery spend of an aggregate beacon UTXO.
+ *
+ * Reconstructs the same Taproot output the cohort funded (MuSig2 internal key +
+ * recovery script tree), spends it through the recovery leaf with the operator's
+ * recovery key, and finalizes the witness (signature + leaf script + control
+ * block). The returned transaction is ready to broadcast once the UTXO has
+ * `recoverySequence` confirmations.
+ *
+ * @throws {AggregationCohortError} when the recovery secret key does not match
+ * the committed recovery key, when there are no cohort keys, or when the fee
+ * exceeds the UTXO value.
+ */
+export declare function buildRecoverySpend(params: RecoverySpendParams): Transaction;
+//# sourceMappingURL=recovery-spend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-spend.d.ts","sourceRoot":"","sources":["../../src/recovery-spend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAQ,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,qGAAqG;IACrG,iBAAiB,EAAE,UAAU,CAAC;IAC9B,mFAAmF;IACnF,WAAW,EAAE,UAAU,CAAC;IACxB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,IAAI,EAAE,aAAa,CAAC;IACpB,6CAA6C;IAC7C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,WAAW,CA+E3E"}

package/dist/types/runner/aggregation-runner.d.ts

@@ -0,0 +1,72 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { AggregationResult } from '../service.js';
+import type { OnProvideUpdate } from './participant-runner.js';
+import type { OnProvideTxData } from './service-runner.js';
+import type { FeeEstimator } from '@did-btcr2/bitcoin';
+/** Identity (DID + keys) for one actor in an {@link AggregationRunner.solo} run. */
+export interface SoloActor {
+    did: string;
+    keys: SchnorrKeyPair;
+}
+/** Options for {@link AggregationRunner.solo}. */
+export interface SoloCohortOptions {
+    /** The coordinating service identity. */
+    service: SoloActor;
+    /** The single participant identity (the lone signer of the cohort). */
+    participant: SoloActor;
+    /**
+     * Bitcoin network and beacon type (`'CASBeacon'` | `'SMTBeacon'`) for the
+     * cohort. Recovery params are optional here: in a solo run the service actor
+     * is the operator and holds full keys, so when `recoveryKey` is omitted the
+     * service's own x-only key is used as the CSV recovery key (it can actually
+     * perform the recovery), with {@link DEFAULT_RECOVERY_SEQUENCE} as the delay.
+     */
+    config: {
+        network: string;
+        beaconType: string;
+        /** Operator recovery key, x-only (64-hex). Defaults to the service actor's x-only key. */
+        recoveryKey?: string;
+        /** Relative-timelock (BIP-68) before recovery is spendable. Defaults to {@link DEFAULT_RECOVERY_SEQUENCE}. */
+        recoverySequence?: number;
+    };
+    /** Provide the participant's signed BTCR2 update for the cohort. */
+    onProvideUpdate: OnProvideUpdate;
+    /** Provide the Bitcoin transaction data the cohort signs. */
+    onProvideTxData: OnProvideTxData;
+    /**
+     * Fee estimator forwarded to {@link onProvideTxData} so the cohort transaction is
+     * sized at a chosen rate. Defaults to a static 5 sat/vB estimator (ADR 045).
+     */
+    feeEstimator?: FeeEstimator;
+    /** Optional overall wall-clock budget for the run (ms). */
+    cohortTtlMs?: number;
+    /** Optional per-phase stall timeout (ms). */
+    phaseTimeoutMs?: number;
+}
+/**
+ * High-level facades for driving an aggregation cohort to completion.
+ *
+ * @class AggregationRunner
+ */
+export declare class AggregationRunner {
+    /**
+     * Run a cohort of ONE participant entirely in-process and return the
+     * aggregated MuSig2 result.
+     *
+     * One party plays both the coordinating service and the lone participant,
+     * connected over an {@link InMemoryTransport} (no relay or HTTP server). This
+     * makes the single-participant aggregate-beacon path (the N=1 corner of the
+     * two-axis beacon matrix, see ADR 037) first-class, useful for generating
+     * and reproducing single-participant aggregate test vectors.
+     *
+     * The service advertises a cohort with `minParticipants: 1`; the participant
+     * joins, submits its update, and the two complete keygen, data distribution,
+     * validation, and a one-signer MuSig2 P2TR key-path signing round.
+     *
+     * @param options Service + participant identities, cohort config, and the
+     *   update / tx-data callbacks.
+     * @returns The {@link AggregationResult} (cohort id, aggregated signature, signed tx).
+     */
+    static solo(options: SoloCohortOptions): Promise<AggregationResult>;
+}
+//# sourceMappingURL=aggregation-runner.d.ts.map

package/dist/types/runner/aggregation-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregation-runner.d.ts","sourceRoot":"","sources":["../../../src/runner/aggregation-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,SAAS,CAAC;IACvB;;;;;;OAMG;IACH,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,0FAA0F;QAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,8GAA8G;QAC9G,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,oEAAoE;IACpE,eAAe,EAAE,eAAe,CAAC;IACjC,6DAA6D;IAC7D,eAAe,EAAE,eAAe,CAAC;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;;;;;OAiBG;WACU,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA+C1E"}

package/dist/types/runner/events.d.ts

@@ -0,0 +1,147 @@
+import type { SerializedSMTProof } from '@did-btcr2/smt';
+import type { CohortAdvert, PendingFallbackRequest, PendingSigningRequest, PendingValidation } from '../participant.js';
+import type { AggregationResult, PendingOptIn, Rejection } from '../service.js';
+/**
+ * Sidecar data a participant keeps when a cohort completes from its
+ * perspective: the cohort's beacon coordinates plus the off-chain artifact it
+ * needs for future DID resolution (the CAS Announcement map for CAS beacons, or
+ * the SMT inclusion proof for SMT beacons). Emitted via `cohort-complete` and
+ * returned by the participant runner's join helpers.
+ */
+export interface CohortCompleteInfo {
+    cohortId: string;
+    beaconAddress: string;
+    beaconType: string;
+    /** True if this participant submitted an update; false if it declined (non-inclusion). */
+    included: boolean;
+    /** DID to base64url update hash. Populated only for CAS beacons. */
+    casAnnouncement?: Record<string, string>;
+    /** Inclusion proof (submitter) or non-inclusion proof (decliner) for this slot. Populated only for SMT beacons. */
+    smtProof?: SerializedSMTProof;
+}
+/**
+ * AggregationServiceRunner events are emitted by the AggregationServiceRunner to signal important
+ * milestones and actions during the aggregation process. They can be listened to by external code
+ * to react to these events, such as logging, updating a UI, or triggering additional actions.
+ */
+export type AggregationServiceEvents = {
+    /** A cohort has been created and the advert message broadcast. */
+    'cohort-advertised': [{
+        cohortId: string;
+    }];
+    /** A participant has opted in. Fires before the accept decision callback. */
+    'opt-in-received': [PendingOptIn];
+    /** A participant has been accepted into the cohort. */
+    'participant-accepted': [{
+        cohortId: string;
+        participantDid: string;
+    }];
+    /** Keygen has been finalized: beacon address is now available. */
+    'keygen-complete': [{
+        cohortId: string;
+        beaconAddress: string;
+    }];
+    /** A participant has submitted a signed update. */
+    'update-received': [{
+        cohortId: string;
+        participantDid: string;
+    }];
+    /**
+     * An inbound message was silently dropped by the state machine (bad proof,
+     * oversized payload, wrong wire version, etc.). Fires for *any* rejection,
+     * not just SUBMIT_UPDATE.
+     */
+    'message-rejected': [Rejection & {
+        cohortId: string;
+    }];
+    /** Aggregated data has been distributed to all participants for validation. */
+    'data-distributed': [{
+        cohortId: string;
+    }];
+    /** A participant has acknowledged validation (approved or rejected). */
+    'validation-received': [{
+        cohortId: string;
+        participantDid: string;
+        approved: boolean;
+    }];
+    /** Signing has started: auth requests sent to participants. */
+    'signing-started': [{
+        cohortId: string;
+        sessionId: string;
+    }];
+    /**
+     * The optimistic n-of-n key path was abandoned and the k-of-n fallback
+     * (script-path) signing round started (ADR 042). After this, the cohort
+     * completes via the fallback once k members sign.
+     */
+    'fallback-started': [{
+        cohortId: string;
+        sessionId: string;
+    }];
+    /** A participant has contributed their MuSig2 nonce. */
+    'nonce-received': [{
+        cohortId: string;
+        participantDid: string;
+    }];
+    /** Signing complete: final aggregated signature is ready to broadcast. */
+    'signing-complete': [AggregationResult];
+    /** Cohort transitioned to Failed phase (e.g. a participant rejected validation). */
+    'cohort-failed': [{
+        cohortId: string;
+        reason: string;
+    }];
+    /** A non-fatal error occurred. Fatal errors reject the run() promise. */
+    'error': [Error];
+};
+/**
+ * AggregationParticipantRunner events are emitted by the AggregationParticipantRunner to signal
+ * important milestones and actions during the participant's involvement in the aggregation process.
+ * They can be listened to by external code to react to these events, such as logging, updating a
+ * UI, or triggering additional actions.
+ */
+export type AggregationParticipantEvents = {
+    /** A new cohort advert was discovered. Fires before the shouldJoin filter. */
+    'cohort-discovered': [CohortAdvert];
+    /** Participant has opted in to a cohort. */
+    'cohort-joined': [{
+        cohortId: string;
+    }];
+    /** Cohort keygen is complete: beacon address is now available. */
+    'cohort-ready': [{
+        cohortId: string;
+        beaconAddress: string;
+    }];
+    /** Participant has submitted their signed update. */
+    'update-submitted': [{
+        cohortId: string;
+    }];
+    /** Participant declined to submit an update this round (cooperative non-inclusion). */
+    'update-declined': [{
+        cohortId: string;
+    }];
+    /** Aggregated data has arrived for validation. Fires before the validate callback. */
+    'validation-requested': [PendingValidation];
+    /** Signing request has arrived. Fires before the sign approval callback. */
+    'signing-requested': [PendingSigningRequest];
+    /**
+     * A fallback (k-of-n script-path) signing request has arrived because the
+     * service abandoned the optimistic key path (ADR 042). Fires before the sign
+     * approval callback; approving signs the fallback spend.
+     */
+    'fallback-requested': [PendingFallbackRequest];
+    /**
+     * Cohort signing is complete from this participant's perspective.
+     * Includes the aggregated sidecar data the participant needs to keep for
+     * future DID resolution: the CAS Announcement map (for CAS beacons) or the
+     * SMT inclusion proof (for SMT beacons).
+     */
+    'cohort-complete': [CohortCompleteInfo];
+    /** Cohort failed (rejected validation, signing error, etc.). */
+    'cohort-failed': [{
+        cohortId: string;
+        reason: string;
+    }];
+    /** A non-fatal error occurred. */
+    'error': [Error];
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/types/runner/events.d.ts.map

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

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

@@ -0,0 +1,6 @@
+export * from './typed-emitter.js';
+export * from './events.js';
+export * from './service-runner.js';
+export * from './participant-runner.js';
+export * from './aggregation-runner.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runner/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC"}

package/dist/types/runner/participant-runner.d.ts

@@ -0,0 +1,122 @@
+import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { CohortAdvert, PendingSigningRequest, PendingValidation } from '../participant.js';
+import { AggregationParticipant } from '../participant.js';
+import type { Transport } from '../transport/transport.js';
+import type { AggregationParticipantEvents, CohortCompleteInfo } from './events.js';
+import { TypedEventEmitter } from './typed-emitter.js';
+/** Decision callback: filter discovered cohorts. Default rejects all. */
+export type ShouldJoin = (advert: CohortAdvert) => Promise<boolean>;
+/** Data callback: provide a signed BTCR2 update for a joined cohort. */
+export type OnProvideUpdate = (info: {
+    cohortId: string;
+    beaconAddress: string;
+}) => Promise<SignedBTCR2Update | null>;
+/** Decision callback: approve or reject aggregated data. */
+export type OnValidateData = (info: PendingValidation) => Promise<{
+    approved: boolean;
+}>;
+/** Decision callback: approve or reject signing. */
+export type OnApproveSigning = (info: PendingSigningRequest) => Promise<{
+    approved: boolean;
+}>;
+export interface AggregationParticipantRunnerOptions {
+    /** Underlying transport. */
+    transport: Transport;
+    /** Participant identity. */
+    did: string;
+    keys: SchnorrKeyPair;
+    /**
+     * Filter discovered cohorts. Returns true to join, false to skip.
+     * Default: rejects all cohorts (caller MUST override or no cohorts will be joined).
+     */
+    shouldJoin?: ShouldJoin;
+    /**
+     * Provide a signed BTCR2 update for the cohort.
+     * REQUIRED - no sensible default.
+     */
+    onProvideUpdate: OnProvideUpdate;
+    /**
+     * Approve or reject aggregated data.
+     * Default: approve if validation matches the submitted update's hash.
+     */
+    onValidateData?: OnValidateData;
+    /**
+     * Approve or reject the signing request.
+     * Default: approve.
+     */
+    onApproveSigning?: OnApproveSigning;
+}
+/**
+ * High-level facade for an Aggregation Participant.
+ *
+ * Long-running listener: waits for cohort adverts, applies the `shouldJoin`
+ * filter, and drives each accepted cohort through the full protocol to
+ * completion in parallel.
+ *
+ * @example
+ * ```typescript
+ * const transport = new NostrTransport({ relays: [RELAY] });
+ * transport.registerActor(myDid, myKeys);
+ *
+ * const runner = new AggregationParticipantRunner({
+ *   transport,
+ *   did: myDid,
+ *   keys: myKeys,
+ *   shouldJoin: async (advert) => advert.beaconType === 'CASBeacon',
+ *   onProvideUpdate: async ({ beaconAddress }) => {
+ *     return Updater.sign(myDid, unsigned, vm, secretKey);
+ *   },
+ * });
+ *
+ * runner.on('cohort-complete', ({ beaconAddress }) => {
+ *   console.log(`Add to DID document: bitcoin:${beaconAddress}`);
+ * });
+ *
+ * await runner.start();
+ * ```
+ *
+ * For full manual control, drop down to the underlying state machine via
+ * `runner.session`. The state machine has no transport coupling and exposes
+ * every protocol decision as an explicit method.
+ *
+ * @class AggregationParticipantRunner
+ * @extends TypedEventEmitter<AggregationParticipantEvents>
+ */
+export declare class AggregationParticipantRunner extends TypedEventEmitter<AggregationParticipantEvents> {
+    #private;
+    /** Direct access to the underlying state machine for advanced use. */
+    readonly session: AggregationParticipant;
+    constructor(options: AggregationParticipantRunnerOptions);
+    /**
+     * Start listening for cohorts. The runner stays active until {@link stop}
+     * is called or the underlying transport disconnects.
+     */
+    start(): Promise<void>;
+    /** Stop the runner and detach transport handlers. Safe to call repeatedly. */
+    stop(): void;
+    /**
+     * Single-shot helper: start, join the first cohort that passes `shouldJoin`,
+     * drive it to completion, and resolve. Convenient for tests and demos. The
+     * single-cohort special case of {@link joinMatching} (count = 1).
+     */
+    static joinFirst(options: AggregationParticipantRunnerOptions): Promise<CohortCompleteInfo>;
+    /**
+     * Multi-cohort helper: start, join EVERY cohort whose advert passes
+     * `shouldJoin`, drive each to completion in parallel, and resolve once
+     * `count` cohorts have completed (the runner stops at that point). The
+     * N-cohort generalization of {@link joinFirst}, for a participant that joins
+     * several cohorts advertised by one service.
+     *
+     * For an open-ended, long-lived subscriber (no fixed count), construct an
+     * {@link AggregationParticipantRunner} directly, set `shouldJoin`, call
+     * `start()`, and listen for `cohort-complete` - the runner already drives
+     * any number of cohorts concurrently.
+     *
+     * @param options Participant runner options (set `shouldJoin` to select cohorts).
+     * @param count Number of completed cohorts to collect before resolving.
+     * @returns The {@link CohortCompleteInfo} for each completed cohort, in completion order.
+     */
+    static joinMatching(options: AggregationParticipantRunnerOptions, count: number): Promise<CohortCompleteInfo[]>;
+}
+//# sourceMappingURL=participant-runner.d.ts.map