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).fromBigInt
Create from bigint.fromNumber
Create from number (must be integer).fromHex
Create from hex string (with or without 0x prefix).fromBytes
Create from byte array (big-endian, up to 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.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.modulo
Modulo operation.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
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:Related
- Uint256 - 256-bit unsigned integers
- Uint64 - 64-bit unsigned integers
- Keccak256 - 256-bit hash values
- Address - Ethereum addresses
Reference
API Reference
Complete API documentation
Examples
Usage examples and patterns

