@qbtc/bitcoinjs-lib

A fork of bitcoinjs-lib with QBitcoin address, WIF, transaction serialization, and signing utilities. The Bitcoin APIs remain available. This package has its own version sequence; version 8.0.0 is the first public release under the @qbtc scope.

Installation

npm install @qbtc/bitcoinjs-lib

For an application that keeps existing bitcoinjs-lib imports, pin an npm alias:

{
  "dependencies": {
    "bitcoinjs-lib": "npm:@qbtc/[email protected]"
  }
}

The package supports Node.js 18 and newer, CommonJS, and ES modules. TypeScript declarations are included (TypeScript 5.3 or newer). Build and release tooling uses Node.js 22. Consumers that need key management can install @qbtc/ecpair separately; the library does not require it at runtime.

import { qbitcoinAddress, qbitcoinNetworks } from '@qbtc/bitcoinjs-lib';
// CommonJS: const { qbitcoinAddress, qbitcoinNetworks } = require('@qbtc/bitcoinjs-lib');

const publicKey = Uint8Array.from(Buffer.from(
  '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
  'hex',
));
const address = qbitcoinAddress.fromPublicKey(publicKey, qbitcoinNetworks.qbitcoin);
// bqQHJ8dsKokoFj58jCHKSSpzk6oiAYKvzZT

QBitcoin APIs

• qbitcoinNetworks: mainnet and testnet parameters; callers can supply their own network object.
• qbitcoinAddress: address encoding and decoding, script hashes, and P2PK scripts for ECDSA, Schnorr, and Falcon-512 public keys.
• qbitcoinWif: QBitcoin private-key payload encoding and decoding.
• qbitcoinTransaction: serialization, transaction IDs, and SIGHASH_ALL for standard QBitcoin transactions.
• qbitcoinSigner: P2PK signing with a caller-provided ECDSA function or externally computed signatures, including Falcon-512.

QBitcoin uses a separate transaction format. The Bitcoin Transaction and Psbt classes do not build QBitcoin transactions. The signing module does not implement Falcon-512 key generation or signing internally.

Only TX_TYPE_STANDARD is supported. Token transactions are rejected during serialization, hashing, and signing, including objects containing the former tokenHash field. Token constants and encodeTokenTransfer are not exported. The general output data field remains available for standard transactions.

Use qbitcoinAddress.toScriptHash(address, network) for a QBitcoin transaction output. address.toOutputScript rejects QBitcoin networks: a script hash cannot reconstruct the original script. When the public key is known, qbitcoinAddress.p2pkScript(publicKey) builds the P2PK script.

payments.p2qbitcoin supports 33/65-byte ECDSA public keys. An input alone provides its signature, but cannot provide a public key, address, hash, or output script. Supply a public key or output script when those fields are needed.

Development

Use Node.js 22 and npm with the committed lockfile:

npm ci
npm test
npm run lint:tests
npm run gitdiff:ci
npm run pack:check
npm run doc

TypeScript sources live in ts_src/. npm run build regenerates the committed CommonJS/ESM files and declarations in src/; edit the sources first. prepack also builds the package. Unit coverage measures all ESM implementation files. pack:check installs the actual npm archive with public runtime dependencies and checks CommonJS, ESM, subpath exports, and TypeScript consumers.

The lint commands account for two exact inherited diagnostics in src/esm/payments/bip341.js and test/payments.spec.ts. Other diagnostics still fail the check; the inherited source lines remain unchanged.

Bitcoin integration tests require a regtest service:

APIURL=http://127.0.0.1:8080/1 npm run integration

CI starts the pinned regtest image automatically. The optional external blockchain.info example is skipped unless RUN_EXTERNAL_TESTS=1 is set. TypeDoc builds in CI. Publishing documentation to GitHub Pages is a separate, manually started workflow and requires Pages to be configured in the repository.

Releases

The public repository is qbitcoin-project/bitcoinjs-lib. Release tags use bitcoinjs-lib-vX.Y.Z and must match the version in both package.json and package-lock.json. For 8.0.0 the tag is bitcoinjs-lib-v8.0.0.

CI publishes to npm only for a matching tag in that repository, after unit, coverage, lint, build, package, runtime, and regtest checks pass. Publication uses the checked npm archive, public access, and provenance. Configure the repository's NPM_TOKEN secret with permission to publish @qbtc/bitcoinjs-lib.

Only the cleaned main branch and selected release tags belong in the public repository. A private development remote can remain configured separately.

Upstream and license

The fork retains the upstream project history and MIT license. See LICENSE for attribution and CHANGELOG.md for the public fork release and retained upstream release notes. Bitcoin examples remain under test/integration/; the upstream documentation describes the original Bitcoin APIs.

Report fork-specific issues in the public issue tracker.