@did-btcr2/method 0.29.0 → 0.32.0

package/src/core/aggregation/transport/http/sse-stream.ts

@@ -0,0 +1,121 @@
+/**
+ * Parsed Server-Sent Events record.
+ *
+ * Events without a `data` field are never yielded (per the SSE spec — only a
+ * blank line that follows at least one `data:` line dispatches an event).
+ */
+export interface SseEvent {
+  /** Optional event name (from `event:` field). Defaults to "message" if omitted. */
+  event?: string;
+  /** Accumulated data payload (multiple `data:` lines joined with `\n`). */
+  data: string;
+  /** Last-Event-ID value for reconnect resumption. */
+  id?: string;
+  /** Retry delay hint in milliseconds. */
+  retry?: number;
+}
+
+/**
+ * Parse an SSE stream into an async iterable of {@link SseEvent} records.
+ *
+ * The parser follows the HTML Living Standard ({@link https://html.spec.whatwg.org/multipage/server-sent-events.html})
+ * closely enough for our needs: LF and CRLF line terminators, multi-line
+ * `data` fields, `event` / `id` / `retry` fields, and `:`-prefixed comments.
+ * CR-only line terminators are not supported (every mainstream SSE
+ * implementation emits LF or CRLF).
+ *
+ * Pure, runtime-agnostic — works anywhere `ReadableStream<Uint8Array>` and
+ * `TextDecoder` exist (browsers and Node 22+).
+ *
+ * The caller owns stream lifecycle: cancellation should be effected via an
+ * `AbortController` on the producing `fetch`, which propagates as a read
+ * error and cleanly unwinds this generator's `finally`.
+ */
+export async function* parseSseStream(
+  readable: ReadableStream<Uint8Array>,
+): AsyncGenerator<SseEvent, void, void> {
+  const decoder = new TextDecoder('utf-8');
+  const reader  = readable.getReader();
+
+  let buffer  = '';
+  let pending: { event?: string; data?: string; id?: string; retry?: number } = {};
+
+  const dispatchPending = (): SseEvent | null => {
+    if(pending.data === undefined) {
+      pending = {};
+      return null;
+    }
+    const ev: SseEvent = { data: pending.data };
+    if(pending.event !== undefined) ev.event = pending.event;
+    if(pending.id    !== undefined) ev.id    = pending.id;
+    if(pending.retry !== undefined) ev.retry = pending.retry;
+    pending = {};
+    return ev;
+  };
+
+  const processLine = (line: string): void => {
+    if(line.startsWith(':')) return; // comment
+
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let   value = colon === -1 ? '' : line.slice(colon + 1);
+    if(value.startsWith(' ')) value = value.slice(1);
+
+    switch(field) {
+      case 'data':
+        pending.data = pending.data === undefined ? value : `${pending.data}\n${value}`;
+        break;
+      case 'event':
+        pending.event = value;
+        break;
+      case 'id':
+        // Per spec: ignore ids containing NUL.
+        if(!value.includes('\0')) pending.id = value;
+        break;
+      case 'retry': {
+        const n = Number(value);
+        if(Number.isInteger(n) && n >= 0) pending.retry = n;
+        break;
+      }
+      // Other fields (including unknown names) are ignored per the spec.
+    }
+  };
+
+  try {
+    for(;;) {
+      const { value, done } = await reader.read();
+      if(done) {
+        // Flush any bytes the decoder is still holding.
+        buffer += decoder.decode();
+        if(buffer.length > 0) {
+          const line = buffer.endsWith('\r') ? buffer.slice(0, -1) : buffer;
+          if(line.length > 0) processLine(line);
+          buffer = '';
+        }
+        const tail = dispatchPending();
+        if(tail) yield tail;
+        return;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Drain as many complete lines as are available.
+      let lineEnd = buffer.indexOf('\n');
+      while(lineEnd !== -1) {
+        let line = buffer.slice(0, lineEnd);
+        if(line.endsWith('\r')) line = line.slice(0, -1);
+        buffer = buffer.slice(lineEnd + 1);
+
+        if(line.length === 0) {
+          const ev = dispatchPending();
+          if(ev) yield ev;
+        } else {
+          processLine(line);
+        }
+        lineEnd = buffer.indexOf('\n');
+      }
+    }
+  } finally {
+    try { reader.releaseLock(); } catch { /* already released */ }
+  }
+}

package/src/core/aggregation/transport/http/sse-writer.ts

@@ -0,0 +1,23 @@
+/**
+ * Format an SSE event frame. Pairs with {@link parseSseStream}.
+ *
+ * Multi-line `data` is split across multiple `data:` lines per the SSE spec —
+ * each embedded `\n` becomes its own line, and the parser rejoins them.
+ *
+ * The returned string includes a trailing blank line (the dispatch marker).
+ */
+export function formatSseEvent(event: string, data: string, id?: string): string {
+  const lines: string[] = [];
+  if(id !== undefined) lines.push(`id: ${id}`);
+  lines.push(`event: ${event}`);
+  for(const part of data.split('\n')) lines.push(`data: ${part}`);
+  lines.push('');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** SSE comment frame (server keepalive). Lines starting with `:` are ignored by compliant parsers. */
+export function formatSseComment(comment: string): string {
+  const safe = comment.replace(/\n/g, ' ');
+  return `: ${safe}\n\n`;
+}

package/src/core/aggregation/transport/index.ts

@@ -3,3 +3,4 @@ export * from './error.js';
 export * from './factory.js';
 export * from './nostr.js';
 export * from './didcomm.js';
+export * from './http/index.js';

package/src/core/aggregation/transport/transport.ts

@@ -5,7 +5,7 @@ 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.

package/src/core/beacon/beacon.ts

@@ -1,9 +1,9 @@
 import type { AddressUtxo, BitcoinConnection, BTCNetwork } from '@did-btcr2/bitcoin';
 import type { KeyBytes } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
-import { getPublicKey } from '@noble/secp256k1';
-import { hexToBytes } from '@noble/hashes/utils';
-import { OP, p2tr, p2wpkh, Script, Transaction } from '@scure/btc-signer';
+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';
@@ -14,13 +14,79 @@ import type { BeaconService, BeaconSignal } from './interfaces.js';
 /** Default fee estimator used when none is supplied. ~5 sat/vB static rate. */
 const DEFAULT_FEE_ESTIMATOR: FeeEstimator = new StaticFeeEstimator(5);
 
+/**
+ * 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.
- * 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.
+ * 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.
  */
-const P2TR_BEACON_TX_VSIZE = 140;
+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.
@@ -47,15 +113,28 @@ export interface BeaconTxPlan {
   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([OP.RETURN, signalBytes]);
+  return Script.encode(['RETURN', signalBytes]);
 }
 
 /**
@@ -70,14 +149,14 @@ async function fetchSpendableUtxo(
   if(!utxos.length) {
     throw new BeaconError(
       'No UTXOs found, please fund address!',
-      'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
+      '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', { bitcoinAddress }
+      'UNFUNDED_BEACON_ADDRESS', { address: bitcoinAddress }
     );
   }
   const prevTxHex = await bitcoin.rest.transaction.getHex(utxo.txid);
@@ -122,11 +201,14 @@ export async function buildAggregationBeaconTx(opts: {
     throw new BeaconError(
       `UTXO value (${utxo.value}) insufficient to cover fee (${feeSats}).`,
       'INSUFFICIENT_FUNDS',
-      { bitcoinAddress: opts.beaconAddress, utxoValue: utxo.value, fee: feeSats.toString() }
+      { address: opts.beaconAddress, valueSats: utxo.value, feeSats }
     );
   }
 
-  const tx = new Transaction();
+  // 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,
@@ -144,9 +226,90 @@ export async function buildAggregationBeaconTx(opts: {
     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
@@ -192,20 +355,23 @@ 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>;
 
   /**
-   * Build + sign + broadcast a single-party beacon signal transaction (P2WPKH spend).
+   * 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.
    *
    * Composed from the three extracted phases ({@link buildSinglePartyTx},
    * {@link signSinglePartyTx}, {@link broadcastRawTx}) so each piece can be exercised
@@ -214,7 +380,7 @@ export abstract class Beacon {
    * 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.
@@ -222,7 +388,7 @@ export abstract class Beacon {
    */
   protected async buildSignAndBroadcast(
     signalBytes: Uint8Array,
-    secretKey: KeyBytes,
+    signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
   ): Promise<string> {
@@ -230,83 +396,113 @@ export abstract class Beacon {
     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,
+      signalBytes, beaconAddress, utxo, prevTxBytes, signer, bitcoin, feeEstimator,
     });
-    const signedHex = this.signSinglePartyTx(plan.tx, secretKey);
+    const signedHex = await this.signSinglePartyTx(plan, signer);
     return this.broadcastRawTx(bitcoin, signedHex);
   }
 
   /**
-   * 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.
+   * Build an unsigned singleton beacon tx ready for {@link signSinglePartyTx}.
    *
-   * The secret key is required here (not just in `signSinglePartyTx`) because the
-   * two-pass fee estimation requires an actual signature to measure vsize accurately.
+   * 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;
-    secretKey: KeyBytes;
+    signer: Signer;
     bitcoin: BitcoinConnection;
     feeEstimator: FeeEstimator;
   }): Promise<BeaconTxPlan> {
-    const pubkey = this.#derivePubkey(opts.secretKey);
-    const witnessOut = p2wpkh(pubkey, opts.bitcoin.data);
-    const witnessScript = witnessOut.script;
+    const network = opts.bitcoin.data;
+    const pubkey = opts.signer.publicKey;
+    const kind = detectSingletonScriptKind(opts.beaconAddress, network);
 
-    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,
+    const derivedAddress = deriveSingletonAddress(kind, pubkey, network);
+    if(derivedAddress !== opts.beaconAddress) {
+      throw new BeaconError(
+        `Signer pubkey produces ${kind.toUpperCase()} address "${derivedAddress}", but beacon address is "${opts.beaconAddress}".`,
+        'SIGNER_KEY_MISMATCH',
+        { kind, address: opts.beaconAddress, derivedAddress }
       );
-      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;
+    }
 
-    const feeSats = await opts.feeEstimator.estimateFee(vsize);
-    if(BigInt(opts.utxo.value) <= feeSats) {
+    const feeSats = await opts.feeEstimator.estimateFee(SINGLETON_BEACON_TX_VSIZE[kind]);
+    const amount = BigInt(opts.utxo.value);
+    if(amount <= feeSats) {
       throw new BeaconError(
         `UTXO value (${opts.utxo.value}) insufficient to cover fee (${feeSats}).`,
         'INSUFFICIENT_FUNDS',
-        { bitcoinAddress: opts.beaconAddress, utxoValue: opts.utxo.value, fee: feeSats.toString() }
+        { address: opts.beaconAddress, valueSats: opts.utxo.value, feeSats }
       );
     }
 
-    // Second pass: real fee.
-    const tx = build(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 });
+
+    // 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,
+      });
+    }
+
+    tx.addOutputAddress(opts.beaconAddress, amount - feeSats, network);
+    tx.addOutput({ script: opReturnScript(opts.signalBytes), amount: 0n });
+
     return {
       tx,
-      prevOutScripts : [witnessScript],
-      prevOutValues  : [BigInt(opts.utxo.value)],
+      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 signSinglePartyTx(tx: Transaction, secretKey: KeyBytes): string {
-    tx.signIdx(secretKey, 0);
-    tx.finalize();
-    return tx.hex;
+  protected async signSinglePartyTx(plan: BeaconTxPlan, signer: Signer): Promise<string> {
+    return signSingletonInput(
+      plan.tx, 0, plan.scriptKind, signer,
+      plan.prevOutScripts[0]!, plan.prevOutValues[0]!,
+    );
   }
 
   /**
@@ -315,9 +511,4 @@ export abstract class Beacon {
   protected async broadcastRawTx(bitcoin: BitcoinConnection, rawHex: string): Promise<string> {
     return bitcoin.rest.transaction.send(rawHex);
   }
-
-  /** Derive the compressed secp256k1 public key from a raw secret key. */
-  #derivePubkey(secretKey: KeyBytes): Uint8Array {
-    return getPublicKey(secretKey, true);
-  }
 }

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) {