@did-btcr2/aggregation 0.1.0

package/src/phases.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 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 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 enum SigningSessionPhase {
+  AwaitingNonceContributions = 'AwaitingNonceContributions',
+  NonceContributionsReceived = 'NonceContributionsReceived',
+  AwaitingPartialSignatures = 'AwaitingPartialSignatures',
+  PartialSignaturesReceived = 'PartialSignaturesReceived',
+  Complete = 'Complete',
+  Failed = 'Failed',
+}

package/src/recovery-policy.ts

@@ -0,0 +1,237 @@
+/**
+ * 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.
+ */
+
+import { schnorr } from '@noble/curves/secp256k1.js';
+import { concatBytes } from '@noble/hashes/utils';
+import { Script, p2tr_ms } from '@scure/btc-signer';
+import { sortKeys } from '@scure/btc-signer/musig2';
+import { AggregationCohortError } from './errors.js';
+
+/**
+ * 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 const DEFAULT_FUNDING_MODEL: FundingModel = 'operator-funded';
+
+/**
+ * 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 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 const MAX_RECOVERY_SEQUENCE = 0xffff;
+
+/** 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 const TAPROOT_LEAF_VERSION = 0xc0;
+
+/** BIP-340 compact-size (varint) prefix for a byte length (scripts stay well under 2^32). */
+function compactSize(n: number): Uint8Array {
+  if(n < 0xfd) return new Uint8Array([ n ]);
+  if(n <= 0xffff) return new Uint8Array([ 0xfd, n & 0xff, (n >> 8) & 0xff ]);
+  return new Uint8Array([ 0xfe, n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >> 24) & 0xff ]);
+}
+
+/**
+ * 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 function tapLeafHash(script: Uint8Array, leafVersion: number = TAPROOT_LEAF_VERSION): Uint8Array {
+  return schnorr.utils.taggedHash(
+    'TapLeaf',
+    concatBytes(new Uint8Array([ leafVersion ]), compactSize(script.length), script)
+  );
+}
+
+/**
+ * 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 function resolveFallbackThreshold(advertised: number | undefined, n: number): number {
+  return advertised ?? Math.max(1, n - 1);
+}
+
+function assertFallbackParams({ cohortKeys, fallbackThreshold }: FallbackPolicyParams): void {
+  const n = cohortKeys.length;
+  if(n === 0) {
+    throw new AggregationCohortError(
+      'Cannot build fallback leaf: no cohort keys.',
+      'NO_COHORT_KEYS'
+    );
+  }
+  for(const key of cohortKeys) {
+    if(key.length !== 33) {
+      throw new AggregationCohortError(
+        `Cohort key must be a 33-byte compressed public key, got ${key.length} bytes.`,
+        'INVALID_COHORT_KEY', { length: key.length }
+      );
+    }
+  }
+  if(!Number.isInteger(fallbackThreshold) || fallbackThreshold < 1 || fallbackThreshold > n) {
+    throw new AggregationCohortError(
+      `Fallback threshold must be an integer in [1, ${n}] (k-of-n), got ${fallbackThreshold}.`,
+      'INVALID_FALLBACK_THRESHOLD', { fallbackThreshold, n }
+    );
+  }
+}
+
+/**
+ * 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 function buildFallbackLeaf(params: FallbackPolicyParams): Uint8Array {
+  assertFallbackParams(params);
+  const xOnlyKeys = sortKeys(params.cohortKeys).map(k => k.slice(1));
+  return p2tr_ms(params.fallbackThreshold, xOnlyKeys).script;
+}
+
+function assertRecoveryParams({ recoveryKey, recoverySequence }: RecoveryPolicyParams): void {
+  if(recoveryKey.length !== 32) {
+    throw new AggregationCohortError(
+      `Recovery key must be a 32-byte x-only public key, got ${recoveryKey.length} bytes.`,
+      'INVALID_RECOVERY_KEY'
+    );
+  }
+  if(!Number.isInteger(recoverySequence) || recoverySequence < 1 || recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    throw new AggregationCohortError(
+      `Recovery sequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}], got ${recoverySequence}.`,
+      'INVALID_RECOVERY_SEQUENCE'
+    );
+  }
+}
+
+/**
+ * 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 function buildRecoveryScript(params: RecoveryPolicyParams): Uint8Array {
+  assertRecoveryParams(params);
+  return Script.encode([
+    params.recoverySequence,
+    'CHECKSEQUENCEVERIFY',
+    'DROP',
+    params.recoveryKey,
+    'CHECKSIG',
+  ]);
+}
+
+/**
+ * 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 function buildRecoveryLeaves(
+  fundingModel: FundingModel,
+  params: BeaconLeafParams
+): TaprootScriptLeaf[] {
+  switch(fundingModel) {
+    case 'operator-funded':
+      return [
+        { script: buildFallbackLeaf(params) },
+        { script: buildRecoveryScript(params) },
+      ];
+    case 'participant-funded':
+      throw new AggregationCohortError(
+        'Funding model \'participant-funded\' is reserved and not yet implemented.',
+        'UNSUPPORTED_FUNDING_MODEL', { fundingModel }
+      );
+    default:
+      throw new AggregationCohortError(
+        `Unknown funding model: ${fundingModel}.`,
+        'UNKNOWN_FUNDING_MODEL', { fundingModel }
+      );
+  }
+}

package/src/recovery-spend.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 { getNetwork } from '@did-btcr2/bitcoin';
+import { schnorr } from '@noble/curves/secp256k1.js';
+import { p2tr, Transaction } from '@scure/btc-signer';
+import { keyAggExport, keyAggregate, sortKeys } from '@scure/btc-signer/musig2';
+import { AggregationCohortError } from './errors.js';
+import type { FundingModel } from './recovery-policy.js';
+import { DEFAULT_FUNDING_MODEL, buildRecoveryLeaves, resolveFallbackThreshold } 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;
+}
+
+/**
+ * Conservative dust floor (satoshis). The standard p2pkh dust limit; a generic
+ * floor below which the recovered output would not be relayable regardless of
+ * the destination script type.
+ */
+const DUST_LIMIT_SATS = 546n;
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+
+/**
+ * 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 function buildRecoverySpend(params: RecoverySpendParams): Transaction {
+  const {
+    cohortKeys, recoverySecretKey, recoveryKey, recoverySequence, fallbackThreshold,
+    fundingModel, network, utxo, destinationAddress, fee, beaconAddress,
+  } = params;
+
+  if(cohortKeys.length === 0) {
+    throw new AggregationCohortError(
+      'Cannot build recovery spend: no cohort keys.',
+      'NO_COHORT_KEYS'
+    );
+  }
+
+  // The recovery leaf commits to recoveryKey; signing it requires the matching
+  // secret. Fail loudly here rather than producing a transaction that cannot
+  // finalize (btc-signer would throw an opaque "No taproot scripts signed").
+  const derivedPub = schnorr.getPublicKey(recoverySecretKey);
+  if(!bytesEqual(derivedPub, recoveryKey)) {
+    throw new AggregationCohortError(
+      'Recovery secret key does not correspond to the committed recovery key.',
+      'RECOVERY_KEY_MISMATCH'
+    );
+  }
+
+  const out = utxo.value - fee;
+  if(out <= 0n) {
+    throw new AggregationCohortError(
+      `Recovery fee ${fee} exceeds UTXO value ${utxo.value}.`,
+      'FEE_EXCEEDS_VALUE', { fee: fee.toString(), value: utxo.value.toString() }
+    );
+  }
+  if(out < DUST_LIMIT_SATS) {
+    throw new AggregationCohortError(
+      `Recovered output ${out} is below the dust limit ${DUST_LIMIT_SATS}; the spend would not relay.`,
+      'DUST_OUTPUT', { output: out.toString(), dustLimit: DUST_LIMIT_SATS.toString() }
+    );
+  }
+
+  // Reconstruct the funded output. sortKeys mirrors the cohort's key ordering so
+  // the aggregate internal key (and therefore the address and control block)
+  // match the UTXO being spent.
+  const internalKey = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey, recoverySequence, cohortKeys,
+    fallbackThreshold : resolveFallbackThreshold(fallbackThreshold, cohortKeys.length),
+  });
+  const net = getNetwork(network);
+  // allowUnknownOutputs: the CSV recovery leaf is a custom script (see cohort.ts).
+  const payment = p2tr(internalKey, leaves, net, true);
+
+  // Catch a caller mismatch up front: if the reconstructed address does not match
+  // the cohort's funded address, the witnessUtxo script would not match the chain
+  // and the spend would be unspendable.
+  if(beaconAddress !== undefined && payment.address !== beaconAddress) {
+    throw new AggregationCohortError(
+      `Reconstructed beacon address ${payment.address} does not match the cohort's funded address ${beaconAddress}.`,
+      'BEACON_ADDRESS_MISMATCH', { reconstructed: payment.address, expected: beaconAddress }
+    );
+  }
+
+  // allowUnknownInputs: the CSV recovery leaf is a custom (non-template) script,
+  // so btc-signer's finalizer treats it as 'unknown' and will only assemble the
+  // witness for it under this flag (it then signs "what we can": our single
+  // recovery signature). version 2 activates BIP-68 relative timelocks.
+  const tx = new Transaction({ version: 2, allowUnknownInputs: true });
+  // Only tapLeafScript is set (no tapInternalKey): btc-signer then skips the
+  // key-path branch and signs the recovery leaf with recoverySecretKey. The
+  // input nSequence carries the BIP-68 relative timelock the leaf enforces.
+  tx.addInput({
+    txid          : utxo.txid,
+    index         : utxo.vout,
+    witnessUtxo   : { script: payment.script, amount: utxo.value },
+    tapLeafScript : payment.tapLeafScript,
+    sequence      : recoverySequence,
+  });
+  tx.addOutputAddress(destinationAddress, out, net);
+  tx.signIdx(recoverySecretKey, 0);
+  tx.finalize();
+  return tx;
+}

package/src/runner/aggregation-runner.ts

@@ -0,0 +1,125 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { bytesToHex } from '@noble/hashes/utils';
+import { DEFAULT_FUNDING_MODEL, DEFAULT_RECOVERY_SEQUENCE } from '../recovery-policy.js';
+import type { AggregationResult } from '../service.js';
+import { InMemoryBus, InMemoryTransport } from '../transport/in-memory.js';
+import { AggregationParticipantRunner } from './participant-runner.js';
+import type { OnProvideUpdate } from './participant-runner.js';
+import { AggregationServiceRunner } from './service-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 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 async solo(options: SoloCohortOptions): Promise<AggregationResult> {
+    const transport = new InMemoryTransport(new InMemoryBus());
+    transport.registerActor(options.service.did, options.service.keys);
+    transport.registerActor(options.participant.did, options.participant.keys);
+    // Pre-register communication keys both ways. Production exchanges these via
+    // the protocol handshake; in-process we wire them directly.
+    transport.registerPeer(options.participant.did, options.participant.keys.publicKey.compressed);
+    transport.registerPeer(options.service.did, options.service.keys.publicKey.compressed);
+    transport.start();
+
+    // In a solo run the service actor is the operator and holds full keys, so it
+    // can both advertise the recovery terms and, if ever needed, perform the
+    // recovery. Default the recovery key to the service's own x-only key.
+    const recoveryKey = options.config.recoveryKey
+      ?? bytesToHex(options.service.keys.publicKey.compressed.slice(1));
+    const recoverySequence = options.config.recoverySequence ?? DEFAULT_RECOVERY_SEQUENCE;
+
+    const service = new AggregationServiceRunner({
+      transport,
+      did                    : options.service.did,
+      keys                   : options.service.keys,
+      config                 : { minParticipants: 1, network: options.config.network, beaconType: options.config.beaconType, recoveryKey, recoverySequence, fundingModel: DEFAULT_FUNDING_MODEL },
+      onProvideTxData        : options.onProvideTxData,
+      feeEstimator           : options.feeEstimator,
+      cohortTtlMs            : options.cohortTtlMs,
+      phaseTimeoutMs         : options.phaseTimeoutMs,
+      // In-process bus with the participant already listening: a single advert
+      // suffices, so disable the republish loop (no dangling interval).
+      advertRepeatIntervalMs : 0,
+    });
+
+    const participant = new AggregationParticipantRunner({
+      transport,
+      did             : options.participant.did,
+      keys            : options.participant.keys,
+      shouldJoin      : async () => true,
+      onProvideUpdate : options.onProvideUpdate,
+    });
+
+    await participant.start();
+    try {
+      return await service.run();
+    } finally {
+      participant.stop();
+      service.stop();
+    }
+  }
+}