@did-btcr2/method 0.13.1

package/src/types/crud.ts

@@ -0,0 +1,41 @@
+import { DidUpdatePayload, ProofBytes } from '@did-btcr2/common';
+import { BeaconService } from '../interfaces/ibeacon.js';
+import { Btc1DidDocument } from '../utils/did-document.js';
+import { BlockV3 } from './bitcoin.js';
+
+export type FindNextSignals = {
+  block: BlockV3;
+  beacons: BeaconService[]
+};
+export type Metadata = {
+  btc1Update: DidUpdatePayload;
+  proofs?: string;
+};
+export type SignalSidecarData = Metadata;
+export interface Btc1SidecarData {
+  did: string;
+}
+export type SignalsMetadata = { [signalId: string]: Metadata; };
+export interface SingletonSidecar extends Btc1SidecarData {
+  signalsMetadata: SignalsMetadata;
+}
+export interface CIDAggregateSidecar extends Btc1SidecarData {
+  initialDocument: Btc1DidDocument;
+  signalsMetadata: SignalsMetadata;
+  cidUpdates: Array<string>;
+}
+export interface SMTAggregateSidecar extends Btc1SidecarData {
+  initialDocument: Btc1DidDocument;
+  signalsMetadata: SignalsMetadata;
+  smtProof: ProofBytes;
+}
+export type BeaconSidecarData<T> =
+  T extends 'SingletonBeacon' ? SingletonSidecar :
+  T extends 'CIDAggregateBeacon' ? CIDAggregateSidecar :
+  T extends 'SMTAggregateBeacon' ? SMTAggregateSidecar :
+  T;
+export type SidecarData = BeaconSidecarData<SingletonSidecar | CIDAggregateSidecar | SMTAggregateSidecar>;
+export type GetSigningMethodParams = {
+  didDocument: Btc1DidDocument;
+  methodId?: string;
+};

package/src/utils/appendix.ts

@@ -0,0 +1,257 @@
+import { Bytes, HashBytes, Logger, W3C_ZCAP_V1 } from '@did-btcr2/common';
+import { strings } from '@helia/strings';
+import {
+  DidDocument,
+  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 { Btc1RootCapability } from '../interfaces/crud.js';
+import { Btc1VerificationMethod } from './did-document.js';
+
+export interface DidComponents {
+    hrp: string;
+    idType: string;
+    version: number;
+    network: string;
+    genesisBytes: Bytes;
+};
+
+/**
+ * Implements {@link https://dcdpr.github.io/did-btcr2/#appendix | 9. Appendix} methods.
+ *
+ * @class Btc1Appendix
+ * @type {Btc1Appendix}
+ */
+export class Btc1Appendix {
+  /**
+   * Extracts a DID fragment from a given input
+   * @param {unknown} input The input to extract the DID fragment from
+   * @returns {string | undefined} The extracted DID fragment or undefined if not found
+   */
+  public static extractDidFragment(input: unknown): string | undefined {
+    if (typeof input !== 'string') return undefined;
+    if (input.length === 0) return undefined;
+    return input;
+  }
+
+  /**
+   * Validates that the given object is a DidVerificationMethod
+   * @param {unknown} obj The object to validate
+   * @returns {boolean} A boolean indicating whether the object is a DidVerificationMethod
+   */
+  public static isDidVerificationMethod(obj: unknown): obj is DidVerificationMethod {
+    // Validate that the given value is an object.
+    if (!obj || typeof obj !== 'object' || obj === null) return false;
+
+    // Validate that the object has the necessary properties of a DidVerificationMethod.
+    if (!('id' in obj && 'type' in obj && 'controller' in obj)) return false;
+
+    if (typeof obj.id !== 'string') return false;
+    if (typeof obj.type !== 'string') return false;
+    if (typeof obj.controller !== 'string') return false;
+
+    return true;
+  }
+
+  /**
+   * Validates that the given object is a DidService
+   * @param {unknown} obj The object to validate
+   * @returns {boolean} A boolean indicating whether the object is a DidService
+   */
+  public static isDidService(obj: unknown): obj is DidService {
+    // Validate that the given value is an object.
+    if (!obj || typeof obj !== 'object' || obj === null) return false;
+    // Validate that the object has the necessary properties of a DidService.
+    if (!('id' in obj && 'type' in obj && 'serviceEndpoint' in obj)) return false;
+    if (typeof obj.id !== 'string') return false;
+    if (typeof obj.type !== 'string') return false;
+    if (typeof obj.serviceEndpoint !== 'string') return false;
+    return true;
+  }
+
+  /**
+   * 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
+   */
+  public static getVerificationMethods(didDocument: DidDocument): Btc1VerificationMethod[] {
+    if (!didDocument) throw new TypeError(`Required parameter missing: 'didDocument'`);
+    const verificationMethods: DidVerificationMethod[] = [];
+    // Check the 'verificationMethod' array.
+    verificationMethods.push(...didDocument.verificationMethod?.filter(Btc1Appendix.isDidVerificationMethod) ?? []);
+    // Check verification relationship properties for embedded verification methods.
+    Object.keys(DidVerificationRelationship).forEach((relationship) => {
+      verificationMethods.push(
+        ...(didDocument[relationship as keyof DidDocument] as (DidVerificationMethod)[])
+          ?.filter(Btc1Appendix.isDidVerificationMethod) ?? []
+      );
+    });
+    return verificationMethods as Btc1VerificationMethod[];
+  }
+
+
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#derive-root-capability-from-didbtc1-identifier | 9.4.1 Derive Root Capability from did:btcr2 Identifier}.
+   *
+   * The Derive Root Capability algorithm deterministically generates a ZCAP-LD root capability from a given did:btcr2
+   * identifier. Each root capability is unique to the identifier. This root capability is defined and understood by the
+   * did:btcr2 specification as the root capability to authorize updates to the specific did:btcr2 identifiers DID
+   * document. It takes in a did:btcr2 identifier and returns a rootCapability object. It returns the root capability.
+   *
+   * @param {string} identifier The did-btcr2 identifier to derive the root capability from
+   * @returns {Btc1RootCapability} The root capability object
+   * @example Root capability for updating the DID document for
+   * did:btcr2:k1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u
+   * ```
+   * {
+   *  "@context": "https://w3id.org/zcap/v1",
+   *  "id": "urn:zcap:root:did:btcr2:k1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u",
+   *  "controller": "did:btcr2:k1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u",
+   *  "invocationTarget": "did:btcr2:k1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u"
+   * }
+   * ```
+   */
+  public static deriveRootCapability(identifier: string): Btc1RootCapability {
+    // 1. Define rootCapability as an empty object.
+    const rootCapability = {} as Btc1RootCapability;
+
+    // 2. Set rootCapability.@context to ‘https://w3id.org/zcap/v1’.
+    rootCapability['@context'] = W3C_ZCAP_V1;
+
+    // 3. Set encodedIdentifier to result of calling algorithm encodeURIComponent(identifier).
+    const encodedIdentifier = encodeURIComponent(identifier);
+
+    // 4. Set rootCapability.id to urn:zcap:root:${encodedIdentifier}.
+    rootCapability.id = `urn:zcap:root:${encodedIdentifier}`;
+
+    // 5. Set rootCapability.controller to identifier.
+    rootCapability.controller = identifier;
+
+    // 6. Set rootCapability.invocationTarget to identifier.
+    rootCapability.invocationTarget = identifier;
+
+    // 7. Return rootCapability.
+    return rootCapability;
+  }
+
+
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#dereference-root-capability-identifier | 9.4.2 Dereference Root Capability Identifier}.
+   *
+   * This algorithm takes in capabilityId, a root capability identifier, and dereferences it to rootCapability, the root
+   * capability object.
+   *
+   * @param {string} capabilityId The root capability identifier to dereference.
+   * @returns {Btc1RootCapability} The root capability object.
+   * @example a didUpdatePayload with an invoked ZCAP-LD capability containing a patch defining how the DID document
+   * for did:btcr2:k1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u SHOULD be mutated.
+   * ```
+   * {
+   *  "@context": [
+   *   "https://w3id.org/zcap/v1",
+   *   "https://w3id.org/security/data-integrity/v2",
+   *   "https://w3id.org/json-ld-patch/v1"
+   *  ],
+   *  "patch": [
+   *   {
+   *    "op": "add",
+   *    "path": "/service/4",
+   *    "value": {
+   *       "id": "#linked-domain",
+   *       "type": "LinkedDomains",
+   *       "serviceEndpoint": "https://contact-me.com"
+   *      }
+   *    }
+   *  ],
+   *  "proof": {
+   *    "type": "DataIntegrityProof",
+   *    "cryptosuite": "schnorr-secp256k1-jcs-2025",
+   *    "verificationMethod": "did:btcr2:k1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u#initialKey",
+   *    "invocationTarget": "did:btcr2:k1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u",
+   *    "capability": "urn:zcap:root:did%3Abtc1%3Ak1q0rnnwf657vuu8trztlczvlmphjgc6q598h79cm6sp7c4fgqh0fkc0vzd9u",
+   *    "capabilityAction": "Write",
+   *    "proofPurpose": "assertionMethod",
+   *    "proofValue": "z381yXYmxU8NudZ4HXY56DfMN6zfD8syvWcRXzT9xD9uYoQToo8QsXD7ahM3gXTzuay5WJbqTswt2BKaGWYn2hHhVFKJLXaDz"
+   *   }
+   * }
+   */
+  public static derefernceRootCapabilityIdentifier(capabilityId: string): Btc1RootCapability {
+    // 1. Set rootCapability to an empty object.
+    const rootCapability = {} as Btc1RootCapability;
+
+    // 2. Set components to the result of capabilityId.split(":").
+    const [urn, zcap, root, did] = capabilityId.split(':') ?? [];
+
+    // 3. Validate components:
+    //    1. Assert length of components is 4.
+    if ([urn, zcap, root, did].length !== 4) {
+      throw new DidError(DidErrorCode.InvalidDid, `Invalid capabilityId: ${capabilityId}`);
+    }
+
+    //    2. components[0] == urn.
+    if (!urn || urn !== 'urn') {
+      throw new DidError(DidErrorCode.InvalidDid, `Invalid capabilityId: ${capabilityId}`);
+    }
+
+    //    3. components[1] == zcap.
+    if (!zcap || zcap !== 'zcap') {
+      throw new DidError(DidErrorCode.InvalidDid, `Invalid capabilityId: ${capabilityId}`);
+    }
+
+    //    4. components[2] == root.
+    if (!root || root !== 'root') {
+      throw new DidError(DidErrorCode.InvalidDid, `Invalid capabilityId: ${capabilityId}`);
+    }
+
+    // 4. Set uriEncodedId to components[3].
+    const uriEncodedId = did;
+
+    // 5. Set btc1Identifier the result of decodeURIComponent(uriEncodedId).
+    const btc1Identifier = decodeURIComponent(uriEncodedId);
+
+    // 6. Set rootCapability.id to capabilityId.
+    rootCapability.id = capabilityId;
+
+    // 7. Set rootCapability.controller to btc1Identifier.
+    rootCapability.controller = btc1Identifier;
+
+    // 8. Set rootCapability.invocationTarget to btc1Identifier.
+    rootCapability.invocationTarget = btc1Identifier;
+
+    // 9. Return rootCapability.
+    return rootCapability;
+  }
+
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#fetch-content-from-addressable-storage | 9.3. Fetch Content from Addressable Storage}.
+   *
+   * The Fetch Content from Addressable Storage function takes in SHA256 hash of some content, hashBytes, converts these
+   * bytes to a IPFS v1 Content Identifier and attempts to retrieve the identified content from Content Addressable
+   * Storage (CAS). It returns the retrieved content or null.
+   *
+   * @param {HashBytes} hashBytes The SHA256 hash of the content to be fetched.
+   * @returns {string} The fetched content or null if not found.
+   */
+  public static async fetchFromCas(hashBytes: HashBytes): Promise<string | undefined> {
+    // 1. Set cid to the result of converting hashBytes to an IPFS v1 CID.
+    const cid = CID.create(1, 1, createDigest(1, hashBytes));
+
+    // Create a Helia node connection to IPFS
+    const helia = strings(await createHelia());
+
+    // 2. Set content to the result of fetching the cid from a CAS system. Which CAS systems checked is up to implementation.
+    Logger.warn('// TODO: Is this right? Are implementations just supposed to check all CAS they trust?');
+    const content = await helia.get(cid, {});
+
+    // 3. If content for cid cannot be found, set content to null.
+    // 4. Return content.
+    return content;
+  }
+}

package/src/utils/beacons.ts

@@ -0,0 +1,276 @@
+import { Btcr2Error, DidBtcr2Error, Maybe, KeyBytes } from '@did-btcr2/common';
+import { DidDocument, DidService } from '@web5/dids';
+import { networks, payments } from 'bitcoinjs-lib';
+import { BeaconFactory } from '../btcr2/beacon/factory.js';
+import { BeaconService, BeaconServiceAddress } from '../interfaces/ibeacon.js';
+import { Btc1Appendix } from './appendix.js';
+import { Btc1DidDocument } from './did-document.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;
+}
+
+/**
+ * Static class of utility functions for the Beacon Service
+ * @class BeaconUtils
+ * @type {BeaconUtils}
+ */
+export class BeaconUtils {
+  /**
+   * Converts a BIP21 Bitcoin URI to a Bitcoin address
+   * @param {string} uri The BIP21 Bitcoin URI to convert
+   * @returns {string} The Bitcoin address extracted from the URI
+   * @throws {DidBtcr2Error} if the URI is not a valid Bitcoin URI
+   */
+  public static parseBitcoinAddress(uri: string): string {
+    if (!uri.startsWith('bitcoin:')) {
+      throw new DidBtcr2Error('Invalid Bitcoin URI format', { type: 'BEACON_ERROR' });
+    }
+    return uri.replace('bitcoin:', '').split('?')[0]; // Extracts address from "bitcoin:<address>?params"
+  }
+
+  /**
+   * Validates that the given object is a Beacon Service
+   * @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 {
+    // Return false if the given obj is not a valid DidService.
+    if(!Btc1Appendix.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;
+
+    // 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;
+  }
+
+  /**
+   * Extracts the services from a given DID Document
+   * @param {DidDocument} didDocument The DID Document to extract the services from
+   * @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(Btc1Appendix.isDidService) ?? [];
+    // Filter for valid beacon service objects.
+    return (didServices.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.
+   * @returns {Array<Array<string>>} 2D Array of bitcoin addresses (p2pkh, p2wpkh, p2tr).
+   * @throws {DidBtcr2Error} if the bitcoin address is invalid.
+   */
+  public static generateBeaconAddresses({ identifier, publicKey, network }: {
+    identifier: string;
+    publicKey: KeyBytes;
+    network: networks.Network;
+  }): Array<Array<string>> {
+    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 DidBtcr2Error('Failed to generate bitcoin addresses');
+      }
+      return [
+        [`${identifier}#initialP2PKH`, p2pkh],
+        [`${identifier}#initialP2WPKH`, p2wpkh],
+        [`${identifier}#initialP2TR`, p2tr]
+      ];
+    } catch (error) {
+      console.error(error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * 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).
+   * @returns {BeaconService} A BeaconService object.
+   * @throws {DidBtcr2Error} 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 {
+    try {
+      if(!id.includes('#')) {
+        id = `${id}#initial${addressType.toUpperCase()}`;
+      }
+      const serviceEndpoint = `bitcoin:${payments[addressType]({ pubkey, network }).address}`;
+      return { id, type, serviceEndpoint, };
+    } catch (error) {
+      console.error(error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Generate a custom Beacon Service.
+   * @param {GenerateBeaconServicesParams} params Required parameters for generating Beacon Services.
+   * @returns
+   */
+  public static generateBeaconServiceCustom({ id, publicKey: pubkey, network, addressType, type }: {
+    id: string;
+    publicKey: KeyBytes;
+    network: networks.Network;
+    addressType: 'p2pkh' | 'p2wpkh' | 'p2tr';
+    type: string;
+  }): BeaconService {
+    try {
+      if(!id.includes('#')) {
+        throw new Btcr2Error(
+          'Invalid id format. It should include a fragment identifier (e.g., #initialP2PKH).',
+          'BEACON_ERROR',
+          { id }
+        );
+      }
+      const serviceEndpoint = `bitcoin:${payments[addressType]({ pubkey, network }).address}`;
+      return { id, type, serviceEndpoint, };
+    } 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 {DidBtcr2Error} 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 {BitcoinAddress} 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.
+   */
+  public static toBeaconServiceAddress(beacons: Array<BeaconService>): Array<BeaconServiceAddress> {
+    return beacons.map((beacon) => ({ ...beacon, address: 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.
+   */
+  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])));
+  }
+
+  /**
+   * Get the beacon service ids from a list of beacon services.
+   * @param {Btc1DidDocument} didDocument The DID Document to extract the services from.
+   * @returns {string[]} An array of beacon service ids.
+   */
+  public static getBeaconServiceIds(didDocument: Btc1DidDocument): string[] {
+    return this.getBeaconServices(didDocument).map((beacon) => beacon.id);
+  }
+}

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

@@ -0,0 +1,73 @@
+import { DidDocumentError, INVALID_DID_DOCUMENT } from '@did-btcr2/common';
+import { BeaconService } from '../interfaces/ibeacon.js';
+import { Btc1DidDocument, Btc1VerificationMethod } from './did-document.js';
+
+export class Btc1DidDocumentBuilder {
+  private document: Partial<Btc1DidDocument> = {};
+
+  constructor(initialDocument: Partial<Btc1DidDocument>) {
+    if (!initialDocument.id) {
+      throw new DidDocumentError('Missing required "id" property', INVALID_DID_DOCUMENT, initialDocument);
+    }
+    this.document.id = initialDocument.id;
+    this.document.verificationMethod = initialDocument.verificationMethod ?? [];
+
+    if (initialDocument['@context']) {
+      this.document['@context'] = initialDocument['@context'];
+    }
+  }
+
+  withController(controller?: Array<string>): this {
+    if (controller) {
+      this.document.controller = controller ?? [this.document.id!];
+    }
+    return this;
+  }
+
+  withAuthentication(authentication: Array<string | Btc1VerificationMethod>): this {
+    if (authentication) {
+      this.document.authentication = authentication;
+    }
+    return this;
+  }
+
+  withAssertionMethod(assertionMethod: Array<string | Btc1VerificationMethod>): this {
+    if (assertionMethod) {
+      this.document.assertionMethod = assertionMethod;
+    }
+    return this;
+  }
+
+  withCapabilityInvocation(capabilityInvocation: Array<string | Btc1VerificationMethod>): this {
+    if (capabilityInvocation) {
+      this.document.capabilityInvocation = capabilityInvocation;
+    }
+    return this;
+  }
+
+  withCapabilityDelegation(capabilityDelegation: Array<string | Btc1VerificationMethod>): this {
+    if (capabilityDelegation) {
+      this.document.capabilityDelegation = capabilityDelegation;
+    }
+    return this;
+  }
+
+  withService(service: Array<BeaconService>): this {
+    if (service) {
+      this.document.service = service;
+    }
+    return this;
+  }
+
+  build(): Btc1DidDocument {
+    const didDocument = new Btc1DidDocument(this.document as Btc1DidDocument);
+
+    for (const key of Object.keys(didDocument)) {
+      if (didDocument[key as keyof Btc1DidDocument] === undefined) {
+        delete didDocument[key as keyof Btc1DidDocument];
+      }
+    }
+
+    return didDocument;
+  }
+}