BigNumber

Many operations in Hedera operate on numbers which are outside the range of safe values to use in JavaScript.

A BigNumber is an object which safely allows mathematical operations on numbers of any magnitude.

Most operations which need to return a value will return a BigNumber and parameters which accept values will generally accept them.

The BigNumber class is directly imported from the The Ethers Project. The complete documentation can be found in the official ethers docs.

Types

BigNumberish

Many functions and methods in this library take in values which can be non-ambiguously and safely converted to a BigNumber. These values can be specified as:

string - A HexString or a decimal string, either of which may be negative.

BytesLike - A BytesLike Object, such as an Array or Uint8Array.

BigNumber - An existing BigNumber instance.

number - A number that is within the safe range for JavaScript numbers.

BigInt - A JavaScript BigInt object, on environments that support BigInt.

Creating Instances

The constructor of BigNumber cannot be called directly. Instead, Use the static BigNumber.from.

hethers.BigNumber.from( aBigNumberish ) ⇒ BigNumber

Returns an instance of a BigNumber for aBigNumberish.

Examples:

// From a decimal string...
BigNumber.from("42")
// { BigNumber: "42" }

// From a HexString...
BigNumber.from("0x2a")
// { BigNumber: "42" }

// From a negative HexString...
BigNumber.from("-0x2a")
// { BigNumber: "-42" }

// From an Array (or Uint8Array)...
BigNumber.from([ 42 ])
// { BigNumber: "42" }

// From an existing BigNumber...
let one1 = constants.One;
let one2 = BigNumber.from(one1)

one2
// { BigNumber: "1" }

// ...which returns the same instance
one1 === one2
// true

// From a (safe) number...
BigNumber.from(42)
// { BigNumber: "42" }

// From a ES2015 BigInt... (only on platforms with BigInt support)
BigNumber.from(42n)
// { BigNumber: "42" }

// Numbers outside the safe range fail:
BigNumber.from(Number.MAX_SAFE_INTEGER);
// [Error: overflow] {
//   code: 'NUMERIC_FAULT',
//   fault: 'overflow',
//   operation: 'BigNumber.from',
//   reason: 'overflow',
//   value: 9007199254740991
// }

Methods

The BigNumber class is immutable, so no operations can change the value it represents.

Math Operations

BigNumber.add( otherValue ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber + otherValue.

BigNumber.sub( otherValue ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber - otherValue.

BigNumber.mul( otherValue ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber × otherValue.

BigNumber.div( divisor ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber ÷ divisor.

BigNumber.mod( divisor ) ⇒ BigNumber

Returns a BigNumber with the value of the remainder of BigNumber ÷ divisor.

BigNumber.pow( exponent ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber to the power of exponent.

BigNumber.abs( ) ⇒ BigNumber

Returns a BigNumber with the absolute value of BigNumber.

BigNumber.mask( bitcount ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber with bits beyond the bitcount least significant bits set to zero.

Two's Complement

Two's Complement is an elegant method used to encode and decode fixed-width signed values while efficiently preserving mathematical operations. Most users will not need to interact with these.

BigNumber.fromTwos( bitwidth ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber converted from twos-complement with bitwidth.

BigNumber.toTwos( bitwidth ) ⇒ BigNumber

Returns a BigNumber with the value of BigNumber converted to twos-complement with bitwidth.

Comparison and Equivalence

BigNumber.eq( otherValue ) ⇒ boolean

Returns true if and only if the value of BigNumber is equal to otherValue.

BigNumber.lt( otherValue ) ⇒ boolean

Returns true if and only if the value of BigNumber < otherValue.

BigNumber.lte( otherValue ) ⇒ boolean

Returns true if and only if the value of BigNumber ≤ otherValue.

BigNumber.gt( otherValue ) ⇒ boolean

Returns true if and only if the value of BigNumber > otherValue.

BigNumber.gte( otherValue ) ⇒ boolean

Returns true if and only if the value of BigNumber ≥ otherValue.

BigNumber.isZero( ) ⇒ boolean

Returns true if and only if the value of BigNumber is zero.

Conversion

BigNumber.toBigInt( ) ⇒ bigint

Returns the value of BigNumber as a JavaScript BigInt value, on platforms which support them.

BigNumber.toNumber( ) ⇒ number

Returns the value of BigNumber as a JavaScript value.

This will throw an error if the value is greater than or equal to Number.MAX_SAFE_INTEGER or less than or equal to Number.MIN_SAFE_INTEGER.

BigNumber.toString( ) ⇒ string

Returns the value of BigNumber as a base-10 string.

BigNumber.toHexString( ) ⇒ string<DataHexString>

Returns the value of BigNumber as a base-16, 0x-prefixed DataHexString.

Inspection

hethers.BigNumber.isBigNumber( object ) ⇒ boolean

Returns true if and only if the object is a BigNumber object.

Examples

let a = BigNumber.from(42);
let b = BigNumber.from("91");

a.mul(b);
// { BigNumber: "3822" }