@did-btcr2/method 0.27.0 → 0.29.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 { getPublicKey } from '@noble/secp256k1';
 import { hexToBytes } from '@noble/hashes/utils';
-import { opcodes, Psbt, script } from 'bitcoinjs-lib';
+import { OP, p2tr, p2wpkh, Script, 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,138 @@ import type { BeaconService, BeaconSignal } from './interfaces.js';
 const DEFAULT_FEE_ESTIMATOR: FeeEstimator = new StaticFeeEstimator(5);
 
 /**
- * Options accepted by {@link Beacon.buildSignAndBroadcast}.
+ * Conservative vsize estimate for a 1-input P2TR key-path → 1 P2TR change + 1 OP_RETURN(32) tx.
+ * Taproot key-path witness is a fixed 64-byte Schnorr signature, so vsize is predictable
+ * without having to sign. Used for fee estimation in the aggregation path where MuSig2
+ * signatures are produced externally.
+ */
+const P2TR_BEACON_TX_VSIZE = 140;
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ */
+export function opReturnScript(signalBytes: Uint8Array): Uint8Array {
+  return Script.encode([OP.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', { 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', { 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',
+      { bitcoinAddress: opts.beaconAddress, utxoValue: utxo.value, fee: feeSats.toString() }
+    );
+  }
+
+  const tx = new Transaction();
+  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,
+  };
+}
+
 /**
  * Abstract base class for all BTCR2 Beacon types.
  * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
@@ -80,29 +205,20 @@ export abstract class Beacon {
   ): Promise<SignedBTCR2Update>;
 
   /**
-   * Shared PSBT construction + signing + broadcast helper used by all beacon types.
+   * Build + sign + broadcast a single-party beacon signal transaction (P2WPKH spend).
    *
-   * 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 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,
@@ -111,72 +227,97 @@ export abstract class Beacon {
     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, secretKey, bitcoin, feeEstimator,
+    });
+    const signedHex = this.signSinglePartyTx(plan.tx, secretKey);
+    return this.broadcastRawTx(bitcoin, signedHex);
+  }
 
-    // Strip the 'bitcoin:' prefix from the service endpoint.
-    const bitcoinAddress = this.service.serviceEndpoint.replace('bitcoin:', '');
+  /**
+   * Build an unsigned P2WPKH single-party beacon tx + probe-sign to determine vsize,
+   * then rebuild with the real fee. Returns the tx and prev-output metadata.
+   *
+   * The secret key is required here (not just in `signSinglePartyTx`) because the
+   * two-pass fee estimation requires an actual signature to measure vsize accurately.
+   */
+  protected async buildSinglePartyTx(opts: {
+    signalBytes: Uint8Array;
+    beaconAddress: string;
+    utxo: AddressUtxo;
+    prevTxBytes: Uint8Array;
+    secretKey: KeyBytes;
+    bitcoin: BitcoinConnection;
+    feeEstimator: FeeEstimator;
+  }): Promise<BeaconTxPlan> {
+    const pubkey = this.#derivePubkey(opts.secretKey);
+    const witnessOut = p2wpkh(pubkey, opts.bitcoin.data);
+    const witnessScript = witnessOut.script;
 
-    // Fetch UTXOs at the beacon address.
-    const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
-    if(!utxos.length) {
-      throw new BeaconError(
-        'No UTXOs found, please fund address!',
-        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
+    const build = (feeSats: bigint): Transaction => {
+      const tx = new Transaction();
+      tx.addInput({
+        txid           : opts.utxo.txid,
+        index          : opts.utxo.vout,
+        nonWitnessUtxo : opts.prevTxBytes,
+        witnessUtxo    : { amount: BigInt(opts.utxo.value), script: witnessScript },
+      });
+      tx.addOutputAddress(
+        opts.beaconAddress,
+        BigInt(opts.utxo.value) - feeSats,
+        opts.bitcoin.data,
       );
-    }
+      tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
+      return tx;
+    };
+
+    // First pass: sign with zero fee to measure vsize.
+    const probe = build(0n);
+    probe.signIdx(opts.secretKey, 0);
+    probe.finalize();
+    const vsize = probe.vsize;
 
-    // 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(vsize);
+    if(BigInt(opts.utxo.value) <= 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',
+        { bitcoinAddress: opts.beaconAddress, utxoValue: opts.utxo.value, fee: feeSats.toString() }
       );
     }
 
-    // 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' }),
+    // Second pass: real fee.
+    const tx = build(feeSats);
+    return {
+      tx,
+      prevOutScripts : [witnessScript],
+      prevOutValues  : [BigInt(opts.utxo.value)],
+      beaconAddress  : opts.beaconAddress,
+      utxo           : opts.utxo,
+      feeSats,
     };
+  }
 
-    // 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() }
-      );
-    }
+  /**
+   * Sign + finalize the unsigned single-party tx and return its raw hex.
+   */
+  protected signSinglePartyTx(tx: Transaction, secretKey: KeyBytes): string {
+    tx.signIdx(secretKey, 0);
+    tx.finalize();
+    return tx.hex;
+  }
 
-    const signedTxHex = build(fee)
-      .signInput(0, signer)
-      .finalizeAllInputs()
-      .extractTransaction()
-      .toHex();
+  /**
+   * 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);
+  }
 
-    return bitcoin.rest.transaction.send(signedTxHex);
+  /** Derive the compressed secp256k1 public key from a raw secret key. */
+  #derivePubkey(secretKey: KeyBytes): Uint8Array {
+    return getPublicKey(secretKey, true);
   }
-}
+}

package/src/core/beacon/utils.ts

@@ -1,8 +1,8 @@
+import type { BTCNetwork } from '@did-btcr2/bitcoin';
 import { getNetwork } from '@did-btcr2/bitcoin';
 import type { KeyBytes, Maybe} from '@did-btcr2/common';
 import { DidMethodError, MethodError } from '@did-btcr2/common';
-import type { networks} from 'bitcoinjs-lib';
-import { payments } from 'bitcoinjs-lib';
+import { p2pkh, p2tr, p2wpkh } from '@scure/btc-signer';
 import { Appendix } from '../../utils/appendix.js';
 import type { DidDocument } from '../../utils/did-document.js';
 import { Identifier } from '../identifier.js';
@@ -100,7 +100,12 @@ export class BeaconUtils {
       // Build the id
       const id = `${did}#initial${addressType.toUpperCase()}`;
       // Generate the bitcoin address
-      const serviceEndpoint = `bitcoin:${payments[addressType]({ pubkey, network }).address}`;
+      const address = addressType === 'p2tr'
+        ? p2tr(pubkey.slice(1, 33), undefined, network).address
+        : addressType === 'p2wpkh'
+          ? p2wpkh(pubkey, network).address
+          : p2pkh(pubkey, network).address;
+      const serviceEndpoint = `bitcoin:${address}`;
       // Return the beacon serviceD
       return { id, type: beaconType, serviceEndpoint, };
     } catch (error: any) {
@@ -120,16 +125,16 @@ export class BeaconUtils {
   static generateBeaconServices({ id, publicKey, network, beaconType }: {
     id: string;
     publicKey: KeyBytes;
-    network: networks.Network;
+    network: BTCNetwork;
     beaconType: string;
   }): Array<BeaconService> {
     try {
       // Generate the bitcoin addresses for the given public key and network
-      const p2pkh = payments.p2pkh({ pubkey: publicKey, network }).address;
-      const p2wpkh = payments.p2wpkh({ pubkey: publicKey, network }).address;
-      const p2tr = payments.p2tr({ network, internalPubkey: publicKey.slice(1, 33) }).address;
+      const p2pkhAddr = p2pkh(publicKey, network).address;
+      const p2wpkhAddr = p2wpkh(publicKey, network).address;
+      const p2trAddr = p2tr(publicKey.slice(1, 33), undefined, network).address;
       // Check that all addresses were generated successfully
-      if (!p2pkh || !p2wpkh || !p2tr) {
+      if (!p2pkhAddr || !p2wpkhAddr || !p2trAddr) {
         throw new DidMethodError('Failed to generate bitcoin addresses');
       }
       // Return the beacon services with the generated addresses as service endpoints
@@ -137,17 +142,17 @@ export class BeaconUtils {
         {
           id              : `${id}#initialP2PKH`,
           type            : beaconType,
-          serviceEndpoint : `bitcoin:${p2pkh}`
+          serviceEndpoint : `bitcoin:${p2pkhAddr}`
         },
         {
           id              : `${id}#initialP2WPKH`,
           type            : beaconType,
-          serviceEndpoint : `bitcoin:${p2wpkh}`
+          serviceEndpoint : `bitcoin:${p2wpkhAddr}`
         },
         {
           id              : `${id}#initialP2TR`,
           type            : beaconType,
-          serviceEndpoint : `bitcoin:${p2tr}`
+          serviceEndpoint : `bitcoin:${p2trAddr}`
         },
       ];
     } catch (error: any) {