@did-btcr2/method 0.28.0 → 0.32.0

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

@@ -1,6 +1,7 @@
 import type { Did } from '@did-btcr2/common';
 import type { SchnorrKeyPair } from '@did-btcr2/keypair';
 import { SimplePool } from 'nostr-tools/pool';
+import type { Logger } from '../logger.js';
 import type { BaseMessage } from '../messages/base.js';
 import type { MessageHandler, Transport } from './transport.js';
 /**
@@ -10,7 +11,24 @@ import type { MessageHandler, Transport } from './transport.js';
 export declare const DEFAULT_NOSTR_RELAYS: string[];
 export interface NostrTransportConfig {
     relays?: string[];
+    /**
+     * Optional logger for transport-level diagnostics (publish/subscribe events,
+     * relay rejections, parse failures). Defaults to {@link CONSOLE_LOGGER}.
+     */
+    logger?: Logger;
+    /**
+     * How far back (in milliseconds) to set the `since` filter on the broadcast
+     * (COHORT_ADVERT) subscription. Some public relays do NOT replay historical
+     * events to late subscribers when the filter has no `since`, so the advert
+     * gets lost if the subscription lands after the publish. A short lookback
+     * window nudges those relays into delivering recent adverts. Set to 0 to
+     * disable the filter entirely (unbounded history). Defaults to
+     * {@link DEFAULT_BROADCAST_LOOKBACK_MS} (5 minutes).
+     */
+    broadcastLookbackMs?: number;
 }
+/** Default `since` lookback for broadcast (COHORT_ADVERT) subscriptions: 5 minutes. */
+export declare const DEFAULT_BROADCAST_LOOKBACK_MS: number;
 /**
  * Nostr Transport for did:btcr2 aggregation messages.
  *
@@ -41,15 +59,95 @@ export declare class NostrTransport implements Transport {
      * @example
      * const transport = new NostrTransport();
      * const keys = SchnorrKeyPair.generate();
-     * transport.registerActor('did:btcr2:...', keys);
+     * const did = DidBtcr2.create(keys.publicKey.compressed, { idType: 'KEY', network: 'mutinynet' });
+     * transport.registerActor(did, keys);
      * transport.start();
      */
     registerActor(did: string, keys: SchnorrKeyPair): void;
+    /**
+     * Detach an actor: drop its handlers, close its relay subscriptions, and remove its keys + peer
+     * mapping. Idempotent.
+     * @param {string} did - The DID of the actor to unregister.
+     * @returns {void}
+     * @throws {TransportAdapterError} If the transport is not started or if the pool is unavailable.
+     * @example
+     * transport.unregisterActor(did);
+     */
+    unregisterActor(did: string): void;
+    /**
+     * Remove a single (actor, messageType) handler. Idempotent.
+     * @param {string} actorDid - The DID of the actor.
+     * @param {string} messageType - The type of message to unregister the handler for.
+     * @returns {void}
+     * @example
+     * transport.unregisterMessageHandler(actorDid, messageType);
+     */
+    unregisterMessageHandler(actorDid: string, messageType: string): void;
+    /**
+     * Gets the public key for a registered actor by their DID.
+     * @param {string} did - The DID of the registered actor to get the public key for.
+     * @returns {Uint8Array | undefined} The compressed public key bytes for the actor's DID, or
+     * undefined if the DID is not registered.
+     */
     getActorPk(did: string): Uint8Array | undefined;
+    /**
+     * Registers a peer's communication public key for encrypted messages.
+     * @param {string} did - The DID of the peer to register.
+     * @param {Uint8Array} communicationPk - The compressed secp256k1 public key bytes for the peer.
+     */
     registerPeer(did: string, communicationPk: Uint8Array): void;
+    /**
+     * Gets the registered communication public key for a peer by their DID.
+     * @param {string} did - The DID of the peer to get the communication public key for.
+     * @returns {Uint8Array | undefined} The compressed secp256k1 public key bytes for the peer, or
+     * undefined if the peer is not registered.
+     */
     getPeerPk(did: string): Uint8Array | undefined;
+    /**
+     * Registers a message handler function for a specific actor and message type. The handler will be called
+     * when a message of the specified type is received for the actor's DID. The transport must have been
+     * started for handlers to be invoked. If the transport is already started, the handler will be registered
+     * immediately; otherwise, it will be registered when the transport starts and the actor's subscription is created.
+     * @param {string} actorDid - The DID of the actor to register the message handler for.
+     * @param {string} messageType - The type of message to handle.
+     * @param {MessageHandler} handler - The function to handle incoming messages of the specified type.
+     * @throws {TransportAdapterError} If the actor DID is not registered or if the handler is invalid.
+     */
     registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void;
+    /**
+     * Starts the transport by connecting to the configured Nostr relays and setting up subscriptions
+     * for all registered actors. This method must be called after registering actors via registerActor()
+     * and before sending or receiving messages. The transport will subscribe to broadcast events (kind 1)
+     * for cohort adverts and directed events (kinds 1 and 1059) for each registered actor based on their
+     * public keys. Incoming events are processed and dispatched to the appropriate handlers based on
+     * message type. If the transport is already started, this method has no effect.
+     * @returns {NostrTransport}
+     */
     start(): NostrTransport;
+    /**
+     * Sends a message by publishing a Nostr event to the configured relays. The message is serialized
+     * as JSON and included in the event content.
+     * @param {BaseMessage} message - The aggregation message to send. Must include a valid `type` property.
+     * @param {Did} sender - The DID of the registered actor sending the message. Must have been
+     * registered via registerActor().
+     * @param {Did} [to] - Optional recipient DID for directed messages. Required for encrypted message
+     * types. If provided, must have been registered via registerPeer().
+     * @returns {Promise<void>} Resolves when the message has been published to the relays. Note that
+     * publication is best-effort: the method will resolve as long as at least one relay accepts the
+     * event, even if others reject it.
+     */
     sendMessage(message: BaseMessage, sender: Did, to?: Did): Promise<void>;
+    /**
+     * Publish the message once immediately and then re-publish on an interval
+     * until the returned stop function is invoked.
+     *
+     * Useful for broadcast messages (COHORT_ADVERT) on relays that don't
+     * 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
+     * repeater once the protocol condition is satisfied.
+     */
+    publishRepeating(message: BaseMessage, sender: Did, intervalMs: number, recipient?: Did): () => void;
 }
 //# sourceMappingURL=nostr.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"nostr.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/nostr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAQD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,SAAS;;IAC9C,IAAI,EAAE,MAAM,CAAW;IAEvB,IAAI,CAAC,EAAE,UAAU,CAAC;gBAMN,MAAM,CAAC,EAAE,oBAAoB;IAIzC;;;;;;;;;;;OAWG;IACI,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAUtD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI;IAY5D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9C,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAW5F,KAAK,IAAI,cAAc;IAsBjB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;CAkMrF"}
+{"version":3,"file":"nostr.d.ts","sourceRoot":"","sources":["../../../../../src/core/aggregation/transport/nostr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,uFAAuF;AACvF,eAAO,MAAM,6BAA6B,QAAgB,CAAC;AAU3D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,SAAS;;IAC9C,IAAI,EAAE,MAAM,CAAW;IAEvB,IAAI,CAAC,EAAE,UAAU,CAAC;gBAQN,MAAM,CAAC,EAAE,oBAAoB;IAMzC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAUtD;;;;;;;;OAQG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAYlC;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAMrE;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI;IAY5D;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9C;;;;;;;;;OASG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAW5F;;;;;;;;OAQG;IACH,KAAK,IAAI,cAAc;IAsCvB;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAmF7E;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,GAAG,MAAM,IAAI;CAwNrG"}

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

@@ -3,7 +3,7 @@ import type { BaseMessage } from '../messages/base.js';
 export type SyncMessageHandler = (msg: any) => void;
 export type AsyncMessageHandler = (msg: any) => Promise<void>;
 export type MessageHandler = SyncMessageHandler | AsyncMessageHandler;
-export type TransportType = 'nostr' | 'didcomm';
+export type TransportType = 'nostr' | 'didcomm' | 'http';
 /**
  * Multi-actor message transport.
  *
@@ -31,7 +31,32 @@ export interface Transport {
     getPeerPk(did: string): Uint8Array | undefined;
     /** Register a message handler scoped to a specific actor. */
     registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void;
+    /** Remove a previously-registered handler. No-op if not registered. */
+    unregisterMessageHandler(actorDid: string, messageType: string): void;
+    /**
+     * Detach an actor: unregister all its handlers, drop its keys, and close any
+     * transport-level subscriptions created for it. No-op if the actor is not
+     * registered.
+     */
+    unregisterActor(did: string): void;
     /** Send a message. The transport looks up sender to resolve signing keys. */
     sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void>;
+    /**
+     * Publish the message once immediately and then repeat it on a fixed
+     * interval. Returns a stop function the caller MUST invoke when the repeat
+     * is no longer needed (e.g. once the protocol state that required the
+     * message is satisfied).
+     *
+     * Useful for broadcasts on transports that don't reliably backfill
+     * 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.
+     */
+    publishRepeating(message: BaseMessage, sender: string, intervalMs: number, recipient?: string): () => void;
 }
 //# sourceMappingURL=transport.d.ts.map

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,CAAC;AAEhD;;;;;;;;;;;;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,6EAA6E;IAC7E,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF"}
+{"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"}

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

@@ -1,17 +1,122 @@
-import type { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type { AddressUtxo, BitcoinConnection, BTCNetwork } from '@did-btcr2/bitcoin';
 import type { KeyBytes } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
+import { Transaction } from '@scure/btc-signer';
 import type { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { FeeEstimator } from './fee-estimator.js';
 import type { BeaconService, BeaconSignal } from './interfaces.js';
 /**
- * Options accepted by {@link Beacon.buildSignAndBroadcast}.
+ * Singleton beacon script kinds. Per the did:btcr2 spec, deterministic DID documents
+ * 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.
+ * 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.
+ * 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.
+ * 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.
+ */
+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>>;
+/**
+ * Detect the singleton script kind of a Bitcoin address (P2PKH / P2WPKH / P2TR).
+ * The deterministic-DID document emits all three kinds; the broadcast path needs
+ * to know which is in use to construct the input and dispatch the signing primitive.
+ */
+export declare function detectSingletonScriptKind(bitcoinAddress: string, network: BTCNetwork): SingletonScriptKind;
+/**
+ * Derive the address that `pubkey` produces under the given script kind. Used to
+ * fail-fast when a caller wires a signer to a beacon address that the signer's
+ * pubkey cannot actually spend.
+ */
+export declare function deriveSingletonAddress(kind: SingletonScriptKind, pubkey: KeyBytes, network: BTCNetwork): string;
+/**
+ * Options accepted by {@link Beacon.buildSignAndBroadcast} and related helpers.
  */
 export interface BroadcastOptions {
     /** Fee estimator for computing the transaction fee. Defaults to {@link DEFAULT_FEE_ESTIMATOR}. */
     feeEstimator?: FeeEstimator;
 }
+/**
+ * Unsigned beacon transaction + the prev-output metadata needed for downstream
+ * signing (single-party ECDSA or multi-party MuSig2 Taproot).
+ */
+export interface BeaconTxPlan {
+    /** The unsigned scure @scure/btc-signer Transaction. */
+    tx: Transaction;
+    /** Scripts of the consumed previous outputs (needed for Taproot sighash). */
+    prevOutScripts: Uint8Array[];
+    /** Amounts (sats) of the consumed previous outputs. */
+    prevOutValues: bigint[];
+    /** Address change was sent back to (same as the beacon address). */
+    beaconAddress: string;
+    /** The UTXO this tx consumes. */
+    utxo: AddressUtxo;
+    /** The fee (sats) already deducted from the change output. */
+    feeSats: bigint;
+    /**
+     * Singleton beacon script kind, when applicable. Drives the signing dispatch
+     * in {@link Beacon.signSinglePartyTx}. Aggregation plans set this to `'p2tr'`.
+     */
+    scriptKind: SingletonScriptKind;
+}
+/**
+ * Build an OP_RETURN script carrying a 32-byte beacon signal.
+ * Exported as a utility so callers building txs outside Beacon (e.g., the aggregation
+ * `onProvideTxData` callback) can produce identical output.
+ *
+ * Uses the opcode *string* `'RETURN'` rather than the numeric `OP.RETURN`
+ * constant because scure's `Script.encode` interprets a number as a byte to
+ * push, not as the opcode. The string form emits the bare opcode (0x6a)
+ * followed by an `OP_PUSHBYTES_32` push, producing the standard NULL_DATA
+ * shape Bitcoin Core's `IsStandard` accepts. The numeric form silently
+ * produces `OP_PUSHBYTES_1 0x6a OP_PUSHBYTES_32 <32 bytes>`, which is
+ * non-standard and rejected at broadcast with `RPC error -26: scriptpubkey`.
+ */
+export declare function opReturnScript(signalBytes: Uint8Array): Uint8Array;
+/**
+ * Build an aggregation beacon transaction (P2TR key-path spend) ready for MuSig2 signing.
+ * Returns the unsigned Transaction + prev-output metadata that an aggregation service's
+ * signing session consumes (via {@link SigningTxData}).
+ *
+ * This is the reusable counterpart to {@link Beacon.buildSignAndBroadcast}'s internal
+ * 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.
+ * @returns A {@link BeaconTxPlan} with the unsigned tx and sighash inputs.
+ */
+export declare function buildAggregationBeaconTx(opts: {
+    /** The beacon (cohort) address where UTXOs live and change returns to. */
+    beaconAddress: string;
+    /** The cohort's MuSig2-aggregated x-only internal pubkey (32 bytes). */
+    internalPubkey: Uint8Array;
+    /** 32-byte beacon signal embedded in the OP_RETURN output. */
+    signalBytes: Uint8Array;
+    /** Bitcoin REST connection for UTXO / prev-tx lookup. */
+    bitcoin: BitcoinConnection;
+    /** Network params used to derive the P2TR witnessUtxo script. */
+    network: BTCNetwork;
+    /** Optional fee estimator (defaults to 5 sat/vB). */
+    feeEstimator?: FeeEstimator;
+}): Promise<BeaconTxPlan>;
 /**
  * Abstract base class for all BTCR2 Beacon types.
  * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
@@ -49,37 +154,59 @@ export declare abstract class Beacon {
      * Broadcasts a signed update as a Beacon Signal to the Bitcoin network.
      * Used during the update path.
      * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
-     * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+     * @param {Signer} signer Signer that produces the signature for the spending input.
+     *   ECDSA for P2PKH / P2WPKH singletons, Schnorr (BIP-340) for P2TR key-path.
      * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
      * @param {BroadcastOptions} [options] Optional broadcast configuration (e.g. fee estimator).
      * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
      */
-    abstract broadcastSignal(signedUpdate: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<SignedBTCR2Update>;
+    abstract broadcastSignal(signedUpdate: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<SignedBTCR2Update>;
     /**
-     * Shared PSBT construction + signing + broadcast helper used by all beacon types.
+     * Build + sign + broadcast a singleton beacon signal transaction. The beacon
+     * address's script kind (P2PKH / P2WPKH / P2TR) is detected automatically
+     * and the input is constructed and signed accordingly.
      *
-     * Steps:
-     * 1. Parse the beacon's `serviceEndpoint` (stripping `bitcoin:` prefix) into a Bitcoin address.
-     * 2. Query the address for unconfirmed/confirmed UTXOs.
-     * 3. Select the most recent confirmed UTXO.
-     * 4. Fetch the previous transaction hex for `nonWitnessUtxo`.
-     * 5. Build a PSBT: input (UTXO) → change output + OP_RETURN(signalBytes).
-     * 6. Compute the fee via the supplied (or default) {@link FeeEstimator} against the tx vsize.
-     * 7. Sign input 0 with an ECDSA signer derived from `secretKey`.
-     * 8. Finalize, extract, and broadcast via the REST transaction endpoint.
-     *
-     * Fee handling: the PSBT is constructed with a placeholder change amount, signed to measure
-     * vsize, then the change is adjusted to pay the actual fee and the input re-signed. This
-     * two-pass approach avoids hardcoded fee constants and produces a tx that matches the
-     * estimator's rate.
+     * 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 —
+     * the multi-party path can't share the signing phase, but the tx-construction
+     * plumbing (UTXO fetch + OP_RETURN output + change output) is shared.
      *
      * @param signalBytes 32-byte payload to embed in OP_RETURN.
-     * @param secretKey Secret key used to sign the spending input.
+     * @param signer Signer used to sign the spending input.
      * @param bitcoin Bitcoin network connection.
      * @param options Broadcast options (fee estimator, etc.).
      * @returns The txid of the broadcast transaction.
-     * @throws {BeaconError} if the address is unfunded or no UTXO is available.
+     * @throws {BeaconError} if the address is unfunded, no UTXO is available, or fee exceeds value.
+     */
+    protected buildSignAndBroadcast(signalBytes: Uint8Array, signer: Signer, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<string>;
+    /**
+     * Build an unsigned singleton beacon tx ready for {@link signSinglePartyTx}.
+     *
+     * 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
+     * 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.
+     */
+    protected buildSinglePartyTx(opts: {
+        signalBytes: Uint8Array;
+        beaconAddress: string;
+        utxo: AddressUtxo;
+        prevTxBytes: Uint8Array;
+        signer: Signer;
+        bitcoin: BitcoinConnection;
+        feeEstimator: FeeEstimator;
+    }): Promise<BeaconTxPlan>;
+    /**
+     * Sign + finalize the unsigned single-party tx and return its raw hex.
+     * Dispatches to the correct signing primitive based on `plan.scriptKind`.
+     */
+    protected signSinglePartyTx(plan: BeaconTxPlan, signer: Signer): Promise<string>;
+    /**
+     * Broadcast raw transaction hex via the Bitcoin REST endpoint. Returns the txid.
      */
-    protected buildSignAndBroadcast(signalBytes: Uint8Array, secretKey: KeyBytes, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<string>;
+    protected broadcastRawTx(bitcoin: BitcoinConnection, rawHex: string): Promise<string>;
 }
 //# sourceMappingURL=beacon.d.ts.map

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,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAIhE,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;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,MAAM;IAC1B;;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;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CACtB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,QAAQ,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;cACa,qBAAqB,CACnC,WAAW,EAAE,UAAU,EACvB,SAAS,EAAE,QAAQ,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC;CAsEnB"}
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/beacon.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,6 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { KeyBytes } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
@@ -56,13 +56,13 @@ export declare class CASBeacon extends Beacon {
      * and broadcast are delegated to {@link Beacon.buildSignAndBroadcast}.
      *
      * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
-     * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+     * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
      * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
      * @param {CASBroadcastOptions} [options] Optional broadcast configuration, including a
      *   `casPublish` callback to publish the announcement off-chain and a `feeEstimator`.
      * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
      * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
      */
-    broadcastSignal(signedUpdate: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection, options?: CASBroadcastOptions): Promise<SignedBTCR2Update>;
+    broadcastSignal(signedUpdate: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection, options?: CASBroadcastOptions): Promise<SignedBTCR2Update>;
 }
 //# sourceMappingURL=cas-beacon.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cas-beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/cas-beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAiB,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAU,SAAQ,MAAM;IACnC;;;OAGG;gBACS,OAAO,EAAE,aAAa;IAIlC;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IAsDtB;;;;;;;;;;;;;;;OAeG;IACG,eAAe,CACnB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,QAAQ,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,iBAAiB,CAAC;CAuB9B"}
+{"version":3,"file":"cas-beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/cas-beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAiB,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAU,SAAQ,MAAM;IACnC;;;OAGG;gBACS,OAAO,EAAE,aAAa;IAIlC;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IAsDtB;;;;;;;;;;;;;;;OAeG;IACG,eAAe,CACnB,YAAY,EAAE,iBAAiB,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,iBAAiB,CAAC;CAuB9B"}

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

@@ -1,6 +1,6 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { KeyBytes } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
@@ -33,12 +33,12 @@ export declare class SingletonBeacon extends Beacon {
      * {@link Beacon.buildSignAndBroadcast}.
      *
      * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
-     * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+     * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
      * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
      * @param {BroadcastOptions} [options] Optional broadcast configuration (e.g. fee estimator).
      * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
      * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
      */
-    broadcastSignal(signedUpdate: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<SignedBTCR2Update>;
+    broadcastSignal(signedUpdate: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<SignedBTCR2Update>;
 }
 //# sourceMappingURL=singleton-beacon.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"singleton-beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/singleton-beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAiB,MAAM,iBAAiB,CAAC;AAElF;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,MAAM;IAEzC;;;OAGG;gBACS,OAAO,EAAE,aAAa;IAIlC;;;;;OAKG;IACH,cAAc,CACZ,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IA0BtB;;;;;;;;;;;;;OAaG;IACG,eAAe,CACnB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,QAAQ,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;CAK9B"}
+{"version":3,"file":"singleton-beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/singleton-beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAiB,MAAM,iBAAiB,CAAC;AAElF;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,MAAM;IAEzC;;;OAGG;gBACS,OAAO,EAAE,aAAa;IAIlC;;;;;OAKG;IACH,cAAc,CACZ,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IA0BtB;;;;;;;;;;;;;OAaG;IACG,eAAe,CACnB,YAAY,EAAE,iBAAiB,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;CAK9B"}

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

@@ -1,6 +1,6 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { KeyBytes } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
@@ -47,12 +47,12 @@ export declare class SMTBeacon extends Beacon {
      * signing, and broadcast are delegated to {@link Beacon.buildSignAndBroadcast}.
      *
      * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
-     * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+     * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
      * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
      * @param {BroadcastOptions} [options] Optional broadcast configuration (e.g. fee estimator).
      * @return {Promise<SignedBTCR2Update>} The signed update that was broadcast.
      * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
      */
-    broadcastSignal(signedUpdate: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<SignedBTCR2Update>;
+    broadcastSignal(signedUpdate: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection, options?: BroadcastOptions): Promise<SignedBTCR2Update>;
 }
 //# sourceMappingURL=smt-beacon.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"smt-beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/smt-beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAiB,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;;GAWG;AACH,qBAAa,SAAU,SAAQ,MAAM;IACnC;;;OAGG;gBACS,OAAO,EAAE,aAAa;IAIlC;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IAiEtB;;;;;;;;;;;;;;OAcG;IACG,eAAe,CACnB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,QAAQ,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;CAgB9B"}
+{"version":3,"file":"smt-beacon.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/smt-beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAiB,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;;GAWG;AACH,qBAAa,SAAU,SAAQ,MAAM;IACnC;;;OAGG;gBACS,OAAO,EAAE,aAAa;IAIlC;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,WAAW,GACnB,mBAAmB;IAiEtB;;;;;;;;;;;;;;OAcG;IACG,eAAe,CACnB,YAAY,EAAE,iBAAiB,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;CAgB9B"}

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

@@ -1,5 +1,5 @@
+import type { BTCNetwork } from '@did-btcr2/bitcoin';
 import type { KeyBytes, Maybe } from '@did-btcr2/common';
-import type { networks } from 'bitcoinjs-lib';
 import type { DidDocument } from '../../utils/did-document.js';
 import type { BeaconService } from './interfaces.js';
 /**
@@ -53,7 +53,7 @@ export declare class BeaconUtils {
     static generateBeaconServices({ id, publicKey, network, beaconType }: {
         id: string;
         publicKey: KeyBytes;
-        network: networks.Network;
+        network: BTCNetwork;
         beaconType: string;
     }): Array<BeaconService>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAC,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAC,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAO/C;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO;IAc1D;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,aAAa,EAAE;IAKnE;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IAiBlF;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa;IAsBpH;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;QACpE,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,QAAQ,CAAC;QACpB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,KAAK,CAAC,aAAa,CAAC;IAoCxB;;;;OAIG;IACH,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;IAIvE;;;;OAIG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC;IAQtF;;;;OAIG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;CAG/D"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/core/beacon/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAC,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAO/C;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO;IAc1D;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,aAAa,EAAE;IAKnE;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IAiBlF;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa;IA2BpH;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;QACpE,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,QAAQ,CAAC;QACpB,OAAO,EAAE,UAAU,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,KAAK,CAAC,aAAa,CAAC;IAoCxB;;;;OAIG;IACH,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;IAIvE;;;;OAIG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC;IAQtF;;;;OAIG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;CAG/D"}

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

@@ -1,12 +1,14 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { KeyBytes, PatchOperation } from '@did-btcr2/common';
+import type { PatchOperation } from '@did-btcr2/common';
 import { type SignedBTCR2Update, type UnsignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import { type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
 import type { BeaconService } from './beacon/interfaces.js';
 /**
- * The updater needs the caller to supply a signing key (or a KMS-backed signature)
- * for the given verification method. The unsigned update is attached so the caller
- * can inspect it before producing a signature.
+ * The updater needs the caller to supply a {@link Signer} for the given
+ * verification method. The unsigned update is attached so the caller can
+ * inspect it before producing a signature. The signer can wrap a local secret
+ * key (`LocalSigner`), a KMS-managed key (`KeyManagerSigner`), or any custom backend.
  */
 export interface NeedSigningKey {
     readonly kind: 'NeedSigningKey';
@@ -29,6 +31,18 @@ export interface NeedFunding {
     /** The beacon service this address belongs to. */
     readonly beaconService: BeaconService;
 }
+/**
+ * Optional proof the caller passes when fulfilling {@link NeedFunding}. The
+ * state machine asserts the proof before transitioning to Broadcast. Sans-I/O
+ * is preserved: the caller still performs the UTXO lookup; this is just a
+ * contract-level handshake.
+ */
+export interface FundingProof {
+    /** Number of spendable UTXOs the caller observed at the beacon address. Must be >= 1. */
+    utxoCount: number;
+    /** Optional txid the caller funded with, for diagnostics. */
+    txid?: string;
+}
 /**
  * The updater needs the caller to broadcast the signed update via the beacon.
  *
@@ -86,20 +100,21 @@ export interface UpdaterParams {
  *
  * ```typescript
  * const updater = DidBtcr2.update({ sourceDocument, patches, ... });
+ * const signer = new LocalSigner(secretKeyBytes); // or KeyManagerSigner / custom
  * let state = updater.advance();
  *
  * while(state.status === 'action-required') {
  *   for(const need of state.needs) {
  *     switch(need.kind) {
  *       case 'NeedSigningKey':
- *         updater.provide(need, secretKeyBytes);
+ *         updater.provide(need, signer);
  *         break;
  *       case 'NeedFunding':
  *         // Check UTXOs at need.beaconAddress, fund if needed
  *         updater.provide(need);
  *         break;
  *       case 'NeedBroadcast':
- *         await Updater.announce(need.beaconService, need.signedUpdate, secretKey, bitcoin);
+ *         await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
  *         updater.provide(need);
  *         break;
  *     }
@@ -143,21 +158,21 @@ export declare class Updater {
      * @param {string} did The did-btcr2 identifier to derive the root capability from.
      * @param {UnsignedBTCR2Update} unsignedUpdate The unsigned update to sign.
      * @param {DidVerificationMethod} verificationMethod The verification method for signing.
-     * @param {KeyBytes} secretKey The secret key bytes.
+     * @param {Signer} signer Signer that produces the BIP-340 Schnorr signature.
      * @returns {SignedBTCR2Update} The signed update with a Data Integrity proof.
      */
-    static sign(did: string, unsignedUpdate: UnsignedBTCR2Update, verificationMethod: DidVerificationMethod, secretKey: KeyBytes): SignedBTCR2Update;
+    static sign(did: string, unsignedUpdate: UnsignedBTCR2Update, verificationMethod: DidVerificationMethod, signer: Signer): SignedBTCR2Update;
     /**
      * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#announce-did-update | 7.3.d Announce DID Update}.
      * Announces a signed update to the Bitcoin blockchain via the specified beacon.
      *
      * @param {BeaconService} beaconService The beacon service to broadcast through.
      * @param {SignedBTCR2Update} update The signed update to announce.
-     * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+     * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
      * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
      * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
      */
-    static announce(beaconService: BeaconService, update: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection): Promise<SignedBTCR2Update>;
+    static announce(beaconService: BeaconService, update: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection): Promise<SignedBTCR2Update>;
     /**
      * Advance the state machine. Returns either:
      * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
@@ -171,8 +186,8 @@ export declare class Updater {
      * @param need The DataNeed being fulfilled (from the `needs` array).
      * @param data The data payload corresponding to the need kind (omit for NeedFunding/NeedBroadcast).
      */
-    provide(need: NeedSigningKey, data: KeyBytes): void;
-    provide(need: NeedFunding): void;
+    provide(need: NeedSigningKey, data: Signer): void;
+    provide(need: NeedFunding, proof?: FundingProof): void;
     provide(need: NeedBroadcast): void;
 }
 //# sourceMappingURL=updater.d.ts.map