j-bitcoin
Version:
Comprehensive JavaScript cryptocurrency wallet library for Bitcoin (BTC), Bitcoin Cash (BCH), and Bitcoin SV (BSV) with custodial and non-custodial wallet support, threshold signatures, and multiple address formats
1,296 lines (428 loc) • 21.2 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Namespace: BECH32</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Namespace: BECH32</h1>
<section>
<header>
<h2>BECH32</h2>
</header>
<article>
<div class="container-overview">
<div class="description"><p>Bech32 and Bech32m address encoding utilities for Bitcoin SegWit addresses</p>
<p>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.</p></div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="src_altAddress_BTC_bech32.js.html">src/altAddress/BTC/bech32.js</a>, <a href="src_altAddress_BTC_bech32.js.html#line17">line 17</a>
</li></ul></dd>
</dl>
<h3>Example</h3>
<pre class="prettyprint"><code>// 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"</code></pre>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id=".data_to_bech32"><span class="type-signature">(static) </span>data_to_bech32<span class="signature">(prefix<span class="signature-attributes">opt</span>, data<span class="signature-attributes">opt</span>, encoding<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {string}</span></h4>
<div class="description">
<p>Encodes arbitrary hex data into a Bech32 address with custom prefix</p>
<p>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.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>prefix</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"Jamallo"
</td>
<td class="description last"><p>Custom Human Readable Part for the address</p></td>
</tr>
<tr>
<td class="name"><code>data</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"hex"
</td>
<td class="description last"><p>Hex-encoded data to include in the address</p></td>
</tr>
<tr>
<td class="name"><code>encoding</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
'bech32'
</td>
<td class="description last"><p>Encoding type: 'bech32' or 'bech32m'</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="src_altAddress_BTC_bech32.js.html">src/altAddress/BTC/bech32.js</a>, <a href="src_altAddress_BTC_bech32.js.html#line196">line 196</a>
</li></ul></dd>
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If the total address length would exceed 90 characters</p>
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Error</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Bech32-encoded address with custom prefix and data</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">string</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// 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");</code></pre>
<h4 class="name" id=".encode"><span class="type-signature">(static) </span>encode<span class="signature">(prefix<span class="signature-attributes">opt</span>, data<span class="signature-attributes">opt</span>, encoding<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {string}</span></h4>
<div class="description">
<p>Encodes data into Bech32 or Bech32m format with specified prefix</p>
<p>The encoding process follows the Bech32 specification:</p>
<ol>
<li>Expands the Human Readable Part (HRP) into 5-bit groups</li>
<li>Concatenates expanded HRP + data + 6 zero bytes</li>
<li>Computes polynomial checksum using the Bech32 generator</li>
<li>XORs with encoding constant (1 for Bech32, 0x2bc830a3 for Bech32m)</li>
<li>Converts checksum to 5-bit representation and appends to data</li>
<li>Encodes the complete payload using Base32 alphabet</li>
</ol>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>prefix</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"bc"
</td>
<td class="description last"><p>Human Readable Part (e.g., "bc" for mainnet, "tb" for testnet)</p></td>
</tr>
<tr>
<td class="name"><code>data</code></td>
<td class="type">
<span class="param-type">Uint8Array</span>
|
<span class="param-type">Buffer</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last"><p>5-bit encoded data to include in address</p></td>
</tr>
<tr>
<td class="name"><code>encoding</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
'bech32'
</td>
<td class="description last"><p>Encoding type: 'bech32' for v0 witnesses, 'bech32m' for v1+</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="src_altAddress_BTC_bech32.js.html">src/altAddress/BTC/bech32.js</a>, <a href="src_altAddress_BTC_bech32.js.html#line57">line 57</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Complete Bech32-encoded address</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">string</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// Encode witness program for P2WPKH
const witnessProgram = new Uint8Array([0, ...hashBytes]); // version 0 + hash
const address = BECH32.encode("bc", witnessProgram, "bech32");</code></pre>
<h4 class="name" id=".expandHRP"><span class="type-signature">(static) </span>expandHRP<span class="signature">(prefix<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Buffer}</span></h4>
<div class="description">
<p>Expands the Human Readable Part (HRP) into the format required for checksum calculation</p>
<p>The expansion converts the HRP into two parts:</p>
<ol>
<li>High 3 bits of each character</li>
<li>A zero separator</li>
<li>Low 5 bits of each character</li>
</ol>
<p>This expansion ensures that the HRP is properly incorporated into the checksum
while maintaining the 5-bit alignment required by the Bech32 algorithm.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>prefix</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"bc"
</td>
<td class="description last"><p>Human Readable Part to expand</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="src_altAddress_BTC_bech32.js.html">src/altAddress/BTC/bech32.js</a>, <a href="src_altAddress_BTC_bech32.js.html#line124">line 124</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Expanded HRP ready for checksum calculation</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Buffer</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>const expanded = BECH32.expandHRP("bc");
// Returns Buffer with: [3, 3] + [0] + [2, 3] (high bits + separator + low bits)</code></pre>
<h4 class="name" id=".polymod"><span class="type-signature">(static) </span>polymod<span class="signature">(values)</span><span class="type-signature"> → {number}</span></h4>
<div class="description">
<p>Computes the Bech32 polynomial checksum using the generator polynomial</p>
<p>Implements the Bech32 checksum algorithm with the generator polynomial:
G(x) = x^5 + x^3 + x + 1 (represented as 0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3)</p>
<p>The algorithm processes each 5-bit value, maintaining a 30-bit checksum state
and applying the generator polynomial when the top bit is set.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>values</code></td>
<td class="type">
<span class="param-type">Buffer</span>
|
<span class="param-type">Uint8Array</span>
</td>
<td class="description last"><p>Array of 5-bit values to process</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="src_altAddress_BTC_bech32.js.html">src/altAddress/BTC/bech32.js</a>, <a href="src_altAddress_BTC_bech32.js.html#line91">line 91</a>
</li></ul></dd>
<dt class="tag-see">See:</dt>
<dd class="tag-see">
<ul>
<li><a href="https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#checksum">BIP173 Checksum Algorithm</a></li>
</ul>
</dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>30-bit polynomial checksum result</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">number</span>
</dd>
</dl>
<h4 class="name" id=".to_P2WPKH"><span class="type-signature">(static) </span>to_P2WPKH<span class="signature">(witness_program<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {string}</span></h4>
<div class="description">
<p>Converts a legacy Bitcoin address to a P2WPKH (Pay to Witness PubKey Hash) Bech32 address</p>
<p>The conversion process:</p>
<ol>
<li>Decodes the legacy Base58Check address to extract the hash160</li>
<li>Determines the appropriate network prefix (bc/tb) from the version byte</li>
<li>Converts the 20-byte hash from 8-bit to 5-bit representation</li>
<li>Prepends witness version 0 to create the witness program</li>
<li>Encodes using Bech32 (not Bech32m, as version 0 uses original Bech32)</li>
</ol>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>witness_program</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"legacy address"
</td>
<td class="description last"><p>Legacy P2PKH address to convert</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="src_altAddress_BTC_bech32.js.html">src/altAddress/BTC/bech32.js</a>, <a href="src_altAddress_BTC_bech32.js.html#line158">line 158</a>
</li></ul></dd>
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If the legacy address is invalid or has wrong format</p>
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Error</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Bech32-encoded P2WPKH address</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">string</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// 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"</code></pre>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="AddressFormats.html">AddressFormats</a></li><li><a href="BECH32.html">BECH32</a></li><li><a href="BIP32.html">BIP32</a></li><li><a href="BIP39.html">BIP39</a></li><li><a href="CASH_ADDR.html">CASH_ADDR</a></li><li><a href="ECDSA.html">ECDSA</a></li><li><a href="KeyDecoding.html">KeyDecoding</a></li><li><a href="Signatures.html">Signatures</a></li><li><a href="ThresholdCrypto.html">ThresholdCrypto</a></li><li><a href="Utilities.html">Utilities</a></li><li><a href="Wallets.html">Wallets</a></li><li><a href="schnorr_sig.html">schnorr_sig</a></li></ul><h3>Classes</h3><ul><li><a href="Custodial_Wallet.html">Custodial_Wallet</a></li><li><a href="Non_Custodial_Wallet.html">Non_Custodial_Wallet</a></li><li><a href="Polynomial.html">Polynomial</a></li><li><a href="ThresholdSignature.html">ThresholdSignature</a></li></ul><h3>Global</h3><ul><li><a href="global.html#CHARSET">CHARSET</a></li><li><a href="global.html#FEATURES">FEATURES</a></li><li><a href="global.html#NETWORKS">NETWORKS</a></li><li><a href="global.html#address">address</a></li><li><a href="global.html#b58encode">b58encode</a></li><li><a href="global.html#base32_encode">base32_encode</a></li><li><a href="global.html#derive">derive</a></li><li><a href="global.html#fromSeed">fromSeed</a></li><li><a href="global.html#hdKey">hdKey</a></li><li><a href="global.html#legacyAddress_decode">legacyAddress_decode</a></li><li><a href="global.html#privateKey_decode">privateKey_decode</a></li><li><a href="global.html#rmd160">rmd160</a></li><li><a href="global.html#standardKey">standardKey</a></li><li><a href="global.html#table">table</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.4</a> on Wed Jun 04 2025 02:28:50 GMT-0400 (Eastern Daylight Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>