Amend Primitives/Tooling

packages/primitives/src/address.ts

@@ -18,13 +18,20 @@ import type { KnownAddressTypeContents } from '@bitauth/libauth';
 
 export type AddressType = 'P2PK' | 'P2PKH' | 'P2SH20' | 'P2SH32';
 
+export const DEFAULT_ADDRESS_PREFIXES = [
+  '',
+  'bitcoincash',
+  'bchtest',
+  'bchreg',
+];
+
 /**
  * Address Entity.
  */
 export class Address {
   public readonly addressContents: KnownAddressTypeContents;
 
-  constructor(addressContents: KnownAddressTypeContents) {
+  protected constructor(addressContents: KnownAddressTypeContents) {
     this.addressContents = addressContents;
   }
 
@@ -37,13 +44,16 @@ export class Address {
    *
    * @returns {Address} Instance of Address.
    */
-  public static from(address: string): Address {
+  public static from(
+    address: string,
+    tryPrefixes = DEFAULT_ADDRESS_PREFIXES,
+  ): Address {
     // Attempt to decode as a Cash Address.
     try {
-      return Address.fromCashAddr(address);
+      return this.fromCashAddr(address, tryPrefixes);
     } catch (_error) {
       // And if that fails, attempt to decode as a Base58 Address.
-      return Address.fromLegacy(address);
+      return this.fromLegacy(address);
     }
   }
 
@@ -61,7 +71,7 @@ export class Address {
    */
   public static fromCashAddr(
     cashAddr: string,
-    tryPrefixes: Array<string> = ['', 'bitcoincash', 'bchtest', 'bchreg'],
+    tryPrefixes: Array<string> = DEFAULT_ADDRESS_PREFIXES,
   ): Address {
     // Try all prefixes (including empty string) until we find a valid decode
     const decodeResult = tryPrefixes
@@ -158,7 +168,7 @@ export class Address {
     }
 
     // Return a new instance of address.
-    return new Address({ payload, type });
+    return this.fromRaw({ payload, type });
   }
 
   /**
@@ -181,7 +191,7 @@ export class Address {
     const contractBytecode = hexToBin(hex);
 
     // Return a new instance of address.
-    return Address.fromRedeemScript(contractBytecode, type);
+    return this.fromRedeemScript(contractBytecode, type);
   }
 
   /**
@@ -201,7 +211,7 @@ export class Address {
       throw new Error(`Invalid type (${addressContents.type})`);
     }
 
-    return new Address(addressContents);
+    return this.fromRaw(addressContents);
   }
 
   /**
@@ -220,7 +230,7 @@ export class Address {
 
     const lockScriptBytes = hexToBin(hex);
 
-    return Address.fromLockscriptBytes(lockScriptBytes);
+    return this.fromLockscriptBytes(lockScriptBytes);
   }
 
   /**
@@ -244,7 +254,7 @@ export class Address {
       );
     }
 
-    return new Address({ payload: hash160, type });
+    return this.fromRaw({ payload: hash160, type });
   }
 
   /**
@@ -267,16 +277,34 @@ export class Address {
 
     const hash160Bytes = hexToBin(hash160Hex);
 
-    return Address.fromHash160(hash160Bytes, type);
+    return this.fromHash160(hash160Bytes, type);
   }
 
+  /**
+   * Creates an Address instance from a raw object representation (LibAuth's KnownAddressTypeContents).
+   *
+   * @remarks This method is UNSAFE and MUST only be used where input is already verified or trusted.
+   *
+   * @param obj - LibAuth Object of type KnownAddressTypeContents
+   * @returns A new Address instance
+   */
   public static fromRaw(addressContents: KnownAddressTypeContents) {
     return new this(addressContents);
   }
 
-  public static isValid(address: string): boolean {
+  /**
+   * Checks whether the given address is a valid Legacy or CashAddr.
+   *
+   * @param address The address.
+   *
+   * @returns boolean indicating whether the address is a valid Legacy Address or CashAddr.
+   */
+  public static isValid(
+    address: string,
+    tryPrefixes = DEFAULT_ADDRESS_PREFIXES,
+  ): boolean {
     try {
-      Address.from(address);
+      Address.from(address, tryPrefixes);
     } catch (_error) {
       return false;
     }
@@ -284,6 +312,13 @@ export class Address {
     return true;
   }
 
+  /**
+   * Checks whether the given address is a valid Legacy Address.
+   *
+   * @param address The address.
+   *
+   * @returns boolean indicating whether the address is a valid Legacy Address.
+   */
   public static isValidLegacy(address: string): boolean {
     try {
       Address.fromLegacy(address);
@@ -294,9 +329,19 @@ export class Address {
     return true;
   }
 
-  public static isValidCashAddr(address: string): boolean {
+  /**
+   * Checks whether the given address is a valid CashAddr.
+   *
+   * @param address The address.
+   *
+   * @returns boolean indicating whether the address is a valid CashAddr.
+   */
+  public static isValidCashAddr(
+    address: string,
+    tryPrefixes = DEFAULT_ADDRESS_PREFIXES,
+  ): boolean {
     try {
-      Address.fromCashAddr(address);
+      Address.fromCashAddr(address, tryPrefixes);
     } catch (_error) {
       return false;
     }
@@ -467,6 +512,11 @@ export class Address {
     return lockscriptAsm;
   }
 
+  /**
+   * Converts the address to its raw LibAuth representation (KnownAddressTypeContents).
+   *
+   * @returns A LibAuth KnownAddressTypeContents object.
+   */
   public toRaw() {
     return { ...this.addressContents };
   }