bitcoinjs-lib

When using this library for Bitcoin operations, adhere to these critical security practices to prevent catastrophic fund loss:

• Do not reuse addresses.
• Do not share BIP32 extended public keys ('xpubs'); they are a liability.
• Never use Math.random for any cryptographic purpose.
• Verify transactions manually: Always ensure users verify a freshly-decoded human-readable version of their transaction before broadcasting.
• Avoid 'brain wallets': Do not ask users to generate mnemonics manually.
• Verify RNG: Ensure your environment's random number generator is cryptographically secure.

The recommended method for browser usage is through browserify. You can compile the library and its dependencies into a single standalone JavaScript file that can be imported as an ESM module.

$ npm install bitcoinjs-lib browserify
$ npx browserify --standalone bitcoin -o bitcoinjs-lib.js <<< "module.exports = require('bitcoinjs-lib');"

Then import it in your HTML:

<script type="module">import "/scripts/bitcoinjs-lib.js"</script>

To run the existing tests and coverage reports for the project, use the following npm commands:

npm test
npm run-script coverage

The repository contains a comprehensive suite of integration tests that serve as practical examples for various Bitcoin operations. These examples cover:

• Taproot: Key spending and script-path spends (OP_CHECKSIG, OP_CHECKSEQUENCEVERIFY, OP_CHECKSIGADD).
• Addresses: Generating random, SegWit, P2SH, multisig (2-of-3, 3-of-4, 2-of-2), Testnet, and Litecoin addresses, as well as importing via WIF.
• Transactions: Creating 1-to-1 transactions, typical transactions, OP_RETURN outputs, and various SegWit input types (P2WPKH, P2WSH, P2PK).
• HD Keys (BIP32): Exporting/importing xpriv/xpub, creating BIP32/BIP44/BIP49 addresses, and using BIP39 mnemonics.
• Advanced Scripts: Implementing CLTV (CheckLockTimeVerify) and CSV (CheckSequenceVerify) logic.

Detailed implementations can be found in the test/integration/ directory.

Install the core library via npm. Note that key management (ECPair and BIP32) has been moved to separate libraries to reduce bundle size for users who do not need cryptographic functions.

npm install bitcoinjs-lib

If you need to perform cryptographic functions such as converting private keys to public keys or generating HD keys, you must install these additional libraries separately:

• ecpair: Provides the ECPair class for single key management.
• bip32: Used for generating HD (Hierarchical Deterministic) keys.

npm install ecpair bip32

The bitcoinjs-lib payments module provides functions to create various Bitcoin address and script types. Supported types include:

• p2pk: Pay-to-PubKey
• p2pkh: Pay-to-PubKey-Hash
• p2sh: Pay-to-Script-Hash
• p2ms: Pay-to-MultiSig
• p2wpkh: Pay-to-Witness-PubKey-Hash
• p2wsh: Pay-to-Witness-Script-Hash
• p2tr: Taproot (P2TR)
• embed: Data embedding

When instantiating Psbt, you can pass an opts object.

• network: A bitcoinjs Network object (defaults to networks.bitcoin). This is required if you use address in addOutput.
• maximumFeeRate: A threshold (in satoshis per byte) used during extractTransaction to prevent accidental high-fee transactions. Defaults to 5000.

You can update the fee rate limit using psbt.setMaximumFeeRate(satoshiPerByte).

The following libraries are recommended for specific Bitcoin-related tasks when working with bitcoinjs-lib:

• BIP21: BIP21 compatible URL encoding.
• BIP38: Passphrase-protected private keys.
• BIP39: Mnemonic generation for deterministic keys.
• BIP32-Utils: Utilities for working with BIP32.
• BIP66: Strict DER signature decoding.
• BIP68: Relative lock-time encoding.
• BIP69: Lexicographical Indexing of Transaction Inputs and Outputs.
• Base58 / Base58 Check: Encoding/decoding.
• Bech32: BIP173/BIP350 compliant encoding.
• coinselect: Fee-optimizing transaction input selection.
• merkle-lib: Merkle root and tree calculations.
• minimaldata: Bitcoin policy checking (SCRIPT_VERIFY_MINIMALDATA).

When using Taproot features in a browser environment, tiny-secp256k1 may have compatibility issues due to its WASM dependency. You can use these alternatives (though they may be slower):

1. @bitcoin-js/tiny-secp256k1-asmjs: A version compiled to ASM.js.
2. @bitcoinerlab/secp256k1: Requires access to the global BigInt primitive.

If you attempt to call getEccLib() before calling initEccLib() with a valid instance, the library will throw the following error:

Error: No ECC Library provided. You must call initEccLib() with a valid TinySecp256k1Interface instance