@did-btcr2/method 0.25.3 → 0.27.0

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

@@ -1,14 +1,24 @@
-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 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 { 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 { 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;
   }
 }

package/src/core/beacon/utils.ts

@@ -1,10 +1,12 @@
 import { getNetwork } from '@did-btcr2/bitcoin';
-import { DidMethodError, KeyBytes, Maybe, MethodError } from '@did-btcr2/common';
-import { networks, payments } from 'bitcoinjs-lib';
+import type { KeyBytes, Maybe} from '@did-btcr2/common';
+import { DidMethodError, MethodError } from '@did-btcr2/common';
+import type { networks} from 'bitcoinjs-lib';
+import { payments } from 'bitcoinjs-lib';
 import { Appendix } from '../../utils/appendix.js';
-import { DidDocument } from '../../utils/did-document.js';
+import type { DidDocument } from '../../utils/did-document.js';
 import { Identifier } from '../identifier.js';
-import { BeaconService } from './interfaces.js';
+import type { BeaconService } from './interfaces.js';
 import { BeaconError } from './error.js';
 
 /**

package/src/core/identifier.ts

@@ -1,7 +1,8 @@
-import { BitcoinNetworkNames, Bytes, DocumentBytes, IdentifierError, IdentifierTypes, INVALID_DID, KeyBytes, METHOD_NOT_SUPPORTED, SchnorrKeyPairObject } from '@did-btcr2/common';
+import type { Bytes, DocumentBytes, KeyBytes, SchnorrKeyPairObject } from '@did-btcr2/common';
+import { BitcoinNetworkNames, IdentifierError, IdentifierTypes, INVALID_DID, METHOD_NOT_SUPPORTED } from '@did-btcr2/common';
 import { CompressedSecp256k1PublicKey, SchnorrKeyPair } from '@did-btcr2/keypair';
 import { bech32m } from '@scure/base';
-import { DidCreateOptions } from '../did-btcr2.js';
+import type { DidCreateOptions } from '../did-btcr2.js';
 
 /**
  * Components of a did:btcr2 identifier.
@@ -290,6 +291,23 @@ export class Identifier {
     return { keyPair: keyPair.exportJSON(), did };
   }
 
+  /**
+   * Extracts the compressed secp256k1 public key from a KEY-type did:btcr2 identifier.
+   * @param {string} did The did:btcr2 identifier to extract the public key from.
+   * @returns {CompressedSecp256k1PublicKey} The compressed public key.
+   * @throws {IdentifierError} If the DID is EXTERNAL type (genesis bytes are a hash, not a pubkey).
+   */
+  static getPublicKey(did: string): CompressedSecp256k1PublicKey {
+    const { idType, genesisBytes } = Identifier.decode(did);
+    if(idType !== 'KEY') {
+      throw new IdentifierError(
+        `Cannot extract public key from EXTERNAL DID: ${did}. EXTERNAL DIDs encode a document hash, not a public key.`,
+        INVALID_DID, { did, idType }
+      );
+    }
+    return new CompressedSecp256k1PublicKey(genesisBytes);
+  }
+
   /**
    * Validates a did:btcr2 identifier.
    * @param {string} identifier The did:btcr2 identifier to validate.

package/src/core/interfaces.ts

@@ -1,5 +1,5 @@
-import { DidResolutionOptions } from '@web5/dids';
-import { Sidecar } from './types.js';
+import type { DidResolutionOptions } from '@web5/dids';
+import type { Sidecar } from './types.js';
 
 export interface RootCapability {
     '@context': string;
@@ -64,11 +64,11 @@ export interface SMTProof {
    */
   id: string;
   /**
-   * Optional 256-bit nonce generated for each update. MUST be encoded as a string using the "base64url" [RFC4648] encoding.
+   * Optional 256-bit nonce generated for each update. Hex-encoded (64 chars).
    */
   nonce?: string;
   /**
-   * Optional BTCR2 Signed Update (data structure) hashed with the JSON Document Hashing algorithm.
+   * Optional hex-encoded canonical hash of the BTCR2 Signed Update.
    */
   updateId?: string;
   /**

package/src/core/resolver.ts

@@ -1,6 +1,7 @@
 import { getNetwork } from '@did-btcr2/bitcoin';
 import {
   canonicalHash,
+  canonicalHashBytes,
   canonicalize,
   DateUtils,
   encode as encodeHash,
@@ -12,23 +13,28 @@ import {
   LATE_PUBLISHING_ERROR,
   ResolveError
 } from '@did-btcr2/common';
+import type { HashBytes } from '@did-btcr2/common';
+import type {
+  SignedBTCR2Update,
+  UnsignedBTCR2Update
+} from '@did-btcr2/cryptosuite';
 import {
   BIP340Cryptosuite,
   BIP340DataIntegrityProof,
-  SchnorrMultikey,
-  SignedBTCR2Update,
-  UnsignedBTCR2Update
+  SchnorrMultikey
 } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
 import { DidBtcr2 } from '../did-btcr2.js';
 import { Appendix } from '../utils/appendix.js';
 import { DidDocument, ID_PLACEHOLDER_VALUE } from '../utils/did-document.js';
 import { BeaconFactory } from './beacon/factory.js';
-import { BeaconService, BeaconSignal, BlockMetadata } from './beacon/interfaces.js';
+import type { BeaconService, BeaconSignal, BlockMetadata } from './beacon/interfaces.js';
 import { BeaconUtils } from './beacon/utils.js';
-import { DidComponents, Identifier } from './identifier.js';
-import { SMTProof } from './interfaces.js';
-import { CASAnnouncement, Sidecar, SidecarData } from './types.js';
+import type { DidComponents} from './identifier.js';
+import { Identifier } from './identifier.js';
+import type { SMTProof } from './interfaces.js';
+import type { CASAnnouncement, Sidecar, SidecarData } from './types.js';
+import { equalBytes } from '@noble/curves/utils.js';
 
 /**
  * The response object for DID Resolution.
@@ -46,7 +52,7 @@ export interface DidResolutionResponse {
 /** The resolver needs a genesis document whose hash matches genesisHash. */
 export interface NeedGenesisDocument {
   readonly kind: 'NeedGenesisDocument';
-  /** Base64url-encoded SHA-256 hash from the DID identifier's genesisBytes. */
+  /** Hex-encoded SHA-256 hash from the DID identifier's genesisBytes. */
   readonly genesisHash: string;
 }
 
@@ -60,7 +66,7 @@ export interface NeedBeaconSignals {
 /** The resolver needs a CAS Announcement whose canonical hash matches announcementHash. */
 export interface NeedCASAnnouncement {
   readonly kind: 'NeedCASAnnouncement';
-  /** Base64url-encoded canonical hash of the CAS Announcement. */
+  /** Hex-encoded canonical hash of the CAS Announcement. */
   readonly announcementHash: string;
   /** The beacon service that produced this signal. */
   readonly beaconServiceId: string;
@@ -69,14 +75,23 @@ export interface NeedCASAnnouncement {
 /** The resolver needs a SignedBTCR2Update whose canonical hash matches updateHash. */
 export interface NeedSignedUpdate {
   readonly kind: 'NeedSignedUpdate';
-  /** Base64url-encoded canonical hash of the signed update. */
+  /** Hex-encoded canonical hash of the signed update. */
   readonly updateHash: string;
   /** The beacon service that produced this signal. */
   readonly beaconServiceId: string;
 }
 
+/** The resolver needs an SMT Proof whose root hash matches smtRootHash. */
+export interface NeedSMTProof {
+  readonly kind: 'NeedSMTProof';
+  /** Hex-encoded SHA-256 root hash of the Sparse Merkle Tree. */
+  readonly smtRootHash: string;
+  /** The beacon service that produced this signal. */
+  readonly beaconServiceId: string;
+}
+
 /** Discriminated union of all data the resolver may request from the caller. */
-export type DataNeed = NeedGenesisDocument | NeedBeaconSignals | NeedCASAnnouncement | NeedSignedUpdate;
+export type DataNeed = NeedGenesisDocument | NeedBeaconSignals | NeedCASAnnouncement | NeedSignedUpdate | NeedSMTProof;
 
 /**
  * Output of {@link Resolver.resolve}. Analogous to Rust's `ResolverState` enum.
@@ -220,22 +235,22 @@ export class Resolver {
     didComponents: DidComponents,
     genesisDocument: object,
   ): DidDocument {
-    // Encode the genesis bytes from the did components
-    const genesisBytes = encodeHash(didComponents.genesisBytes);
+    // Canonicalize and sha256 hash the genesis document
+    const genesisDocumentHash = canonicalHashBytes(genesisDocument);
 
-    // Canonicalize and sha256 hash the currentDocument
-    const genesisDocumentBytes = canonicalHash(genesisDocument);
-
-    // If the genesisBytes do not match the hashBytes, throw an error
-    if (genesisBytes !== genesisDocumentBytes) {
+    // Compare genesis bytes from identifier against the document hash (byte comparison)
+    if (!equalBytes(didComponents.genesisBytes, genesisDocumentHash)) {
       throw new ResolveError(
-        `Initial document mismatch: genesisBytes !== genesisDocumentBytes`,
-        INVALID_DID_DOCUMENT, { genesisBytes, genesisDocumentBytes }
+        `Initial document mismatch: genesisBytes !== genesisDocumentHash`,
+        INVALID_DID_DOCUMENT, {
+          genesisBytes        : encodeHash(didComponents.genesisBytes, 'hex'),
+          genesisDocumentHash : encodeHash(genesisDocumentHash, 'hex')
+        }
       );
     }
 
     // Encode the did from the didComponents
-    const did = Identifier.encode(decodeHash(genesisBytes), didComponents);
+    const did = Identifier.encode(didComponents.genesisBytes, didComponents);
 
     // Replace the placeholder did with the did throughout the currentDocument.
     const currentDocument = JSON.parse(
@@ -256,14 +271,14 @@ export class Resolver {
     const updateMap = new Map<string, SignedBTCR2Update>();
     if(sidecar.updates?.length)
       for(const update of sidecar.updates) {
-        updateMap.set(canonicalHash(update), update);
+        updateMap.set(canonicalHash(update, { encoding: 'hex' }), update);
       }
 
     // CAS Announcements map
     const casMap = new Map<string, CASAnnouncement>();
     if(sidecar.casUpdates?.length)
       for(const update of sidecar.casUpdates) {
-        casMap.set(canonicalHash(update), update);
+        casMap.set(canonicalHash(update, { encoding: 'hex' }), update);
       }
 
     // SMT Proofs map
@@ -293,8 +308,8 @@ export class Resolver {
     // Start the version number being processed at 1
     let currentVersionId = 1;
 
-    // Initialize an empty array to hold the update hashes
-    const updateHashHistory: string[] = [];
+    // Initialize an empty array to hold the update hashes (raw bytes)
+    const updateHashHistory: HashBytes[] = [];
 
     // 1. Sort updates by targetVersionId (ascending), using blockheight as tie-breaker
     const updates = unsortedUpdates.sort(([upd0, blk0], [upd1, blk1]) =>
@@ -314,8 +329,8 @@ export class Resolver {
 
     // Iterate over each (update block) pair
     for(const [update, block] of updates) {
-      // Get the hash of the current document
-      const currentDocumentHash = canonicalHash(response.didDocument);
+      // Get the hash of the current document as raw bytes
+      const currentDocumentHash = canonicalHashBytes(response.didDocument);
 
       // Safely convert block.time to timestamp
       const blocktime = DateUtils.blocktimeToTimestamp(block.time);
@@ -345,12 +360,15 @@ export class Resolver {
 
       // If update.targetVersionId == currentVersionId + 1, apply the update
       else if (update.targetVersionId === currentVersionId + 1) {
-        // Check if update.sourceHash !== currentDocumentHash
-        if (update.sourceHash !== currentDocumentHash) {
-          // Raise an INVALID_DID_UPDATE error if they do not match
+        // Check if update.sourceHash !== currentDocumentHash (byte comparison)
+        const sourceHashBytes = decodeHash(update.sourceHash, 'base64urlnopad');
+        if (!equalBytes(sourceHashBytes, currentDocumentHash)) {
           throw new ResolveError(
             `Hash mismatch: update.sourceHash !== currentDocumentHash`,
-            INVALID_DID_UPDATE, { sourceHash: update.sourceHash, currentDocumentHash }
+            INVALID_DID_UPDATE, {
+              sourceHash          : update.sourceHash,
+              currentDocumentHash : encodeHash(currentDocumentHash, 'hex')
+            }
           );
         }
         // Apply the update to the currentDocument and set it in the response
@@ -358,8 +376,8 @@ export class Resolver {
 
         // Create unsigned_update by removing the proof property from update.
         const unsignedUpdate = JSONUtils.deleteKeys(update, ['proof']) as UnsignedBTCR2Update;
-        // Push the canonicalized unsigned update hash to the updateHashHistory
-        updateHashHistory.push(canonicalHash(unsignedUpdate));
+        // Push the canonicalized unsigned update hash bytes to the updateHashHistory
+        updateHashHistory.push(canonicalHashBytes(unsignedUpdate));
       }
 
       // If update.targetVersionId > currentVersionId + 1, throw LATE_PUBLISHING error
@@ -398,30 +416,31 @@ export class Resolver {
     return response;
   }
 
-  // ─── Private static: update internals ──────────────────────────────
-
   /**
    * Implements subsection {@link https://dcdpr.github.io/did-btcr2/#confirm-duplicate-update | 7.2.f.1 Confirm Duplicate Update}.
    * This step confirms that an update with a lower-than-expected targetVersionId is a true duplicate.
    * @param {SignedBTCR2Update} update The BTCR2 Signed Update to confirm as a duplicate.
-   * @param {string[]} updateHashHistory The accumulated hash history for comparison.
+   * @param {HashBytes[]} updateHashHistory The accumulated hash history for comparison.
    * @returns {void} Does not return a value, but throws an error if the update is not a valid duplicate.
    */
-  private static confirmDuplicate(update: SignedBTCR2Update, updateHashHistory: string[]): void {
+  private static confirmDuplicate(update: SignedBTCR2Update, updateHashHistory: HashBytes[]): void {
     // Create unsigned_update by removing the proof property from update.
     const { proof: _, ...unsignedUpdate } = update;
 
-    // Hash unsignedUpdate with JSON Document Hashing algorithm
-    const unsignedUpdateHash = canonicalHash(unsignedUpdate);
+    // Hash unsignedUpdate with JSON Document Hashing algorithm (raw bytes)
+    const unsignedUpdateHash = canonicalHashBytes(unsignedUpdate);
 
     // Let historicalUpdateHash equal updateHashHistory[updateHashIndex].
     const historicalUpdateHash = updateHashHistory[update.targetVersionId - 2];
 
-    // Check if the updateHash matches the historical hash
-    if (updateHashHistory[update.targetVersionId - 2] !== unsignedUpdateHash) {
+    // Check if the updateHash matches the historical hash (byte comparison)
+    if (!equalBytes(historicalUpdateHash, unsignedUpdateHash)) {
       throw new ResolveError(
-        `Invalid duplicate: ${unsignedUpdateHash} does not match ${historicalUpdateHash}`,
-        LATE_PUBLISHING_ERROR, { unsignedUpdateHash, updateHashHistory }
+        `Invalid duplicate: unsigned update hash does not match historical hash`,
+        LATE_PUBLISHING_ERROR, {
+          unsignedUpdateHash : encodeHash(unsignedUpdateHash, 'hex'),
+          historicalHash     : encodeHash(historicalUpdateHash, 'hex')
+        }
       );
     }
   }
@@ -499,14 +518,14 @@ export class Resolver {
     // Verify that updatedDocument is conformant to DID Core v1.1.
     DidDocument.validate(updatedDocument);
 
-    // Canonicalize and hash the updatedDocument to get the currentDocumentHash.
-    const currentDocumentHash = canonicalHash(updatedDocument);
+    // Canonicalize and hash the updatedDocument to get the currentDocumentHash (raw bytes).
+    const currentDocumentHash = canonicalHashBytes(updatedDocument);
 
     // Prepare the update targetHash for comparison with currentDocumentHash.
-    const updateTargetHash = update.targetHash;
+    const updateTargetHash = decodeHash(update.targetHash);
 
     // Make sure the update.targetHash equals currentDocumentHash.
-    if (update.targetHash !== currentDocumentHash) {
+    if (!equalBytes(updateTargetHash, currentDocumentHash)) {
       // If they do not match, throw INVALID_DID_UPDATE error.
       throw new ResolveError(
         `Invalid update: update.targetHash !== currentDocumentHash`,
@@ -518,8 +537,6 @@ export class Resolver {
     return updatedDocument;
   }
 
-  // ─── Instance: state machine ───────────────────────────────────────
-
   /**
    * Advance the state machine. Returns either:
    * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
@@ -546,7 +563,7 @@ export class Resolver {
           }
 
           // Need genesis document from caller
-          const genesisHash = encodeHash(this.#didComponents.genesisBytes);
+          const genesisHash = encodeHash(this.#didComponents.genesisBytes, 'hex');
           return {
             status : 'action-required',
             needs  : [{ kind: 'NeedGenesisDocument', genesisHash }]
@@ -675,7 +692,8 @@ export class Resolver {
   provide(need: NeedBeaconSignals, data: Map<BeaconService, Array<BeaconSignal>>): void;
   provide(need: NeedCASAnnouncement, data: CASAnnouncement): void;
   provide(need: NeedSignedUpdate, data: SignedBTCR2Update): void;
-  provide(need: DataNeed, data: object | Map<BeaconService, Array<BeaconSignal>> | CASAnnouncement | SignedBTCR2Update): void {
+  provide(need: NeedSMTProof, data: SMTProof): void;
+  provide(need: DataNeed, data: object | Map<BeaconService, Array<BeaconSignal>> | CASAnnouncement | SignedBTCR2Update | SMTProof): void {
     switch(need.kind) {
       case 'NeedGenesisDocument': {
         this.#providedGenesisDocument = data;
@@ -692,13 +710,26 @@ export class Resolver {
 
       case 'NeedCASAnnouncement': {
         const announcement = data as CASAnnouncement;
-        this.#sidecarData.casMap.set(canonicalHash(announcement), announcement);
+        this.#sidecarData.casMap.set(canonicalHash(announcement, { encoding: 'hex' }), announcement);
         break;
       }
 
       case 'NeedSignedUpdate': {
         const update = data as SignedBTCR2Update;
-        this.#sidecarData.updateMap.set(canonicalHash(update), update);
+        this.#sidecarData.updateMap.set(canonicalHash(update, { encoding: 'hex' }), update);
+        break;
+      }
+
+      case 'NeedSMTProof': {
+        const smtNeed = need as NeedSMTProof;
+        const proof = data as SMTProof;
+        if(proof.id !== smtNeed.smtRootHash) {
+          throw new ResolveError(
+            `SMT proof root hash mismatch: expected ${smtNeed.smtRootHash}, got ${proof.id}`,
+            INVALID_DID_UPDATE, { expected: smtNeed.smtRootHash, actual: proof.id }
+          );
+        }
+        this.#sidecarData.smtMap.set(smtNeed.smtRootHash, proof);
         break;
       }
     }

package/src/core/types.ts

@@ -1,6 +1,5 @@
-import { HexString } from '@did-btcr2/common';
-import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
-import { SMTProof } from './interfaces.js';
+import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SMTProof } from './interfaces.js';
 
 /**
  * {@link https://dcdpr.github.io/did-btcr2/data-structures.html#cas-announcement | CAS Announcement }
@@ -58,12 +57,14 @@ export type Sidecar = {
 
 /**
  * The Sidecar data structure used for Singleton Beacons.
+ * Map keyed by hex-encoded canonical hash of the signed update.
  */
-export type SingletonBeaconSidecarData = Map<HexString, SignedBTCR2Update>;
+export type SingletonBeaconSidecarData = Map<string, SignedBTCR2Update>;
 /**
  * The Sidecar data structure used for CAS Beacons.
+ * Map keyed by hex-encoded canonical hash of the CAS announcement.
  */
-export type CASBeaconSidecarData = Map<HexString, CASAnnouncement>;
+export type CASBeaconSidecarData = Map<string, CASAnnouncement>;
 /**
  * The Sidecar data structure used for SMT Beacons.
  */

package/src/core/update.ts

@@ -1,21 +1,25 @@
+import type {
+  KeyBytes,
+  PatchOperation} from '@did-btcr2/common';
 import {
   canonicalHash,
   INVALID_DID_UPDATE,
   JSONPatch,
-  KeyBytes,
-  PatchOperation,
   UpdateError
 } from '@did-btcr2/common';
-import {
+import type {
   DataIntegrityConfig,
-  SchnorrMultikey,
   SignedBTCR2Update,
   UnsignedBTCR2Update
 } from '@did-btcr2/cryptosuite';
-import { Btcr2DidDocument, DidDocument, DidVerificationMethod } from '../utils/did-document.js';
+import {
+  SchnorrMultikey
+} from '@did-btcr2/cryptosuite';
+import type { Btcr2DidDocument, DidVerificationMethod } from '../utils/did-document.js';
+import { DidDocument } from '../utils/did-document.js';
 import { BeaconFactory } from './beacon/factory.js';
-import { BeaconService } from './beacon/interfaces.js';
-import { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type { BeaconService } from './beacon/interfaces.js';
+import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/operations/update.html | 7.3 Update}.

package/src/did-btcr2.ts

@@ -1,33 +1,35 @@
-import { BitcoinConnection } from '@did-btcr2/bitcoin';
-import {
+import type { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type {
   DocumentBytes,
   HexString,
+  KeyBytes,
+  PatchOperation} from '@did-btcr2/common';
+import {
   IdentifierHrp,
   INVALID_DID_DOCUMENT,
   INVALID_DID_UPDATE,
-  KeyBytes,
   METHOD_NOT_SUPPORTED,
   MethodError,
-  PatchOperation,
   UpdateError
 } from '@did-btcr2/common';
-import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type {
+  DidMethod} from '@web5/dids';
 import {
   Did,
   DidError,
-  DidErrorCode,
-  DidMethod,
+  DidErrorCode
 } from '@web5/dids';
 import * as ecc from '@bitcoinerlab/secp256k1';
 import { hexToBytes } from '@noble/hashes/utils';
 import { initEccLib } from 'bitcoinjs-lib';
-import { BeaconService } from './core/beacon/interfaces.js';
+import type { BeaconService } from './core/beacon/interfaces.js';
 import { Identifier } from './core/identifier.js';
-import { ResolutionOptions } from './core/interfaces.js';
+import type { ResolutionOptions } from './core/interfaces.js';
 import { Resolver } from './core/resolver.js';
 import { Update } from './core/update.js';
 import { Appendix } from './utils/appendix.js';
-import { Btcr2DidDocument, DidVerificationMethod } from './utils/did-document.js';
+import type { Btcr2DidDocument, DidVerificationMethod } from './utils/did-document.js';
 
 export interface DidCreateOptions {
   /** Type of identifier to create (key or external) */