BN.js: Arbitrary-Precision Big Numbers

5.2.3 · active · verified Sun Apr 19

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.

Common errors

Warnings

Install

Imports

Quickstart

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

view raw JSON →