@did-btcr2/method 0.26.0 → 0.27.0

package/src/core/beacon/beacon.ts

@@ -1,10 +1,27 @@
+import type { AddressUtxo, BitcoinConnection } from '@did-btcr2/bitcoin';
 import type { KeyBytes } from '@did-btcr2/common';
-import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 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 { BeaconProcessResult } from '../resolver.js';
 import type { SidecarData } from '../types.js';
+import { BeaconError } from './error.js';
+import { StaticFeeEstimator } from './fee-estimator.js';
+import type { FeeEstimator } from './fee-estimator.js';
 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);
+
+/**
+ * Options accepted by {@link Beacon.buildSignAndBroadcast}.
+ */
+export interface BroadcastOptions {
+  /** Fee estimator for computing the transaction fee. Defaults to {@link DEFAULT_FEE_ESTIMATOR}. */
+  feeEstimator?: FeeEstimator;
+}
+
 /**
  * Abstract base class for all BTCR2 Beacon types.
  * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
@@ -52,11 +69,114 @@ export abstract class Beacon {
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {KeyBytes} secretKey The secret key for signing 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.
    */
   abstract broadcastSignal(
     signedUpdate: SignedBTCR2Update,
     secretKey: KeyBytes,
-    bitcoin: BitcoinConnection
+    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.
+   *
+   * 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.
+   *
+   * @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.
+   */
+  protected async buildSignAndBroadcast(
+    signalBytes: Uint8Array,
+    secretKey: KeyBytes,
+    bitcoin: BitcoinConnection,
+    options?: BroadcastOptions
+  ): Promise<string> {
+    const feeEstimator = options?.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
+
+    // Strip the 'bitcoin:' prefix from the service endpoint.
+    const bitcoinAddress = this.service.serviceEndpoint.replace('bitcoin:', '');
+
+    // 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 }
+      );
+    }
+
+    // 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) {
+      throw new BeaconError(
+        'Beacon bitcoin address unfunded or utxos unconfirmed.',
+        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
+      );
+    }
+
+    // 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' }),
+    };
+
+    // 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() }
+      );
+    }
+
+    const signedTxHex = build(fee)
+      .signInput(0, signer)
+      .finalizeAllInputs()
+      .extractTransaction()
+      .toHex();
+
+    return bitcoin.rest.transaction.send(signedTxHex);
+  }
 }

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

@@ -1,15 +1,21 @@
-import type { AddressUtxo, BitcoinConnection } from '@did-btcr2/bitcoin';
+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 { SchnorrKeyPair } from '@did-btcr2/keypair';
-import { hexToBytes } from '@noble/hashes/utils';
-import { opcodes, Psbt, script } from 'bitcoinjs-lib';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
+import type { BroadcastOptions } from './beacon.js';
 import { Beacon } from './beacon.js';
-import { CASBeaconError } from './error.js';
-import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
+import type { BeaconService, BeaconSignal, BlockMetadata, CasPublishFn } from './interfaces.js';
+
+/**
+ * CAS-specific broadcast options — extends {@link BroadcastOptions} with an optional
+ * `casPublish` callback used to publish the CAS Announcement off-chain after the
+ * OP_RETURN signal is broadcast.
+ */
+export interface CASBroadcastOptions extends BroadcastOptions {
+  casPublish?: CasPublishFn;
+}
 
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#cas-beacon | CAS Beacon}.
@@ -39,7 +45,7 @@ export class CASBeacon extends Beacon {
    * For each signal, the signalBytes contain the hex-encoded hash of a CAS Announcement.
    * The CAS Announcement maps DIDs to their base64url-encoded update hashes.
    * This method looks up the CAS Announcement from the sidecar, extracts the update
-   * hash for the DID being resolved, and retrieves the corresponding signed update.
+   * hash for the DID being resolved, and retrieves the corresponding signed update from sidecar.
    *
    * @param {Array<BeaconSignal>} signals The array of Beacon Signals to process.
    * @param {SidecarData} sidecar The sidecar data associated with the CAS Beacon.
@@ -106,99 +112,45 @@ export class CASBeacon extends Beacon {
   /**
    * Broadcasts a CAS Beacon signal to the Bitcoin network.
    *
-   * Creates a CAS Announcement mapping the DID to the update hash, then broadcasts
-   * the hash of the announcement via OP_RETURN. The CAS Announcement is distributed
-   * to resolvers via sidecar data.
+   * Creates a CAS Announcement mapping the DID to the update hash, broadcasts the hash of the
+   * announcement via OP_RETURN, and optionally publishes the announcement off-chain via the
+   * supplied `casPublish` callback. UTXO selection, PSBT construction, fee estimation, 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 {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 {CASBeaconError} if the bitcoin address is invalid or unfunded.
+   * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
    */
   async broadcastSignal(
     signedUpdate: SignedBTCR2Update,
     secretKey: KeyBytes,
-    bitcoin: BitcoinConnection
+    bitcoin: BitcoinConnection,
+    options?: CASBroadcastOptions
   ): Promise<SignedBTCR2Update> {
     // Extract the DID from the beacon service id (strip the #fragment)
     const did = this.service.id.split('#')[0];
 
-    // Hash the signed update (base64url for the CAS Announcement entry)
+    // Hash the signed update (base64urlnopad for the CAS Announcement entry per spec)
     const updateHash = canonicalHash(signedUpdate);
 
     // Create the CAS Announcement mapping this DID to its update hash
     const casAnnouncement = { [did]: updateHash };
 
-    // TODO: Publish CAS Announcement to content-addressed store (e.g., IPFS via Helia)
-
     // Canonicalize and hash the CAS Announcement for the OP_RETURN output
     const announcementHash = hash(canonicalize(casAnnouncement));
 
-    // Convert the serviceEndpoint to a bitcoin address by removing the 'bitcoin:' prefix
-    const bitcoinAddress = this.service.serviceEndpoint.replace('bitcoin:', '');
-
-    // Query the Bitcoin network for UTXOs associated with the bitcoinAddress
-    const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
-
-    // If no utxos are found, throw an error indicating the address is unfunded.
-    if(!utxos.length) {
-      throw new CASBeaconError(
-        'No UTXOs found, please fund address!',
-        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
-      );
-    }
+    // Delegate UTXO selection, PSBT construction, fee estimation, signing, and broadcast
+    await this.buildSignAndBroadcast(announcementHash, secretKey, bitcoin, options);
 
-    // Sort utxos by block height and take the most recent one
-    const utxo: AddressUtxo | undefined = utxos.sort(
-      (a, b) => b.status.block_height - a.status.block_height
-    ).shift();
-
-    // If no utxos are found, throw an error.
-    if(!utxo) {
-      throw new CASBeaconError(
-        'Beacon bitcoin address unfunded or utxos unconfirmed.',
-        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
-      );
+    // Publish CAS Announcement to content-addressed store if callback provided
+    if(options?.casPublish) {
+      await options.casPublish(casAnnouncement);
     }
 
-    // Get the previous tx to the utxo being spent
-    const prevTx = await bitcoin.rest.transaction.getHex(utxo.txid);
-
-    // Construct a spend transaction
-    const spendTx = new Psbt({ network: bitcoin.data })
-      // Spend tx contains the utxo as its input
-      .addInput({
-        hash           : utxo.txid,
-        index          : utxo.vout,
-        nonWitnessUtxo : hexToBytes(prevTx)
-      })
-      // Add a change output minus a fee of 500 sats
-      // TODO: calculate fee based on transaction vsize and current fee rates
-      .addOutput({ address: bitcoinAddress, value: BigInt(utxo.value) - BigInt(500) })
-      // Add an OP_RETURN output containing the CAS Announcement hash
-      .addOutput({ script: script.compile([opcodes.OP_RETURN, announcementHash]), value: 0n });
-
-    // Construct a key pair and PSBT 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' }),
-    };
-
-    // Sign 0th input, finalize extract to hex in prep for broadcast
-    const signedTx = spendTx.signInput(0, signer)
-      .finalizeAllInputs()
-      .extractTransaction()
-      .toHex();
-
-    // Broadcast spendTx to the Bitcoin network.
-    const txid = await bitcoin.rest.transaction.send(signedTx);
-
-    // Log the txid of the broadcasted transaction
-    console.info(`CAS Beacon Signal Broadcasted with txid: ${txid}`);
-
-    // Return the signed update
     return signedUpdate;
   }
 }

package/src/core/beacon/error.ts

@@ -6,18 +6,6 @@ export class BeaconError extends MethodError {
   }
 }
 
-export class BeaconCoordinatorError extends MethodError {
-  constructor(message: string, type: string = 'BeaconCoordinatorError', data?: Record<string, any>) {
-    super(message, type, data);
-  }
-}
-
-export class BeaconParticipantError extends MethodError {
-  constructor(message: string, type: string = 'BeaconParticipantError', data?: Record<string, any>) {
-    super(message, type, data);
-  }
-}
-
 export class SingletonBeaconError extends MethodError {
   constructor(message: string, type: string = 'SingletonBeaconError', data?: Record<string, any>) {
     super(message, type, data);

package/src/core/beacon/fee-estimator.ts

@@ -0,0 +1,52 @@
+/**
+ * Estimates the fee (in satoshis) for a transaction of a given virtual size.
+ *
+ * Beacons delegate fee calculation to a `FeeEstimator` so that callers can
+ * plug in different strategies: static fee rates for tests/regtest, mempool
+ * APIs for mainnet, Bitcoin Core `estimatesmartfee` RPC for full-node setups,
+ * etc.
+ *
+ * Implementations return the **total fee in satoshis** for a transaction of
+ * the given virtual size (`vsize`). Callers pass the vsize; the estimator
+ * decides the fee rate and computes the total.
+ */
+export interface FeeEstimator {
+  /**
+   * Estimate the total fee in satoshis for a transaction of the given vsize.
+   * @param vsize Transaction virtual size in vbytes.
+   * @returns Total fee in satoshis.
+   */
+  estimateFee(vsize: number): Promise<bigint>;
+}
+
+/**
+ * Fee estimator that returns a fixed fee rate regardless of network conditions.
+ *
+ * Suitable for:
+ * - Tests (deterministic outputs)
+ * - Regtest (no real fee market)
+ * - Environments where a fee rate is supplied out-of-band
+ *
+ * For mainnet production use, prefer a dynamic estimator that queries current
+ * network conditions (mempool APIs, Bitcoin Core RPC).
+ */
+export class StaticFeeEstimator implements FeeEstimator {
+  readonly satsPerVbyte: number;
+
+  /**
+   * @param satsPerVbyte Fee rate in satoshis per virtual byte. Default: 5 sat/vB.
+   */
+  constructor(satsPerVbyte: number = 5) {
+    if(satsPerVbyte < 0 || !Number.isFinite(satsPerVbyte)) {
+      throw new Error(`Invalid satsPerVbyte: ${satsPerVbyte}`);
+    }
+    this.satsPerVbyte = satsPerVbyte;
+  }
+
+  async estimateFee(vsize: number): Promise<bigint> {
+    if(vsize < 0 || !Number.isFinite(vsize)) {
+      throw new Error(`Invalid vsize: ${vsize}`);
+    }
+    return BigInt(Math.ceil(vsize * this.satsPerVbyte));
+  }
+}

package/src/core/beacon/interfaces.ts

@@ -64,4 +64,13 @@ export interface BeaconSignal {
    * Metadata about the block containing the Beacon Signal.
    */
   blockMetadata: BlockMetadata;
-}
+}
+
+/**
+ * Callback for publishing a CAS Announcement to a content-addressed store.
+ * The method package defines this type; the api layer provides the implementation
+ * (e.g., via CasApi.publish backed by IPFS/Helia).
+ *
+ * @param announcement The CAS Announcement object (DID → update hash mapping).
+ */
+export type CasPublishFn = (announcement: Record<string, string>) => Promise<void>;

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

@@ -1,14 +1,11 @@
-import type { AddressUtxo, BitcoinConnection } from '@did-btcr2/bitcoin';
+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 { SchnorrKeyPair } from '@did-btcr2/keypair';
-import { hexToBytes } from '@noble/hashes/utils';
-import { opcodes, Psbt, script } from 'bitcoinjs-lib';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
+import type { BroadcastOptions } from './beacon.js';
 import { Beacon } from './beacon.js';
-import { SingletonBeaconError } from './error.js';
 import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
 /**
@@ -64,84 +61,26 @@ export class SingletonBeacon extends Beacon {
   }
   /**
    * Broadcasts a SingletonBeacon signal to the Bitcoin network.
+   *
+   * The signal bytes embedded in OP_RETURN are the SHA-256 canonical hash of the signed update.
+   * UTXO selection, PSBT construction, fee estimation, 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 {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 {SingletonBeaconError} if the bitcoin address is invalid or unfunded.
+   * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
    */
   async broadcastSignal(
     signedUpdate: SignedBTCR2Update,
     secretKey: KeyBytes,
-    bitcoin: BitcoinConnection
+    bitcoin: BitcoinConnection,
+    options?: BroadcastOptions
   ): Promise<SignedBTCR2Update> {
-    // Convert the serviceEndpoint to a bitcoin address by removing the 'bitcoin:' prefix
-    const bitcoinAddress = this.service.serviceEndpoint.replace('bitcoin:', '');
-
-    // Query the Bitcoin network for UTXOs associated with the bitcoinAddress
-    const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
-
-    // If no utxos are found, throw an error indicating the address is unfunded.
-    if(!utxos.length) {
-      throw new SingletonBeaconError(
-        'No UTXOs found, please fund address!',
-        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
-      );
-    }
-
-    // Sort utxos by block height and take the most recent one
-    const utxo: AddressUtxo | undefined = utxos.sort(
-      (a, b) => b.status.block_height - a.status.block_height
-    ).shift();
-
-    // If no utxos are found, throw an error.
-    if(!utxo) {
-      throw new SingletonBeaconError(
-        'Beacon bitcoin address unfunded or utxos unconfirmed.',
-        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
-      );
-    }
-
-    // Get the previous tx to the utxo being spent
-    const prevTx = await bitcoin.rest.transaction.getHex(utxo.txid);
-
-    // Canonicalize and hash the signed update for OP_RETURN output
-    const updateHash = hash(canonicalize(signedUpdate));
-
-    // Construct a spend transaction
-    const spendTx = new Psbt({ network: bitcoin.data })
-      // Spend tx contains the utxo as its input
-      .addInput({
-        hash           : utxo.txid,
-        index          : utxo.vout,
-        nonWitnessUtxo : hexToBytes(prevTx)
-      })
-      // Add a change output minus a fee of 500 sats
-      // TODO: calculate fee based on transaction vsize and current fee rates
-      .addOutput({ address: bitcoinAddress, value: BigInt(utxo.value) - BigInt(500) })
-      // Add an OP_RETURN output containing the update hash
-      .addOutput({ script: script.compile([opcodes.OP_RETURN, updateHash]), value: 0n });
-
-    // Construct a key pair and PSBT 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' }),
-    };
-
-    // Sign 0th input, finalize extract to hex in prep for broadcast
-    const signedTx = spendTx.signInput(0, signer)
-      .finalizeAllInputs()
-      .extractTransaction()
-      .toHex();
-
-    // Broadcast spendTx to the Bitcoin network.
-    const txid = await bitcoin.rest.transaction.send(signedTx);
-
-    // Log the txid of the broadcasted transaction
-    console.info(`Singleton Beacon Signal Broadcasted with txid: ${txid}`);
-
-    // Return the signed update
+    const signalBytes = hash(canonicalize(signedUpdate));
+    await this.buildSignAndBroadcast(signalBytes, secretKey, bitcoin, options);
     return signedUpdate;
   }
-}
+}

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

@@ -1,14 +1,24 @@
 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 { BeaconProcessResult } from '../resolver.js';
+import { blockHash, BTCR2MerkleTree, didToIndex, hexToHash, verifySerializedProof } from '@did-btcr2/smt';
+import { randomBytes } from '@noble/hashes/utils';
+import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
+import type { BroadcastOptions } from './beacon.js';
 import { Beacon } from './beacon.js';
 import { SMTBeaconError } from './error.js';
-import type { BeaconService, BeaconSignal } from './interfaces.js';
+import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
 /**
- * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#smt-beacon | SMTBeacon}.
+ * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#smt-beacon | SMT Beacon}.
+ *
+ * An SMT (Sparse Merkle Tree) Beacon aggregates updates for multiple DIDs
+ * into a single Merkle root hash broadcast on-chain via OP_RETURN.
+ * During resolution, the SMT Proof from the sidecar is verified against the
+ * on-chain root, and the proof's updateId is used to retrieve the signed update.
+ *
  * @class SMTBeacon
  * @type {SMTBeacon}
  * @extends {Beacon}
@@ -24,31 +34,119 @@ export class SMTBeacon extends Beacon {
 
   /**
    * Implements {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#process-smt-beacon | 7.2.e.1 Process SMT Beacon}.
+   *
+   * For each signal, the signalBytes contain the hex-encoded SMT root hash.
+   * This method looks up the SMT Proof from the sidecar by root hash,
+   * validates the Merkle inclusion proof, and retrieves the corresponding
+   * signed update using the proof's updateId.
+   *
    * @param {Array<BeaconSignal>} signals The array of Beacon Signals to process.
    * @param {SidecarData} sidecar The sidecar data associated with the SMT Beacon.
-   * @returns {BeaconProcessResult} The processed signals.
-   * @throws {SMTBeaconError} if processing fails.
+   * @returns {BeaconProcessResult} Successfully resolved updates and any data needs.
+   * @throws {SMTBeaconError} if proof verification fails or proof is malformed.
    */
   processSignals(
     signals: Array<BeaconSignal>,
     sidecar: SidecarData
   ): BeaconProcessResult {
-    throw new SMTBeaconError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {signals, sidecar});
+    const updates = new Array<[SignedBTCR2Update, BlockMetadata]>();
+    const needs = new Array<DataNeed>();
+
+    // Extract the DID from the beacon service id (strip the #fragment)
+    const did = this.service.id.split('#')[0];
+
+    for(const signal of signals) {
+      // Signal bytes are the hex-encoded SMT root hash; smtMap is keyed by proof.id (also hex)
+      const smtProof = sidecar.smtMap.get(signal.signalBytes);
+
+      if(!smtProof) {
+        // SMT Proof not available — emit a need
+        needs.push({
+          kind            : 'NeedSMTProof',
+          smtRootHash     : signal.signalBytes,
+          beaconServiceId : this.service.id
+        });
+        continue;
+      }
+
+      // Non-inclusion proof — no update for this DID in this epoch, skip
+      if(!smtProof.updateId) {
+        continue;
+      }
+
+      // Nonce is required for proof verification
+      if(!smtProof.nonce) {
+        throw new SMTBeaconError(
+          'SMT proof missing required nonce field.',
+          'INVALID_SMT_PROOF', { smtProof, did }
+        );
+      }
+
+      // Verify Merkle inclusion: leaf = hash(hash(nonce) || updateId)
+      const index = didToIndex(did);
+      const candidateHash = blockHash(blockHash(hexToHash(smtProof.nonce)), hexToHash(smtProof.updateId));
+      const valid = verifySerializedProof(smtProof, index, candidateHash);
+
+      if(!valid) {
+        throw new SMTBeaconError(
+          'SMT proof verification failed.',
+          'INVALID_SMT_PROOF', { smtProof, did }
+        );
+      }
+
+      // Look up the signed update in sidecar updateMap (keyed by hex canonical hash)
+      const signedUpdate = sidecar.updateMap.get(smtProof.updateId);
+
+      if(!signedUpdate) {
+        // Signed update not available — emit a need
+        needs.push({
+          kind             : 'NeedSignedUpdate',
+          updateHash       : smtProof.updateId,
+          beaconServiceId  : this.service.id
+        });
+        continue;
+      }
+
+      updates.push([signedUpdate, signal.blockMetadata]);
+    }
+
+    return { updates, needs };
   }
 
   /**
-   * Broadcast CAS Beacon signal to the Bitcoin network.
+   * Broadcasts an SMT Beacon signal to the Bitcoin network.
+   *
+   * Builds a single-entry Sparse Merkle Tree from the signed update, then broadcasts the tree's
+   * root hash via OP_RETURN. For multi-party aggregation, use the {@link AggregationService}
+   * subsystem directly instead of this method. UTXO selection, PSBT construction, fee estimation,
+   * 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 {BitcoinConnection} bitcoin The Bitcoin network connection.
-   * @return {Promise<SignedBTCR2Update>} The signed update that was broadcasted.
-   * @throws {SMTBeaconError} if broadcasting fails.
+   * @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.
    */
   async broadcastSignal(
     signedUpdate: SignedBTCR2Update,
     secretKey: KeyBytes,
-    bitcoin: BitcoinConnection
+    bitcoin: BitcoinConnection,
+    options?: BroadcastOptions
   ): Promise<SignedBTCR2Update> {
-    throw new SMTBeaconError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {signedUpdate, secretKey, bitcoin});
+    // Extract the DID from the beacon service id (strip the #fragment)
+    const did = this.service.id.split('#')[0];
+
+    // Build a single-entry SMT from the signed update
+    const canonicalBytes = new TextEncoder().encode(canonicalize(signedUpdate));
+    const nonce = randomBytes(32);
+    const tree = new BTCR2MerkleTree();
+    tree.addEntries([{ did, nonce, signedUpdate: canonicalBytes }]);
+    tree.finalize();
+
+    // Root hash is the signal bytes for the OP_RETURN output
+    await this.buildSignAndBroadcast(tree.rootHash, secretKey, bitcoin, options);
+
+    return signedUpdate;
   }
 }