Registry / serialization / bn.js
library5.2.3jsnpmunverified

bn.js is a fundamental pure JavaScript library providing a comprehensive implementation for arbitrary-precision integers, commonly referred to as "Big Numbers." It is currently at version 5.2.3 and maintains an active release cadence, frequently addressing bug fixes and minor improvements, as seen in recent updates like v5.2.1 and v5.2.0. A key design principle is its focus on integer arithmetic; it explicitly does not support decimal numbers, which is an important consideration for users. Differentiating features include support for in-place operations (e.g., `iadd`), unsigned operations (e.g., `umod`), and operations that take native JavaScript numbers as arguments (e.g., `addn`), allowing for performance optimizations and flexible usage patterns. It provides a wide array of utilities, arithmetic, and bitwise operations crucial for cryptographic applications, large financial calculations, and other domains requiring precision beyond standard JavaScript `Number` limits.

npm install bn.js
INSTALL
IMPORT
SIG · BN.JS
B
bn.js
serializationjavascriptv5.2.3
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.

BN
✓ const BN = require('bn.js');
✗ import BN from 'bn.js';
bn.js primarily ships as a CommonJS module. While modern bundlers or TypeScript with `esModuleInterop` enabled might allow `import BN from 'bn.js'`, the canonical way, especially in Node.js, is `require`. For TypeScript without `esModuleInterop`, `import * as BN from 'bn.js'` is often recommended.
BN.isBN
✓ const BN = require('bn.js'); const isBN = BN.isBN;
✗ import { isBN } from 'bn.js';
Static methods like `isBN` are properties of the main `BN` object, not named exports from the package root. The library exports `BN` as the module's default export.
Red
✓ const BN = require('bn.js'); const Red = BN.red('k256');
The `Red` context (for Montgomery reduction) is accessed via the `BN.red()` static method, passing a prime or a BN instance. This is not a direct import.

This quickstart demonstrates how to initialize `BN` objects from various bases and large strings, perform basic arithmetic and bitwise operations including in-place and unsigned variants, and convert `BN` instances to different output formats. It also shows how to check if an object is a `BN` instance.

const BN = require('bn.js'); // Initialize Big Numbers from various bases const hexValue = new BN('DEADBEEF', 16); const binValue = new BN('10101010101010101010', 2); // Decimal numbers can be large strings, exceeding standard JS Number limits const decValue = new BN('123456789012345678901234567890'); console.log('Initialized from Hex:', hexValue.toString(16)); console.log('Initialized from Binary:', binValue.toString(2)); console.log('Initialized from large Decimal String:', decValue.toString(10)); // Perform arithmetic operations let sum = hexValue.add(binValue); console.log('\nSum (hexValue + binValue) in decimal:', sum.toString(10)); let product = decValue.mul(new BN(2)); // Multiply by another BN instance console.log('Product (decValue * 2):', product.toString(10)); // Demonstrate in-place operation: `a.iadd(b)` modifies `a` let a = new BN('100', 10); let b = new BN('50', 10); a.iadd(b); console.log('In-place addition (a.iadd(b)), "a" is now:', a.toString(10)); // Should be 150 // Demonstrate unsigned modulo with negative numbers let negative = new BN('-10'); let modulo = new BN('3'); console.log('Signed modulo (-10 mod 3):', negative.mod(modulo).toString(10)); // Expected: -1 console.log('Unsigned modulo (-10 umod 3):', negative.umod(modulo).toString(10)); // Expected: 2 ((-10 % 3) + 3) // Convert to different formats (e.g., Buffer, Array) // Requires Node.js Buffer to be available in the environment for toBuffer try { const buffer = hexValue.toBuffer('be', 4); // Big-endian, 4 bytes padded console.log('Buffer representation of hexValue (hex string):', buffer.toString('hex')); } catch (e) { console.log('Buffer operations skipped (Buffer class might not be available in this environment).'); } // Check if an object is a BN.js instance console.log('\nIs hexValue a BN instance?', BN.isBN(hexValue)); console.log('Is a plain number a BN instance?', BN.isBN(123));
Debug
Known issues
breakingSince `v5.0.0`, the BN constructor enforces stricter input validation, specifically rejecting decimal numbers when passed as a string. It expects pure integer strings matching the specified base.
fix
Ensure all string inputs to the `BN` constructor represent integers without decimal points. For example, use `new BN('123', 10)` instead of `new BN('123.45', 10)` (which is not supported).
affects: >=5.0.0
deprecatedThe `.modn()` method was deprecated in `v5.0.0` and should no longer be used.
fix
Replace `.modn()` with `.mod()` or `.umod()`, ensuring the modulus argument is also a `BN` instance if it's not a small JavaScript Number (which can be used with `modn` like alternatives).
affects: >=5.0.0
gotchaBN.js is designed exclusively for integer arithmetic. It does not support decimal numbers or floating-point operations anywhere in the library.
fix
If decimal precision is required, consider using alternative libraries like `bignumber.js` or `decimal.js`. Ensure all inputs and operations are strictly integer-based when using BN.js.
affects: all
gotchaThe `.toNumber()` method can only safely convert `BN` instances to JavaScript `Number` primitives if their value fits within 53 bits (equivalent to `Number.MAX_SAFE_INTEGER`). Larger values will lose precision or result in incorrect numbers.
fix
For `BN` values exceeding 53 bits, use `.toString(10)` for full decimal representation, or `.toArray()`, `.toBuffer()` for byte representations. Avoid `.toNumber()` for cryptographic keys, hashes, or large financial amounts.
affects: all
gotchaThere were interoperability issues when mixing `bn.js` v4 and v5 instances, leading to potential unexpected behavior in shared codebases.
fix
Ensure all `bn.js` installations within a project are consistent at `v5.1.2` or later to avoid mixing major versions and their internal differences.
affects: 5.0.0 - 5.1.1
gotchaVersions prior to `v5.2.1` contained a serious bug in the `.toString(16)` method, potentially producing incorrect hexadecimal string representations.
fix
Upgrade to `bn.js@5.2.1` or newer to ensure correct hexadecimal string conversions. Verify critical output if upgrading is not immediately possible.
affects: <5.2.1
gotchaMethods with the `n` postfix (e.g., `iaddn`, `muln`) which accept a plain JavaScript `Number` argument, have an upper limit of `0x4000000` (67,108,864) for that argument. Providing a larger number will throw a `RangeError`.
fix
For JavaScript `Number` arguments exceeding `0x4000000`, convert the number into a `BN` instance first (e.g., `new BN(largeNum)`) and then use the corresponding method without the `n` suffix (e.g., `bnInstance.iadd(new BN(largeNum))`).
affects: all
Errors
Common errors & fixes
Error: not that many bits (or similar for invalid input)
Attempting to initialize a BN instance with a string containing non-integer parts (e.g., decimals) or characters invalid for the specified base, especially after v5.0.0's stricter validation.
fix
Ensure all string inputs to the `BN` constructor are pure integer representations matching the provided base (e.g., `new BN('10', 10)` is valid, `new BN('10.5', 10)` is not).
TypeError: BN.modn is not a function
Attempting to use the `.modn()` method, which was deprecated and removed in `v5.0.0`.
fix
Replace `bnInstance.modn(num)` with `bnInstance.mod(new BN(num))` or, for unsigned results, `bnInstance.umod(new BN(num))`. Alternatively, if `num` is a small JavaScript number, use `bnInstance.mod(new BN(num))` or `bnInstance.modn` alternatives for specific contexts if available in newer versions (refer to documentation).
RangeError: Number can only safely store up to 53 bits (or incorrect numerical output from toNumber())
Calling `.toNumber()` on a BN instance that holds an integer value greater than `Number.MAX_SAFE_INTEGER` (2^53 - 1), leading to precision loss or an incorrect result.
fix
For values larger than `Number.MAX_SAFE_INTEGER`, use `.toString(10)` to get the full decimal string representation. Other conversion methods like `.toArray()` or `.toBuffer()` can provide byte-level access without numeric precision limits.
RangeError: n must be less than 0x4000000
A JavaScript `Number` argument passed to an `n`-suffixed method (e.g., `iaddn`, `muln`) exceeds the maximum allowed value of `0x4000000` (67,108,864).
fix
For number arguments greater than `0x4000000`, convert the JavaScript `Number` into a `BN` instance first (e.g., `new BN(largeNum)`) and then use the corresponding method without the `n` suffix (e.g., `bnInstance.iadd(new BN(largeNum))`).
Upgrade
Version history
5.2.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
bn.js — npm install bn.js · libregistry