@cosmjs/math

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"

CosmJS

Concepts

Guides

API Reference

Uint32

Uint53

Int53

Uint64

Decimal

Static Methods

Instance Methods

Instance Properties

Usage

​Uint32

​Uint53

​Int53

​Uint64

​Decimal

​Static Methods

​Instance Methods

​Instance Properties

​Usage

Uint32

Uint53

Int53

Uint64

Decimal

Static Methods

Instance Methods

Instance Properties

Usage