feat(bitcoinAddress): Multiple bitcoin address types and testnet

src/definitions/finance.ts

@@ -1,4 +1,9 @@
-import type { Currency } from '../modules/finance';
+import type {
+  BitcoinAddressType,
+  BitcoinNetwork,
+  Currency,
+} from '../modules/finance';
+import type { Casing } from '../modules/string';
 import type { LocaleEntry } from './definitions';
 /**
  * The possible definitions related to finance.
@@ -26,4 +31,17 @@ export type FinanceDefinition = LocaleEntry<{
    * Types of transactions (e.g. `deposit`).
    */
   transaction_type: string[];
+
+  /**
+   * Specifications for generating different types of bitcoin addresses (e.g. `bech32`).
+   */
+  bitcoin_address_specs: Record<
+    BitcoinAddressType,
+    {
+      prefix: Record<BitcoinNetwork, string>;
+      length: { min: number; max: number };
+      casing: Casing;
+      exclude: string;
+    }
+  >;
 }>;

src/locales/base/finance/bitcoin_address_specs/bech32.ts

@@ -0,0 +1,8 @@
+import type { Casing } from '../../../../modules/string';
+
+export default {
+  prefix: { mainnet: 'bc1', testnet: 'tb1' },
+  length: { min: 42, max: 42 },
+  casing: 'lower' as Casing,
+  exclude: '1bBiIoO',
+};

src/locales/base/finance/bitcoin_address_specs/index.ts

@@ -0,0 +1,18 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { FinanceDefinition } from '../../../..';
+import bech32 from './bech32';
+import legacy from './legacy';
+import segwit from './segwit';
+import taproot from './taproot';
+
+const bitcoin_address_specs: FinanceDefinition['bitcoin_address_specs'] = {
+  bech32,
+  legacy,
+  segwit,
+  taproot,
+};
+
+export default bitcoin_address_specs;

src/locales/base/finance/bitcoin_address_specs/legacy.ts

@@ -0,0 +1,8 @@
+import type { Casing } from '../../../../modules/string';
+
+export default {
+  prefix: { mainnet: '1', testnet: 'm' },
+  length: { min: 26, max: 34 },
+  casing: 'mixed' as Casing,
+  exclude: '0OIl',
+};

src/locales/base/finance/bitcoin_address_specs/segwit.ts

@@ -0,0 +1,8 @@
+import type { Casing } from '../../../../modules/color';
+
+export default {
+  prefix: { mainnet: '3', testnet: '2' },
+  length: { min: 26, max: 34 },
+  casing: 'mixed' as Casing,
+  exclude: '0OIl',
+};

src/locales/base/finance/bitcoin_address_specs/taproot.ts

@@ -0,0 +1,8 @@
+import type { Casing } from '../../../../modules/string';
+
+export default {
+  prefix: { mainnet: 'bc1p', testnet: 'tb1p' },
+  length: { min: 62, max: 62 },
+  casing: 'lower' as Casing,
+  exclude: '1bBiIoO',
+};

src/locales/base/finance/index.ts

@@ -0,0 +1,12 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { FinanceDefinition } from '../../..';
+import bitcoin_address_specs from './bitcoin_address_specs';
+
+const finance: FinanceDefinition = {
+  bitcoin_address_specs,
+};
+
+export default finance;

src/locales/base/index.ts

@@ -5,6 +5,7 @@
 import type { LocaleDefinition } from '../..';
 import color from './color';
 import database from './database';
+import finance from './finance';
 import hacker from './hacker';
 import internet from './internet';
 import location from './location';
@@ -14,6 +15,7 @@ import system from './system';
 const base: LocaleDefinition = {
   color,
   database,
+  finance,
   hacker,
   internet,
   location,

src/modules/finance/index.ts

@@ -22,6 +22,10 @@ export interface Currency {
   symbol: string;
 }
 
+export type BitcoinAddressType = 'legacy' | 'segwit' | 'bech32' | 'taproot';
+
+export type BitcoinNetwork = 'mainnet' | 'testnet';
+
 /**
  * Puts a space after every 4 characters.
  *
@@ -486,23 +490,54 @@ export class FinanceModule extends ModuleBase {
   /**
    * Generates a random Bitcoin address.
    *
+   * @param options An options object.
+   * @param options.type The bitcoin address type (`'legacy'`, `'sewgit'`, `'bech32'` or `'taproot'`). Defaults to `'legacy'`.
+   * @param options.network The bitcoin network (`'mainnet'` or `'testnet'`). Defaults to `'mainnet'`.
+   *
    * @example
-   * faker.finance.bitcoinAddress() // '3ySdvCkTLVy7gKD4j6JfSaf5d'
+   * faker.finance.bitcoinAddress() // '1TeZEFLmGPLEQrSRdAcnZLoWwYeiHwmRog'
+   * faker.finance.bitcoinAddress({ type: 'bech32' }) // 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4'
+   * faker.finance.bitcoinAddress({ type: 'bech32', network: 'testnet' }) // 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx'
    *
    * @since 3.1.0
    */
-  bitcoinAddress(): string {
-    const addressLength = this.faker.number.int({ min: 25, max: 39 });
-
-    let address = this.faker.helpers.arrayElement(['1', '3']);
-
-    address += this.faker.string.alphanumeric({
-      length: addressLength,
-      casing: 'mixed',
-      exclude: '0OIl',
+  bitcoinAddress(
+    options: {
+      /**
+       * The bitcoin address type (`'legacy'`, `'sewgit'`, `'bech32'` or `'taproot'`).
+       *
+       * @default faker.helpers.arrayElement(['legacy', 'segwit', 'bech32', 'taproot'])
+       */
+      type?: BitcoinAddressType;
+      /**
+       * The bitcoin network (`'mainnet'` or `'testnet'`).
+       *
+       * @default 'mainnet'
+       */
+      network?: BitcoinNetwork;
+    } = {}
+  ): string {
+    const {
+      type = this.faker.helpers.arrayElement([
+        'legacy',
+        'segwit',
+        'bech32',
+        'taproot',
+      ]),
+      network = 'mainnet',
+    } = options;
+    const addressSpec =
+      this.faker.definitions.finance.bitcoin_address_specs[type];
+    const addressPrefix = addressSpec.prefix[network];
+    const addressLength = this.faker.number.int(addressSpec.length);
+
+    const address = this.faker.string.alphanumeric({
+      length: addressLength - addressPrefix.length,
+      casing: addressSpec.casing,
+      exclude: addressSpec.exclude,
     });
 
-    return address;
+    return addressPrefix + address;
   }
 
   /**

test/modules/__snapshots__/finance.spec.ts.snap

@@ -24,7 +24,11 @@ exports[`finance > 42 > bic > noArgs 1`] = `"YTPECC2VXXX"`;
 
 exports[`finance > 42 > bic > with branch code 1`] = `"JYTPCD52XXX"`;
 
-exports[`finance > 42 > bitcoinAddress 1`] = `"3JAaa4SAH2YQdbbiwrhB9hnsMcvA3Ba"`;
+exports[`finance > 42 > bitcoinAddress > noArgs 1`] = `"3JAaa4SAH2YQdbbiwrhB9hnsMcvA3Ba4XY"`;
+
+exports[`finance > 42 > bitcoinAddress > with type and network option 1`] = `"1XJAaa4SAH2YQdbbiwrhB9hnsMcvA"`;
+
+exports[`finance > 42 > bitcoinAddress > with type option 1`] = `"1XJAaa4SAH2YQdbbiwrhB9hnsMcvA"`;
 
 exports[`finance > 42 > creditCardCVV 1`] = `"397"`;
 
@@ -108,7 +112,11 @@ exports[`finance > 1211 > bic > noArgs 1`] = `"XFZROMRC"`;
 
 exports[`finance > 1211 > bic > with branch code 1`] = `"YXFZNPOROTR"`;
 
-exports[`finance > 1211 > bitcoinAddress 1`] = `"3eZEFLmGPLEQrSRdAcnZLoWwYeiHwmRogjbyG9G"`;
+exports[`finance > 1211 > bitcoinAddress > noArgs 1`] = `"bc1pw8zppsdqusnufvv7l7dzsexkz8aqjdve9a6kq5qh8f7vlh2q6q9sjg7mv4"`;
+
+exports[`finance > 1211 > bitcoinAddress > with type and network option 1`] = `"1TeZEFLmGPLEQrSRdAcnZLoWwYeiHwmRog"`;
+
+exports[`finance > 1211 > bitcoinAddress > with type option 1`] = `"1TeZEFLmGPLEQrSRdAcnZLoWwYeiHwmRog"`;
 
 exports[`finance > 1211 > creditCardCVV 1`] = `"982"`;
 
@@ -192,7 +200,11 @@ exports[`finance > 1337 > bic > noArgs 1`] = `"EHLILK9ZXXX"`;
 
 exports[`finance > 1337 > bic > with branch code 1`] = `"GEHLGGI9XXX"`;
 
-exports[`finance > 1337 > bitcoinAddress 1`] = `"1hsjwgYJ7oC8ZrMNmqzLbhEubpcwQ"`;
+exports[`finance > 1337 > bitcoinAddress > noArgs 1`] = `"3hsjwgYJ7oC8ZrMNmqzLbhEubpc"`;
+
+exports[`finance > 1337 > bitcoinAddress > with type and network option 1`] = `"1ahsjwgYJ7oC8ZrMNmqzLbhEubpc"`;
+
+exports[`finance > 1337 > bitcoinAddress > with type option 1`] = `"1ahsjwgYJ7oC8ZrMNmqzLbhEubpc"`;
 
 exports[`finance > 1337 > creditCardCVV 1`] = `"212"`;
 

test/modules/finance.spec.ts

@@ -1,8 +1,11 @@
-import isValidBtcAddress from 'validator/lib/isBtcAddress';
 import isCreditCard from 'validator/lib/isCreditCard';
 import { describe, expect, it } from 'vitest';
 import { faker, fakerZH_CN } from '../../src';
 import { FakerError } from '../../src/errors/faker-error';
+import type {
+  BitcoinAddressType,
+  BitcoinNetwork,
+} from '../../src/modules/finance';
 import ibanLib from '../../src/modules/finance/iban';
 import { luhnCheck } from '../../src/modules/helpers/luhn-check';
 import { seededTests } from '../support/seeded-runs';
@@ -21,7 +24,6 @@ describe('finance', () => {
       'currencyCode',
       'currencyName',
       'currencySymbol',
-      'bitcoinAddress',
       'litecoinAddress',
       'creditCardCVV',
       'ethereumAddress',
@@ -91,6 +93,15 @@ describe('finance', () => {
           ellipsis: true,
         });
     });
+
+    t.describe('bitcoinAddress', (t) => {
+      t.it('noArgs')
+        .it('with type option', { type: 'legacy' })
+        .it('with type and network option', {
+          type: 'legacy',
+          network: 'mainnet',
+        });
+    });
   });
 
   describe.each(times(NON_SEEDED_BASED_RUN).map(() => faker.seed()))(
@@ -313,17 +324,103 @@ describe('finance', () => {
       });
 
       describe('bitcoinAddress()', () => {
+        // Utility for validating Bitcoin addresses (validator lib doesn't support taproot and testnets yet)
+        const bech32 = /^(bc1|tb1|bc1p|tb1p)[a-z0-9]{39,58}$/;
+        const base58 = /^(1|2|3|m)[A-HJ-NP-Za-km-z1-9]{25,39}$/;
+        const isBtcAddress = (address: string) =>
+          bech32.test(address) || base58.test(address);
+
         it('should return a valid bitcoin address', () => {
           const bitcoinAddress = faker.finance.bitcoinAddress();
-          /**
-           *  Note: Although the total length of a Bitcoin address can be 25-33 characters, regex quantifiers only check the preceding token
-           *  Therefore we take one from the total length of the address not including the first character ([13])
-           */
 
           expect(bitcoinAddress).toBeTruthy();
           expect(bitcoinAddress).toBeTypeOf('string');
-          expect(bitcoinAddress).toSatisfy(isValidBtcAddress);
-        });
+          expect(bitcoinAddress).toSatisfy(isBtcAddress);
+        });
+        it.each`
+          type         | expectedPrefix
+          ${'legacy'}  | ${'1'}
+          ${'segwit'}  | ${'3'}
+          ${'bech32'}  | ${'bc1'}
+          ${'taproot'} | ${'bc1p'}
+        `(
+          'should handle the type = $type argument',
+          ({
+            type,
+            expectedPrefix,
+          }: {
+            type: BitcoinAddressType;
+            expectedPrefix: string;
+          }) => {
+            const bitcoinAddress = faker.finance.bitcoinAddress({
+              type,
+            });
+
+            expect(bitcoinAddress).toBeTruthy();
+            expect(bitcoinAddress).toBeTypeOf('string');
+            expect(bitcoinAddress).toSatisfy(isBtcAddress);
+            expect(bitcoinAddress.startsWith(expectedPrefix)).toBe(true);
+          }
+        );
+
+        it.each`
+          network      | expectedPrefixes
+          ${'mainnet'} | ${['1', '3', 'bc1', 'bc1p']}
+          ${'testnet'} | ${['2', 'm', 'tb1', 'tb1p']}
+        `(
+          'should handle the network = $network argument',
+          ({
+            network,
+            expectedPrefixes,
+          }: {
+            network: BitcoinNetwork;
+            expectedPrefixes: string[];
+          }) => {
+            const bitcoinAddress = faker.finance.bitcoinAddress({
+              network,
+            });
+
+            expect(bitcoinAddress).toBeTruthy();
+            expect(bitcoinAddress).toBeTypeOf('string');
+            expect(bitcoinAddress).toSatisfy(isBtcAddress);
+            expect(
+              expectedPrefixes.some((p: string) => bitcoinAddress.startsWith(p))
+            ).toBe(true);
+          }
+        );
+
+        it.each`
+          type         | network      | expectedPrefix
+          ${'legacy'}  | ${'mainnet'} | ${'1'}
+          ${'legacy'}  | ${'testnet'} | ${'m'}
+          ${'segwit'}  | ${'mainnet'} | ${'3'}
+          ${'segwit'}  | ${'testnet'} | ${'2'}
+          ${'bech32'}  | ${'mainnet'} | ${'bc1'}
+          ${'bech32'}  | ${'testnet'} | ${'tb1'}
+          ${'taproot'} | ${'mainnet'} | ${'bc1p'}
+          ${'taproot'} | ${'testnet'} | ${'tb1p'}
+        `(
+          'should handle the type = $type and network = $network arguments',
+          ({
+            type,
+            network,
+            expectedPrefix,
+          }: {
+            type: BitcoinAddressType;
+            network: BitcoinNetwork;
+            expectedPrefix: string;
+          }) => {
+            const bitcoinAddress = faker.finance.bitcoinAddress({
+              type,
+              network,
+            });
+
+            expect(bitcoinAddress).toBeTruthy();
+            expect(bitcoinAddress).toBeTypeOf('string');
+            expect(bitcoinAddress.startsWith(expectedPrefix)).toBe(true);
+            expect(bitcoinAddress).toSatisfy(isBtcAddress);
+          }
+        );
       });
 
       describe('litecoinAddress()', () => {