bip322-js

library3.0.0jsnpmunverified

bip322-js is a TypeScript/JavaScript library providing utility functions for the BIP-322 signature scheme, enabling generic message signing and verification across various Bitcoin address types. It supports P2PKH, P2SH-P2WPKH, P2WPKH, and single-key-spend P2TR addresses on mainnet, testnet, and regtest. The current stable version is 3.0.0, released in April 2025. A key differentiator is its 'Loose BIP-137 Verification' by default, which allows backward compatibility with legacy BIP-137 signatures, even if they have non-standard header flags, by assuming ownership of the private key for all derivable addresses. It also provides functionalities to generate raw `toSpend` and `toSign` BIP-322 transactions.

auth-security serialization database http-networking

npm install bip322-js

github ↗package ↗

INSTALL

IMPORT

SIG · BIP322-JS

bip322-js

auth-securityjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Signer

✓ import { Signer } from 'bip322-js'

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

ESM is preferred for modern JavaScript/TypeScript projects. CommonJS `require` is also supported.

Verifier

✓ import { Verifier } from 'bip322-js'

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

ESM is preferred for modern JavaScript/TypeScript projects. CommonJS `require` is also supported.

BIP322

✓ import { BIP322 } from 'bip322-js'

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

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

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();

Debug

Known issues

breakingThe `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.

affects: >=3.0.0

breakingThe `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.

affects: >=2.0.0

breakingThe utility functions `Address.compressPublicKey` and `Address.uncompressPublicKey` have been moved.

fix

Update imports and calls to `Key.compressPublicKey` and `Key.uncompressPublicKey` respectively.

affects: >=2.0.0

breakingUpdating `@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.

affects: >=3.0.0

gotchaBy 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)`.

affects: >=1.1.0

gotchaThe 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.

affects: >=1.1.0

Errors

Common errors & fixes

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

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')

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

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

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.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ACken2/bip322-js ↗

packagehttps://www.npmjs.com/package/bip322-js ↗