@did-btcr2/method 0.19.0 → 0.22.0

package/src/core/beacon/singleton.ts

@@ -1,74 +1,51 @@
 import { AddressUtxo, BitcoinNetworkConnection } from '@did-btcr2/bitcoin';
-import { HexString, INVALID_SIDECAR_DATA, MethodError, MISSING_UPDATE_DATA, SingletonBeaconError } from '@did-btcr2/common';
-import { BTCR2SignedUpdate } from '@did-btcr2/cryptosuite';
-import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
-import { Kms, Signer } from '@did-btcr2/kms';
+import { Canonicalization, INVALID_SIDECAR_DATA, KeyBytes, MISSING_UPDATE_DATA } from '@did-btcr2/common';
+import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { Signer } from '@did-btcr2/kms';
 import { opcodes, Psbt, script } from 'bitcoinjs-lib';
 import { base58btc } from 'multiformats/bases/base58';
-import { canonicalization } from '../../did-btcr2.js';
-import { Identifier } from '../identifier.js';
 import { SidecarData } from '../types.js';
-import { AggregateBeacon, BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
+import { Beacon } from './beacon.js';
+import { SingletonBeaconError } from './error.js';
+import { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#singleton-beacon | Singleton Beacon}.
- *
  * @class SingletonBeacon
  * @type {SingletonBeacon}
- * @extends {AggregateBeacon}
+ * @extends {Beacon}
  */
-export class SingletonBeacon extends AggregateBeacon {
+export class SingletonBeacon extends Beacon {
 
   /**
    * Creates an instance of SingletonBeacon.
-   * @param {BeaconService} service The Beacon service.
-   * @param {?BeaconSidecarData} sidecar The SingletonBeacon sidecar data.
-   */
-  constructor(
-    service: BeaconService,
-    signals: Array<BeaconSignal>,
-    sidecar: SidecarData,
-    bitcoin?: BitcoinNetworkConnection
-  ) {
-    super({ ...service, type: 'SingletonBeacon' }, signals, sidecar, bitcoin);
-  }
-
-  /**
-   * Static, convenience method for establishing a CASBeacon object.
-   * @param {string} service The Beacon service.
-   * @param {SidecarData} sidecar The sidecar data.
-   * @returns {SingletonBeacon} The Singleton Beacon.
-   */
-  static establish(service: BeaconService, signals: Array<BeaconSignal>, sidecar: SidecarData): SingletonBeacon {
-    return new SingletonBeacon(service, signals, sidecar);
-  }
-
-  /**
-   * Generates a Beacon Signal for a Singleton Beacon Service.
-   * @param {HexString} updateHash The update hash to be included in the Beacon Signal.
-   * @returns {BeaconSignal} The generated signal.
-   * @throws {MethodError} if the signal is invalid.
+   * @param {BeaconService} service The BeaconService object representing the funded beacon to announce the update to.
+   *
    */
-  generateSignal(updateHash: HexString): BeaconSignal {
-    throw new MethodError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {updateHash});
+  constructor(service: BeaconService) {
+    super({ ...service, type: 'SingletonBeacon' });
   }
 
   /**
    * Processes an array of Beacon Signals associated with a Singleton Beacon Service.
-   * @returns {Promise<BTCR2SignedUpdate | undefined>} The DID Update payload announced by the Beacon Signal.
+   * @returns {Promise<SignedBTCR2Update | undefined>} The DID Update payload announced by the Beacon Signal.
    * @throws {SingletonBeaconError} if the signalTx is invalid or the signalSidecarData is invalid.
    */
-  async processSignals(): Promise<Array<[BTCR2SignedUpdate, BlockMetadata]>> {
+  async processSignals(
+    signals: Array<BeaconSignal>,
+    sidecar: SidecarData
+  ): Promise<Array<[SignedBTCR2Update, BlockMetadata]>> {
     // Initialize an empty array to hold the BTCR2 signed updates
-    const updates = new Array<[BTCR2SignedUpdate, BlockMetadata]>();
+    const updates = new Array<[SignedBTCR2Update, BlockMetadata]>();
 
-    // Loop through each signal in this.signals
-    for(const signal of this.signals || []) {
+    // Loop through each signal in signals
+    for(const signal of signals) {
       // Grab the beacon signal bytes hash from the signal
       const updateHash = signal.signalBytes;
 
       // Use the updateHash as the sidecar data lookup key to retrieve the btcr2 update
-      const signedUpdate = this.sidecar.updateMap.get(updateHash);
+      const signedUpdate = sidecar.updateMap.get(updateHash);
 
       // If no btcr2 update is found in sidecar data maps, throw missingUpdateData error.
       if(!signedUpdate) {
@@ -79,7 +56,7 @@ export class SingletonBeacon extends AggregateBeacon {
       }
 
       // Canonicalize, hash and encode to base58 the signed update object found in sidecar or CAS
-      const encodedUpdate = canonicalization.process(signedUpdate, { encoding: 'base58' });
+      const encodedUpdate = Canonicalization.process(signedUpdate, { encoding: 'base58' });
 
       // Encode the signal bytes hex string to base58
       const signalBytes = base58btc.encode(Buffer.from(updateHash, 'hex'));
@@ -100,28 +77,39 @@ export class SingletonBeacon extends AggregateBeacon {
     // Return the array of signed updates
     return updates;
   }
-
   /**
-   * Broadcasts a SingletonBeacon signal.
-   * TODO: Design and implement a way to construct, sign and send via RPC
-   *
-   * @returns {SignedRawTx} Successful output of a bitcoin transaction.
+   * Broadcasts a SingletonBeacon 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.
+   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
    * @throws {SingletonBeaconError} if the bitcoin address is invalid or unfunded.
    */
-  async broadcastSignal(updateHash: HexString): Promise<HexString> {
-    // 1. Initialize an addressURI variable to beacon.serviceEndpoint.
-    // 2. Set bitcoinAddress to the decoding of addressURI following BIP21.
+  async broadcastSignal(
+    signedUpdate: SignedBTCR2Update,
+    secretKey: KeyBytes,
+    bitcoin: BitcoinNetworkConnection
+  ): Promise<SignedBTCR2Update> {
+    // Convert the serviceEndpoint to a bitcoin address by removing the 'bitcoin:' prefix
     const bitcoinAddress = this.service.serviceEndpoint.replace('bitcoin:', '');
 
-    // 3. Ensure bitcoinAddress is funded, if not, fund this address.
-    // let inputs: Array<CreateRawTxInputs> = [];
+    // Query the Bitcoin network for UTXOs associated with the bitcoinAddress
+    const utxos = await bitcoin.network.rest.address.getUtxos(bitcoinAddress);
 
-    const utxos = await this.bitcoin.network.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 });
+      throw new SingletonBeaconError(
+        'No UTXOs found, please fund address!',
+        'UNFUNDED_BEACON_ADDRESS', { bitcoinAddress }
+      );
     }
 
-    const utxo: AddressUtxo = utxos.sort((a, b) => b.status.block_height - a.status.block_height)[0];
+    // 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.',
@@ -129,55 +117,45 @@ export class SingletonBeacon extends AggregateBeacon {
       );
     }
 
-    // 4. Set hashBytes to the result of passing signedUpdate to the JSON Canonicalization and Hash algorithm.
-    const udpateHashBytes = Buffer.from(updateHash, 'hex');
-    if (udpateHashBytes.length !== 32) {
-      throw new SingletonBeaconError('Hash must be 32 bytes');
-    }
-
-    // 5. Initialize spendTx to a Bitcoin transaction that spends a transaction controlled by the bitcoinAddress and
-    //    contains at least one transaction output. This output MUST have the following format
-    //    [OP_RETURN, OP_PUSH32, hashBytes]
-    const {txid, vout} = utxo;
-    const prevTx = await this.bitcoin.network.rest.transaction.getHex(txid);
-    const input = {
-      hash           : txid,
-      index          : vout,
-      nonWitnessUtxo : Buffer.from(prevTx, 'hex')
-    };
-    // TODO: Figure out a good way to estimate fees
-    const spendTx  = new Psbt({ network: this.bitcoin.network.data })
-      .addInput(input)
+    // Get the previous tx to the utxo being spent
+    const prevTx = await bitcoin.network.rest.transaction.getHex(utxo.txid);
+
+    // Canonicalize and hash the signed update for OP_RETURN output
+    const updateHash = Canonicalization.andHash(signedUpdate);
+
+    // Construct a spend transaction
+    const spendTx = new Psbt({ network: bitcoin.network.data })
+      // Spend tx contains the utxo as its input
+      .addInput({
+        hash           : utxo.txid,
+        index          : utxo.vout,
+        nonWitnessUtxo : Buffer.from(prevTx, 'hex')
+      })
+      // 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) })
-      .addOutput({ script: script.compile([opcodes.OP_RETURN, udpateHashBytes]), value: 0n });
-
-    // 6. Retrieve the cryptographic material, e.g private key or signing capability, associated with the bitcoinAddress
-    //    or service. How this is done is left to the implementer.
-    const components = Identifier.decode(this.service.id);
-    const keyUri = new CompressedSecp256k1PublicKey(components.genesisBytes).hex;
-    const keyPair = Kms.getKey(keyUri as string);
-    if (!keyPair) {
-      throw new Error('Key pair not found.');
-    }
+      // Add an OP_RETURN output containing the update hash
+      .addOutput({ script: script.compile([opcodes.OP_RETURN, updateHash]), value: 0n });
+
+    // Construct a Schnorr key pair from the secret key
+    const keyPair = SchnorrKeyPair.fromSecret(secretKey);
 
-    const signer = new Signer({ keyPair, network: this.bitcoin.network.name });
+    // Construct a signer object from the key pair and bitcoin network
+    const signer = new Signer({ keyPair, network: bitcoin.network.name });
 
-    // 7. Sign the spendTx.
+    // Sign 0th input, finalize extract to hex in prep for broadcast
     const signedTx = spendTx.signInput(0, signer)
       .finalizeAllInputs()
       .extractTransaction()
       .toHex();
-    if(!spendTx) {
-      throw new SingletonBeaconError('Failed to sign raw transaction.', 'RAW_TX_SIGN_FAILED', { spendTx });
-    }
 
-    // 8. Broadcast spendTx to the Bitcoin network.
-    const spentTx = await this.bitcoin.network.rest.transaction.send(signedTx);
-    if(!spentTx) {
-      throw new SingletonBeaconError('Failed to send raw transaction.', 'SEND_FAILED', { spentTx });
-    }
+    // Broadcast spendTx to the Bitcoin network.
+    const txid = await bitcoin.network.rest.transaction.send(signedTx);
+
+    // Log the txid of the broadcasted transaction
+    console.info(`Singleton Beacon Signal Broadcasted with txid: ${txid}`);
 
-    // Return the signed update and the spend tx id.
-    return spentTx;
+    // Return the signed update
+    return signedUpdate;
   }
 }

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

@@ -1,70 +1,53 @@
 import { BitcoinNetworkConnection } from '@did-btcr2/bitcoin';
-import { HexString, MethodError } from '@did-btcr2/common';
-import { BTCR2SignedUpdate } from '@did-btcr2/cryptosuite';
+import { KeyBytes } from '@did-btcr2/common';
+import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import { SidecarData } from '../types.js';
-import { AggregateBeacon, BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
+import { Beacon } from './beacon.js';
+import { SMTBeaconError } from './error.js';
+import { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
 /**
- * TODO: Finish implementation
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#smt-beacon | SMTBeacon}.
  * @class SMTBeacon
  * @type {SMTBeacon}
- * @extends {AggregateBeacon}
+ * @extends {Beacon}
  */
-export class SMTBeacon extends AggregateBeacon {
+export class SMTBeacon extends Beacon {
   /**
-   * Creates an instance of SingletonBeacon.
+   * Creates an instance of SMTBeacon.
    * @param {BeaconService} service The Beacon service.
-   * @param {Array<BeaconSignal>} signals The SingletonBeacon sidecar data.
-   * @param {SidecarData} sidecar The sidecar data.
    */
-  constructor(
-    service: BeaconService,
-    signals: Array<BeaconSignal>,
-    sidecar: SidecarData,
-    bitcoin?: BitcoinNetworkConnection
-  ) {
-    super({ ...service, type: 'SMTBeacon' }, signals, sidecar, bitcoin);
-  }
-
-  /**
-   * Static, convenience method for establishing a SMTBeacon object.
-   * @param {string} service The Beacon service.
-   * @param {SidecarData} sidecar The sidecar data.
-   * @returns {SingletonBeacon} The Singleton Beacon.
-   */
-  static establish(service: BeaconService, signals: Array<BeaconSignal>, sidecar: SidecarData): SMTBeacon {
-    return new SMTBeacon(service, signals, sidecar);
-  }
-
-  /**
-   * TODO: Figure out if this is necessary or not.
-   * @param {HexString} updateHash The hash of the BTCR2 update to generate the signal for.
-   * @returns {BeaconSignal} The generated signal.
-   * @throws {MethodError} if the signal is invalid.
-   */
-  generateSignal(updateHash: HexString): BeaconSignal {
-    throw new MethodError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {updateHash});
+  constructor(service: BeaconService) {
+    super({ ...service, type: 'SMTBeacon' });
   }
 
   /**
-   * Process SMTBeacon signals.
-   * @returns {Promise<Array<BTCR2SignedUpdate>>} The processed signed update or undefined.
-   * @throws {MethodError} if the signal processing fails.
+   * Implements {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#process-smt-beacon | 7.2.e.1 Process SMT Beacon}.
+   * @param {Array<BeaconSignal>} signals The array of Beacon Signals to process.
+   * @param {SidecarData} sidecar The sidecar data associated with the SMT Beacon.
+   * @returns {Promise<Array<[SignedBTCR2Update, BlockMetadata]>>} The processed signals.
+   * @throws {SMTBeaconError} if processing fails.
    */
-  async processSignals(): Promise<Array<[BTCR2SignedUpdate, BlockMetadata]>> {
-    throw new MethodError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`);
+  processSignals(
+    signals: Array<BeaconSignal>,
+    sidecar: SidecarData
+  ): Promise<Array<[SignedBTCR2Update, BlockMetadata]>> {
+    throw new SMTBeaconError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {signals, sidecar});
   }
 
-
   /**
-   * Broadcast a SMTBeacon signal.
-   * @param {HexString} updateHash The hash of the BTCR2 update to broadcast.
-   * @returns {Promise<SignalsMetadata>} The result of the broadcast.
-   * @throws {MethodError} if the broadcast fails.
+   * 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 {SMTBeaconError} if broadcasting fails.
    */
-  async broadcastSignal(updateHash: HexString): Promise<HexString> {
-    throw new MethodError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {updateHash});
+  async broadcastSignal(
+    signedUpdate: SignedBTCR2Update,
+    secretKey: KeyBytes,
+    bitcoin: BitcoinNetworkConnection
+  ): Promise<SignedBTCR2Update> {
+    throw new SMTBeaconError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {signedUpdate, secretKey, bitcoin});
   }
-
 }

package/src/core/beacon/utils.ts

@@ -5,6 +5,7 @@ import { Appendix } from '../../utils/appendix.js';
 import { DidDocument } from '../../utils/did-document.js';
 import { Identifier } from '../identifier.js';
 import { BeaconService } from './interfaces.js';
+import { BeaconError } from './error.js';
 
 /**
  * Static class of utility functions for the Beacon Service
@@ -40,9 +41,6 @@ export class BeaconUtils {
     // Return false if the serviceEndpoint is not a valid BIP21 bitcoin address.
     if ([obj.serviceEndpoint].flat().some(ep => typeof ep === 'string' && !ep.startsWith('bitcoin:'))) return false;
 
-    // Return false if the casType exists and is not a string.
-    if(obj.casType && typeof obj.casType !== 'string') return false;
-
     // Else return true
     return true;
   }
@@ -73,9 +71,11 @@ export class BeaconUtils {
       return addrTypes.map(
         (addrType) => this.createBeaconService(did, addrType, beaconType)
       );
-    } catch (error) {
-      console.error(error);
-      process.exit(1);
+    } catch (error: any) {
+      throw new BeaconError(
+        'Failed to create beacon services: ' + error.message,
+        'BEACON_SERVICE_ERROR', { did, beaconType }
+      );
     }
   }
 
@@ -101,13 +101,14 @@ export class BeaconUtils {
       const serviceEndpoint = `bitcoin:${payments[addressType]({ pubkey, network }).address}`;
       // Return the beacon serviceD
       return { id, type: beaconType, serviceEndpoint, };
-    } catch (error) {
-      console.error(error);
-      process.exit(1);
+    } catch (error: any) {
+      throw new BeaconError(
+        'Failed to create beacon service: ' + error.message,
+        'BEACON_SERVICE_ERROR', { did, beaconType }
+      );
     }
   }
 
-
   /**
    * Generate three default Beacon Service Endpoints for a given `k` (public-key-based) identifier.
    * @param {string} did The DID for which to create the beacon services.
@@ -147,9 +148,11 @@ export class BeaconUtils {
           serviceEndpoint : `bitcoin:${p2tr}`
         },
       ];
-    } catch (error) {
-      console.error(error);
-      process.exit(1);
+    } catch (error: any) {
+      throw new BeaconError(
+        'Failed to create beacon services: ' + error.message,
+        'BEACON_SERVICE_ERROR', { id, publicKey, network, beaconType }
+      );
     }
   }
 

package/src/core/interfaces.ts

@@ -43,17 +43,9 @@ export interface ResolutionOptions extends ResolutionOptionsCore {
   /**
    * Drivers for interacting with external systems, such as the Bitcoin network.
    */
-  drivers: {
+  drivers?: {
     bitcoin?: BitcoinNetworkConnection;
   };
-
-  /**
-   * Flag to signal a full blockchain search for beacon signals from genesis
-   * block to chain tip during resolution, instead of using an indexer.
-   * @type {boolean}
-   * @default false
-   */
-  fullBlockchainTraversal?: boolean;
 }
 
 /**