@did-btcr2/method 0.24.1 → 0.25.2

package/src/core/beacon/factory.ts

@@ -2,7 +2,7 @@ import { MethodError } from '@did-btcr2/common';
 import { Beacon } from './beacon.js';
 import { CASBeacon } from './cas-beacon.js';
 import { BeaconService } from './interfaces.js';
-import { SingletonBeacon } from './singleton.js';
+import { SingletonBeacon } from './singleton-beacon.js';
 import { SMTBeacon } from './smt-beacon.js';
 
 /**

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

@@ -38,7 +38,7 @@ export class BeaconSignalDiscovery {
       beaconServiceSignals.set(beaconService, []);
       // Get the transactions for the beacon address via REST
       const beaconSignals = await bitcoin.rest.address.getTxs(
-        beaconService.serviceEndpoint as string
+        BeaconUtils.parseBitcoinAddress(beaconService.serviceEndpoint as string)
       );
 
       // If no signals are found, continue

package/src/core/beacon/{singleton.ts → singleton-beacon.ts}

@@ -1,9 +1,10 @@
 import { AddressUtxo, BitcoinConnection } from '@did-btcr2/bitcoin';
-import { canonicalHash, canonicalize, hash, INVALID_SIDECAR_DATA, KeyBytes, MISSING_UPDATE_DATA } from '@did-btcr2/common';
+import { canonicalize, decode, encode, hash, KeyBytes } from '@did-btcr2/common';
 import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import { SchnorrKeyPair } from '@did-btcr2/keypair';
-import { base64urlnopad } from '@scure/base';
+import { hexToBytes } from '@noble/hashes/utils';
 import { opcodes, Psbt, script } from 'bitcoinjs-lib';
+import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import { SidecarData } from '../types.js';
 import { Beacon } from './beacon.js';
 import { SingletonBeaconError } from './error.js';
@@ -27,54 +28,38 @@ export class SingletonBeacon extends Beacon {
 
   /**
    * Processes an array of Beacon Signals associated with a Singleton Beacon Service.
-   * @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.
+   * @param {Array<BeaconSignal>} signals The beacon signals discovered on-chain.
+   * @param {SidecarData} sidecar The processed sidecar data.
+   * @returns {BeaconProcessResult} Successfully resolved updates and any data needs.
    */
-  async processSignals(
+  processSignals(
     signals: Array<BeaconSignal>,
     sidecar: SidecarData
-  ): Promise<Array<[SignedBTCR2Update, BlockMetadata]>> {
-    // Initialize an empty array to hold the BTCR2 signed updates
+  ): BeaconProcessResult {
     const updates = new Array<[SignedBTCR2Update, BlockMetadata]>();
+    const needs = new Array<DataNeed>();
 
-    // Loop through each signal in signals
     for(const signal of signals) {
-      // Grab the beacon signal bytes hash from the signal
-      const updateHash = signal.signalBytes;
+      // Decode signal bytes from hex and re-encode to base64url for sidecar lookup
+      const updateHash = encode(decode(signal.signalBytes, 'hex'));
 
-      // Use the updateHash as the sidecar data lookup key to retrieve the btcr2 update
+      // Look up the signed update in sidecar updateMap
       const signedUpdate = sidecar.updateMap.get(updateHash);
 
-      // If no btcr2 update is found in sidecar data maps, throw missingUpdateData error.
       if(!signedUpdate) {
-        throw new SingletonBeaconError(
-          `BTCR2 Signed Update not found for update hash ${updateHash}.`,
-          MISSING_UPDATE_DATA, signal
-        );
+        // Data not available — emit a need instead of throwing
+        needs.push({
+          kind             : 'NeedSignedUpdate',
+          updateHash,
+          beaconServiceId  : this.service.id
+        });
+        continue;
       }
 
-      // TODO: Review for simplification how we are encoding and comparing
-      // Canonicalize, hash and encode to base64url the signed update object found in sidecar or CAS
-      const encodedUpdate = canonicalHash(signedUpdate, { encoding: 'base64url' });
-
-      // Encode the signal bytes hex string to base64url
-      const signalBytes = base64urlnopad.encode(Buffer.from(updateHash, 'hex'));
-
-      // Check for mismatch between found sidecar/cas update hash and onchain beacon signal hash
-      if (encodedUpdate !== signalBytes) {
-        // If mismatch, throw invalidSidecarData error.
-        throw new SingletonBeaconError(
-          `Hash mismatch: sidecar update ${encodedUpdate} !== signal bytes ${signalBytes}.`,
-          INVALID_SIDECAR_DATA, { encodedUpdate, signalBytes }
-        );
-      }
-
-      // Push signedUpdate to updates array
       updates.push([signedUpdate, signal.blockMetadata]);
     }
 
-    // Return the array of signed updates
-    return updates;
+    return { updates, needs };
   }
   /**
    * Broadcasts a SingletonBeacon signal to the Bitcoin network.
@@ -128,7 +113,7 @@ export class SingletonBeacon extends Beacon {
       .addInput({
         hash           : utxo.txid,
         index          : utxo.vout,
-        nonWitnessUtxo : Buffer.from(prevTx, 'hex')
+        nonWitnessUtxo : hexToBytes(prevTx)
       })
       // Add a change output minus a fee of 500 sats
       // TODO: calculate fee based on transaction vsize and current fee rates

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

@@ -1,10 +1,11 @@
 import { BitcoinConnection } from '@did-btcr2/bitcoin';
 import { KeyBytes } from '@did-btcr2/common';
 import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { BeaconProcessResult } from '../resolver.js';
 import { SidecarData } from '../types.js';
 import { Beacon } from './beacon.js';
 import { SMTBeaconError } from './error.js';
-import { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
+import { BeaconService, BeaconSignal } from './interfaces.js';
 
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#smt-beacon | SMTBeacon}.
@@ -25,13 +26,13 @@ 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}.
    * @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.
+   * @returns {BeaconProcessResult} The processed signals.
    * @throws {SMTBeaconError} if processing fails.
    */
   processSignals(
     signals: Array<BeaconSignal>,
     sidecar: SidecarData
-  ): Promise<Array<[SignedBTCR2Update, BlockMetadata]>> {
+  ): BeaconProcessResult {
     throw new SMTBeaconError('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {signals, sidecar});
   }
 

package/src/core/interfaces.ts

@@ -1,4 +1,3 @@
-import { BitcoinConnection } from '@did-btcr2/bitcoin';
 import { DidResolutionOptions } from '@web5/dids';
 import { Sidecar } from './types.js';
 
@@ -12,8 +11,12 @@ export interface RootCapability {
 /**
  * See {@link https://dcdpr.github.io/did-btcr2/data-structures.html#resolution-options-example-panel-show | Resolution Options}
  * for data structure details.
+ *
+ * Resolution is now fully sans-I/O via the {@link Resolver} state machine.
+ * External data (Bitcoin signals, CAS data) is provided through the
+ * `resolver.resolve()` / `resolver.provide()` protocol.
  */
-export interface ResolutionOptionsCore extends DidResolutionOptions {
+export interface ResolutionOptions extends DidResolutionOptions {
   /**
    * Optional ASCII string representation of the specific version of a DID document
    * to be resolved.
@@ -34,20 +37,6 @@ export interface ResolutionOptionsCore extends DidResolutionOptions {
   sidecar?: Sidecar;
 }
 
-/**
- * Full set of resolution options for the did:btcr2 method. See {@link ResolutionOptionsCore}
- * for the resolution options defined by the specification.
- * @extends ResolutionOptionsCore
- */
-export interface ResolutionOptions extends ResolutionOptionsCore {
-  /**
-   * Drivers for interacting with external systems, such as the Bitcoin network.
-   */
-  drivers?: {
-    bitcoin?: BitcoinConnection;
-  };
-}
-
 /**
  * {@link https://dcdpr.github.io/did-btcr2/terminology.html#smt-proof | SMT Proof}
  * a set of SHA-256 hashes for nodes in a Sparse Merkle Tree that together form