Skip to main content

Try it Live

Run Uint examples in the interactive playground

Uint128

Uint128 is a 128-bit unsigned integer type optimized for large counters, cumulative values, and intermediate calculations that exceed 64-bit range.

Overview

Uint128 provides a bigint-based implementation for 128-bit unsigned integers with a comprehensive API for arithmetic, bitwise operations, and conversions. It follows Tevm’s branded type pattern for type safety.

Range

  • Minimum: 0n
  • Maximum: 340282366920938463463374607431768211455n (2^128 - 1)
  • Size: 16 bytes

Use Cases

  • Large counters and accumulators
  • Cumulative token amounts
  • Intermediate calculations in financial applications
  • State values requiring more than 64 bits
  • Cross-chain identifiers

Installation

Basic Usage

Constants

Constructors

from

Create Uint128 from bigint, number, or string (decimal or hex).
Throws: Error if value is negative or exceeds MAX.

fromBigInt

Create from bigint.

fromNumber

Create from number (must be integer).
Throws: Error if not an integer or out of range.

fromHex

Create from hex string (with or without 0x prefix).

fromBytes

Create from byte array (big-endian, up to 16 bytes).
Throws: Error if length exceeds 16 bytes.

fromAbiEncoded

Create from ABI-encoded bytes (32 bytes, right-aligned).

tryFrom

Try to create Uint128, returns null on failure.

Conversions

toBigInt

Convert to bigint.

toNumber

Convert to number.
Throws: Error if value exceeds Number.MAX_SAFE_INTEGER.

toHex

Convert to hex string with 0x prefix.

toBytes

Convert to 16-byte array (big-endian).

toAbiEncoded

Convert to 32-byte ABI-encoded value.

toString

Convert to decimal string.

Arithmetic

All arithmetic operations wrap on overflow/underflow.

plus

Add two values with wrapping.

minus

Subtract with wrapping.

times

Multiply with wrapping.

dividedBy

Integer division.
Throws: Error on division by zero.

modulo

Modulo operation.
Throws: Error on modulo by zero.

toPower

Exponentiation with wrapping.

Comparison

equals / notEquals

lessThan / lessThanOrEqual

greaterThan / greaterThanOrEqual

minimum / maximum

Get min/max of two values.

min / max

Get min/max from array.

Bitwise Operations

bitwiseAnd / bitwiseOr / bitwiseXor

bitwiseNot

shiftLeft / shiftRight

Shifts >= 128 bits return zero.

Utilities

isZero

Check if value is zero.

isValid

Check if value is valid Uint128 (0 to MAX).

bitLength

Get number of bits required to represent value.

leadingZeros

Get number of leading zero bits.

popCount

Count number of set bits (1s).

clone

Clone a value (no-op for bigint).

Aggregate Operations

sum

Sum array of values with wrapping.

product

Multiply array of values with wrapping.

Mathematical Functions

gcd

Calculate greatest common divisor.

lcm

Calculate least common multiple.

isPowerOf2

Check if value is a power of 2.

Examples

Large Counters

Token Amounts

Intermediate Calculations

Bitwise Flags

Performance Notes

  • Implementation: Pure bigint (no assembly optimization)
  • Operations: Arithmetic operations wrap using bitwise AND with MAX
  • Memory: 16-byte representation
  • Best for: Values exceeding 64-bit range but not requiring full 256 bits

Type Safety

Uint128 uses branded types to prevent mixing with other numeric types:

Reference

API Reference

Complete API documentation

Examples

Usage examples and patterns