Bech32 and Bech32m address encoding utilities for Bitcoin SegWit addresses
Provides comprehensive support for encoding witness programs into human-readable addresses with error detection capabilities. Supports both legacy Bech32 (for v0 witnesses) and Bech32m (for v1+ witnesses) encoding schemes.
- Source:
Example
// Convert legacy address to P2WPKH
const legacyAddr = "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";
const segwitAddr = BECH32.to_P2WPKH(legacyAddr);
// Returns: "bc1qhkfq3zahaqkkzx5mjnamwjsfpw3tvke7v6aaph"
// Encode arbitrary data with custom prefix
const encoded = BECH32.data_to_bech32("hello", "48656c6c6f20576f726c64", "bech32");
// Returns: "hello1dpjkcmr0vpmkxettv9xjqn50p2u"Methods
(static) data_to_bech32(prefixopt, dataopt, encodingopt) → {string}
Encodes arbitrary hex data into a Bech32 address with custom prefix
This function provides a general-purpose interface for encoding any data into the Bech32 format. It handles the conversion from 8-bit bytes to 5-bit groups and validates the total length constraints.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
prefix |
string |
<optional> |
"Jamallo" | Custom Human Readable Part for the address |
data |
string |
<optional> |
"hex" | Hex-encoded data to include in the address |
encoding |
string |
<optional> |
'bech32' | Encoding type: 'bech32' or 'bech32m' |
- Source:
Throws:
-
If the total address length would exceed 90 characters
- Type
- Error
Returns:
Bech32-encoded address with custom prefix and data
- Type
- string
Example
// Encode custom data
const customAddr = BECH32.data_to_bech32("myapp", "48656c6c6f", "bech32");
// Returns: "myapp1dpjkcmr0vx8nrwl"
// Using Bech32m encoding
const modernAddr = BECH32.data_to_bech32("test", "deadbeef", "bech32m");(static) encode(prefixopt, dataopt, encodingopt) → {string}
Encodes data into Bech32 or Bech32m format with specified prefix
The encoding process follows the Bech32 specification:
- Expands the Human Readable Part (HRP) into 5-bit groups
- Concatenates expanded HRP + data + 6 zero bytes
- Computes polynomial checksum using the Bech32 generator
- XORs with encoding constant (1 for Bech32, 0x2bc830a3 for Bech32m)
- Converts checksum to 5-bit representation and appends to data
- Encodes the complete payload using Base32 alphabet
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
prefix |
string |
<optional> |
"bc" | Human Readable Part (e.g., "bc" for mainnet, "tb" for testnet) |
data |
Uint8Array | Buffer |
<optional> |
5-bit encoded data to include in address |
|
encoding |
string |
<optional> |
'bech32' | Encoding type: 'bech32' for v0 witnesses, 'bech32m' for v1+ |
- Source:
Returns:
Complete Bech32-encoded address
- Type
- string
Example
// Encode witness program for P2WPKH
const witnessProgram = new Uint8Array([0, ...hashBytes]); // version 0 + hash
const address = BECH32.encode("bc", witnessProgram, "bech32");(static) expandHRP(prefixopt) → {Buffer}
Expands the Human Readable Part (HRP) into the format required for checksum calculation
The expansion converts the HRP into two parts:
- High 3 bits of each character
- A zero separator
- Low 5 bits of each character
This expansion ensures that the HRP is properly incorporated into the checksum while maintaining the 5-bit alignment required by the Bech32 algorithm.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
prefix |
string |
<optional> |
"bc" | Human Readable Part to expand |
- Source:
Returns:
Expanded HRP ready for checksum calculation
- Type
- Buffer
Example
const expanded = BECH32.expandHRP("bc");
// Returns Buffer with: [3, 3] + [0] + [2, 3] (high bits + separator + low bits)(static) polymod(values) → {number}
Computes the Bech32 polynomial checksum using the generator polynomial
Implements the Bech32 checksum algorithm with the generator polynomial: G(x) = x^5 + x^3 + x + 1 (represented as 0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3)
The algorithm processes each 5-bit value, maintaining a 30-bit checksum state and applying the generator polynomial when the top bit is set.
Parameters:
| Name | Type | Description |
|---|---|---|
values |
Buffer | Uint8Array | Array of 5-bit values to process |
- Source:
- See:
Returns:
30-bit polynomial checksum result
- Type
- number
(static) to_P2WPKH(witness_programopt) → {string}
Converts a legacy Bitcoin address to a P2WPKH (Pay to Witness PubKey Hash) Bech32 address
The conversion process:
- Decodes the legacy Base58Check address to extract the hash160
- Determines the appropriate network prefix (bc/tb) from the version byte
- Converts the 20-byte hash from 8-bit to 5-bit representation
- Prepends witness version 0 to create the witness program
- Encodes using Bech32 (not Bech32m, as version 0 uses original Bech32)
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
witness_program |
string |
<optional> |
"legacy address" | Legacy P2PKH address to convert |
- Source:
Throws:
-
If the legacy address is invalid or has wrong format
- Type
- Error
Returns:
Bech32-encoded P2WPKH address
- Type
- string
Example
// Mainnet conversion
const legacy = "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";
const segwit = BECH32.to_P2WPKH(legacy);
// Returns: "bc1qhkfq3zahaqkkzx5mjnamwjsfpw3tvke7v6aaph"
// Testnet conversion
const testLegacy = "mgRpP3zP1hmxyoeYJgfbcmN3c2Qsurw48D";
const testSegwit = BECH32.to_P2WPKH(testLegacy);
// Returns: "tb1qp8lhpx0jmcusxnq6cyktwp8rfpaunccntw8kty"