@did-btcr2/method 0.28.0 → 0.32.0

package/src/core/beacon/beacon.ts

@@ -1,9 +1,9 @@
-import type { AddressUtxo, 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 { SchnorrKeyPair } from '@did-btcr2/keypair';
-import { hexToBytes } from '@noble/hashes/utils';
-import { opcodes, Psbt, script } from 'bitcoinjs-lib';
+import type { Signer } from '@did-btcr2/keypair';
+import { concatBytes, hexToBytes } from '@noble/hashes/utils.js';
+import { Address, OutScript, p2pkh, p2tr, p2wpkh, Script, SigHash, Transaction } from '@scure/btc-signer';
 import type { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import { BeaconError } from './error.js';
@@ -15,13 +15,301 @@ import type { BeaconService, BeaconSignal } from './interfaces.js';
 const DEFAULT_FEE_ESTIMATOR: FeeEstimator = new StaticFeeEstimator(5);
 
 /**
- * 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 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 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 const P2PKH_BEACON_TX_VSIZE = 240;
+
+/** Per-kind vsize lookup for singleton beacon fee estimation. */
+export const SINGLETON_BEACON_TX_VSIZE: Readonly<Record<SingletonScriptKind, number>> = {
+  p2pkh  : P2PKH_BEACON_TX_VSIZE,
+  p2wpkh : P2WPKH_BEACON_TX_VSIZE,
+  p2tr   : P2TR_BEACON_TX_VSIZE,
+};
+
+/**
+ * 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 function detectSingletonScriptKind(
+  bitcoinAddress: string,
+  network: BTCNetwork,
+): SingletonScriptKind {
+  const decoded = Address(network).decode(bitcoinAddress);
+  if(decoded.type === 'pkh') return 'p2pkh';
+  if(decoded.type === 'wpkh') return 'p2wpkh';
+  if(decoded.type === 'tr') return 'p2tr';
+  throw new BeaconError(
+    `Unsupported singleton beacon address type "${decoded.type}". `
+    + 'Expected P2PKH, P2WPKH, or P2TR (taproot key-path).',
+    'UNSUPPORTED_BEACON_ADDRESS_TYPE',
+    { address: bitcoinAddress, kind: decoded.type }
+  );
+}
+
+/**
+ * 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 function deriveSingletonAddress(
+  kind: SingletonScriptKind,
+  pubkey: KeyBytes,
+  network: BTCNetwork,
+): string {
+  if(kind === 'p2pkh')  return p2pkh(pubkey, network).address!;
+  if(kind === 'p2wpkh') return p2wpkh(pubkey, network).address!;
+  // P2TR key-path: x-only internal key (drop the SEC prefix byte).
+  return p2tr(pubkey.slice(1, 33), undefined, network).address!;
+}
+
+/**
+ * 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 function opReturnScript(signalBytes: Uint8Array): Uint8Array {
+  return Script.encode(['RETURN', signalBytes]);
+}
+
+/**
+ * Fetch the most recent confirmed UTXO at `bitcoinAddress` + the raw bytes of its
+ * parent transaction (needed by PSBT inputs). Throws if unfunded.
+ */
+async function fetchSpendableUtxo(
+  bitcoinAddress: string,
+  bitcoin: BitcoinConnection,
+): Promise<{ utxo: AddressUtxo; prevTxBytes: Uint8Array }> {
+  const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
+  if(!utxos.length) {
+    throw new BeaconError(
+      'No UTXOs found, please fund address!',
+      'UNFUNDED_BEACON_ADDRESS', { address: bitcoinAddress }
+    );
+  }
+  const utxo = utxos.sort((a, b) => b.status.block_height - a.status.block_height).shift();
+  if(!utxo) {
+    throw new BeaconError(
+      'Beacon bitcoin address unfunded or utxos unconfirmed.',
+      'UNFUNDED_BEACON_ADDRESS', { address: bitcoinAddress }
+    );
+  }
+  const prevTxHex = await bitcoin.rest.transaction.getHex(utxo.txid);
+  return { utxo, prevTxBytes: hexToBytes(prevTxHex) };
+}
+
+/**
+ * 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 async 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> {
+  const feeEstimator = opts.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
+  const { utxo, prevTxBytes } = await fetchSpendableUtxo(opts.beaconAddress, opts.bitcoin);
+
+  const tapOut = p2tr(opts.internalPubkey, undefined, opts.network);
+  const witnessScript = tapOut.script;
+
+  // Fee cannot be probe-measured (no secret key for MuSig2 round). Use fixed P2TR vsize.
+  const feeSats = await feeEstimator.estimateFee(P2TR_BEACON_TX_VSIZE);
+  if(BigInt(utxo.value) <= feeSats) {
+    throw new BeaconError(
+      `UTXO value (${utxo.value}) insufficient to cover fee (${feeSats}).`,
+      'INSUFFICIENT_FUNDS',
+      { address: opts.beaconAddress, valueSats: utxo.value, feeSats }
+    );
+  }
+
+  // allowUnknownOutputs: scure does not classify OP_RETURN as a "known" output
+  // type because it is unspendable by design. The opt-in flag tells scure we
+  // know the output is intentional (the beacon signal embedded in OP_RETURN).
+  const tx = new Transaction({ allowUnknownOutputs: true });
+  tx.addInput({
+    txid           : utxo.txid,
+    index          : utxo.vout,
+    nonWitnessUtxo : prevTxBytes,
+    witnessUtxo    : { amount: BigInt(utxo.value), script: witnessScript },
+    tapInternalKey : opts.internalPubkey,
+  });
+  tx.addOutputAddress(opts.beaconAddress, BigInt(utxo.value) - feeSats, opts.network);
+  tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
+
+  return {
+    tx,
+    prevOutScripts : [witnessScript],
+    prevOutValues  : [BigInt(utxo.value)],
+    beaconAddress  : opts.beaconAddress,
+    utxo,
+    feeSats,
+    scriptKind     : 'p2tr',
+  };
+}
+
+/**
+ * Sign the single input of a singleton beacon transaction. Dispatches to the
+ * correct sighash + signature-application path based on `kind`, finalizes the
+ * tx, and returns the signed raw hex.
+ *
+ * - **P2PKH**: legacy ECDSA sighash; scure assembles the scriptSig from `partialSig`.
+ * - **P2WPKH**: BIP-143 segwit-v0 sighash (P2PKH-shaped scriptCode); scure assembles
+ *   the witness from `partialSig`.
+ * - **P2TR**: BIP-341 taproot key-path sighash (SIGHASH_DEFAULT); 64-byte BIP-340
+ *   Schnorr signature applied via `tapKeySig`.
+ */
+async function signSingletonInput(
+  tx: Transaction,
+  inputIdx: number,
+  kind: SingletonScriptKind,
+  signer: Signer,
+  prevOutScript: Uint8Array,
+  amount: bigint,
+): Promise<string> {
+  const pubkey = signer.publicKey;
+
+  if(kind === 'p2pkh') {
+    // Legacy sighash: scriptCode is the prev-output P2PKH script itself.
+    // scure-btc-signer marks `preimageLegacy` as TypeScript-private but does not
+    // expose a public alternative; its own `signIdx` consumes the secret key
+    // directly. We need only the sighash bytes so an external Signer can produce
+    // the signature, so we reach through the type system here. If scure ever
+    // renames this method, the P2PKH path tests fail loudly.
+    // TODO: track https://github.com/paulmillr/scure-btc-signer/issues/142 —
+    // drop the cast once a public preimage (e.g. `preimageP2PKH`) lands upstream.
+    const sighashType = SigHash.ALL;
+    const sighash = (tx as unknown as {
+      preimageLegacy: (idx: number, prevScript: Uint8Array, hashType: number) => Uint8Array;
+    }).preimageLegacy(inputIdx, prevOutScript, sighashType);
+    const sig = signer.sign(sighash, 'ecdsa');
+    const sigWithType = concatBytes(sig, new Uint8Array([sighashType]));
+    tx.updateInput(inputIdx, { partialSig: [[pubkey, sigWithType]] }, true);
+    tx.finalize();
+    return tx.hex;
+  }
+
+  if(kind === 'p2wpkh') {
+    // BIP-143: scriptCode for a P2WPKH input is the equivalent legacy P2PKH script
+    // (`OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG`). The P2PKH-shaped
+    // script appearing here in P2WPKH signing is intentional, not a bug.
+    //
+    // Derive the hash from `prevOutScript` (the bytes actually committed on-chain),
+    // not by re-hashing `signer.publicKey`. BIP-143 commits to the prev output, so
+    // the sighash must follow those bytes exactly. Rebuilding from the signer's
+    // pubkey assumes (rather than verifies) the two are in sync.
+    const decoded = OutScript.decode(prevOutScript);
+    if(decoded.type !== 'wpkh') {
+      throw new BeaconError(
+        `Expected P2WPKH prev-output script, got "${decoded.type}".`,
+        'PREVOUT_SCRIPT_MISMATCH',
+        { kind, observedScriptType: decoded.type }
+      );
+    }
+    const sighashScript = OutScript.encode({ type: 'pkh', hash: decoded.hash });
+    const sighashType = SigHash.ALL;
+    const sighash = tx.preimageWitnessV0(inputIdx, sighashScript, sighashType, amount);
+    const sig = signer.sign(sighash, 'ecdsa');
+    const sigWithType = concatBytes(sig, new Uint8Array([sighashType]));
+    tx.updateInput(inputIdx, { partialSig: [[pubkey, sigWithType]] }, true);
+    tx.finalize();
+    return tx.hex;
+  }
+
+  // P2TR key-path. BIP-341 requires signing with the taproot-tweaked secret
+  // `d' = taprootTweakPrivKey(d, merkleRoot)`; the verifier checks against the
+  // tweaked output internal key `Q = P + tG`. The tweak lives inside the Signer
+  // (it needs the secret key), so we use scheme 'bip341' rather than the raw
+  // 'bip340' scheme. No script tree on singleton beacons → no merkleRoot.
+  const sighash = tx.preimageWitnessV1(inputIdx, [prevOutScript], SigHash.DEFAULT, [amount]);
+  const sig = signer.sign(sighash, 'bip341');
+  tx.updateInput(inputIdx, { tapKeySig: sig });
+  tx.finalize();
+  return tx.hex;
+}
+
 /**
  * Abstract base class for all BTCR2 Beacon types.
  * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
@@ -67,116 +355,160 @@ export 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,
+    signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
   ): Promise<SignedBTCR2Update>;
 
   /**
-   * Shared PSBT construction + signing + broadcast helper used by all beacon types.
-   *
-   * 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.
+   * 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.
    *
-   * 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 async buildSignAndBroadcast(
     signalBytes: Uint8Array,
-    secretKey: KeyBytes,
+    signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
   ): Promise<string> {
     const feeEstimator = options?.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
+    const beaconAddress = this.service.serviceEndpoint.replace('bitcoin:', '');
+    const { utxo, prevTxBytes } = await fetchSpendableUtxo(beaconAddress, bitcoin);
+    const plan = await this.buildSinglePartyTx({
+      signalBytes, beaconAddress, utxo, prevTxBytes, signer, bitcoin, feeEstimator,
+    });
+    const signedHex = await this.signSinglePartyTx(plan, signer);
+    return this.broadcastRawTx(bitcoin, signedHex);
+  }
 
-    // Strip the 'bitcoin:' prefix from the service endpoint.
-    const bitcoinAddress = this.service.serviceEndpoint.replace('bitcoin:', '');
+  /**
+   * 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 async buildSinglePartyTx(opts: {
+    signalBytes: Uint8Array;
+    beaconAddress: string;
+    utxo: AddressUtxo;
+    prevTxBytes: Uint8Array;
+    signer: Signer;
+    bitcoin: BitcoinConnection;
+    feeEstimator: FeeEstimator;
+  }): Promise<BeaconTxPlan> {
+    const network = opts.bitcoin.data;
+    const pubkey = opts.signer.publicKey;
+    const kind = detectSingletonScriptKind(opts.beaconAddress, network);
 
-    // Fetch UTXOs at the beacon address.
-    const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
-    if(!utxos.length) {
+    const derivedAddress = deriveSingletonAddress(kind, pubkey, network);
+    if(derivedAddress !== opts.beaconAddress) {
       throw new BeaconError(
-        'No UTXOs found, please fund address!',
-        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
+        `Signer pubkey produces ${kind.toUpperCase()} address "${derivedAddress}", but beacon address is "${opts.beaconAddress}".`,
+        'SIGNER_KEY_MISMATCH',
+        { kind, address: opts.beaconAddress, derivedAddress }
       );
     }
 
-    // Take the most recently confirmed UTXO.
-    const utxo: AddressUtxo | undefined = utxos.sort(
-      (a, b) => b.status.block_height - a.status.block_height
-    ).shift();
-    if(!utxo) {
+    const feeSats = await opts.feeEstimator.estimateFee(SINGLETON_BEACON_TX_VSIZE[kind]);
+    const amount = BigInt(opts.utxo.value);
+    if(amount <= feeSats) {
       throw new BeaconError(
-        'Beacon bitcoin address unfunded or utxos unconfirmed.',
-        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
+        `UTXO value (${opts.utxo.value}) insufficient to cover fee (${feeSats}).`,
+        'INSUFFICIENT_FUNDS',
+        { address: opts.beaconAddress, valueSats: opts.utxo.value, feeSats }
       );
     }
 
-    // Get the previous tx hex for non-witness UTXO reference.
-    const prevTx = await bitcoin.rest.transaction.getHex(utxo.txid);
-
-    // Build the ECDSA signer from the secret key.
-    const keyPair = SchnorrKeyPair.fromSecret(secretKey);
-    const signer = {
-      publicKey : keyPair.publicKey.compressed,
-      sign      : (hash: Uint8Array) => keyPair.secretKey.sign(hash, { scheme: 'ecdsa' }),
-    };
+    // allowUnknownOutputs: scure does not classify OP_RETURN as a "known" output
+    // type because it is unspendable by design. The opt-in flag tells scure we
+    // know the output is intentional (the beacon signal embedded in OP_RETURN).
+    const tx = new Transaction({ allowUnknownOutputs: true });
 
-    // First pass: build with a placeholder fee (0 sats) so we can measure vsize.
-    const build = (fee: bigint) =>
-      new Psbt({ network: bitcoin.data })
-        .addInput({
-          hash           : utxo.txid,
-          index          : utxo.vout,
-          nonWitnessUtxo : hexToBytes(prevTx),
-        })
-        .addOutput({ address: bitcoinAddress, value: BigInt(utxo.value) - fee })
-        .addOutput({ script: script.compile([opcodes.OP_RETURN, signalBytes]), value: 0n });
-
-    const probeTx = build(0n)
-      .signInput(0, signer)
-      .finalizeAllInputs()
-      .extractTransaction();
-    const vsize = probeTx.virtualSize();
-
-    // Second pass: use the estimator to compute the real fee.
-    const fee = await feeEstimator.estimateFee(vsize);
-    if(BigInt(utxo.value) <= fee) {
-      throw new BeaconError(
-        `UTXO value (${utxo.value}) insufficient to cover fee (${fee}).`,
-        'INSUFFICIENT_FUNDS', { bitcoinAddress, utxoValue: utxo.value, fee: fee.toString() }
-      );
+    // Per-kind input setup: P2PKH consumes via nonWitnessUtxo only (legacy);
+    // P2WPKH and P2TR also carry a witnessUtxo (and P2TR carries tapInternalKey).
+    let prevOutScript: Uint8Array;
+    if(kind === 'p2pkh') {
+      prevOutScript = p2pkh(pubkey, network).script;
+      tx.addInput({
+        txid           : opts.utxo.txid,
+        index          : opts.utxo.vout,
+        nonWitnessUtxo : opts.prevTxBytes,
+      });
+    } else if(kind === 'p2wpkh') {
+      prevOutScript = p2wpkh(pubkey, network).script;
+      tx.addInput({
+        txid           : opts.utxo.txid,
+        index          : opts.utxo.vout,
+        nonWitnessUtxo : opts.prevTxBytes,
+        witnessUtxo    : { amount, script: prevOutScript },
+      });
+    } else {
+      // p2tr key-path
+      const internalKey = pubkey.slice(1, 33);
+      prevOutScript = p2tr(internalKey, undefined, network).script;
+      tx.addInput({
+        txid           : opts.utxo.txid,
+        index          : opts.utxo.vout,
+        nonWitnessUtxo : opts.prevTxBytes,
+        witnessUtxo    : { amount, script: prevOutScript },
+        tapInternalKey : internalKey,
+      });
     }
 
-    const signedTxHex = build(fee)
-      .signInput(0, signer)
-      .finalizeAllInputs()
-      .extractTransaction()
-      .toHex();
+    tx.addOutputAddress(opts.beaconAddress, amount - feeSats, network);
+    tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
 
-    return bitcoin.rest.transaction.send(signedTxHex);
+    return {
+      tx,
+      prevOutScripts : [prevOutScript],
+      prevOutValues  : [amount],
+      beaconAddress  : opts.beaconAddress,
+      utxo           : opts.utxo,
+      feeSats,
+      scriptKind     : kind,
+    };
+  }
+
+  /**
+   * Sign + finalize the unsigned single-party tx and return its raw hex.
+   * Dispatches to the correct signing primitive based on `plan.scriptKind`.
+   */
+  protected async signSinglePartyTx(plan: BeaconTxPlan, signer: Signer): Promise<string> {
+    return signSingletonInput(
+      plan.tx, 0, plan.scriptKind, signer,
+      plan.prevOutScripts[0]!, plan.prevOutValues[0]!,
+    );
   }
-}
+
+  /**
+   * Broadcast raw transaction hex via the Bitcoin REST endpoint. Returns the txid.
+   */
+  protected async broadcastRawTx(bitcoin: BitcoinConnection, rawHex: string): Promise<string> {
+    return bitcoin.rest.transaction.send(rawHex);
+  }
+}

package/src/core/beacon/cas-beacon.ts

@@ -1,7 +1,7 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { KeyBytes } from '@did-btcr2/common';
 import { canonicalHash, canonicalize, decode, encode, hash } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
@@ -118,7 +118,7 @@ export 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`.
@@ -127,7 +127,7 @@ export class CASBeacon extends Beacon {
    */
   async broadcastSignal(
     signedUpdate: SignedBTCR2Update,
-    secretKey: KeyBytes,
+    signer: Signer,
     bitcoin: BitcoinConnection,
     options?: CASBroadcastOptions
   ): Promise<SignedBTCR2Update> {
@@ -144,7 +144,7 @@ export class CASBeacon extends Beacon {
     const announcementHash = hash(canonicalize(casAnnouncement));
 
     // Delegate UTXO selection, PSBT construction, fee estimation, signing, and broadcast
-    await this.buildSignAndBroadcast(announcementHash, secretKey, bitcoin, options);
+    await this.buildSignAndBroadcast(announcementHash, signer, bitcoin, options);
 
     // Publish CAS Announcement to content-addressed store if callback provided
     if(options?.casPublish) {

package/src/core/beacon/singleton-beacon.ts

@@ -1,7 +1,7 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { KeyBytes } from '@did-btcr2/common';
 import { canonicalize, hash } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
 import type { BroadcastOptions } from './beacon.js';
@@ -67,7 +67,7 @@ export 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.
@@ -75,12 +75,12 @@ export class SingletonBeacon extends Beacon {
    */
   async broadcastSignal(
     signedUpdate: SignedBTCR2Update,
-    secretKey: KeyBytes,
+    signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
   ): Promise<SignedBTCR2Update> {
     const signalBytes = hash(canonicalize(signedUpdate));
-    await this.buildSignAndBroadcast(signalBytes, secretKey, bitcoin, options);
+    await this.buildSignAndBroadcast(signalBytes, signer, bitcoin, options);
     return signedUpdate;
   }
 }

package/src/core/beacon/smt-beacon.ts

@@ -1,7 +1,7 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 import { canonicalize } from '@did-btcr2/common';
-import type { KeyBytes } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import { blockHash, BTCR2MerkleTree, didToIndex, hexToHash, verifySerializedProof } from '@did-btcr2/smt';
 import { randomBytes } from '@noble/hashes/utils';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
@@ -122,7 +122,7 @@ export 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.
@@ -130,7 +130,7 @@ export class SMTBeacon extends Beacon {
    */
   async broadcastSignal(
     signedUpdate: SignedBTCR2Update,
-    secretKey: KeyBytes,
+    signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
   ): Promise<SignedBTCR2Update> {
@@ -145,7 +145,7 @@ export class SMTBeacon extends Beacon {
     tree.finalize();
 
     // Root hash is the signal bytes for the OP_RETURN output
-    await this.buildSignAndBroadcast(tree.rootHash, secretKey, bitcoin, options);
+    await this.buildSignAndBroadcast(tree.rootHash, signer, bitcoin, options);
 
     return signedUpdate;
   }