@cosmjs/math

Safe integer and decimal arithmetic

Provides safe integer types and arbitrary-precision decimal arithmetic to prevent JavaScript number precision issues when handling token amounts.

npm install @cosmjs/math

Uint32

32-bit unsigned integer. Range: 0 to 4,294,967,295.

Method	Parameters	Returns
constructor	input: number	Uint32
fromString (static)	str: string	Uint32
fromBytes (static)	bytes: ArrayLike<number>, endianness?: "be" | "le" (default "be")	Uint32
toBytesBigEndian	—	Uint8Array
toBytesLittleEndian	—	Uint8Array
toNumber	—	number
toString	—	string
toBigInt	—	bigint

Uint53

53-bit unsigned integer (JavaScript safe integer range). Range: 0 to 9,007,199,254,740,991.

Method	Parameters	Returns
constructor	input: number	Uint53
fromString (static)	str: string	Uint53
toNumber	—	number
toString	—	string
toBigInt	—	bigint

Int53

53-bit signed integer. Range: -9,007,199,254,740,991 to 9,007,199,254,740,991.

Method	Parameters	Returns
constructor	input: number	Int53
fromString (static)	str: string	Int53
toNumber	—	number
toString	—	string
toBigInt	—	bigint

Uint64

64-bit unsigned integer. Uses bigint internal representation for values beyond JavaScript’s safe integer range.

Method	Parameters	Returns
fromString (static)	str: string	Uint64
fromNumber (static)	input: number (must be a safe integer)	Uint64
fromBytes (static)	bytes: ArrayLike<number>, endianness?: "be" | "le" (default "be")	Uint64
toBytesBigEndian	—	Uint8Array
toBytesLittleEndian	—	Uint8Array
toNumber	—	number
toString	—	string
toBigInt	—	bigint

import { Uint64 } from "@cosmjs/math";

const large = Uint64.fromString("9007199254740993");
large.toString(); // "9007199254740993"

Decimal

Arbitrary-precision decimal type for safe financial calculations. Internally stores values as integer atomics with a fixed fractional digit count.

Static Methods

Method	Parameters	Returns
fromAtomics	atomics: string | bigint, fractionalDigits: number	Decimal
fromUserInput	input: string, fractionalDigits: number	Decimal
zero	fractionalDigits: number	Decimal
one	fractionalDigits: number	Decimal
compare	a: Decimal, b: Decimal	number (< 0 if a < b, > 0 if a > b, 0 if equal)

Instance Methods

Method	Parameters	Returns
plus	other: Decimal	Decimal
minus	other: Decimal	Decimal
multiply	b: Uint32 | Uint53 | Uint64	Decimal
floor	—	Decimal
ceil	—	Decimal
neg	—	Decimal
abs	—	Decimal
isNegative	—	boolean
adjustFractionalDigits	newFractionalDigits: number	Decimal
equals	other: Decimal	boolean
isLessThan	other: Decimal	boolean
isLessThanOrEqual	other: Decimal	boolean
isGreaterThan	other: Decimal	boolean
isGreaterThanOrEqual	other: Decimal	boolean
toString	—	string
toFloatApproximation	—	number

Instance Properties

Property	Type	Description
atomics	string	Value in smallest unit
fractionalDigits	number	Number of decimal places

Usage

import { Decimal, Uint32 } from "@cosmjs/math";

const amount = Decimal.fromAtomics("1000000", 6);
amount.toString(); // "1"
amount.atomics;    // "1000000"

const fee = Decimal.fromAtomics("5000", 6);
const total = amount.plus(fee);
total.toString(); // "1.005"
total.atomics;    // "1005000"

const quantity = new Uint32(3);
const cost = amount.multiply(quantity);
cost.toString(); // "3"