@did-btcr2/method 0.36.1 → 0.38.0

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

@@ -11,7 +11,7 @@ export type ShouldJoin = (advert: CohortAdvert) => Promise<boolean>;
 export type OnProvideUpdate = (info: {
     cohortId: string;
     beaconAddress: string;
-}) => Promise<SignedBTCR2Update>;
+}) => Promise<SignedBTCR2Update | null>;
 /** Decision callback: approve or reject aggregated data. */
 export type OnValidateData = (info: PendingValidation) => Promise<{
     approved: boolean;
@@ -33,7 +33,7 @@ export interface AggregationParticipantRunnerOptions {
     shouldJoin?: ShouldJoin;
     /**
      * Provide a signed BTCR2 update for the cohort.
-     * REQUIRED — no sensible default.
+     * REQUIRED - no sensible default.
      */
     onProvideUpdate: OnProvideUpdate;
     /**
@@ -110,7 +110,7 @@ export declare class AggregationParticipantRunner extends TypedEventEmitter<Aggr
      *
      * 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
+     * `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).

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

@@ -1 +1 @@
-{"version":3,"file":"participant-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/participant-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAUzD,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpE,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEjC,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEzF,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE/F,MAAM,WAAW,mCAAmC;IAClD,4BAA4B;IAC5B,SAAS,EAAE,SAAS,CAAC;IAErB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB,CAAC,4BAA4B,CAAC;;IAC/F,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;gBAY7B,OAAO,EAAE,mCAAmC;IAexD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,8EAA8E;IAC9E,IAAI,IAAI,IAAI;IA4BZ;;;;OAIG;WACU,SAAS,CACpB,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,kBAAkB,CAAC;IAY9B;;;;;;;;;;;;;;;OAeG;WACU,YAAY,CACvB,OAAO,EAAE,mCAAmC,EAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,EAAE,CAAC;CA+NjC"}
+{"version":3,"file":"participant-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/participant-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAWzD,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpE,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,KAAK,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;AAExC,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEzF,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE/F,MAAM,WAAW,mCAAmC;IAClD,4BAA4B;IAC5B,SAAS,EAAE,SAAS,CAAC;IAErB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB,CAAC,4BAA4B,CAAC;;IAC/F,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;gBAY7B,OAAO,EAAE,mCAAmC;IAexD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,8EAA8E;IAC9E,IAAI,IAAI,IAAI;IA6BZ;;;;OAIG;WACU,SAAS,CACpB,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,kBAAkB,CAAC;IAY9B;;;;;;;;;;;;;;;OAeG;WACU,YAAY,CACvB,OAAO,EAAE,mCAAmC,EAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAiRjC"}

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

@@ -2,6 +2,7 @@ import type { SchnorrKeyPair } from '@did-btcr2/keypair';
 import type { AggregationResult, CohortConfig, PendingOptIn, SigningTxData } from '../service.js';
 import { AggregationService } from '../service.js';
 import type { Transport } from '../transport/transport.js';
+import type { FeeEstimator } from '../../beacon/fee-estimator.js';
 import type { AggregationServiceEvents } from './events.js';
 import { TypedEventEmitter } from './typed-emitter.js';
 /** Decision callback: accept or reject a participant's opt-in. */
@@ -20,6 +21,13 @@ export type OnProvideTxData = (info: {
     cohortId: string;
     beaconAddress: string;
     signalBytes: Uint8Array;
+    /**
+     * Fee estimator the runner is configured with (the runner's `feeEstimator`
+     * option, or a static 5 sat/vB default). Forward it to the beacon transaction
+     * builder so a dynamic rate injected at the runner is honored, rather than
+     * hard-coding a rate inside this callback (ADR 045).
+     */
+    feeEstimator: FeeEstimator;
 }) => Promise<SigningTxData>;
 export interface AggregationServiceRunnerOptions {
     /** Underlying transport (NostrTransport, MockTransport, etc.). */
@@ -47,9 +55,17 @@ export interface AggregationServiceRunnerOptions {
     onReadyToFinalize?: OnReadyToFinalize;
     /**
      * Provide the Bitcoin transaction data to sign.
-     * REQUIRED — no sensible default.
+     * REQUIRED - no sensible default.
      */
     onProvideTxData: OnProvideTxData;
+    /**
+     * Fee estimator passed to {@link OnProvideTxData} so the beacon transaction the
+     * callback builds is sized at a chosen rate. Inject a dynamic estimator (a mempool
+     * API or Bitcoin Core `estimatesmartfee`) here as the single standard point for
+     * fee-rate selection, instead of hard-coding a rate inside the callback (ADR 045).
+     * Defaults to a static 5 sat/vB estimator.
+     */
+    feeEstimator?: FeeEstimator;
     /**
      * Maximum canonicalized byte-length of a signed update body. Submissions
      * above this cap are rejected and surfaced via the `message-rejected` event.
@@ -73,7 +89,7 @@ export interface AggregationServiceRunnerOptions {
     /**
      * Re-publish COHORT_ADVERT on this interval until a cohort's keygen is
      * finalized. Works around relays that don't backfill historical events to
-     * late subscribers — a republish gives late joiners a window to discover the
+     * late subscribers - a republish gives late joiners a window to discover the
      * advert without protocol changes. The first publish is immediate;
      * subsequent publishes fire every `advertRepeatIntervalMs` until that
      * cohort's keygen completes, fails, or is stopped. Defaults to
@@ -81,6 +97,16 @@ export interface AggregationServiceRunnerOptions {
      * once and never retry.
      */
     advertRepeatIntervalMs?: number;
+    /**
+     * When a cohort stalls (phase timeout) while the optimistic n-of-n signing
+     * round is in flight, fall back to the k-of-n script path instead of failing
+     * the cohort (graceful liveness, ADR 042). Off by default: enabling it trades a
+     * cheaper/private key-path spend for a larger script-path spend whenever the
+     * optimistic round does not complete in time. A stall outside the signing
+     * phases still fails the cohort. Operators can also drive the fallback
+     * explicitly via {@link AggregationServiceRunner.triggerFallback}.
+     */
+    autoFallbackOnStall?: boolean;
 }
 /** Default cadence for re-publishing COHORT_ADVERT until keygen completes: 60 seconds. */
 export declare const DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 60000;
@@ -93,7 +119,7 @@ export declare const DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 60000;
  *
  * A single runner is a long-lived multiplexer: it advertises and drives many
  * cohorts concurrently over one transport. Each advertised cohort owns an
- * independent completion promise and fails in isolation — a stalled or failed
+ * independent completion promise and fails in isolation - a stalled or failed
  * cohort never settles its siblings (see ADR 040). Use
  * {@link AggregationServiceRunner.advertiseCohort} for the multi-cohort path;
  * {@link AggregationServiceRunner.run} is a thin single-cohort convenience over
@@ -108,8 +134,9 @@ export declare const DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 60000;
  *   transport,
  *   did: serviceDid,
  *   keys: serviceKeys,
- *   onProvideTxData: async ({ cohortId, beaconAddress, signalBytes }) => {
- *     return await buildBeaconTransaction(beaconAddress, signalBytes, bitcoin);
+ *   onProvideTxData: async ({ beaconAddress, signalBytes, feeEstimator }) => {
+ *     // Forward feeEstimator so a dynamic rate injected at the runner is honored.
+ *     return await buildBeaconTransaction(beaconAddress, signalBytes, bitcoin, feeEstimator);
  *   },
  * });
  *
@@ -170,6 +197,21 @@ export declare class AggregationServiceRunner extends TypedEventEmitter<Aggregat
      * @returns {Promise<AggregationResult[]>} Results of the cohorts that completed.
      */
     runAll(): Promise<AggregationResult[]>;
+    /**
+     * Abandon the optimistic n-of-n key path for a cohort and collect k-of-n
+     * fallback (script-path) signatures instead (ADR 042). Idempotent and safe
+     * against the optimistic completion: it commits the cohort to the fallback
+     * path synchronously (the `committedPath` latch) before sending anything, so a
+     * late optimistic signature can no longer complete-and-broadcast a competing
+     * spend of the same UTXO. No-op if the cohort is unknown, already settled, or
+     * already committed to a path.
+     *
+     * Wired automatically to the phase-stall timer when `autoFallbackOnStall` is
+     * set; otherwise call it from an operator decision (a UI "fall back now"
+     * action). Throws only if the underlying state machine rejects the transition
+     * (e.g. signing has not started).
+     */
+    triggerFallback(cohortId: string): Promise<void>;
     /**
      * Stop a single cohort early without affecting the rest of the runner. Drops
      * the cohort's state machine state; its `completion` promise rejects with a

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

@@ -1 +1 @@
-{"version":3,"file":"service-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/service-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAWzD,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,aAAa,EAAC,MAAM,eAAe,CAAC;AACtC,OAAO,EACL,kBAAkB,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEtF,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAErC,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,UAAU,CAAC;CACzB,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE7B,MAAM,WAAW,+BAA+B;IAC9C,kEAAkE;IAClE,SAAS,EAAE,SAAS,CAAC;IAErB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IAErB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,0FAA0F;AAC1F,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAqCxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,wBAAyB,SAAQ,iBAAiB,CAAC,wBAAwB,CAAC;;IACvF,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAiBzB,OAAO,EAAE,+BAA+B;IAyCpD;;;;;;;;;OASG;IACH,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;KAAE;IA6CnG;;;;;;OAMG;IACH,GAAG,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAcjC;;;;;;;;;;OAUG;IACG,MAAM,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAiI5C;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IASlC;;;;OAIG;IACH,IAAI,IAAI,IAAI;CAyQb"}
+{"version":3,"file":"service-runner.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/runner/service-runner.ts"],"names":[],"mappings":"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"}

package/dist/types/core/aggregation/service.d.ts

@@ -31,8 +31,19 @@ export interface ValidationProgress {
 /** Final aggregation result for a cohort. */
 export interface AggregationResult {
     cohortId: string;
+    /**
+     * The 64-byte aggregated MuSig2 signature for the optimistic key path. Empty
+     * for a `script-path` result: the k-of-n fallback embeds k separate signatures
+     * directly in the witness of {@link signedTx}, with no single aggregate sig.
+     */
     signature: Uint8Array;
     signedTx: Transaction;
+    /**
+     * Which Taproot spend path produced {@link signedTx}: `key-path` is the
+     * optimistic n-of-n MuSig2 spend, `script-path` is the k-of-n fallback (ADR
+     * 042). Absent is treated as `key-path` for backward compatibility.
+     */
+    path?: 'key-path' | 'script-path';
 }
 /** Transaction data needed to start a signing session. */
 export interface SigningTxData {
@@ -95,7 +106,7 @@ export declare class AggregationService {
     drainRejections(cohortId: string): Array<Rejection>;
     /**
      * Create a new cohort with the given config. Returns the cohort ID.
-     * Cohort starts in `Created` phase — call `advertise()` to broadcast.
+     * Cohort starts in `Created` phase - call `advertise()` to broadcast.
      */
     createCohort(config: CohortConfig): string;
     /**
@@ -125,7 +136,7 @@ export declare class AggregationService {
     validationProgress(cohortId: string): ValidationProgress;
     /**
      * Start a signing session by creating auth requests for all participants.
-     * The caller provides the transaction data — typically built via
+     * The caller provides the transaction data - typically built via
      * `buildBeaconTransaction()` against a Bitcoin connection.
      */
     startSigning(cohortId: string, txData: SigningTxData): BaseMessage[];
@@ -134,6 +145,19 @@ export declare class AggregationService {
      * Call after `validationProgress(cohortId).approved.size === total`.
      */
     sendAggregatedNonce(cohortId: string): BaseMessage[];
+    /**
+     * Abandon the optimistic n-of-n key path and ask members to authorize the
+     * k-of-n fallback (script-path) spend of the SAME beacon transaction (graceful
+     * liveness, ADR 042). Reuses the in-flight signing session's transaction and
+     * spent output, so the announcement and its outputs are unchanged: only the
+     * witness path differs. Returns one FALLBACK_AUTHORIZATION_REQUEST per
+     * participant.
+     *
+     * Callable once optimistic signing has started (the session and its tx exist)
+     * and before it completes. A cohort can take exactly one of the two paths: the
+     * caller (runner) must commit to fallback and stop driving the optimistic path.
+     */
+    startFallbackSigning(cohortId: string): BaseMessage[];
     getResult(cohortId: string): AggregationResult | undefined;
     getCohortPhase(cohortId: string): ServiceCohortPhaseType | undefined;
     getCohort(cohortId: string): AggregationCohort | undefined;

package/dist/types/core/aggregation/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAGvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAA4B,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKlF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAoBtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,UAAU,CAAC;IAC1B,eAAe,EAAE,UAAU,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,EAAE,UAAU,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;CACnC;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,kBAAkB,GAClB,4BAA4B,GAC5B,kBAAkB,CAAC;AAEvB,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,EAAE,eAAe,CAAC;IACtB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAqBD,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,QAAa,CAAC;AAExD,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,SAAS,EAAE,4BAA4B,CAAC;IACxC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAkB;;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,4BAA4B,CAAC;IACjD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;gBAKxB,EAAE,GAAG,EAAE,SAAS,EAAE,kBAAkB,EAAE,EAAE,wBAAwB;IAO5E,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IA+CnC;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC;IASnD;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IA8B1C;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IA2B1C,kDAAkD;IAClD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAwClE;;;OAGG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,WAAW,EAAE;IAwC1E;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IA4C/C,6CAA6C;IAC7C,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAgL1E;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAwCnD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB;IAwCxD;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,EAAE;IAgEpE;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IA6DpD;;;;;;;;;;;OAWG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAkIrD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAI1D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS;IAIpE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAI1D;;;;OAIG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzD,IAAI,OAAO,IAAI,aAAa,CAAC,iBAAiB,CAAC,CAE9C;IAED;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAGrC"}

package/dist/types/core/aggregation/signing-session.d.ts

@@ -32,11 +32,11 @@ export declare class BeaconSigningSession {
     prevOutScripts: Uint8Array[];
     /** Previous output values for Taproot sighash computation. */
     prevOutValues: bigint[];
-    /** Map of participant publicKey-hex → public nonce contribution. */
+    /** Map of participant publicKey-hex to public nonce contribution. */
     nonceContributions: Map<PublicKeyHex, Nonce>;
     /** Aggregated MuSig2 nonce (66 bytes). */
     aggregatedNonce?: Uint8Array;
-    /** Map of participant DID → partial signature. */
+    /** Map of participant DID to partial signature. */
     partialSignatures: Map<string, Uint8Array>;
     /** Final 64-byte Schnorr signature. */
     signature?: Uint8Array;

package/dist/types/core/aggregation/signing-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signing-session.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/signing-session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D,KAAK,YAAY,GAAG,MAAM,CAAC;AAC3B,KAAK,KAAK,GAAG,UAAU,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,WAAW,CAAC;IACvB,cAAc,CAAC,EAAE,UAAU,EAAE,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;;IAC/B,kDAAkD;IAC3C,EAAE,EAAE,MAAM,CAAC;IAElB,yCAAyC;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAEjC,4CAA4C;IACrC,SAAS,EAAE,WAAW,CAAC;IAE9B,yEAAyE;IAClE,cAAc,EAAE,UAAU,EAAE,CAAC;IAEpC,8DAA8D;IACvD,aAAa,EAAE,MAAM,EAAE,CAAC;IAE/B,oEAAoE;IAC7D,kBAAkB,EAAE,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAa;IAEhE,0CAA0C;IACnC,eAAe,CAAC,EAAE,UAAU,CAAC;IAEpC,kDAAkD;IAC3C,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAa;IAE9D,uCAAuC;IAChC,SAAS,CAAC,EAAE,UAAU,CAAC;IAE9B,qCAAqC;IAC9B,KAAK,EAAE,uBAAuB,CAAC;gBAW1B,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,EAAE,oBAAoB;IAS1F;;OAEG;IACH,IAAI,OAAO,IAAI,UAAU,CAaxB;IAEM,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE,UAAU,GAAG,IAAI;IAgCjF,uBAAuB,IAAI,UAAU;IAYrC,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IA0BzE,sBAAsB,IAAI,UAAU;IA4D3C;;;OAGG;IACI,yBAAyB,CAAC,oBAAoB,EAAE,UAAU,EAAE,oBAAoB,EAAE,UAAU,GAAG,UAAU;IAOhH;;;;;;;;;OASG;IACI,wBAAwB,CAAC,oBAAoB,EAAE,UAAU,GAAG,UAAU;IAqB7E;;;;;OAKG;IACI,YAAY,IAAI,IAAI;IAOpB,UAAU,IAAI,OAAO;IAIrB,QAAQ,IAAI,OAAO;CAG3B"}
+{"version":3,"file":"signing-session.d.ts","sourceRoot":"","sources":["../../../../src/core/aggregation/signing-session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D,KAAK,YAAY,GAAG,MAAM,CAAC;AAC3B,KAAK,KAAK,GAAG,UAAU,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,WAAW,CAAC;IACvB,cAAc,CAAC,EAAE,UAAU,EAAE,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;;IAC/B,kDAAkD;IAC3C,EAAE,EAAE,MAAM,CAAC;IAElB,yCAAyC;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAEjC,4CAA4C;IACrC,SAAS,EAAE,WAAW,CAAC;IAE9B,yEAAyE;IAClE,cAAc,EAAE,UAAU,EAAE,CAAC;IAEpC,8DAA8D;IACvD,aAAa,EAAE,MAAM,EAAE,CAAC;IAE/B,qEAAqE;IAC9D,kBAAkB,EAAE,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAa;IAEhE,0CAA0C;IACnC,eAAe,CAAC,EAAE,UAAU,CAAC;IAEpC,mDAAmD;IAC5C,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAa;IAE9D,uCAAuC;IAChC,SAAS,CAAC,EAAE,UAAU,CAAC;IAE9B,qCAAqC;IAC9B,KAAK,EAAE,uBAAuB,CAAC;gBAW1B,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,EAAE,oBAAoB;IAS1F;;OAEG;IACH,IAAI,OAAO,IAAI,UAAU,CAaxB;IAEM,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE,UAAU,GAAG,IAAI;IAgCjF,uBAAuB,IAAI,UAAU;IAYrC,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IA0BzE,sBAAsB,IAAI,UAAU;IA4D3C;;;OAGG;IACI,yBAAyB,CAAC,oBAAoB,EAAE,UAAU,EAAE,oBAAoB,EAAE,UAAU,GAAG,UAAU;IAOhH;;;;;;;;;OASG;IACI,wBAAwB,CAAC,oBAAoB,EAAE,UAAU,GAAG,UAAU;IAqB7E;;;;;OAKG;IACI,YAAY,IAAI,IAAI;IAOpB,UAAU,IAAI,OAAO;IAIrB,QAAQ,IAAI,OAAO;CAG3B"}

package/dist/types/core/aggregation/transport/http/envelope.d.ts

@@ -26,7 +26,7 @@ export interface VerifyEnvelopeOptions {
 /**
  * Build a {@link SignedEnvelope} around `message`.
  *
- * Pure function — no I/O beyond `randomBytes` for nonce generation (which
+ * Pure function - no I/O beyond `randomBytes` for nonce generation (which
  * uses the platform's cryptographic RNG: `crypto.getRandomValues` in browsers,
  * `node:crypto` in Node). Deterministic when both `nonce` and `timestamp` are
  * supplied via {@link SignEnvelopeOptions}.
@@ -40,7 +40,7 @@ export declare function signEnvelope(message: EnvelopeMessage, sender: {
  * communication public key. Throws {@link HttpTransportError} on any failure;
  * returns normally on success.
  *
- * Does NOT check nonce uniqueness — replay protection is the caller's
+ * Does NOT check nonce uniqueness - replay protection is the caller's
  * responsibility (the server-side transport maintains an LRU cache).
  */
 export declare function verifyEnvelope(envelope: SignedEnvelope, senderPk: CompressedSecp256k1PublicKey, opts?: VerifyEnvelopeOptions): void;
@@ -51,7 +51,7 @@ export declare function verifyEnvelope(envelope: SignedEnvelope, senderPk: Compr
  *
  * Without this, `JSON.stringify` serializes a `Uint8Array` as an index-keyed
  * object (`{"0":1,"1":2,...}`), which `canonicalize` then re-parses into a
- * plain object — the receiver cannot reconstruct the original bytes even
+ * plain object - the receiver cannot reconstruct the original bytes even
  * though the signature still verifies.
  */
 export declare function normalizeForWire(value: unknown): unknown;

package/dist/types/core/aggregation/transport/http/inbox-buffer.d.ts

@@ -12,7 +12,7 @@ export interface StoredEvent {
  * When a subscriber (re)connects with a `Last-Event-ID` header, the server
  * uses {@link since} to replay everything that arrived while the subscriber
  * was disconnected. Events older than the replay window (evicted from the
- * ring) are unrecoverable — callers should choose `capacity` based on
+ * ring) are unrecoverable - callers should choose `capacity` based on
  * expected message rate × acceptable reconnect window.
  */
 export declare class InboxBuffer {

package/dist/types/core/aggregation/transport/http/nonce-cache.d.ts

@@ -5,7 +5,7 @@ export interface NonceCacheConfig {
 /**
  * Bounded anti-replay cache for `(did, nonce)` pairs.
  *
- * Replay windowing is the caller's responsibility — this cache only detects
+ * Replay windowing is the caller's responsibility - this cache only detects
  * duplicates. Callers are expected to reject envelopes/headers whose timestamp
  * is outside the clock-skew window *before* consulting the cache, so entries
  * here are always within the protocol's acceptable window.

package/dist/types/core/aggregation/transport/http/rate-limiter.d.ts

@@ -29,7 +29,7 @@ export interface RateLimiterConfig {
  * sender DID). Tokens refill linearly at `rps` up to `burst`. Each `consume`
  * call atomically debits one token or returns `false` to reject.
  *
- * The limiter is synchronous and deterministic given `nowMs` — tests can
+ * The limiter is synchronous and deterministic given `nowMs` - tests can
  * drive it with a fixed clock to exercise exact boundaries.
  */
 export declare class RateLimiter {

package/dist/types/core/aggregation/transport/http/request-auth.d.ts

@@ -32,7 +32,7 @@ export interface BuildRequestAuthOptions {
 export declare function buildRequestAuth(did: string, keys: SchnorrKeyPair, path: string, opts?: BuildRequestAuthOptions): string;
 /**
  * Parse a `BTCR2-Sig` auth header value into its structured fields. Does NOT
- * verify the signature — call {@link verifyRequestAuth} for that.
+ * verify the signature: call {@link verifyRequestAuth} for that.
  */
 export declare function parseRequestAuth(headerValue: string): ParsedRequestAuth;
 export interface VerifyRequestAuthOptions {

package/dist/types/core/aggregation/transport/http/server.d.ts

@@ -65,7 +65,7 @@ export interface HttpServerTransportConfig {
     now?: () => number;
 }
 /**
- * Server-side HTTP transport. Sans-I/O — the caller mounts
+ * Server-side HTTP transport. Sans-I/O - the caller mounts
  * {@link handleRequest} and {@link handleSse} under their HTTP framework of
  * choice; the transport owns only in-memory state (actors, inboxes, advert
  * cache, replay / rate-limit policies).

package/dist/types/core/aggregation/transport/http/sse-stream.d.ts

@@ -1,7 +1,7 @@
 /**
  * Parsed Server-Sent Events record.
  *
- * Events without a `data` field are never yielded (per the SSE spec — only a
+ * Events without a `data` field are never yielded (per the SSE spec - only a
  * blank line that follows at least one `data:` line dispatches an event).
  */
 export interface SseEvent {
@@ -23,7 +23,7 @@ export interface SseEvent {
  * CR-only line terminators are not supported (every mainstream SSE
  * implementation emits LF or CRLF).
  *
- * Pure, runtime-agnostic — works anywhere `ReadableStream<Uint8Array>` and
+ * Pure, runtime-agnostic - works anywhere `ReadableStream<Uint8Array>` and
  * `TextDecoder` exist (browsers and Node 22+).
  *
  * The caller owns stream lifecycle: cancellation should be effected via an

package/dist/types/core/aggregation/transport/http/sse-writer.d.ts

@@ -1,7 +1,7 @@
 /**
  * Format an SSE event frame. Pairs with {@link parseSseStream}.
  *
- * Multi-line `data` is split across multiple `data:` lines per the SSE spec —
+ * Multi-line `data` is split across multiple `data:` lines per the SSE spec -
  * each embedded `\n` becomes its own line, and the parser rejoins them.
  *
  * The returned string includes a trailing blank line (the dispatch marker).

package/dist/types/core/aggregation/transport/in-memory.d.ts

@@ -4,7 +4,7 @@ import type { MessageHandler, Transport } from './transport.js';
 /**
  * In-process message bus connecting one or more {@link InMemoryTransport}
  * instances. Routes broadcasts to every registered actor and directed messages
- * to the actor that owns the recipient DID — with no relay, server, or network.
+ * to the actor that owns the recipient DID, with no relay, server, or network.
  *
  * Each delivery does a JSON round-trip (Uint8Array preserved as `__bytes` hex)
  * so handlers receive an isolated, serialization-faithful copy, exactly as a

package/dist/types/core/aggregation/transport/nostr.d.ts

@@ -38,9 +38,9 @@ export declare const DEFAULT_BROADCAST_LOOKBACK_MS: number;
  * sending or receiving.
  *
  * Message routing:
- * - Keygen messages (COHORT_ADVERT, COHORT_OPT_IN, COHORT_OPT_IN_ACCEPT, COHORT_READY) → kind 1 (plaintext)
- * - Update messages (SUBMIT_UPDATE, DISTRIBUTE_AGGREGATED_DATA, VALIDATION_ACK) → kind 1059 (NIP-44 encrypted)
- * - Sign messages → kind 1059 (NIP-44 encrypted)
+ * - Keygen messages (COHORT_ADVERT, COHORT_OPT_IN, COHORT_OPT_IN_ACCEPT, COHORT_READY) to kind 1 (plaintext)
+ * - Update messages (SUBMIT_UPDATE, DISTRIBUTE_AGGREGATED_DATA, VALIDATION_ACK) to kind 1059 (NIP-44 encrypted)
+ * - Sign messages to kind 1059 (NIP-44 encrypted)
  *
  * @class NostrTransport
  * @implements {Transport}
@@ -145,7 +145,7 @@ export declare class NostrTransport implements Transport {
      * backfill historical events to late subscribers: republishing gives late
      * joiners a window to discover the message without requiring protocol
      * changes. Relay rate-limit / publish failures inside the interval are
-     * caught and logged rather than propagated — the caller should stop the
+     * caught and logged rather than propagated - the caller should stop the
      * repeater once the protocol condition is satisfied.
      */
     publishRepeating(message: BaseMessage, sender: Did, intervalMs: number, recipient?: Did): () => void;

package/dist/types/core/aggregation/transport/transport.d.ts

@@ -11,7 +11,7 @@ export type TransportType = 'nostr' | 'didcomm' | 'http';
  * shared by all registered actors. Each actor registers its own DID and keys;
  * the transport resolves the correct identity when sending or receiving messages.
  *
- * The transport is a pure passthrough — it knows nothing about the aggregation
+ * The transport is a pure passthrough: it knows nothing about the aggregation
  * protocol. It only signs/encrypts outgoing messages with the sender's keys and
  * dispatches incoming messages to the correct actor's registered handler.
  *
@@ -19,7 +19,7 @@ export type TransportType = 'nostr' | 'didcomm' | 'http';
  */
 export interface Transport {
     name: string;
-    /** Start the underlying transport (idempotent — only starts once). */
+    /** Start the underlying transport (idempotent, only starts once). */
     start(): void;
     /** Register an actor (service or participant) with this transport. */
     registerActor(did: string, keys: SchnorrKeyPair): void;
@@ -48,14 +48,14 @@ export interface Transport {
      * message is satisfied).
      *
      * Useful for broadcasts on transports that don't reliably backfill
-     * historical events to late subscribers (many Nostr relays) — republishing
+     * historical events to late subscribers (many Nostr relays): republishing
      * gives late joiners a window in which to discover the message. The first
      * publish is synchronous-ish (fired before the method returns).
      *
      * Callers specify `recipient` only for directed messages; for broadcasts
      * it is omitted.
      *
-     * @returns A stop function. Idempotent — safe to call more than once.
+     * @returns A stop function. Idempotent, safe to call more than once.
      */
     publishRepeating(message: BaseMessage, sender: string, intervalMs: number, recipient?: string): () => void;
 }

package/dist/types/core/aggregation/transport/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEtE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IAEb,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAAC;IAEd,sEAAsE;IACtE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAEvD,uEAAuE;IACvE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEhD,4EAA4E;IAC5E,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D,yDAAyD;IACzD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAE/C,6DAA6D;IAC7D,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7F,uEAAuE;IACvE,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtE;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,6EAA6E;IAC7E,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CACd,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,IAAI,CAAC;CACf"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEtE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IAEb,qEAAqE;IACrE,KAAK,IAAI,IAAI,CAAC;IAEd,sEAAsE;IACtE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAEvD,uEAAuE;IACvE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEhD,4EAA4E;IAC5E,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D,yDAAyD;IACzD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAE/C,6DAA6D;IAC7D,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7F,uEAAuE;IACvE,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtE;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,6EAA6E;IAC7E,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CACd,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,IAAI,CAAC;CACf"}

package/dist/types/core/beacon/beacon.d.ts

@@ -9,25 +9,25 @@ import type { FeeEstimator } from './fee-estimator.js';
 import type { BeaconService, BeaconSignal } from './interfaces.js';
 /**
  * Singleton beacon script kinds. Per the did:btcr2 spec, deterministic DID documents
- * include three beacon services: P2PKH, P2WPKH, and P2TR (taproot key-path) — all
+ * include three beacon services: P2PKH, P2WPKH, and P2TR (taproot key-path), all
  * derived from the genesis secp256k1 public key. The singleton broadcast path must
  * support signing for all three.
  */
 export type SingletonScriptKind = 'p2pkh' | 'p2wpkh' | 'p2tr';
 /**
- * Conservative vsize estimate for a 1-input P2TR key-path → 1 P2TR change + 1 OP_RETURN(32) tx.
+ * Conservative vsize estimate for a 1-input P2TR key-path to 1 P2TR change + 1 OP_RETURN(32) tx.
  * Stripped 137 + witness ≈ 68 (marker + flag + stack-count + sig-len + 64 BIP-340 sig).
  * Weight = 137*4 + 68 = 616, vsize ≈ 154, rounded to 160 for headroom.
  */
 export declare const P2TR_BEACON_TX_VSIZE = 160;
 /**
- * Conservative vsize estimate for a 1-input P2WPKH → 1 P2WPKH change + 1 OP_RETURN(32) tx.
+ * Conservative vsize estimate for a 1-input P2WPKH to 1 P2WPKH change + 1 OP_RETURN(32) tx.
  * Stripped 125 + witness ≈ 110 (worst-case DER ECDSA sig 72 + sighash byte + 33 pubkey + framing).
  * vsize = ceil((125*4 + 110) / 4) ≈ 153, rounded to 155.
  */
 export declare const P2WPKH_BEACON_TX_VSIZE = 155;
 /**
- * Conservative vsize estimate for a 1-input P2PKH → 1 P2PKH change + 1 OP_RETURN(32) tx.
+ * Conservative vsize estimate for a 1-input P2PKH to 1 P2PKH change + 1 OP_RETURN(32) tx.
  * Legacy (non-segwit): scriptSig carries the full sig+pubkey (~108 bytes), no witness
  * discount. Stripped ≈ 4 nVer + 1 vin-count + (32+4+1+108+4) input + 1 vout-count +
  * 34 P2PKH-change + 43 OP_RETURN + 4 nLockTime ≈ 236 bytes. vsize = 236, rounded to 240.
@@ -35,6 +35,37 @@ export declare const P2WPKH_BEACON_TX_VSIZE = 155;
 export declare const P2PKH_BEACON_TX_VSIZE = 240;
 /** Per-kind vsize lookup for singleton beacon fee estimation. */
 export declare const SINGLETON_BEACON_TX_VSIZE: Readonly<Record<SingletonScriptKind, number>>;
+/**
+ * Serialized size (vbytes) of a single change output, by script kind:
+ * 8 (value) + 1 (scriptPubKey length) + scriptPubKey bytes. P2PKH 25, P2WPKH 22,
+ * P2TR 34. These are non-witness bytes, so each contributes its full byte count to
+ * the transaction vsize. The {@link SINGLETON_BEACON_TX_VSIZE} constants bake in a
+ * same-kind change output; {@link beaconTxVsize} uses these deltas to re-size the
+ * fee when a caller routes change to an address of a different kind (ADR 044).
+ */
+export declare const CHANGE_OUTPUT_VBYTES: Readonly<Record<SingletonScriptKind, number>>;
+/**
+ * Dust threshold (sats) below which a change output is not worth creating, by script
+ * kind (the standard Bitcoin Core dust relay thresholds at the default 3 sat/vB dust
+ * rate). When the change after fees falls below this, the builders omit the change
+ * output and let the remainder fall into the fee rather than emit an unspendable,
+ * relay-rejected dust output (ADR 044).
+ */
+export declare const DUST_LIMIT_SATS: Readonly<Record<SingletonScriptKind, number>>;
+/**
+ * vsize (vbytes) for a beacon transaction that spends one input of `beaconKind`
+ * and returns change to an output of `changeKind`, plus the OP_RETURN(32) signal.
+ *
+ * When `changeKind === beaconKind` (the default, change to the beacon address) this
+ * returns the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant unchanged, so the
+ * default path and the constants' lock-in tests are byte-identical. A differing
+ * `changeKind` swaps the assumed same-kind change output for the actual one, keeping
+ * the result a valid upper bound. The aggregation key-path spend is the
+ * `beaconKind: 'p2tr'` case (its input is always the cohort's P2TR key path; only the
+ * change output varies), the analytical sizing ADR 045 calls for, computed without a
+ * secret.
+ */
+export declare function beaconTxVsize(beaconKind: SingletonScriptKind, changeKind: SingletonScriptKind): number;
 /**
  * Detect the singleton script kind of a Bitcoin address (P2PKH / P2WPKH / P2TR).
  * The deterministic-DID document emits all three kinds; the broadcast path needs
@@ -47,12 +78,26 @@ export declare function detectSingletonScriptKind(bitcoinAddress: string, networ
  * pubkey cannot actually spend.
  */
 export declare function deriveSingletonAddress(kind: SingletonScriptKind, pubkey: KeyBytes, network: BTCNetwork): string;
+/**
+ * Resolve the change-output recipient for a beacon transaction. Returns the beacon
+ * address when no change address is supplied (preserving the prior behavior of
+ * returning change to the spent address), otherwise validates the caller-supplied
+ * address against the network and returns it. Validating here fails fast rather than
+ * burning a real UTXO on a transaction that breaks at broadcast (ADR 044).
+ */
+export declare function resolveChangeAddress(beaconAddress: string, network: BTCNetwork, changeAddress?: string): string;
 /**
  * Options accepted by {@link SinglePartyBeacon.buildSignAndBroadcast} and related helpers.
  */
 export interface BroadcastOptions {
     /** Fee estimator for computing the transaction fee. Defaults to {@link DEFAULT_FEE_ESTIMATOR}. */
     feeEstimator?: FeeEstimator;
+    /**
+     * Address to send change to. Defaults to the beacon address (reuses the spent
+     * address, the prior behavior). Supply a fresh address the controller owns to
+     * stop linking the beacon's announcements into one on-chain chain (ADR 044).
+     */
+    changeAddress?: string;
 }
 /**
  * Unsigned beacon transaction + the prev-output metadata needed for downstream
@@ -65,8 +110,10 @@ export interface BeaconTxPlan {
     prevOutScripts: Uint8Array[];
     /** Amounts (sats) of the consumed previous outputs. */
     prevOutValues: bigint[];
-    /** Address change was sent back to (same as the beacon address). */
+    /** The beacon address this tx spends from. */
     beaconAddress: string;
+    /** Address the change output was sent to (the beacon address unless a change address was supplied). */
+    changeAddress: string;
     /** The UTXO this tx consumes. */
     utxo: AddressUtxo;
     /** The fee (sats) already deducted from the change output. */
@@ -97,7 +144,7 @@ export declare function opReturnScript(signalBytes: Uint8Array): Uint8Array;
  * signing session consumes (via {@link SigningTxData}).
  *
  * This is the reusable counterpart to {@link SinglePartyBeacon.buildSignAndBroadcast}'s internal
- * construction step — the aggregation path must produce an unsigned tx because the
+ * construction step: the aggregation path must produce an unsigned tx because the
  * signature comes from a MuSig2 round, not a local secret key.
  *
  * @param opts Parameters including the cohort's aggregate internal pubkey.
@@ -116,6 +163,13 @@ export declare function buildAggregationBeaconTx(opts: {
     network: BTCNetwork;
     /** Optional fee estimator (defaults to 5 sat/vB). */
     feeEstimator?: FeeEstimator;
+    /**
+     * Address to send change to. Defaults to the beacon (cohort) address. Supply the
+     * funder's address (an operator-funded cohort's funding wallet) to stop reusing the
+     * cohort address for change (ADR 044). Change ownership is the funder's call, which
+     * the cohort-condition model leaves to the caller (ADR 039).
+     */
+    changeAddress?: string;
 }): Promise<BeaconTxPlan>;
 /**
  * Abstract base class providing the single-party broadcast machinery shared by
@@ -170,7 +224,7 @@ export declare abstract class SinglePartyBeacon {
      *
      * Composed from the three extracted phases ({@link buildSinglePartyTx},
      * {@link signSinglePartyTx}, {@link broadcastRawTx}) so each piece can be exercised
-     * in isolation. Aggregation beacons use {@link buildAggregationBeaconTx} instead —
+     * in isolation. Aggregation beacons use {@link buildAggregationBeaconTx} instead:
      * the multi-party path can't share the signing phase, but the tx-construction
      * plumbing (UTXO fetch + OP_RETURN output + change output) is shared.
      *
@@ -187,10 +241,11 @@ export declare abstract class SinglePartyBeacon {
      *
      * Detects the beacon address script kind (P2PKH / P2WPKH / P2TR) and configures
      * the input accordingly. Validates that the signer's pubkey produces the beacon
-     * address under that script kind — without this check, a misconfigured caller
+     * address under that script kind: without this check, a misconfigured caller
      * would burn a real UTXO on a tx that fails at broadcast. Fees are computed from
-     * the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant, avoiding any probe-sign
-     * round-trip.
+     * the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant (via {@link beaconTxVsize}),
+     * avoiding any probe-sign round-trip; a change address of a different kind re-sizes
+     * the fee by the change output's size delta so it stays a valid upper bound.
      */
     protected buildSinglePartyTx(opts: {
         signalBytes: Uint8Array;
@@ -200,6 +255,7 @@ export declare abstract class SinglePartyBeacon {
         signer: Signer;
         bitcoin: BitcoinConnection;
         feeEstimator: FeeEstimator;
+        changeAddress?: string;
     }): Promise<BeaconTxPlan>;
     /**
      * Sign + finalize the unsigned single-party tx and return its raw hex.

package/dist/types/core/beacon/beacon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAA4D,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC1G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKnE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAInF,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,UAAU,GAClB,mBAAmB,CAWrB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,UAAU,GAClB,MAAM,CAKR;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,EAAE,EAAE,WAAW,CAAC;IAChB,6EAA6E;IAC7E,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,uDAAuD;IACvD,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,IAAI,EAAE,WAAW,CAAC;IAClB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,mBAAmB,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,UAAU,GAAG,UAAU,CAElE;AA4BD;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,cAAc,EAAE,UAAU,CAAC;IAC3B,8DAA8D;IAC9D,WAAW,EAAE,UAAU,CAAC;IACxB,yDAAyD;IACzD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,iEAAiE;IACjE,OAAO,EAAE,UAAU,CAAC;IACpB,qDAAqD;IACrD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,GAAG,OAAO,CAAC,YAAY,CAAC,CAwCxB;AAkFD;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,iBAAiB;IACrC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;gBAEpB,OAAO,EAAE,aAAa;IAIlC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CACrB,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IAEtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,eAAe,CACtB,YAAY,EAAE,iBAAiB,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;IAE7B;;;;;;;;;;;;;;;;;OAiBG;cACa,qBAAqB,CACnC,WAAW,EAAE,UAAU,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC;IAWlB;;;;;;;;;OASG;cACa,kBAAkB,CAAC,IAAI,EAAE;QACvC,WAAW,EAAE,UAAU,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,WAAW,CAAC;QAClB,WAAW,EAAE,UAAU,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,iBAAiB,CAAC;QAC3B,YAAY,EAAE,YAAY,CAAC;KAC5B,GAAG,OAAO,CAAC,YAAY,CAAC;IA0EzB;;;OAGG;cACa,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOtF;;OAEG;cACa,cAAc,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAG5F"}
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/beacon.ts"],"names":[],"mappings":"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"}