BIP-322 JavaScript Library

Common errors

• TypeError: Signer.sign() missing 4th argument 'network'

  cause Attempting to pass the `network` argument to `Signer.sign` in versions 2.0.0 or higher.
  fix Remove the `network` argument. The function now infers the network directly from the provided Bitcoin address. E.g., `Signer.sign(privateKey, address, message)`.

• TypeError: Cannot read properties of undefined (reading 'compressPublicKey')

  cause Using `Address.compressPublicKey` or `Address.uncompressPublicKey` directly from the `Address` class in versions 2.0.0 or higher.
  fix These functions have been moved to the `Key` class. Use `Key.compressPublicKey` or `Key.uncompressPublicKey` instead.

• Error: Invalid signature format: expected Base64 string

  cause Your code is expecting `Signer.sign` to return a Buffer for P2PKH addresses, but it now returns a Base64 string.
  fix Update your code to expect a `string` (Base64-encoded) return from `Signer.sign` for all address types. If a Buffer is needed, decode the Base64 string, e.g., `Buffer.from(signature, 'base64')`.

• Signatures for Taproot addresses are inconsistent across runs/machines

  cause Due to an update in the underlying secp256k1 library, BIP-322 Schnorr signatures for Taproot addresses are now non-deterministic.
  fix This is expected behavior and does not indicate an invalid signature. Instead of byte-for-byte comparison, always use `Verifier.verifySignature()` to validate the signature.

Warnings

• breaking The `Signer.sign` function now consistently returns a Base64-encoded string for all address types. Previously, for P2PKH addresses, it incorrectly returned a raw Buffer. Code expecting a Buffer for P2PKH signatures must be updated.
  Fix: Ensure your code expects a `string` (Base64-encoded) return type from `Signer.sign` for all address types. If you need a Buffer, decode the Base64 string.
• breaking The `network` argument in `Signer.sign` was removed. The network is now automatically inferred from the provided address.
  Fix: Remove the `network` argument from `Signer.sign` calls. The library will infer the network (mainnet, testnet, regtest) from the address string.
• breaking The utility functions `Address.compressPublicKey` and `Address.uncompressPublicKey` have been moved.
  Fix: Update imports and calls to `Key.compressPublicKey` and `Key.uncompressPublicKey` respectively.
• breaking Updating `@bitcoinerlab/secp256k1` to v1.2.0 for BIP-322 Schnorr signatures means `signSchnorr` now uses secure internal randomness (auxRand) by default. This makes BIP-322 signatures for Taproot addresses non-deterministic.
  Fix: Do not rely on byte-for-byte comparison of Taproot BIP-322 signatures. Instead, use `Verifier.verifySignature()` to validate signatures, which correctly handles non-deterministic outputs.
• gotcha By default, the library uses 'Loose BIP-137 Verification,' meaning it will attempt to verify BIP-137 signatures even if they have an incorrect header flag, assuming the signature is valid for any address derivable from the public key. This behavior can lead to unexpected valid verifications if strict adherence to BIP-137 header flags is required.
  Fix: To enforce strict BIP-137 verification, pass `true` as the fourth argument to `Verifier.verifySignature(address, message, signature, true)`.
• gotcha The library's 'Loose BIP-137 Verification' also allows BIP-137 signatures to be used for taproot addresses, which is technically out-of-spec for both BIP-137 and BIP-322 specifications. This might lead to compatibility issues with other stricter implementations.
  Fix: Be aware of this behavior when interacting with systems that enforce strict adherence to BIP-137 and BIP-322 specifications regarding taproot addresses. For strict verification, consider using the `useStrictVerification` flag where applicable or ensuring a clear understanding of the expected signature scheme.

Install

• npm install bip322-js npm
• yarn add bip322-js yarn
• pnpm add bip322-js pnpm

Imports

• Signer
  wrong:

  const Signer = require('bip322-js').Signer

  correct:

  import { Signer } from 'bip322-js'

  ESM is preferred for modern JavaScript/TypeScript projects. CommonJS `require` is also supported.
• Verifier
  wrong:

  const Verifier = require('bip322-js').Verifier

  correct:

  import { Verifier } from 'bip322-js'

  ESM is preferred for modern JavaScript/TypeScript projects. CommonJS `require` is also supported.
• BIP322
  wrong:

  const BIP322 = require('bip322-js').BIP322

  correct:

  import { BIP322 } from 'bip322-js'

  Used for generating raw BIP-322 transactions. ESM is preferred for modern JavaScript/TypeScript projects.

Quickstart

Demonstrates how to sign a message using a private key for a P2WPKH address and then verify the generated signature, including an example of toggling strict BIP-137 verification.

import { Signer, Verifier } from 'bip322-js';

const privateKey = 'L3VFeEujGtevx9w18HD1fhRbCH67Az2dpCymeRE1SoPK6XQtaN2k'; // Example private key (do not use in production)
const address = 'bc1q9vza2e8x573nczrlzms0wvx3gsqjx7vavgkx0l'; // P2WPKH address
const message = 'Hello World';

async function runBip322Example() {
  try {
    // Sign the message
    const signature = Signer.sign(privateKey, address, message);
    console.log('Generated Signature:', signature);

    // Verify the signature
    const isValid = Verifier.verifySignature(address, message, signature);
    console.log('Is signature valid (strict verification disabled by default)?', isValid);

    // Verify with strict BIP-137 verification (if applicable for BIP-137 signatures)
    const isStrictlyValid = Verifier.verifySignature(address, message, signature, true);
    console.log('Is signature valid (strict verification enabled)?', isStrictlyValid);

  } catch (error) {
    console.error('An error occurred:', error);
  }
}

runBip322Example();