@did-btcr2/method 0.13.1

package/src/utils/did-document.ts

@@ -0,0 +1,474 @@
+import {
+  BTCR2_DID_DOCUMENT_CONTEXT,
+  Btcr2IdentifierTypes,
+  DidDocumentError,
+  ID_PLACEHOLDER_VALUE,
+  INVALID_DID_DOCUMENT,
+  JSONObject,
+  Logger
+} from '@did-btcr2/common';
+import { DidService, DidVerificationMethod, DidDocument as IDidDocument } from '@web5/dids';
+import { BeaconService } from '../interfaces/ibeacon.js';
+import { Btc1Appendix } from './appendix.js';
+import { BeaconUtils } from './beacons.js';
+import { Btc1Identifier } from './identifier.js';
+
+export const BECH32M_CHARS = '';
+export const BTC1_DID_REGEX = /did:btcr2:(x1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]*)/g;
+
+export type ExternalData = {
+  id: string,
+  verificationMethod: Array<Btc1VerificationMethod>,
+  authentication?: Array<string | Btc1VerificationMethod>,
+  assertionMethod?: Array<string | Btc1VerificationMethod>,
+  capabilityInvocation?: Array<string | Btc1VerificationMethod>,
+  capabilityDelegation?: Array<string | Btc1VerificationMethod>,
+  service: Array<BeaconService>
+}
+export type VerificationRelationships = {
+  authentication?: Array<string | Btc1VerificationMethod>;
+  assertionMethod?: Array<string | Btc1VerificationMethod>;
+  capabilityInvocation?: Array<string | Btc1VerificationMethod>;
+  capabilityDelegation?: Array<string | Btc1VerificationMethod>;
+}
+
+export interface IBtc1VerificationMethod extends DidVerificationMethod {
+  id: string;
+  type: string;
+  controller: string;
+  publicKeyMultibase: string;
+  secretKeyMultibase?: string | undefined;
+}
+
+/**
+ * DID BTCR2 Verification Method extends the DidVerificationMethod class adding helper methods and properties
+ * @class Btc1VerificationMethod
+ * @type {Btc1VerificationMethod}
+ *
+ */
+export class Btc1VerificationMethod implements IBtc1VerificationMethod {
+  id: string;
+  type: string;
+  controller: string;
+  publicKeyMultibase: string;
+  secretKeyMultibase?: string | undefined;
+
+  constructor({ id, type, controller, publicKeyMultibase, secretKeyMultibase }: IBtc1VerificationMethod) {
+    this.id = id;
+    this.type = type;
+    this.controller = controller;
+    this.publicKeyMultibase = publicKeyMultibase;
+    this.secretKeyMultibase = secretKeyMultibase;
+    if(!secretKeyMultibase){
+      delete this.secretKeyMultibase;
+    }
+  }
+  // TODO: Add helper methods and properties
+}
+
+/**
+ * BTCR2 DID Document Interface
+ * @interface IBtc1DidDocument
+ * @type {IBtc1DidDocument}
+ * @extends {IDidDocument}
+ * @property {string} id - The identifier of the DID Document.
+ * @property {Array<string>} [controller] - The controller of the DID Document.
+ * @property {Array<string | JSONObject>} ['@context'] - The context of the DID Document.
+ * @property {Array<DidVerificationMethod>} verificationMethod - The verification methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [authentication] - The authentication methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [assertionMethod] - The assertion methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [capabilityInvocation] - The capability invocation methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [capabilityDelegation] - The capability delegation methods of the DID Document.
+ * @property {Array<BeaconService>} service - The services of the DID Document.
+ */
+export interface IBtc1DidDocument extends IDidDocument {
+  id: string;
+  controller?: Array<string>;
+  '@context'?: Array<string | JSONObject>;
+  verificationMethod: Array<Btc1VerificationMethod>;
+  authentication?: Array<string | Btc1VerificationMethod>;
+  assertionMethod?: Array<string | Btc1VerificationMethod>;
+  capabilityInvocation?: Array<string | Btc1VerificationMethod>;
+  capabilityDelegation?: Array<string | Btc1VerificationMethod>;
+  service: Array<BeaconService>;
+}
+
+/**
+ * BTCR2 DID Document extends the DidDocument class adding helper methods and properties
+ * @class Btc1DidDocument
+ * @type {Btc1DidDocument}
+ * @implements {IBtc1DidDocument}
+ * @property {string} id - The identifier of the DID Document.
+ * @property {Array<string>} [controller] - The controller of the DID Document.
+ * @property {Array<string | JSONObject>} ['@context'] - The context of the DID Document.
+ * @property {Array<DidVerificationMethod>} verificationMethod - The verification methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [authentication] - The authentication methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [assertionMethod] - The assertion methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [capabilityInvocation] - The capability invocation methods of the DID Document.
+ * @property {Array<string | Btc1VerificationMethod>} [capabilityDelegation] - The capability delegation methods of the DID Document.
+ * @property {Array<BeaconService>} service - The services of the DID Document.
+ */
+export class Btc1DidDocument implements IBtc1DidDocument {
+  id: string;
+  controller?: Array<string>;
+  '@context'?: Array<string | JSONObject> = BTCR2_DID_DOCUMENT_CONTEXT;
+  verificationMethod: Array<Btc1VerificationMethod>;
+  authentication?: Array<string | Btc1VerificationMethod>;
+  assertionMethod?: Array<string | Btc1VerificationMethod>;
+  capabilityInvocation?: Array<string | Btc1VerificationMethod>;
+  capabilityDelegation?: Array<string | Btc1VerificationMethod>;
+  service: Array<BeaconService>;
+
+  constructor(document: IBtc1DidDocument) {
+    // Set the ID and ID type
+    const idType = document.id.includes('k1')
+      ? Btcr2IdentifierTypes.KEY
+      : Btcr2IdentifierTypes.EXTERNAL;
+
+    // Validate ID and parts for non-intermediate
+    const isIntermediate = document.id === ID_PLACEHOLDER_VALUE;
+    // Deconstruct the document parts for validation
+    const { id, controller, verificationMethod: vm, service } = document;
+    if (!isIntermediate) {
+      if (!Btc1DidDocument.isValidId(id)) {
+        throw new DidDocumentError(`Invalid id: ${id}`, INVALID_DID_DOCUMENT, document);
+      }
+      if(!Btc1DidDocument.isValidController(controller ?? [id])) {
+        throw new DidDocumentError(`Invalid controller: ${controller}`, INVALID_DID_DOCUMENT, document);
+      }
+      if (!Btc1DidDocument.isValidVerificationMethods(vm)) {
+        throw new DidDocumentError('Invalid verificationMethod: ' + vm, INVALID_DID_DOCUMENT, document);
+      }
+      if (!Btc1DidDocument.isValidServices(service)) {
+        throw new DidDocumentError('Invalid service: ' + service, INVALID_DID_DOCUMENT, document);
+      }
+    }
+
+    // Set core properties
+    this.id = document.id;
+    this.verificationMethod = document.verificationMethod;
+    this.service = document.service;
+    this['@context'] = document['@context'] || BTCR2_DID_DOCUMENT_CONTEXT;
+    this.controller = document.controller || [this.id];
+
+    // Relationships logic based on idType
+    if (idType === Btcr2IdentifierTypes.KEY) {
+      // auto-generate #initialKey if missing
+      const keyRef = `${this.id}#initialKey`;
+      this.authentication = document.authentication || [keyRef];
+      this.assertionMethod = document.assertionMethod || [keyRef];
+      this.capabilityInvocation = document.capabilityInvocation || [keyRef];
+      this.capabilityDelegation = document.capabilityDelegation || [keyRef];
+    } else {
+      // EXTERNAL: use provided arrays, must be defined
+      this.authentication = document.authentication;
+      this.assertionMethod = document.assertionMethod;
+      this.capabilityInvocation = document.capabilityInvocation;
+      this.capabilityDelegation = document.capabilityDelegation;
+    }
+
+    // Sanitize the DID Document
+    Btc1DidDocument.sanitize(this);
+    // If the DID Document is not an intermediateDocument, validate it
+    if (!isIntermediate) {
+      Btc1DidDocument.validate(this);
+    } else {
+      this.validateIntermediate();
+    }
+  }
+
+  /**
+   * Convert the Btc1DidDocument to a JSON object.
+   * @returns {JSONObject} The JSON representation of the Btc1DidDocument.
+   */
+  public json(): JSONObject {
+    return {
+      id                   : this.id,
+      controller           : this.controller,
+      '@context'           : this['@context'],
+      verificationMethod   : this.verificationMethod,
+      authentication       : this.authentication,
+      assertionMethod      : this.assertionMethod,
+      capabilityInvocation : this.capabilityInvocation,
+      capabilityDelegation : this.capabilityDelegation,
+      service              : this.service
+    };
+  }
+
+  /**
+   * Create a minimal Btc1DidDocument from "k1" btcr2 identifier.
+   * @param {string} publicKeyMultibase The public key in multibase format.
+   * @param {Array<BeaconService>} service The beacon services to be included in the document.
+   * @returns {Btc1DidDocument} A new Btc1DidDocument with the placeholder ID.
+   */
+  public static fromKeyIdentifier(
+    id: string,
+    publicKeyMultibase: string,
+    service: Array<BeaconService>
+  ): Btc1DidDocument {
+    // Ensure the ID is in the correct format
+    id = id.includes('#') ? id : `${id}#initialKey`;
+    // Create the verification method and the Btc1DidDocument
+    const document = {
+      id,
+      verificationMethod : [
+        new Btc1VerificationMethod({
+          id,
+          type       : 'Multikey',
+          controller : id,
+          publicKeyMultibase
+        })
+      ],
+      service
+    } as IBtc1DidDocument;
+    return new Btc1DidDocument(document);
+  }
+
+  /**
+   * Create a Btc1DidDocument from "x1" btcr2 identifier.
+   * @param {ExternalData} data The verification methods of the DID Document.
+   * @returns {Btc1DidDocument} A new Btc1DidDocument.
+   */
+  public static fromExternalIdentifier(data: ExternalData): Btc1DidDocument {
+    return new Btc1DidDocument(data as IBtc1DidDocument);
+  }
+
+
+  /**
+   * Sanitize the DID Document by removing undefined values
+   * @returns {Btc1DidDocument} The sanitized DID Document
+   */
+  public static sanitize(doc: Btc1DidDocument): Btc1DidDocument {
+    for (const key of Object.keys(doc)) {
+      if (doc[key as keyof Btc1DidDocument] === undefined) {
+        delete doc[key as keyof Btc1DidDocument];
+      }
+    }
+    return doc;
+  }
+
+  /**
+   * Validates a Btc1DidDocument by breaking it into modular validation methods.
+   * @param {Btc1DidDocument} didDocument The DID document to validate.
+   * @returns {boolean} True if the DID document is valid.
+   * @throws {DidDocumentError} If any validation check fails.
+   */
+  public static isValid(didDocument: Btc1DidDocument): boolean {
+    if (!this.isValidContext(didDocument?.['@context'])) {
+      throw new DidDocumentError('Invalid "@context"', INVALID_DID_DOCUMENT, didDocument);
+    }
+    if (!this.isValidId(didDocument?.id)) {
+      throw new DidDocumentError('Invalid "id"', INVALID_DID_DOCUMENT, didDocument);
+    }
+    if (!this.isValidVerificationMethods(didDocument?.verificationMethod)) {
+      throw new DidDocumentError('Invalid "verificationMethod"', INVALID_DID_DOCUMENT, didDocument);
+    }
+    if (!this.isValidServices(didDocument?.service)) {
+      throw new DidDocumentError('Invalid "service"', INVALID_DID_DOCUMENT, didDocument);
+    }
+    if (!this.isValidVerificationRelationships(didDocument)) {
+      throw new DidDocumentError('Invalid verification relationships', INVALID_DID_DOCUMENT, didDocument);
+    }
+    return true;
+  }
+
+  /**
+   * Validates that "@context" exists and includes correct values.
+   * @private
+   * @param {Btc1DidDocument['@context']} context The context to validate.
+   * @returns {boolean} True if the context is valid.
+   */
+  private static isValidContext(context: Btc1DidDocument['@context']): boolean {
+    if(!context) return false;
+    if(!Array.isArray(context)) return false;
+    if(!context.every(ctx => typeof ctx === 'string' && BTCR2_DID_DOCUMENT_CONTEXT.includes(ctx))) return false;
+    return true;
+  }
+
+  /**
+   * Validates that the DID Document has a valid id.
+   * @private
+   * @param {string} id The id to validate.
+   * @returns {boolean} True if the id is valid.
+   */
+  private static isValidId(id: string): boolean {
+    try {
+      Btc1Identifier.decode(id);
+      return true;
+    } catch (error: any) {
+      Logger.error('Invalid DID Document ID', error);
+      return false;
+    }
+  }
+
+  /**
+   * Validates that the controller exists and is correctly formatted.
+   * @param {Array<string>} controller The controller to validate.
+   * @returns {boolean} True if the controller is valid.
+   */
+  private static isValidController(controller: Array<string>): boolean {
+    if(!controller) return false;
+    if(!Array.isArray(controller)) return false;
+    if(!controller.every(c => typeof c === 'string')) return false;
+    return true;
+  }
+
+  /**
+   * Validates that verification methods exist and are correctly formatted.
+   * @private
+   * @param {DidVerificationMethod[]} verificationMethod The verification methods to validate.
+   * @returns {boolean} True if the verification methods are valid.
+   */
+  private static isValidVerificationMethods(verificationMethod: DidVerificationMethod[]): boolean {
+    return Array.isArray(verificationMethod) && verificationMethod.every(Btc1Appendix.isDidVerificationMethod);
+  }
+
+  /**
+   * Validates that the DID Document has valid services.
+   * @private
+   * @param {DidService[]} service The services to validate.
+   * @returns {boolean} True if the services are valid.
+   */
+  private static isValidServices(service: DidService[]): boolean {
+    return Array.isArray(service) && service.every(BeaconUtils.isBeaconService);
+  }
+
+  /**
+   * Validates verification relationships (authentication, assertionMethod, capabilityInvocation, capabilityDelegation).
+   * @private
+   * @param {Btc1DidDocument} didDocument The DID Document to validate.
+   * @returns {boolean} True if the verification relationships are valid.
+   */
+  public static isValidVerificationRelationships(didDocument: Btc1DidDocument): boolean {
+    // Define the available verification relationships
+    const possibleVerificationRelationships: (keyof Btc1DidDocument)[] = [
+      'authentication',
+      'assertionMethod',
+      'capabilityInvocation',
+      'capabilityDelegation'
+    ];
+
+    // Get the DID Document keys
+    const verificationRelationships = Object.keys(didDocument) as Array<keyof Btc1DidDocument>;
+
+    // Filter the DID Document keys to only those that are in the available verification relationships
+    const availableVerificationRelationships = possibleVerificationRelationships.filter(
+      key => verificationRelationships.includes(key as keyof Btc1DidDocument)
+    ) as (keyof Btc1DidDocument)[];
+
+    // Check if all available verification relationships are valid
+    return availableVerificationRelationships.every((key) =>
+      // Check if the key exists in the DID Document
+      didDocument[key] &&
+      // Check if the key is an array
+      Array.isArray(didDocument[key]) &&
+      // Check that every value in the array is a string or DidVerificationMethod
+      didDocument[key].every(
+        entry => typeof entry === 'string' || Btc1Appendix.isDidVerificationMethod(entry)
+      ));
+  }
+
+  /**
+   * Validate the DID Document
+   * @returns {Btc1DidDocument} Validated DID Document.
+   * @throws {DidDocumentError} If the DID Document is invalid.
+   */
+  public static validate(didDocument: Btc1DidDocument | IntermediateDidDocument): Btc1DidDocument {
+    // Validate the DID Document
+    if (didDocument.id === ID_PLACEHOLDER_VALUE) {
+      (didDocument as IntermediateDidDocument).validateIntermediate();
+    } else {
+      Btc1DidDocument.isValid(didDocument);
+    }
+    // Return the DID Document
+    return didDocument;
+  }
+
+  /**
+   * Validate the IntermediateDidDocument.
+   * @returns {boolean} True if the IntermediateDidDocument is valid.
+   */
+  public validateIntermediate(): void {
+    // Validate the id
+    if(this.id !== ID_PLACEHOLDER_VALUE) {
+      throw new DidDocumentError('Invalid IntermediateDidDocument ID', INVALID_DID_DOCUMENT, this);
+    }
+    // Validate the controller
+    if(!this.controller?.every(c => c === ID_PLACEHOLDER_VALUE)) {
+      throw new DidDocumentError('Invalid IntermediateDidDocument controller', INVALID_DID_DOCUMENT, this);
+    }
+    // Validate the verificationMethod
+    if(!this.verificationMethod.every(vm => vm.id.includes(ID_PLACEHOLDER_VALUE) && vm.controller === ID_PLACEHOLDER_VALUE)) {
+      throw new DidDocumentError('Invalid IntermediateDidDocument verificationMethod', INVALID_DID_DOCUMENT, this);
+    }
+    // Validate the service
+    if(!this.service.every(svc => svc.id.includes(ID_PLACEHOLDER_VALUE))) {
+      throw new DidDocumentError('Invalid IntermediateDidDocument service', INVALID_DID_DOCUMENT, this);
+    }
+    if(!Btc1DidDocument.isValidVerificationRelationships(this)) {
+      // Return true if all validations pass
+      throw new DidDocumentError('Invalid IntermediateDidDocument assertionMethod', INVALID_DID_DOCUMENT, this);
+    }
+  }
+
+  /**
+   * Convert the Btc1DidDocument to an IntermediateDidDocument.
+   * @returns {IntermediateDidDocument} The IntermediateDidDocument representation of the Btc1DidDocument.
+   */
+  public toIntermediate(): IntermediateDidDocument {
+    if(this.id.includes('k1')) {
+      throw new DidDocumentError('Cannot convert a key identifier to an intermediate document', INVALID_DID_DOCUMENT, this);
+    }
+    return new IntermediateDidDocument(this);
+  }
+}
+
+/**
+ * IntermediateDidDocument extends the Btc1DidDocument class for creating and managing intermediate DID documents.
+ * This class is used to create a minimal DID document with a placeholder ID.
+ * It is used in the process of creating a new DID document.
+ * @class IntermediateDidDocument
+ * @extends {Btc1DidDocument}
+ */
+export class IntermediateDidDocument extends Btc1DidDocument {
+  constructor(document: IBtc1DidDocument) {
+    const intermediateDocument = JSON.cloneReplace(document, BTC1_DID_REGEX, ID_PLACEHOLDER_VALUE) as IBtc1DidDocument;
+    super(intermediateDocument);
+  }
+
+  /**
+   * Create a minimal IntermediateDidDocument with a placeholder ID.
+   * @param {Array<Btc1VerificationMethod>} verificationMethod The public key in multibase format.
+   * @param {VerificationRelationships} relationships The public key in multibase format.
+   * @param {Array<BeaconService>} service The service to be included in the document.
+   * @returns {IntermediateDidDocument} A new IntermediateDidDocument with the placeholder ID.
+   */
+  public static create(
+    verificationMethod: Array<Btc1VerificationMethod>,
+    relationships: VerificationRelationships,
+    service: Array<BeaconService>
+  ): IntermediateDidDocument {
+    const id = ID_PLACEHOLDER_VALUE;
+    return new IntermediateDidDocument({ id, ...relationships, verificationMethod, service, });
+  }
+
+  /**
+   * Convert the IntermediateDidDocument to a Btc1DidDocument by replacing the placeholder value with the provided DID.
+   * @param did The DID to replace the placeholder value in the document.
+   * @returns {Btc1DidDocument} A new Btc1DidDocument with the placeholder value replaced by the provided DID.
+   */
+  public toBtc1DidDocument(did: string): Btc1DidDocument {
+    const stringThis = JSON.stringify(this).replaceAll(ID_PLACEHOLDER_VALUE, did);
+    const parseThis = JSON.parse(stringThis) as IBtc1DidDocument;
+    return new Btc1DidDocument(parseThis);
+  }
+
+  /**
+   * Create a Btc1DidDocument from a JSON object.
+   * @param {JSONObject} object The JSON object to convert.
+   * @returns {Btc1DidDocument} The created Btc1DidDocument.
+   */
+  public static from(object: JSONObject): Btc1DidDocument {
+    return new IntermediateDidDocument(object as IBtc1DidDocument).toBtc1DidDocument(object.id as string);
+  }
+}

package/src/utils/general.ts

@@ -0,0 +1,204 @@
+import { KeyBytes, BIP340_PUBLIC_KEY_MULTIBASE_PREFIX, HdWallet } from '@did-btcr2/common';
+import { sha256 } from '@noble/hashes/sha2';
+import { CURVE, getPublicKey, utils } from '@noble/secp256k1';
+import { HDKey } from '@scure/bip32';
+import { generateMnemonic, mnemonicToSeed } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+import { base58btc } from 'multiformats/bases/base58';
+
+/**
+ * Static class of general utility functions for the did-btcr2 spec implementation
+ * @class GeneralUtils
+ * @type {GeneralUtils}
+ */
+export class GeneralUtils {
+  /**
+   * Helper function to encode a secp256k1 key in SchnorrSecp256k1 Multikey Format
+   * @param {KeyBytes} xOnlyKeyBytes
+   * @returns {PublicKeyMultibase}
+   */
+  public static encode(xOnlyKeyBytes: KeyBytes): string {
+    if (xOnlyKeyBytes.length !== 32) {
+      throw new Error('x-only public key must be 32 bytes');
+    }
+    const prefix = Array.from(BIP340_PUBLIC_KEY_MULTIBASE_PREFIX);
+    const x = Array.from(xOnlyKeyBytes);
+    // Set the prefix and the public key bytes
+    const multikeyBytes = new Uint8Array([...prefix, ...x]);
+    // Encode the public key as a multibase base58btc string
+    return base58btc.encode(multikeyBytes);
+  }
+
+  /**
+   * Converts a bigint to a buffer
+   * @param {bigint} value The bigint to convert
+   * @returns {Buffer} The buffer representation of the bigint
+   */
+  static bigintToBuffer(value: bigint): Buffer {
+    const hex = value.toString(16).padStart(64, '0');
+    return Buffer.fromHex(hex);
+  }
+
+  /**
+   * Generates a new mnemonic phrase and HD wallet
+   * @returns {HdWallet} Promise resolving to a new hdwallet object w/ mnemonic and hdkey
+   * @throws {Error} if the public key bytes cannot be derived
+   */
+  static async generateHdWallet(): Promise<HdWallet> {
+    // Generate random mnemonic phrase.
+    const mnemonic = generateMnemonic(wordlist, 128);
+    // Generate seed from random mnemonic phrase.
+    const seed = await mnemonicToSeed(mnemonic);
+    // Generate HDKey from seed.
+    const hdkey = HDKey.fromMasterSeed(seed);
+    // Ensure HDKey returns valid
+    if (!hdkey) {
+      throw new Error('Failed to derive hd wallet');
+    }
+    return { mnemonic, hdkey };
+  }
+
+  static generateCompressedSecp256k1KeyPair(){
+    const privateKey = utils.randomPrivateKey();
+    if(!utils.isValidPrivateKey(privateKey)) {
+      throw new Error('Invalid private key');
+    }
+    return { privateKey, publicKey: getPublicKey(privateKey, true) };
+  };
+
+  /**
+   * Recovers an HDKey from a mnemonic phrase
+   * @param {string} mnemonic The mnemonic phrase to recover the HDKey from
+   * @param {Uint8Array} seed Optional seed to recover the HDKey from
+   * @returns {HDKey} Promise resolving to the recovered HDKey
+   * @throws Error if the HDKey cannot be recovered
+   */
+  static async recoverHdWallet(mnemonic: string, seed?: Uint8Array): Promise<HDKey> {
+    seed ??= await mnemonicToSeed(mnemonic);
+    // Generate HDKey from seed.
+    const hdkey = HDKey.fromMasterSeed(seed);
+    // Ensure HDKey returns valid
+    if (!hdkey) {
+      throw new Error('Failed to recover hdkey');
+    }
+    // Return the HDKey
+    return hdkey;
+  }
+
+  /**
+   * Recovers a secp256k1 privateKey from its original entropy
+   * @param {Uint8Array} xorEntropy The original entropy to recover the privateKey from
+   * @param {Uint8Array} salt The salt used to tweak the privateKey
+   * @returns {Uint8Array} The recovered privateKey
+   * @throws {Error} if the privateKey cannot be recovered
+   */
+  static recoverTweakedRawPrivateKey(xorEntropy: Uint8Array, salt: Uint8Array): Uint8Array {
+    // If entropy is not 32 bytes, hash it to get a deterministic 32-byte private key
+    if (xorEntropy.length !== 32) {
+      xorEntropy = sha256(xorEntropy);
+    }
+    const entropy = this.XNOR(xorEntropy, salt);
+    // Convert entropy to hex
+    const hexEntropy = Buffer.from(entropy).toString('hex');
+    // Convert hexEntropy to BigInt
+    const privateKey = BigInt(`0x${hexEntropy}`);
+    // Ensure private key is in valid secp256k1 range1
+    if (privateKey < BigInt(1) || privateKey >= CURVE.n) {
+      throw new Error('Invalid private key derived from entropy');
+    }
+    // The valid 32-byte private key
+    return entropy;
+  }
+
+  /**
+   * Recovers a secp256k1 privateKey from its original entropy
+   * @param {Uint8Array} entropy The entropy to recover the privateKey from
+   * @returns {Uint8Array} The recovered privateKey
+   * @throws {Error} if the privateKey cannot be recovered
+   */
+  static recoverRawPrivateKey(entropy: Uint8Array): Uint8Array {
+    // If entropy is not 32 bytes, hash it to get a deterministic 32-byte private key
+    if (entropy.length !== 32) {
+      entropy = sha256(entropy);
+    }
+    // Convert entropy to hex
+    const hexEntropy = Buffer.from(entropy).toString('hex');
+    // Convert hexEntropy to BigInt
+    const privateKey = BigInt(`0x${hexEntropy}`);
+    // Ensure private key is in valid secp256k1 range1
+    if (privateKey < BigInt(1) || privateKey >= CURVE.n) {
+      throw new Error('Invalid private key derived from entropy');
+    }
+    // The valid 32-byte private key
+    return entropy;
+  }
+
+  /**
+   * Tweak the entropy with a salt using XOR
+   * @param {Uint8Array} entropy The entropy to tweak
+   * @param {Uint8Array} salt The salt to tweak the entropy with
+   * @returns {Uint8Array} The tweaked entropy
+   */
+  static XOR(entropy: Uint8Array, salt: Uint8Array): Uint8Array {
+    const tweaked = new Uint8Array(entropy.length);
+    for (let i = 0; i < entropy.length; i++) {
+      tweaked[i] = entropy[i] ^ salt[i % salt.length]; // XOR with repeating salt
+    }
+    return tweaked;
+  }
+
+  /**
+   * Untweak the entropy with a salt using XNOR
+   *
+   * @param {Uint8Array} tweakedEntropy The tweaked entropy to untweak
+   * @param {Uint8Array} salt The salt to untweak the entropy with
+   * @returns {Uint8Array} The original entropy
+   */
+  static XNOR(tweakedEntropy: Uint8Array, salt: Uint8Array): Uint8Array {
+    const originalEntropy = new Uint8Array(tweakedEntropy.length);
+    for (let i = 0; i < tweakedEntropy.length; i++) {
+      originalEntropy[i] = tweakedEntropy[i] ^ salt[i % salt.length]; // XOR with salt again
+    }
+    return originalEntropy;
+  }
+
+  /**
+   * Recovers an HDKey from a mnemonic phrase
+   * @param {string} mnemonic The mnemonic phrase to recover the HDKey from
+   * @param {string} path The path to derive the child key from
+   * @returns {Uint8Array} Promise resolving to the recovered private key bytes
+   * @throws {Error} if the HDKey cannot be recovered
+   */
+  static async recoverHdChildFromMnemonic(mnemonic: string, path: string): Promise<Uint8Array> {
+    // Generate HDKey from seed.
+    const hdkey = await this.recoverHdWallet(mnemonic);
+    // Ensure HDKey returns valid
+    if (!hdkey) {
+      throw new Error('Failed to recover hdkey');
+    }
+    // Return the privateKey of the derived childKey
+    const childPrivKeyBytes = hdkey.derive(path).privateKey;
+    if (!childPrivKeyBytes) {
+      throw new Error('Failed to recover child private key');
+    }
+    return childPrivKeyBytes;
+  }
+
+  /**
+   * Derives a child key from an HDKey
+   * @param {HDKey} hdkey The HDKey to derive the child key from
+   * @param {string} path The path to derive the child key from
+   * @returns {HDKey} A Promise resolving to the child key
+   * @throws {Error} Error if the child key cannot be derived
+   */
+  static deriveChildKey(hdkey: HDKey, path: string): HDKey {
+    // Derive child key from HDKey.
+    const childKey = hdkey.derive(path);
+    // Ensure child key returns valid
+    if (!childKey) {
+      throw new Error(`Failed to derive child key`);
+    }
+    // Return the child key
+    return childKey;
+  }
+}