@did-btcr2/aggregation 0.1.0

package/dist/esm/phases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phases.js","sourceRoot":"","sources":["../../src/phases.ts"],"names":[],"mappings":"AAyBA,MAAM,CAAN,IAAY,kBAeX;AAfD,WAAY,kBAAkB;IAC5B,yCAAmB,CAAA;IACnB,+CAAyB,CAAA;IACzB,6CAAuB,CAAA;IACvB,6DAAuC,CAAA;IACvC,2DAAqC,CAAA;IACrC,yDAAmC,CAAA;IACnC,6CAAuB,CAAA;IACvB,uDAAiC,CAAA;IACjC,yDAAmC,CAAA;IACnC,iEAA2C,CAAA;IAC3C,6FAA6F;IAC7F,6DAAuC,CAAA;IACvC,2CAAqB,CAAA;IACrB,uCAAiB,CAAA;AACnB,CAAC,EAfW,kBAAkB,KAAlB,kBAAkB,QAe7B;AAiBD,MAAM,CAAN,IAAY,sBAgBX;AAhBD,WAAY,sBAAsB;IAChC,mDAAyB,CAAA;IACzB,6CAAmB,CAAA;IACnB,qDAA2B,CAAA;IAC3B,6DAAmC,CAAA;IACnC,+FAA+F;IAC/F,qDAA2B,CAAA;IAC3B,mEAAyC,CAAA;IACzC,2DAAiC,CAAA;IACjC,6DAAmC,CAAA;IACnC,iDAAuB,CAAA;IACvB,mEAAyC,CAAA;IACzC,2FAA2F;IAC3F,qEAA2C,CAAA;IAC3C,+CAAqB,CAAA;IACrB,2CAAiB,CAAA;AACnB,CAAC,EAhBW,sBAAsB,KAAtB,sBAAsB,QAgBjC;AAUD,MAAM,CAAN,IAAY,mBAOX;AAPD,WAAY,mBAAmB;IAC7B,gFAAyD,CAAA;IACzD,gFAAyD,CAAA;IACzD,8EAAuD,CAAA;IACvD,8EAAuD,CAAA;IACvD,4CAAqB,CAAA;IACrB,wCAAiB,CAAA;AACnB,CAAC,EAPW,mBAAmB,KAAnB,mBAAmB,QAO9B"}

package/dist/esm/recovery-policy.js

@@ -0,0 +1,156 @@
+/**
+ * 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';
+/** Default funding model when an advert/config leaves it unspecified. */
+export const DEFAULT_FUNDING_MODEL = '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;
+/** 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) {
+    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, leafVersion = TAPROOT_LEAF_VERSION) {
+    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, n) {
+    return advertised ?? Math.max(1, n - 1);
+}
+function assertFallbackParams({ cohortKeys, fallbackThreshold }) {
+    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) {
+    assertFallbackParams(params);
+    const xOnlyKeys = sortKeys(params.cohortKeys).map(k => k.slice(1));
+    return p2tr_ms(params.fallbackThreshold, xOnlyKeys).script;
+}
+function assertRecoveryParams({ recoveryKey, recoverySequence }) {
+    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) {
+    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, params) {
+    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 });
+    }
+}
+//# sourceMappingURL=recovery-policy.js.map

package/dist/esm/recovery-policy.js.map

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

package/dist/esm/recovery-spend.js

@@ -0,0 +1,106 @@
+/**
+ * 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 { DEFAULT_FUNDING_MODEL, buildRecoveryLeaves, resolveFallbackThreshold } from './recovery-policy.js';
+/**
+ * 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, b) {
+    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) {
+    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;
+}
+//# sourceMappingURL=recovery-spend.js.map

package/dist/esm/recovery-spend.js.map

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

package/dist/esm/runner/aggregation-runner.js

@@ -0,0 +1,75 @@
+import { bytesToHex } from '@noble/hashes/utils';
+import { DEFAULT_FUNDING_MODEL, DEFAULT_RECOVERY_SEQUENCE } from '../recovery-policy.js';
+import { InMemoryBus, InMemoryTransport } from '../transport/in-memory.js';
+import { AggregationParticipantRunner } from './participant-runner.js';
+import { AggregationServiceRunner } from './service-runner.js';
+/**
+ * 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) {
+        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();
+        }
+    }
+}
+//# sourceMappingURL=aggregation-runner.js.map

package/dist/esm/runner/aggregation-runner.js.map

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

package/dist/esm/runner/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/dist/esm/runner/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/runner/events.ts"],"names":[],"mappings":""}

package/dist/esm/runner/index.js

@@ -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.js.map

package/dist/esm/runner/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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"}