@did-btcr2/method 0.25.2 → 0.26.0

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.

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;

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,7 +75,7 @@ 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;
@@ -220,22 +226,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 currentDocument
-    const genesisDocumentBytes = canonicalHash(genesisDocument);
+    // Canonicalize and sha256 hash the genesis document
+    const genesisDocumentHash = canonicalHashBytes(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 +262,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 +299,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 +320,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 +351,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 +367,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 +407,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 +509,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 +528,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 +554,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 }]
@@ -692,13 +700,13 @@ 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;
       }
     }

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) */

package/src/utils/appendix.ts

@@ -1,17 +1,16 @@
-import { HashBytes } from '@did-btcr2/common';
-import { strings } from '@helia/strings';
-import {
+import type { HashBytes } from '@did-btcr2/common';
+import type {
   DidDocument,
+  DidService,
+  DidVerificationMethod} from '@web5/dids';
+import {
   DidError,
   DidErrorCode,
-  DidService,
-  DidVerificationMethod,
   DidVerificationRelationship
 } from '@web5/dids';
-import { createHelia } from 'helia';
 import { CID } from 'multiformats';
 import { create as createDigest } from 'multiformats/hashes/digest';
-import { RootCapability } from '../core/interfaces.js';
+import type { RootCapability } from '../core/interfaces.js';
 
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/#appendix | 9. Appendix} methods.
@@ -67,10 +66,10 @@ export class Appendix {
   }
 
   /**
-   * Extracts the verification methods from a given DID Document
-   * @param {DidDocument} params.didDocument The DID Document to extract the verification methods from
-   * @returns {DidVerificationMethod[]} An array of DidVerificationMethod objects
-   * @throws {TypeError} if the didDocument is not provided
+   * Extracts the verification methods from a given DID Document.
+   * @param didDocument The DID Document to extract the verification methods from
+   * @returns An array of DidVerificationMethod objects
+   * @throws TypeError if the didDocument is not provided
    */
   public static getVerificationMethods(didDocument: DidDocument): DidVerificationMethod[] {
     if (!didDocument) throw new TypeError(`Required parameter missing: 'didDocument'`);
@@ -215,6 +214,10 @@ export class Appendix {
     // Construct CID from hash bytes
     const cid = CID.create(1, 1, createDigest(1, hashBytes));
 
+    // Lazy-load helia to avoid bundling its native deps into downstream CJS builds.
+    const { createHelia } = await import('helia');
+    const { strings } = await import('@helia/strings');
+
     // Connect to IPFS/Helia node
     const helia = await createHelia();
     const node = strings(helia);
@@ -223,8 +226,3 @@ export class Appendix {
     return await node.get(cid, {});
   }
 }
-
-
-
-
-

package/src/utils/did-document-builder.ts

@@ -1,6 +1,7 @@
 import { DidDocumentError, INVALID_DID_DOCUMENT } from '@did-btcr2/common';
-import { BeaconService } from '../core/beacon/interfaces.js';
-import { DidDocument, DidVerificationMethod } from './did-document.js';
+import type { BeaconService } from '../core/beacon/interfaces.js';
+import type { DidVerificationMethod } from './did-document.js';
+import { DidDocument } from './did-document.js';
 
 /**
  * A builder class for constructing DID Documents.

package/src/utils/did-document.ts

@@ -1,20 +1,22 @@
 import { getNetwork } from '@did-btcr2/bitcoin';
+import type {
+  HashBytes,
+  JSONObject,
+  KeyBytes
+} from '@did-btcr2/common';
 import {
   canonicalize,
   DidDocumentError,
   hash,
-  HashBytes,
   IdentifierTypes,
   INVALID_DID_DOCUMENT,
-  JSONObject,
-  JSONUtils,
-  KeyBytes
+  JSONUtils
 } from '@did-btcr2/common';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
-import { DidDocument as W3CDidDocument, DidVerificationMethod as W3CDidVerificationMethod } from '@web5/dids';
+import type { DidDocument as W3CDidDocument, DidVerificationMethod as W3CDidVerificationMethod } from '@web5/dids';
+import { isDidService } from '@web5/dids/utils';
 import { payments } from 'bitcoinjs-lib';
-import { BeaconService } from '../core/beacon/interfaces.js';
-import { BeaconUtils } from '../core/beacon/utils.js';
+import type { BeaconService } from '../core/beacon/interfaces.js';
 import { Identifier } from '../core/identifier.js';
 import { Appendix } from './appendix.js';
 
@@ -342,7 +344,7 @@ export class DidDocument implements Btcr2DidDocument {
    * @returns {boolean} True if the services are valid.
    */
   private static isValidServices(service: unknown): boolean {
-    return Array.isArray(service) && service.every(BeaconUtils.isBeaconService);
+    return Array.isArray(service) && service.every(isDidService);
   }
 
   /**