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
948 lines (335 loc) • 18.2 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Namespace: schnorr_sig</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: schnorr_sig</h1>
<section>
<header>
<h2>schnorr_sig</h2>
</header>
<article>
<div class="container-overview">
<div class="description"><p>Schnorr signature operations for Bitcoin according to BIP340</p>
<p>Provides comprehensive Schnorr signature functionality including:</p>
<ul>
<li>Deterministic and randomized signature generation</li>
<li>Public key derivation from private keys</li>
<li>Signature verification with proper point validation</li>
<li>Integration with Bitcoin's Taproot upgrade</li>
</ul>
<p>Key advantages over ECDSA:</p>
<ul>
<li>Linear signature aggregation</li>
<li>Smaller signature size (64 bytes vs 71-73 bytes for ECDSA)</li>
<li>Batch verification for improved performance</li>
<li>Eliminates signature malleability</li>
<li>Enables more sophisticated multi-signature schemes</li>
</ul></div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="src_Schnorr-signature_Schnorr_Signature.js.html">src/Schnorr-signature/Schnorr_Signature.js</a>, <a href="src_Schnorr-signature_Schnorr_Signature.js.html#line19">line 19</a>
</li></ul></dd>
</dl>
<h3>Example</h3>
<pre class="prettyprint"><code>// Basic Schnorr signature workflow
const privateKey = "L1vHfV6GUbMJSvFaqjnButzwq5x4ThdFaotpUgsfScwMNKjdGVuS";
const message = "Hello Schnorr!";
// Sign the message
const signature = schnorr_sig.sign(privateKey, message);
// Get the public key
const publicKey = schnorr_sig.retrieve_public_key(privateKey);
// Verify the signature
const isValid = schnorr_sig.verify(signature, message, publicKey);
console.log(isValid); // true</code></pre>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id=".retrieve_public_key"><span class="type-signature">(static) </span>retrieve_public_key<span class="signature">(private_key<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Uint8Array}</span></h4>
<div class="description">
<p>Derives the Schnorr public key from a private key according to BIP340</p>
<p>Computes the x-only public key representation used in BIP340:</p>
<ol>
<li>Compute the full public key point P = d*G</li>
<li>If P.y is odd, negate d to make P.y even</li>
<li>Return only the x-coordinate (32 bytes)</li>
</ol>
<p>The x-only representation saves space and simplifies signature verification
while maintaining the same security properties as full public keys.</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>private_key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"L1vHfV6GUbMJSvFaqjnButzwq5x4ThdFaotpUgsfScwMNKjdGVuS"
</td>
<td class="description last"><p>WIF-encoded private key</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_Schnorr-signature_Schnorr_Signature.js.html">src/Schnorr-signature/Schnorr_Signature.js</a>, <a href="src_Schnorr-signature_Schnorr_Signature.js.html#line158">line 158</a>
</li></ul></dd>
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If private key is invalid</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>32-byte x-only public key for use with Schnorr signatures</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Uint8Array</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// Get public key for Schnorr operations
const privateKey = "L1vHfV6GUbMJSvFaqjnButzwq5x4ThdFaotpUgsfScwMNKjdGVuS";
const publicKey = schnorr_sig.retrieve_public_key(privateKey);
console.log(publicKey.length); // 32 bytes (x-only)
// Use in signature verification
const message = "Taproot transaction";
const signature = schnorr_sig.sign(privateKey, message);
const verified = schnorr_sig.verify(signature, message, publicKey);
console.log(verified); // true
// Compare with different private key
const otherPrivKey = "KwDiBf89QgGbjEhKnhXJuH7LrciVrZi3qYjgd9M7rFU73sVHnoWn";
const otherPubKey = schnorr_sig.retrieve_public_key(otherPrivKey);
console.log(Buffer.from(publicKey).equals(Buffer.from(otherPubKey))); // false</code></pre>
<h4 class="name" id=".sign"><span class="type-signature">(static) </span>sign<span class="signature">(private_key<span class="signature-attributes">opt</span>, msg<span class="signature-attributes">opt</span>, auxRand<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Uint8Array}</span></h4>
<div class="description">
<p>Creates a Schnorr signature for a given message using BIP340 specification</p>
<p>The signing process follows BIP340:</p>
<ol>
<li>Parse and validate the private key</li>
<li>Compute the public key P = d*G (where d is private key)</li>
<li>Generate nonce k using auxiliary randomness (prevents side-channel attacks)</li>
<li>Compute R = k*G and ensure R.y is even (BIP340 requirement)</li>
<li>Compute challenge e = SHA256(R.x || P || m)</li>
<li>Compute signature s = (k + e*d) mod n</li>
<li>Return signature as 64-byte array: R.x || s</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>private_key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"L1vHfV6GUbMJSvFaqjnButzwq5x4ThdFaotpUgsfScwMNKjdGVuS"
</td>
<td class="description last"><p>WIF-encoded private key</p></td>
</tr>
<tr>
<td class="name"><code>msg</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"Hello world"
</td>
<td class="description last"><p>Message to sign (will be UTF-8 encoded)</p></td>
</tr>
<tr>
<td class="name"><code>auxRand</code></td>
<td class="type">
<span class="param-type">Uint8Array</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
randomBytes(32)
</td>
<td class="description last"><p>32 bytes of auxiliary randomness for nonce generation</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_Schnorr-signature_Schnorr_Signature.js.html">src/Schnorr-signature/Schnorr_Signature.js</a>, <a href="src_Schnorr-signature_Schnorr_Signature.js.html#line83">line 83</a>
</li></ul></dd>
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If private key is invalid or signing fails</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>64-byte Schnorr signature (32-byte R.x + 32-byte s)</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Uint8Array</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// Sign with default randomness
const signature = schnorr_sig.sign(privateKey, "Hello Bitcoin!");
console.log(signature.length); // 64 bytes
// Sign with custom auxiliary randomness
const customAux = new Uint8Array(32).fill(0xaa);
const deterministicSig = schnorr_sig.sign(privateKey, "Hello Bitcoin!", customAux);
// Multiple signatures of same message with different aux data will differ
const sig1 = schnorr_sig.sign(privateKey, "test", new Uint8Array(32).fill(1));
const sig2 = schnorr_sig.sign(privateKey, "test", new Uint8Array(32).fill(2));
console.log(Buffer.from(sig1).equals(Buffer.from(sig2))); // false</code></pre>
<h4 class="name" id=".verify"><span class="type-signature">(static) </span>verify<span class="signature">(sig, msg<span class="signature-attributes">opt</span>, public_key)</span><span class="type-signature"> → {boolean}</span></h4>
<div class="description">
<p>Verifies a Schnorr signature against a message and public key</p>
<p>The verification process implements BIP340 algorithm:</p>
<ol>
<li>Parse the 64-byte signature into R.x (32 bytes) and s (32 bytes)</li>
<li>Validate that R.x and s are valid field elements</li>
<li>Compute challenge e = SHA256(R.x || P || m)</li>
<li>Compute point S = s<em>G - e</em>P</li>
<li>Verify that S.x == R.x and S.y is even</li>
</ol>
<p>This verification is more efficient than ECDSA and allows for batch
verification when verifying multiple signatures simultaneously.</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>sig</code></td>
<td class="type">
<span class="param-type">Uint8Array</span>
|
<span class="param-type">Buffer</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last"><p>64-byte Schnorr signature to verify</p></td>
</tr>
<tr>
<td class="name"><code>msg</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"Hello World"
</td>
<td class="description last"><p>Original message that was signed</p></td>
</tr>
<tr>
<td class="name"><code>public_key</code></td>
<td class="type">
<span class="param-type">Uint8Array</span>
|
<span class="param-type">Buffer</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last"><p>32-byte x-only public key (BIP340 format)</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_Schnorr-signature_Schnorr_Signature.js.html">src/Schnorr-signature/Schnorr_Signature.js</a>, <a href="src_Schnorr-signature_Schnorr_Signature.js.html#line122">line 122</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>True if signature is valid, false otherwise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">boolean</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// Standard verification
const signature = schnorr_sig.sign(privateKey, "Hello Schnorr!");
const publicKey = schnorr_sig.retrieve_public_key(privateKey);
const isValid = schnorr_sig.verify(signature, "Hello Schnorr!", publicKey);
console.log(isValid); // true
// Invalid signature detection
const invalidSig = new Uint8Array(64); // All zeros
const isInvalid = schnorr_sig.verify(invalidSig, "test", publicKey);
console.log(isInvalid); // false
// Wrong message detection
const wrongMsg = schnorr_sig.verify(signature, "Wrong message", publicKey);
console.log(wrongMsg); // false</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>