@did-btcr2/method 0.18.0 → 0.19.0

package/src/core/beacon/utils.ts

@@ -1,36 +1,10 @@
+import { getNetwork } from '@did-btcr2/bitcoin';
 import { DidMethodError, KeyBytes, Maybe, MethodError } from '@did-btcr2/common';
-import { DidService } from '@web5/dids';
 import { networks, payments } from 'bitcoinjs-lib';
-import { BeaconService, BeaconServiceAddress } from '../../interfaces/beacon.js';
 import { Appendix } from '../../utils/appendix.js';
 import { DidDocument } from '../../utils/did-document.js';
-import { BeaconFactory } from './factory.js';
-export interface GenerateBeaconParams {
-  identifier: string;
-  publicKey: KeyBytes;
-  network: networks.Network;
-  type: string;
-}
-/**
- * Required parameters for generating Beacon Services.
- * @interface GenerateBitcoinAddrsParams
- * @type {GenerateBitcoinAddrsParams}
- */
-export interface GenerateBitcoinAddrsParams {
-  publicKey: KeyBytes;
-  network: networks.Network;
-}
-
-/**
- * Required parameters for generating Beacon Services.
- * @interface GenerateBeaconServicesParams
- * @type {GenerateBeaconServicesParams}
- */
-export interface GenerateBeaconServicesParams {
-  publicKey: KeyBytes;
-  network: networks.Network
-  beaconType: string;
-}
+import { Identifier } from '../identifier.js';
+import { BeaconService } from './interfaces.js';
 
 /**
  * Static class of utility functions for the Beacon Service
@@ -44,11 +18,11 @@ export class BeaconUtils {
    * @returns {string} The Bitcoin address extracted from the URI
    * @throws {DidMethodError} if the URI is not a valid Bitcoin URI
    */
-  public static parseBitcoinAddress(uri: string): string {
+  static parseBitcoinAddress(uri: string): string {
     if (!uri.startsWith('bitcoin:')) {
-      throw new DidMethodError('Invalid Bitcoin URI format', { type: 'BEACON_ERROR' });
+      throw new MethodError('Invalid Bitcoin URI format', 'BEACON_SERVICE_ERROR', { uri });
     }
-    return uri.replace('bitcoin:', '').split('?')[0]; // Extracts address from "bitcoin:<address>?params"
+    return uri.replace('bitcoin:', '').split('?')[0];
   }
 
   /**
@@ -56,12 +30,12 @@ export class BeaconUtils {
    * @param {BeaconService} obj The object to validate
    * @returns {boolean} A boolean indicating whether the object is a Beacon Service
    */
-  public static isBeaconService(obj: Maybe<BeaconService>): boolean {
+  static isBeaconService(obj: Maybe<BeaconService>): boolean {
     // Return false if the given obj is not a valid DidService.
     if(!Appendix.isDidService(obj)) return false;
 
     // Return false if the type is not a valid beacon service type.
-    if(!['SingletonBeacon', 'CIDAggregateBeacon', 'SMTAggregateBeacon'].includes(obj.type)) return false;
+    if(!['SingletonBeacon', 'CASBeacon', 'SMTBeacon'].includes(obj.type)) return false;
 
     // 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;
@@ -79,38 +53,26 @@ export class BeaconUtils {
    * @returns {DidService[]} An array of DidService objects
    * @throws {TypeError} if the didDocument is not provided
    */
-  public static getBeaconServices(didDocument: DidDocument): BeaconService[] {
-    // Filter out any invalid did service objects.
-    const didServices: DidService[] = didDocument.service?.filter(Appendix.isDidService) ?? [];
+  static getBeaconServices(didDocument: DidDocument): BeaconService[] {
     // Filter for valid beacon service objects.
-    return (didServices.filter(this.isBeaconService) ?? []) as BeaconService[];
+    return (didDocument.service.filter(this.isBeaconService) ?? []) as BeaconService[];
   }
 
   /**
-   * Generate all 3 Beacon Service Endpoints for a given public key.
-   * @param {GenerateBitcoinAddrsParams} params Required parameters for generating Beacon Services.
-   * @param {KeyBytes} params.publicKey Public key bytes used to generate the beacon object serviceEndpoint.
-   * @param {Network} params.network Bitcoin network interface from bitcoinlib-js.
+   * Create the 3 default Beacon Service Endpoints for a given `k` (public-key-based) identifier.
+   * @param {string} did The DID for which to create the beacon services.
    * @returns {Array<Array<string>>} 2D Array of bitcoin addresses (p2pkh, p2wpkh, p2tr).
    * @throws {DidMethodError} if the bitcoin address is invalid.
    */
-  public static generateBeaconAddresses({ identifier, publicKey, network }: {
-    identifier: string;
-    publicKey: KeyBytes;
-    network: networks.Network;
-  }): Array<Array<string>> {
+  static createBeaconServices(did: string, beaconType: string): Array<BeaconService> {
     try {
-      const p2pkh = payments.p2pkh({ pubkey: publicKey, network }).address;
-      const p2wpkh = payments.p2wpkh({ pubkey: publicKey, network }).address;
-      const p2tr = payments.p2tr({ network, internalPubkey: publicKey.slice(1, 33) }).address;
-      if (!p2pkh || !p2wpkh || !p2tr) {
-        throw new DidMethodError('Failed to generate bitcoin addresses');
-      }
-      return [
-        [`${identifier}#initialP2PKH`, p2pkh],
-        [`${identifier}#initialP2WPKH`, p2wpkh],
-        [`${identifier}#initialP2TR`, p2tr]
-      ];
+      // Get the Network class
+      const addrTypes = ['p2pkh', 'p2wpkh', 'p2tr'] as Array<'p2pkh' | 'p2wpkh' | 'p2tr'>;
+
+      // Map over the address types and create the beacon services
+      return addrTypes.map(
+        (addrType) => this.createBeaconService(did, addrType, beaconType)
+      );
     } catch (error) {
       console.error(error);
       process.exit(1);
@@ -119,150 +81,98 @@ export class BeaconUtils {
 
   /**
    * Generate a set of Beacon Services for a given public key.
-   * @param {GenerateBeaconServicesParams} params Required parameters for generating Beacon Services.
-   * @param {KeyBytes} params.publicKey Public key bytes used to generate the beacon object serviceEndpoint.
-   * @param {Network} params.network Bitcoin network interface from bitcoinlib-js.
-   * @param {string} params.beaconType The type of beacon service to create.
-   * @param {string} params.addressType The type of address to create (p2pkh, p2wpkh, p2tr).
+   * @param {string} did The did for the beacon service.
+   * @param {string} addressType The type of bitcoin address to generate (p2pkh, p2wpkh, p2tr).
+   * @param {string} beaconType The type of beacon service to create.
    * @returns {BeaconService} A BeaconService object.
    * @throws {DidMethodError} if the bitcoin address is invalid.
    */
-  public static generateBeaconService({ id, publicKey: pubkey, network, addressType, type }: {
-    id: string;
-    publicKey: KeyBytes;
-    network: networks.Network;
-    addressType: 'p2pkh' | 'p2wpkh' | 'p2tr';
-    type: string;
-  }): BeaconService {
+  static createBeaconService(did: string, addressType: 'p2pkh' | 'p2wpkh' | 'p2tr', beaconType: string): BeaconService {
     try {
-      if(!id.includes('#')) {
-        id = `${id}#initial${addressType.toUpperCase()}`;
-      }
+      // Decode the DID to get the network and genesis bytes
+      const components = Identifier.decode(did);
+      // Get the Network class
+      const network = getNetwork(components.network);
+      // Get the genesis bytes
+      const pubkey = components.genesisBytes;
+      // Build the id
+      const id = `${did}#initial${addressType.toUpperCase()}`;
+      // Generate the bitcoin address
       const serviceEndpoint = `bitcoin:${payments[addressType]({ pubkey, network }).address}`;
-      return { id, type, serviceEndpoint, };
+      // Return the beacon serviceD
+      return { id, type: beaconType, serviceEndpoint, };
     } catch (error) {
       console.error(error);
       process.exit(1);
     }
   }
 
+
   /**
-   * Generate a custom Beacon Service.
-   * @param {GenerateBeaconServicesParams} params Required parameters for generating Beacon Services.
-   * @returns
+   * 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.
+   * @returns {Array<Array<string>>} 2D Array of bitcoin addresses (p2pkh, p2wpkh, p2tr).
+   * @throws {DidMethodError} if the bitcoin address is invalid.
    */
-  public static generateBeaconServiceCustom({ id, publicKey: pubkey, network, addressType, type }: {
+  static generateBeaconServices({ id, publicKey, network, beaconType }: {
     id: string;
     publicKey: KeyBytes;
     network: networks.Network;
-    addressType: 'p2pkh' | 'p2wpkh' | 'p2tr';
-    type: string;
-  }): BeaconService {
+    beaconType: string;
+  }): Array<BeaconService> {
     try {
-      if(!id.includes('#')) {
-        throw new MethodError(
-          'Invalid id format. It should include a fragment identifier (e.g., #initialP2PKH).',
-          'BEACON_ERROR',
-          { id }
-        );
+      // Generate the bitcoin addresses for the given public key and network
+      const p2pkh = payments.p2pkh({ pubkey: publicKey, network }).address;
+      const p2wpkh = payments.p2wpkh({ pubkey: publicKey, network }).address;
+      const p2tr = payments.p2tr({ network, internalPubkey: publicKey.slice(1, 33) }).address;
+      // Check that all addresses were generated successfully
+      if (!p2pkh || !p2wpkh || !p2tr) {
+        throw new DidMethodError('Failed to generate bitcoin addresses');
       }
-      const serviceEndpoint = `bitcoin:${payments[addressType]({ pubkey, network }).address}`;
-      return { id, type, serviceEndpoint, };
+      // Return the beacon services with the generated addresses as service endpoints
+      return [
+        {
+          id              : `${id}#initialP2PKH`,
+          type            : beaconType,
+          serviceEndpoint : `bitcoin:${p2pkh}`
+        },
+        {
+          id              : `${id}#initialP2WPKH`,
+          type            : beaconType,
+          serviceEndpoint : `bitcoin:${p2wpkh}`
+        },
+        {
+          id              : `${id}#initialP2TR`,
+          type            : beaconType,
+          serviceEndpoint : `bitcoin:${p2tr}`
+        },
+      ];
     } catch (error) {
       console.error(error);
       process.exit(1);
     }
   }
 
-  /**
-   * Generate beacon services.
-   * @param {GenerateBeaconServicesParams} params Required parameters for generating Beacon Services.
-   * @param {string} params.network The name of the Bitcoin network to use.
-   * @param {Uint8Array} params.publicKey Byte array representation of a public key used to generate a new btcr2 key-id-type.
-   * @param {string} params.beaconType Optional beacon type to use (default: SingletonBeacon).
-   * @returns {DidService[]} Array of DidService objects.
-   */
-  public static generateBeaconServices({ identifier, network, type, publicKey }: {
-    identifier: string;
-    publicKey: KeyBytes;
-    network: networks.Network;
-    type: string;
-  }): Array<BeaconService> {
-    // Generate the bitcoin addresses
-    const bitcoinAddrs = this.generateBeaconAddresses({ identifier, publicKey, network, });
-
-    // Map the bitcoin addresses to the beacon service
-    return bitcoinAddrs.map(([id, address]) => {
-      // Convert the address to a BIP-21 URI
-      const serviceEndpoint = `bitcoin:${address}`;
-      // Create the beacon object
-      const beacon = BeaconFactory.establish({ id, type, serviceEndpoint });
-      // Return the beacon service
-      return beacon.service;
-    });
-  }
-
-  /**
-   * Generate a single beacon service.
-   * @param {GenerateBeaconParams} params Required parameters for generating a single Beacon Service.
-   * @param {string} params.identifier The identifier for the beacon service.
-   * @param {string} params.network The name of the Bitcoin network to use.
-   * @param {Uint8Array} params.publicKey Byte array representation of a public key used to generate a new btcr2 key-id-type.
-   * @param {string} params.type The type of beacon service to create.
-   * @returns {BeaconService} A BeaconService object.
-   * @throws {DidMethodError} if the bitcoin address is invalid.
-   */
-  public static generateBeacon({ identifier, network, type, publicKey }: {
-    identifier: string;
-    publicKey: KeyBytes;
-    network: networks.Network;
-    type: string;
-  }): BeaconService {
-    // Generate the bitcoin addresses
-    const bitcoinAddrs = this.generateBeaconAddresses({ identifier, publicKey, network, });
-
-    // Map the bitcoin addresses to the beacon service
-    const beacon = bitcoinAddrs.map(([id, address]) => {
-      // Convert the address to a BIP-21 URI
-      const serviceEndpoint = `bitcoin:${address}`;
-      // Create the beacon object
-      const beacon = BeaconFactory.establish({ id, type, serviceEndpoint });
-      // Return the beacon service
-      return beacon.service;
-    });
-
-    return beacon[0];
-  }
-
-  /**
-   * Manufacture a pre-filled Beacon using the BeaconFactory.
-   * @param {BeaconServicesParams} params Required parameters for generating a single Beacon Service.
-   * @param {string} params.serviceId The type of service being created (#initialP2PKH, #initialP2WPKH, #initialP2TR).
-   * @param {string} params.beaconType The type of beacon service being created (SingletonBeacon, SMTAggregatorBeacon).
-   * @param {string} params.bitcoinAddress The bitcoin address to use for the service endpoint.
-   * @returns {BeaconService} One BeaconService object.
-   */
-  public static manufactureBeacon(params: BeaconService): BeaconService {
-    return BeaconFactory.establish(params).service;
-  }
-
   /**
    * Convert beacon service endpoints from BIP-21 URIs to addresses.
-   * @param {Array<BeaconService>} beacons The list of beacon services.
-   * @returns {Array<BeaconServiceAddress>} An array of beacon services with address: bitcoinAddress.
+   * @param {BeaconService} beacon The beacon service to parse.
+   * @returns {BeaconServiceAddress} The beacon service with the address field extracted from the serviceEndpoint.
    */
-  public static toBeaconServiceAddress(beacons: Array<BeaconService>): Array<BeaconServiceAddress> {
-    return beacons.map((beacon) => ({ ...beacon, address: beacon.serviceEndpoint.replace('bitcoin:', '')}));
+  static parseBeaconServiceEndpoint(beacon: BeaconService): BeaconService {
+    return { ...beacon, serviceEndpoint: beacon.serviceEndpoint.replace('bitcoin:', '')};
   }
 
   /**
    * Create a map of address => beaconService with address field.
    * @param {Array<BeaconService>} beacons The list of beacon services.
-   * @returns {Map<string, BeaconServiceAddress>} A map of address => beaconService.
+   * @returns {Map<string, BeaconService>} A map of address => beaconService.
    */
-  public static getBeaconServiceAddressMap(beacons: Array<BeaconService>): Map<string, BeaconServiceAddress> {
-    const beaconAddrs = this.toBeaconServiceAddress(beacons);
-    return new Map<string, BeaconServiceAddress>(beaconAddrs.map((beacon) => ([beacon.address, beacon])));
+  static getBeaconServicesMap(beacons: Array<BeaconService>): Map<string, BeaconService> {
+    return new Map<string, BeaconService>(
+      beacons
+        .map(this.parseBeaconServiceEndpoint)
+        .map((beacon) => ([beacon.serviceEndpoint as string, beacon]))
+    );
   }
 
   /**
@@ -270,7 +180,7 @@ export class BeaconUtils {
    * @param {DidDocument} didDocument The DID Document to extract the services from.
    * @returns {string[]} An array of beacon service ids.
    */
-  public static getBeaconServiceIds(didDocument: DidDocument): string[] {
+  static getBeaconServiceIds(didDocument: DidDocument): string[] {
     return this.getBeaconServices(didDocument).map((beacon) => beacon.id);
   }
 }

package/src/core/identifier.ts

@@ -1,4 +1,4 @@
-import { BitcoinNetworkNames, Bytes, IdentifierTypes, INVALID_DID, METHOD_NOT_SUPPORTED, MethodError } from '@did-btcr2/common';
+import { BitcoinNetworkNames, Bytes, IdentifierError, IdentifierTypes, INVALID_DID, METHOD_NOT_SUPPORTED } from '@did-btcr2/common';
 import { CompressedSecp256k1PublicKey, SchnorrKeyPair } from '@did-btcr2/keypair';
 import { bech32m } from '@scure/base';
 
@@ -48,7 +48,7 @@ export class Identifier {
    * @param {KeyBytes | DocumentBytes} params.genesisBytes Public key or an intermediate document bytes.
    * @returns {string} The new did:btcr2 identifier.
    */
-  public static encode({ idType, version, network, genesisBytes }: {
+  static encode({ idType, version, network, genesisBytes }: {
     idType: string;
     version: number;
     network: string;
@@ -56,22 +56,22 @@ export class Identifier {
   }): string {
     // 1. If idType is not a valid value per above, raise invalidDid error.
     if (!(idType in IdentifierTypes)) {
-      throw new MethodError('Expected "idType" to be "KEY" or "EXTERNAL"', INVALID_DID, {idType});
+      throw new IdentifierError('Expected "idType" to be "KEY" or "EXTERNAL"', INVALID_DID, {idType});
     }
 
     // 2. If version is greater than 1, raise invalidDid error.
     if (isNaN(version) || version > 1) {
-      throw new MethodError('Expected "version" to be 1', INVALID_DID, {version});
+      throw new IdentifierError('Expected "version" to be 1', INVALID_DID, {version});
     }
 
     // 3. If network is not a valid value (bitcoin|signet|regtest|testnet3|testnet4|number), raise invalidDid error.
     if (typeof network === 'string' && !(network in BitcoinNetworkNames)) {
-      throw new MethodError('Invalid "network" name', INVALID_DID, {network});
+      throw new IdentifierError('Invalid "network" name', INVALID_DID, {network});
     }
 
     // 4. If network is a number and is outside the range of 1-8, raise invalidDid error.
     if(typeof network === 'number' && (network < 0 || network > 8)) {
-      throw new MethodError('Invalid "network" number', INVALID_DID, {network});
+      throw new IdentifierError('Invalid "network" number', INVALID_DID, {network});
     }
 
     // 5. If idType is “key” and genesisBytes is not a valid compressed secp256k1 public key, raise invalidDid error.
@@ -79,7 +79,7 @@ export class Identifier {
       try {
         new CompressedSecp256k1PublicKey(genesisBytes);
       } catch {
-        throw new MethodError(
+        throw new IdentifierError(
           'Expected "genesisBytes" to be a valid compressed secp256k1 public key',
           INVALID_DID, { genesisBytes }
         );
@@ -127,15 +127,12 @@ export class Identifier {
     // 14. Create a dataBytes byte array from nibbles, where index is from 0 to nibbles.length / 2 - 1 and
     //     encodingBytes[index] = (nibbles[2 * index] << 4) | nibbles[2 * index + 1].
     if (fCount !== 0){
-      for(let index in Array.from({ length: (nibbles.length / 2) - 1 })) {
-        throw new MethodError('Not implemented', 'NOT_IMPLEMENTED', { index });
+      for(const index in Array.from({ length: (nibbles.length / 2) - 1 })) {
+        throw new IdentifierError('Not implemented', 'NOT_IMPLEMENTED', { index });
       }
     }
     const dataBytes = new Uint8Array([(nibbles[2 * 0] << 4) | nibbles[2 * 0 + 1], ...genesisBytes]);
 
-    // 15. Set identifier to “did:btcr2:”.
-    // 16. Pass hrp and dataBytes to the Bech32m Encoding algorithm, retrieving encodedString.
-    // 17. Append encodedString to identifier.
     // 18. Return identifier.
     return `did:btcr2:${bech32m.encodeFromBytes(hrp, dataBytes)}`;
   }
@@ -148,13 +145,13 @@ export class Identifier {
    * @throws {DidErrorCode.InvalidDid} if identifier is invalid
    * @throws {DidErrorCode.MethodNotSupported} if the method is not supported
    */
-  public static decode(identifier: string): DidComponents {
+  static decode(identifier: string): DidComponents {
     // 1. Split identifier into an array of components at the colon : character.
     const components = identifier.split(':');
 
     // 2. If the length of the components array is not 3, raise invalidDid error.
     if (components.length !== 3){
-      throw new MethodError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
+      throw new IdentifierError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
     }
 
     // Deconstruct the components of the identifier: scheme, method, encoded
@@ -162,26 +159,26 @@ export class Identifier {
 
     // 3. If components[0] is not “did”, raise invalidDid error.
     if (scheme !== 'did') {
-      throw new MethodError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
+      throw new IdentifierError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
     }
     // 4. If components[1] is not “btcr2”, raise methodNotSupported error.
     if (method !== 'btcr2') {
-      throw new MethodError(`Invalid did method: ${method}`, METHOD_NOT_SUPPORTED, { identifier });
+      throw new IdentifierError(`Invalid did method: ${method}`, METHOD_NOT_SUPPORTED, { identifier });
     }
 
     // 5. Set encodedString to components[2].
     if (!encoded) {
-      throw new MethodError(`Invalid method-specific id: ${identifier}`, INVALID_DID, { identifier });
+      throw new IdentifierError(`Invalid method-specific id: ${identifier}`, INVALID_DID, { identifier });
     }
     // 6. Pass encodedString to the Bech32m Decoding algorithm, retrieving hrp and dataBytes.
     const {prefix: hrp, bytes: dataBytes} = bech32m.decodeToBytes(encoded);
 
     // 7. If the Bech32m decoding algorithm fails, raise invalidDid error.
     if (!['x', 'k'].includes(hrp)) {
-      throw new MethodError(`Invalid hrp: ${hrp}`, INVALID_DID, { identifier });
+      throw new IdentifierError(`Invalid hrp: ${hrp}`, INVALID_DID, { identifier });
     }
     if (!dataBytes) {
-      throw new MethodError(`Failed to decode id: ${encoded}`, INVALID_DID, { identifier });
+      throw new IdentifierError(`Failed to decode id: ${encoded}`, INVALID_DID, { identifier });
     }
 
     // 8. Map hrp to idType from the following:
@@ -216,7 +213,7 @@ export class Identifier {
       nibblesConsumed += 1;
       // 14. If version is greater than 1, raise invalidDid error.
       if (version > 1) {
-        throw new MethodError(`Invalid version: ${version}`, INVALID_DID, { identifier });
+        throw new IdentifierError(`Invalid version: ${version}`, INVALID_DID, { identifier });
       }
     }
 
@@ -244,7 +241,7 @@ export class Identifier {
       if (networkValue >= 0x8 && networkValue <= 0xF) {
         network = networkValue - 11;
       } else {
-        throw new MethodError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
+        throw new IdentifierError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
       }
     }
 
@@ -254,7 +251,7 @@ export class Identifier {
       const fillerNibble = currentByte & 0x0F;
       //     17.2 If fillerNibble is not 0, raise invalidDid error.
       if (fillerNibble !== 0) {
-        throw new MethodError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
+        throw new IdentifierError(`Invalid did: ${identifier}`, INVALID_DID, { identifier });
       }
     }
 
@@ -266,7 +263,7 @@ export class Identifier {
       try {
         new CompressedSecp256k1PublicKey(genesisBytes);
       } catch {
-        throw new MethodError(`Invalid genesisBytes: ${genesisBytes}`, INVALID_DID, { identifier });
+        throw new IdentifierError(`Invalid genesisBytes: ${genesisBytes}`, INVALID_DID, { identifier });
       }
     }
 
@@ -278,7 +275,7 @@ export class Identifier {
    * Generates a new did:btcr2 identifier based on a newly generated key pair.
    * @returns {string} The new did:btcr2 identifier.
    */
-  public static generate(): { keys: SchnorrKeyPair; identifier: { controller: string; id: string } } {
+  static generate(): { keys: SchnorrKeyPair; identifier: { controller: string; id: string } } {
     const keys = SchnorrKeyPair.generate();
     const did = this.encode({
       idType       : IdentifierTypes.KEY,

package/src/core/interfaces.ts

@@ -0,0 +1,101 @@
+import { BitcoinNetworkConnection } from '@did-btcr2/bitcoin';
+import { DidResolutionOptions } from '@web5/dids';
+import { Sidecar } from './types.js';
+
+export interface RootCapability {
+    '@context': string;
+    id: string;
+    controller: string;
+    invocationTarget: string;
+}
+
+/**
+ * See {@link https://dcdpr.github.io/did-btcr2/data-structures.html#resolution-options-example-panel-show | Resolution Options}
+ * for data structure details.
+ */
+export interface ResolutionOptionsCore extends DidResolutionOptions {
+  /**
+   * Optional ASCII string representation of the specific version of a DID document
+   * to be resolved.
+   */
+  versionId?: string
+
+  /**
+   * Optional XML Datetime normalized to UTC without sub-second decimal precision.
+   * The DID document to be resolved is the most recent version of the DID document
+   * that was valid for the DID before the specified versionTime.
+   */
+  versionTime?: string;
+
+  /**
+   * Data transmitted via {@link https://dcdpr.github.io/did-btcr2/data-structures.html#sidecar-data-example-panel-show | Sidecar (data structure)}.
+   * Includes Singleton beacon updates, CAS announcements, and SMT proofs.
+   */
+  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?: 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;
+}
+
+/**
+ * {@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
+ * a path from a leaf in the tree to the Merkle root, proving that the leaf is in the tree.
+ * See {@link https://dcdpr.github.io/did-btcr2/data-structures.html#smt-proof | SMT Proof (data structure)}.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "<< Hexadecimal of Root Hash >>",
+ *   "nonce": "<< Hexadecimal of Nonce 1101 >>",
+ *   "updateId": "<< Hexadecimal of hash(Data Block 1101) >>",
+ *   "collapsed": "<< Hexadecimal of 0001 >>",
+ *   "hashes": [
+ *     "<< Hexadecimal of Hash 1110 >>",
+ *     "<< Hexadecimal of Hash 1001 >>",
+ *     "<< Hexadecimal of Hash 0 >>"
+ *   ]
+ * }
+ * ```
+ */
+export interface SMTProof {
+  /**
+   * The SHA-256 hash of the root node of the Sparse Merkle Tree.
+   */
+  id: string;
+  /**
+   * Optional 256-bit nonce generated for each update. MUST be encoded as a string using the "base64url" [RFC4648] encoding.
+   */
+  nonce?: string;
+  /**
+   * Optional BTCR2 Signed Update (data structure) hashed with the JSON Document Hashing algorithm.
+   */
+  updateId?: string;
+  /**
+   * Bitmap of zero nodes within the path (see: collapsed leaves).
+   */
+  collapsed: string;
+  /**
+   * Array of SHA-256 hashes representing the sibling SMT nodes from the leaf, containing the SHA-256 hash of the BTCR2 Signed Update or the “zero identity”, to the root.
+   */
+  hashes: string[];
+}