@did-btcr2/method 0.18.1 → 0.20.0

package/src/core/beacon/beacon.ts

@@ -0,0 +1,58 @@
+import { KeyBytes } from '@did-btcr2/common';
+import { BitcoinNetworkConnection } from '../../../../bitcoin/dist/types/bitcoin.js';
+import { SignedBTCR2Update } from '../../../../cryptosuite/dist/types/data-integrity-proof/interface.js';
+import { SidecarData } from '../types.js';
+import { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
+
+/**
+ * Abstract base class for all BTCR2 Beacon types.
+ * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
+ * how to find authentic updates to the DID.
+ *
+ * Beacons are lightweight typed wrappers around a {@link BeaconService} configuration.
+ * Dependencies (signals, sidecar data, bitcoin connection) are passed as method
+ * parameters rather than held as instance state.
+ *
+ * Use {@link BeaconFactory.establish} to create typed instances from service config.
+ *
+ * @abstract
+ * @class Beacon
+ * @type {Beacon}
+ */
+export abstract class Beacon {
+  /**
+   * The Beacon service configuration parsed from the DID Document.
+   */
+  readonly service: BeaconService;
+
+  constructor(service: BeaconService) {
+    this.service = service;
+  }
+
+  /**
+   * Processes an array of Beacon Signals to extract BTCR2 Signed Updates.
+   * Used during the resolve path.
+   * @param {Array<BeaconSignal>} signals The beacon signals discovered on-chain.
+   * @param {SidecarData} sidecar The processed sidecar data containing update/CAS/SMT maps.
+   * @returns {Promise<Array<[SignedBTCR2Update, BlockMetadata]>>} The updates announced by the signals.
+   */
+  abstract processSignals(
+    signals: Array<BeaconSignal>,
+    sidecar: SidecarData,
+  ): Promise<Array<[SignedBTCR2Update, BlockMetadata]>>;
+
+
+  /**
+   * 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 {BitcoinNetworkConnection} bitcoin The Bitcoin network connection.
+   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   */
+  abstract broadcastSignal(
+    signedUpdate: SignedBTCR2Update,
+    secretKey: KeyBytes,
+    bitcoin: BitcoinNetworkConnection
+  ): Promise<SignedBTCR2Update>;
+}

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

@@ -0,0 +1,53 @@
+import { BitcoinNetworkConnection } from '@did-btcr2/bitcoin';
+import { KeyBytes } from '@did-btcr2/common';
+import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { SidecarData } from '../types.js';
+import { Beacon } from './beacon.js';
+import { CASBeaconError } from './error.js';
+import { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
+
+/**
+ * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#cas-beacon | CAS Beacon}.
+ * @class CASBeacon
+ * @type {CASBeacon}
+ * @extends {Beacon}
+ */
+export class CASBeacon extends Beacon {
+  /**
+   * Creates an instance of CASBeacon.
+   * @param {BeaconService} service The service of the Beacon.
+   */
+  constructor(service: BeaconService) {
+    super({ ...service, type: 'CASBeacon' });
+  }
+
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#process-cas-beacon | 7.2.e.1 Process CAS Beacon}.
+   * @param {Array<BeaconSignal>} signals The array of Beacon Signals to process.
+   * @param {SidecarData} sidecar The sidecar data associated with the CAS Beacon.
+   * @returns {Promise<Array<[SignedBTCR2Update, BlockMetadata]>>} The processed signals.
+   * @throws {CASBeaconError} if processing fails.
+   */
+  processSignals(
+    signals: Array<BeaconSignal>,
+    sidecar: SidecarData
+  ): Promise<Array<[SignedBTCR2Update, BlockMetadata]>> {
+    throw new CASBeaconError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, { signals, sidecar });
+  }
+
+  /**
+   * Broadcast CAS Beacon signal to the Bitcoin network.
+   * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
+   * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+   * @param {BitcoinNetworkConnection} bitcoin The Bitcoin network connection.
+   * @return {Promise<SignedBTCR2Update>} The signed update that was broadcasted.
+   * @throws {CASBeaconError} if broadcasting fails.
+   */
+  async broadcastSignal(
+    signedUpdate: SignedBTCR2Update,
+    secretKey: KeyBytes,
+    bitcoin: BitcoinNetworkConnection
+  ): Promise<SignedBTCR2Update> {
+    throw new CASBeaconError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {signedUpdate, secretKey, bitcoin});
+  }
+}

package/src/core/beacon/error.ts

@@ -18,7 +18,6 @@ export class BeaconParticipantError extends MethodError {
   }
 }
 
-
 export class SingletonBeaconError extends MethodError {
   constructor(message: string, type: string = 'SingletonBeaconError', data?: Record<string, any>) {
     super(message, type, data);
@@ -31,14 +30,14 @@ export class AggregateBeaconError extends MethodError {
   }
 }
 
-export class CIDAggregateBeaconError extends MethodError {
-  constructor(message: string, type: string = 'CIDAggregateBeaconError', data?: Record<string, any>) {
+export class CASBeaconError extends MethodError {
+  constructor(message: string, type: string = 'CASBeaconError', data?: Record<string, any>) {
     super(message, type, data);
   }
 }
 
-export class SMTAggregateBeaconError extends MethodError {
-  constructor(message: string, type: string = 'SMTAggregateBeaconError', data?: Record<string, any>) {
+export class SMTBeaconError extends MethodError {
+  constructor(message: string, type: string = 'SMTBeaconError', data?: Record<string, any>) {
     super(message, type, data);
   }
-}
+}

package/src/core/beacon/factory.ts

@@ -1,9 +1,9 @@
 import { MethodError } from '@did-btcr2/common';
-import { Beacon, BeaconService } from '../../interfaces/beacon.js';
-import { CIDAggregateSidecar, SidecarData, SMTAggregateSidecar } from '../../utils/types.js';
-import { CIDAggregateBeacon } from './cid-aggregate.js';
+import { Beacon } from './beacon.js';
+import { CASBeacon } from './cas-beacon.js';
+import { BeaconService } from './interfaces.js';
 import { SingletonBeacon } from './singleton.js';
-import { SMTAggregateBeacon } from './smt-aggregate.js';
+import { SMTBeacon } from './smt-beacon.js';
 
 /**
  * Beacon Factory pattern to create Beacon instances.
@@ -13,23 +13,19 @@ import { SMTAggregateBeacon } from './smt-aggregate.js';
 export class BeaconFactory {
   /**
    * Establish a Beacon instance based on the provided service and optional sidecar data.
-   * @param {BeaconService} service - The beacon service configuration.
-   * @param {SidecarData} [sidecar] - The optional sidecar data.
+   * @param {BeaconService} service The beacon service configuration.
    * @returns {Beacon} The established Beacon instance.
    */
-  static establish(service: BeaconService, sidecar?: SidecarData): Beacon {
+  static establish(service: BeaconService): Beacon {
     switch (service.type) {
       case 'SingletonBeacon':
-        return new SingletonBeacon(service, sidecar);
-      case 'CIDAggregateBeacon':
-        return new CIDAggregateBeacon(service, sidecar as CIDAggregateSidecar);
-      case 'SMTAggregateBeacon':
-        return new SMTAggregateBeacon(service, sidecar as SMTAggregateSidecar);
+        return new SingletonBeacon(service);
+      case 'CASBeacon':
+        return new CASBeacon(service);
+      case 'SMTBeacon':
+        return new SMTBeacon(service);
       default:
-        throw new MethodError(
-          'Invalid Beacon Type',
-          'INVALID_BEACON_ERROR', { service, sidecar }
-        );
+        throw new MethodError('Invalid Beacon Type', 'INVALID_BEACON_ERROR', service);
     }
   }
 }

package/src/core/beacon/interfaces.ts

@@ -0,0 +1,67 @@
+import { RawTransactionRest, RawTransactionV2 } from '@did-btcr2/bitcoin';
+import { UnixTimestamp } from '@did-btcr2/common';
+import { DidServiceEndpoint, DidService } from '@web5/dids';
+
+/**
+ * Represents a Beacon Service, which extends a W3C DID Service by setting serviceEndpoint
+ * as a single DidServiceEndpoint.
+ * @interface BeaconService
+ * @extends DidService
+ */
+export interface BeaconService extends DidService {
+    serviceEndpoint: DidServiceEndpoint;
+}
+
+/**
+ * Represents a parsed Beacon Service, which extends the Beacon Service with a Bitcoin address.
+ * @interface ParsedBeaconService
+ * @extends BeaconService
+ */
+export interface ParsedBeaconService extends BeaconService {
+    /**
+     * The Bitcoin address associated with this Beacon Service.
+     */
+    address: string;
+}
+
+/**
+ * Metadata about a Bitcoin block containing a Beacon Signal.
+ * @interface BlockMetadata
+ */
+export interface BlockMetadata {
+   /**
+   * The block height at which the Beacon Signal was included.
+   */
+  height: number;
+
+  /**
+   * The timestamp of the block containing the Beacon Signal.
+   */
+  time: UnixTimestamp;
+
+  /**
+   * The number of confirmations for the block containing the Beacon Signal.
+   */
+  confirmations: number;
+}
+
+/**
+ * Represents a Beacon Signal, which is a transaction broadcasted by a Beacon to announce a DID update.
+ * @interface BeaconSignal
+ */
+export interface BeaconSignal {
+  /**
+   * The raw Bitcoin transaction representing the Beacon Signal.
+   */
+  tx: RawTransactionRest | RawTransactionV2;
+
+  /**
+   * The beacon signal bytes hash (i.e. the hash of the BTCR2 update included in the Beacon Signal tx).
+   */
+  signalBytes: string;
+
+  /**
+   * Metadata about the block containing the Beacon Signal.
+   */
+  blockMetadata: BlockMetadata;
+}

package/src/core/beacon/signal-discovery.ts

@@ -0,0 +1,237 @@
+import {
+  BitcoinNetworkConnection,
+  BlockV3,
+  GENESIS_TX_ID,
+  RawTransactionV2,
+  TXIN_WITNESS_COINBASE
+} from '@did-btcr2/bitcoin';
+import { ResolveError } from '@did-btcr2/common';
+import { BeaconService, BeaconSignal } from './interfaces.js';
+import { BeaconUtils } from './utils.js';
+
+/**
+ * Static utility class for discovering Beacon Signals on the Bitcoin blockchain.
+ * Extracted from {@link Resolve} for single-responsibility and independent testability.
+ *
+ * @class BeaconSignalDiscovery
+ */
+export class BeaconSignalDiscovery {
+
+  /**
+   * Retrieves the beacon signals for the given array of BeaconService objects
+   * using an esplora/electrs REST API connection via a bitcoin I/O driver.
+   * @param {Array<BeaconService>} beaconServices Array of BeaconService objects to retrieve signals for
+   * @param {BitcoinNetworkConnection} bitcoin Bitcoin network connection to use for REST calls
+   * @returns {Promise<Map<BeaconService, Array<BeaconSignal>>>} Map of beacon service to its discovered signals
+   */
+  static async indexer(
+    beaconServices: Array<BeaconService>,
+    bitcoin: BitcoinNetworkConnection
+  ): Promise<Map<BeaconService, Array<BeaconSignal>>> {
+    const beaconServiceSignals = new Map<BeaconService, Array<BeaconSignal>>();
+
+    // Fetch the current block count once before the loop
+    const currentBlockCount = await bitcoin.network.rest.block.count();
+
+    // Iterate over each beacon
+    for (const beaconService of beaconServices) {
+      beaconServiceSignals.set(beaconService, []);
+      // Get the transactions for the beacon address via REST
+      const beaconSignals = await bitcoin.network.rest.address.getTxs(
+        beaconService.serviceEndpoint as string
+      );
+
+      // If no signals are found, continue
+      if (!beaconSignals || !beaconSignals.length) {
+        continue;
+      }
+
+      // Iterate over each signal
+      for (const beaconSignal of beaconSignals) {
+        // Get the last vout in the transaction
+        const signalVout = beaconSignal.vout.slice(-1)[0];
+
+        /**
+         * Look for OP_RETURN in last vout scriptpubkey_asm
+         * Vout (rest) format:
+         * {
+         *  scriptpubkey: '6a20570f177c65e64fb5cf61180b664cdddf09ab76153c2b192e22006e5b22a3917a',
+         *  scriptpubkey_asm: 'OP_RETURN OP_PUSHBYTES_32 570f177c65e64fb5cf61180b664cdddf09ab76153c2b192e22006e5b22a3917a',
+         *  scriptpubkey_type: 'op_return',
+         *  value: 0
+         * }
+         */
+        if(!signalVout || !signalVout.scriptpubkey_asm.includes('OP_RETURN')) {
+          continue;
+        }
+
+        // Construct output map for easier access
+        const outputMap = new Map<string, string | number>(Object.entries(signalVout));
+
+        // Grab the signal vout scriptpubkey
+        const signalVoutScriptPubkey = outputMap.get('scriptpubkey_asm') as string;
+
+        // If the signal vout scriptpubkey does not exist, continue to next signal
+        if(!signalVoutScriptPubkey){
+          continue;
+        }
+
+        // Extract hex string hash of the signal bytes from the scriptpubkey
+        const updateHash = signalVoutScriptPubkey.split(' ').slice(-1)[0];
+        if(!updateHash) {
+          continue;
+        }
+
+        // Use the pre-fetched block count instead of calling per-signal
+        const confirmations = currentBlockCount - beaconSignal.status.block_height + 1;
+
+        // Push the beacon signal object to the signals array for the beacon service
+        beaconServiceSignals.get(beaconService)?.push({
+          tx            : beaconSignal,
+          signalBytes   : updateHash,
+          blockMetadata : {
+            confirmations,
+            height : beaconSignal.status.block_height,
+            time   : beaconSignal.status.block_time,
+          }
+        });
+      }
+    }
+
+    return beaconServiceSignals;
+  }
+
+  /**
+   * Traverse the full blockchain from genesis to chain top looking for beacon signals.
+   * @param {Array<BeaconService>} beaconServices Array of BeaconService objects to search for signals.
+   * @param {BitcoinNetworkConnection} bitcoin Bitcoin network connection to use for RPC calls.
+   * @returns {Promise<Map<BeaconService, Array<BeaconSignal>>>} Map of beacon service to its discovered signals.
+   */
+  static async fullnode(
+    beaconServices: Array<BeaconService>,
+    bitcoin: BitcoinNetworkConnection
+  ): Promise<Map<BeaconService, Array<BeaconSignal>>> {
+    const beaconServiceSignals = new Map<BeaconService, Array<BeaconSignal>>();
+
+    for(const beaconService of beaconServices) {
+      beaconServiceSignals.set(beaconService, []);
+    }
+
+    // Get the RPC connection from the bitcoin network
+    const rpc = bitcoin.network.rpc;
+
+    // Ensure that the RPC connection is available
+    if(!rpc) {
+      throw new ResolveError('RPC connection is not available', 'RPC_CONNECTION_ERROR', bitcoin);
+    }
+
+    // Get the current block height once before the loop
+    const targetHeight = await rpc.getBlockCount();
+
+    // Hoist the beacon services map before the loop
+    const beaconServicesMap = BeaconUtils.getBeaconServicesMap(beaconServices);
+
+    // Set genesis height
+    let height = 0;
+
+    // Opt into rpc connection to get the block data at the blockhash
+    let block = await bitcoin.network.rpc!.getBlock({ height }) as BlockV3;
+
+    console.info(`Searching for beacon signals, please wait ...`);
+    while (block.height <= targetHeight) {
+      // Iterate over each transaction in the block
+      for (const tx of block.tx) {
+        // If the txid is a coinbase, continue ...
+        if (tx.txid === GENESIS_TX_ID) {
+          continue;
+        }
+
+        // Iterate over each input in the transaction
+        for (const vin of tx.vin) {
+
+          // If the vin is a coinbase transaction, continue ...
+          if (vin.coinbase) {
+            continue;
+          }
+
+          // If the vin txinwitness contains a coinbase did, continue ...
+          if (vin.txinwitness && vin.txinwitness.length === 1 && vin.txinwitness[0] === TXIN_WITNESS_COINBASE) {
+            continue;
+          }
+
+          // If the txid from the vin is undefined, continue ...
+          if (!vin.txid) {
+            continue;
+          }
+
+          // If the vout from the vin is undefined, continue ...
+          if (vin.vout === undefined) {
+            continue;
+          }
+
+          // Get the previous output transaction data
+          const prevout = await rpc.getRawTransaction(vin.txid, 2) as RawTransactionV2;
+
+          // If the previous output vout at the vin.vout index is undefined, continue ...
+          if (!prevout.vout[vin.vout]) {
+            continue;
+          }
+
+          // Get the address from the scriptPubKey from the prevvout
+          const scriptPubKey = prevout.vout[vin.vout].scriptPubKey;
+
+          // If the scriptPubKey.address is undefined, continue ...
+          if (!scriptPubKey.address) {
+            continue;
+          }
+
+          // Use the hoisted beaconServicesMap instead of rebuilding per-vin
+          const beaconService = beaconServicesMap.get(scriptPubKey.address);
+          if (!beaconService) {
+            continue;
+          }
+
+          // Look for 'OP_RETURN' in the scriptPubKey asm
+          const txVoutScriptPubkeyAsm = prevout.vout[vin.vout].scriptPubKey.asm;
+          if(!txVoutScriptPubkeyAsm.includes('OP_RETURN')) {
+            continue;
+          }
+
+          // Log the found txid and beacon
+          console.info(`Tx ${tx.txid} contains beacon service address ${scriptPubKey.address} and OP_RETURN!`, tx);
+
+          // Extract hex string hash of the signal bytes from the scriptpubkey
+          const updateHash = txVoutScriptPubkeyAsm.split(' ').slice(-1)[0];
+          if(!updateHash) {
+            continue;
+          }
+
+          // Push the beacon signal object to the beacon signals array for that beacon service
+          beaconServiceSignals.get(beaconService)?.push({
+            tx,
+            signalBytes   : updateHash,
+            blockMetadata : {
+              height        : block.height,
+              time          : block.time,
+              confirmations : block.confirmations
+            }
+          });
+        };
+      }
+
+      // Increment the height
+      height += 1;
+
+      // Use pre-fetched targetHeight instead of calling rpc.getBlockCount() every iteration
+      if(height > targetHeight) {
+        console.info(`Chain tip reached ${height}, breaking ...`);
+        break;
+      }
+
+      // Reset the block var to the next block data
+      block = await rpc.getBlock({ height }) as BlockV3;
+    }
+
+    return beaconServiceSignals;
+  }
+}