JSDoc: Namespace: CASH

Bitcoin Cash CashAddr address format utilities

Provides comprehensive support for converting legacy Bitcoin addresses to the CashAddr format used by Bitcoin Cash. Features include:

Legacy address decoding and validation
Network prefix determination (bitcoincash/bchtest)
Polynomial checksum generation and validation
Base32 encoding with custom alphabet
Support for both P2PKH and P2SH address types

Source:

src/altAddress/BCH/cash_addr.js, line 24

Example

// Convert legacy address to CashAddr format
const legacy = "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";
const cashAddr = CASH_ADDR.to_cashAddr(legacy, "p2pkh");
// Returns: "bitcoincash:qztxx64w20kmy5y9sskjwtgxp3j8dc20ksvef26ssu"

// Convert testnet address
const testLegacy = "mgRpP3zP1hmxyoeYJgfbcmN3c2Qsurw48D";
const testCashAddr = CASH_ADDR.to_cashAddr(testLegacy, "p2pkh");
// Returns: "bchtest:qqyl7uye7t0rjq6vrtqjedcyudy8hj0rzvnwwa5c5g"

Methods

(static) checksum_5bit(checksumopt) → {Uint8Array}

Converts a numeric checksum to 5-bit representation for Base32 encoding

Takes a 40-bit checksum value and converts it to an array of eight 5-bit values for inclusion in the final CashAddr string. The conversion extracts 5 bits at a time from least significant to most significant.

Parameters:

Name	Type	Attributes	Default	Description
`checksum`	number	<optional>	19310	40-bit checksum value to convert

Source:

src/altAddress/BCH/cash_addr.js, line 304

Returns:

Array of 8 values, each containing 5 bits

Type: Uint8Array

Example

const checksum = 0x1234567890; // Example 40-bit checksum
const fiveBitChecksum = CASH_ADDR.checksum_5bit(checksum);
// Returns: [16, 18, 6, 22, 15, 4, 18, 0] (8 five-bit values)

// The values can be directly used with Base32 encoding
const checksumString = base32_encode(fiveBitChecksum);

(static) convertBits(data, from, to) → {Uint8Array}

Converts data between different bit-width representations

Performs bit-packing conversion between arbitrary bit widths, commonly used to convert from 8-bit bytes to 5-bit groups for Base32 encoding. The conversion handles padding and ensures no data loss.

Parameters:

Name	Type	Description
`data`	Uint8Array \| Buffer	Input data to convert
`from`	number	Source bit width (e.g., 8 for bytes)
`to`	number	Target bit width (e.g., 5 for Base32)

Source:

src/altAddress/BCH/cash_addr.js, line 256

Returns:

Converted data in target bit width

Type: Uint8Array

Example

// Convert bytes to 5-bit groups for Base32
const bytes = new Uint8Array([0xFF, 0x80, 0x00]);
const fiveBit = CASH_ADDR.convertBits(bytes, 8, 5);
// Returns: [31, 30, 0, 0, 0] (0xFF80 in 5-bit groups)

// Convert back from 5-bit to 8-bit
const backToBytes = CASH_ADDR.convertBits(fiveBit, 5, 8);

(static) decode_legacy_address(legacy_addropt) → {DecodedAddress}

Decodes a legacy Base58Check address to extract network and hash information

Validates the address format and extracts:

Network type from version byte (0x00 = mainnet, 0x6f = testnet)
Hash160 value (20 bytes) from the address payload
Checksum validation through Base58Check decoding

Parameters:

Name	Type	Attributes	Default	Description
`legacy_addr`	string	<optional>	""	Legacy address to decode

Source:

src/altAddress/BCH/cash_addr.js, line 119

Throws:

If address format is invalid or unsupported
Type Error

Returns:

Tuple of [network prefix, hex-encoded hash]

Type: DecodedAddress

Example

// Decode mainnet address
const [prefix, hash] = CASH_ADDR.decode_legacy_address("1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2");
// Returns: ["bitcoincash", "76a04053bda0a88bda5177b86a15c3b29f559873"]

// Decode testnet address
const [testPrefix, testHash] = CASH_ADDR.decode_legacy_address("mgRpP3zP1hmxyoeYJgfbcmN3c2Qsurw48D");
// Returns: ["bchtest", "0e7c6e0e0b2c07d6a7b5b8b4d8b5b8b4d8b5b8b4"]

(static) polymod(v) → {number}

Computes CashAddr polynomial checksum using the generator polynomial

Implements the CashAddr checksum algorithm with a 40-bit generator polynomial. The algorithm processes 5-bit values and maintains a 40-bit state, applying the generator when specific bits are set.

Generator constants:

0x98f2bc8e61, 0x79b76d99e2, 0xf33e5fb3c4, 0xae2eabe2a8, 0x1e4f43e470

Parameters:

Name	Type	Description
`v`	Buffer \| Uint8Array	Array of 5-bit values to process

Source:

src/altAddress/BCH/cash_addr.js, line 156

See:

CashAddr Checksum Algorithm

Returns:

40-bit polynomial checksum result

Type: number

Example

const data = Buffer.from([1, 2, 3, 4, 5]); // 5-bit values
const checksum = CASH_ADDR.polymod(data);
console.log(checksum.toString(16)); // Hex representation

(static) prefix_5bit(prefixopt) → {Uint8Array}

Converts network prefix string to 5-bit representation

Extracts the lower 5 bits of each character in the prefix for use in checksum calculation. This ensures the network prefix is properly incorporated into the address validation.

Parameters:

Name	Type	Attributes	Default	Description
`prefix`	string	<optional>	'bitcoincash'	Network prefix to convert

Source:

src/altAddress/BCH/cash_addr.js, line 232

Returns:

Array of 5-bit values representing the prefix

Type: Uint8Array

Example

const prefix5bit = CASH_ADDR.prefix_5bit('bitcoincash');
// Returns array of lower 5 bits: [2, 9, 20, 3, 15, 9, 14, 3, 1, 19, 8]

const testPrefix = CASH_ADDR.prefix_5bit('bchtest');
// Returns array: [2, 3, 8, 20, 5, 19, 20]

(static) to_cashAddr(legacy_addressopt, typeopt) → {string}

Converts a legacy Bitcoin address to CashAddr format

The conversion process:

Decodes the legacy Base58Check address to extract hash and network
Prepends version byte based on address type and hash length
Converts from 8-bit to 5-bit representation for Base32 encoding
Computes CashAddr checksum using polynomial algorithm
Combines all components into final CashAddr format

Parameters:

Name	Type	Attributes	Default	Description
`legacy_address`	string	<optional>	""	Legacy Base58Check address to convert
`type`	string	<optional>	"p2pkh"	Address type: "p2pkh" or "p2sh"

Source:

src/altAddress/BCH/cash_addr.js, line 72

Throws:

If legacy address is invalid or unsupported
Type Error

Returns:

CashAddr formatted address with network prefix

Type: string

Example

// Convert P2PKH address
const p2pkh = CASH_ADDR.to_cashAddr("1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2", "p2pkh");
// Returns: "bitcoincash:qztxx64w20kmy5y9sskjwtgxp3j8dc20ksvef26ssu"

// Convert P2SH address
const p2sh = CASH_ADDR.to_cashAddr("3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy", "p2sh");
// Returns: "bitcoincash:pztxx64w20kmy5y9sskjwtgxp3j8dc20ksvef26ssu"

(static) versionByte(typeopt, hash) → {Buffer}

Generates version byte for CashAddr encoding based on address type and hash size

The version byte encodes both the address type and hash length:

Bits 3-7: Hash size bits (mapping hash length to predefined values)
Bits 0-2: Type bits (0 for P2PKH, 8 for P2SH)

Supported hash sizes: 160, 192, 224, 256, 320, 384, 448, 512 bits

Parameters:

Name	Type	Attributes	Default	Description
`type`	string	<optional>	"p2pkh"	Address type: "p2pkh" or "p2sh"
`hash`	Buffer			Hash buffer to determine size

Source:

src/altAddress/BCH/cash_addr.js, line 195

Throws:

If hash size is unsupported or type is invalid
Type Error

Returns:

Single-byte buffer containing version information

Type: Buffer

Example

const hash160 = Buffer.alloc(20); // 160-bit hash
const versionByte = CASH_ADDR.versionByte("p2pkh", hash160);
console.log(versionByte[0]); // 0 (P2PKH with 160-bit hash)

const versionP2SH = CASH_ADDR.versionByte("p2sh", hash160);
console.log(versionP2SH[0]); // 8 (P2SH with 160-bit hash)

Namespace: CASH_ADDR

Example

Methods

(static) checksum_5bit(checksumopt) → {Uint8Array}

Parameters:

Returns:

Example

(static) convertBits(data, from, to) → {Uint8Array}

Parameters:

Returns:

Example

(static) decode_legacy_address(legacy_addropt) → {DecodedAddress}

Parameters:

Throws:

Returns:

Example

(static) polymod(v) → {number}

Parameters:

Returns:

Example

(static) prefix_5bit(prefixopt) → {Uint8Array}

Parameters:

Returns:

Example

(static) to_cashAddr(legacy_addressopt, typeopt) → {string}

Parameters:

Throws:

Returns:

Example

(static) versionByte(typeopt, hash) → {Buffer}

Parameters:

Throws:

Returns:

Example