Skip to main content

Try it Live

Run Uint256 examples in the interactive playground

​
Uint (Uint256)

A branded type for 256-bit unsigned integers - the native word size of the EVM. Represented as JavaScript bigint with compile-time type safety.

​
Overview

Uint256Type provides:
  • Compile-time type branding
  • Range validation (0 to 2^256-1)
  • Full arithmetic operations with overflow checking
  • Bitwise operations
  • Comparison operators
  • Conversion utilities

​
Type Definition

import type { brand } from '../../../brand.js';

export type Uint256Type = bigint & { readonly [brand]: "Uint256" };

​
Range

  • Minimum: 0
  • Maximum: 2^256 - 1 (115792089237316195423570985008687907853269984665640564039457584007913129639935)
  • Size: 256 bits (32 bytes)

​
Constants

import * as Uint from '@voltaire/primitives/Uint';

Uint.MIN;   // 0n
Uint.MAX;   // 2^256 - 1
Uint.ZERO;  // 0n
Uint.ONE;   // 1n
Uint.SIZE;  // 32 (bytes)

​
Construction

​
from

Create from bigint, number, or string: 
import * as Uint from '@voltaire/primitives/Uint';

const a = Uint.from(100n);
const b = Uint.from(255);
const c = Uint.from("0xff");
const d = Uint.from("12345");

​
fromBigInt

Create from bigint: 
const value = Uint.fromBigInt(1000000000000000000n);  // 1 ETH in wei

​
fromNumber

Create from number: 
const value = Uint.fromNumber(21000);  // Gas limit

​
fromHex

Create from hex string: 
const value = Uint.fromHex("0xde0b6b3a7640000");  // 1 ETH in wei

​
fromBytes

Create from Uint8Array (big-endian): 
const bytes = new Uint8Array([0x01, 0x00]);  // 256 in big-endian
const value = Uint.fromBytes(bytes);

​
fromAbiEncoded

Create from 32-byte ABI-encoded data: 
const encoded = new Uint8Array(32);
encoded[31] = 0x64;  // 100
const value = Uint.fromAbiEncoded(encoded);

​
tryFrom

Safe construction that returns undefined on invalid input: 
const valid = Uint.tryFrom(100n);    // Uint256Type
const invalid = Uint.tryFrom(-1n);   // undefined

​
Conversion

​
toBigInt

const bigint = Uint.toBigInt(Uint.from(100n));  // 100n

​
toNumber

const num = Uint.toNumber(Uint.from(100n));  // 100
// Throws if value > Number.MAX_SAFE_INTEGER

​
toHex

const hex = Uint.toHex(Uint.from(255n));           // "0xff"
const padded = Uint.toHex(Uint.from(255n), true);  // "0x00...00ff" (64 chars)

​
toBytes

const bytes = Uint.toBytes(Uint.from(256n));       // Minimal bytes
const fixed = Uint.toBytes(Uint.from(256n), 32);   // 32 bytes, zero-padded

​
toAbiEncoded

const encoded = Uint.toAbiEncoded(Uint.from(100n));  // 32-byte Uint8Array

​
toString

const decimal = Uint.toString(Uint.from(255n));      // "255"
const hex = Uint.toString(Uint.from(255n), 16);      // "ff"
const binary = Uint.toString(Uint.from(255n), 2);    // "11111111"

​
Arithmetic

All operations validate results stay within valid range.

​
plus

const sum = Uint.plus(Uint.from(100n), Uint.from(50n));  // 150n
// Throws on overflow

​
minus

const diff = Uint.minus(Uint.from(100n), Uint.from(50n));  // 50n
// Throws on underflow

​
times

const product = Uint.times(Uint.from(10n), Uint.from(5n));  // 50n
// Throws on overflow

​
dividedBy

const quotient = Uint.dividedBy(Uint.from(100n), Uint.from(7n));  // 14n (integer division)

​
modulo

const remainder = Uint.modulo(Uint.from(100n), Uint.from(7n));  // 2n

​
toPower

const result = Uint.toPower(Uint.from(2n), Uint.from(10n));  // 1024n

​
sum (variadic)

const total = Uint.sum(Uint.from(1n), Uint.from(2n), Uint.from(3n));  // 6n

​
product (variadic)

const result = Uint.product(Uint.from(2n), Uint.from(3n), Uint.from(4n));  // 24n

​
Comparison

​
equals / notEquals

Uint.equals(Uint.from(100n), Uint.from(100n));     // true
Uint.notEquals(Uint.from(100n), Uint.from(50n));   // true

​
lessThan / lessThanOrEqual

Uint.lessThan(Uint.from(50n), Uint.from(100n));         // true
Uint.lessThanOrEqual(Uint.from(100n), Uint.from(100n)); // true

​
greaterThan / greaterThanOrEqual

Uint.greaterThan(Uint.from(100n), Uint.from(50n));         // true
Uint.greaterThanOrEqual(Uint.from(100n), Uint.from(100n)); // true

​
isZero

Uint.isZero(Uint.from(0n));   // true
Uint.isZero(Uint.from(1n));   // false

​
minimum / maximum

const min = Uint.minimum(Uint.from(100n), Uint.from(50n));  // 50n
const max = Uint.maximum(Uint.from(100n), Uint.from(50n));  // 100n

​
min / max (variadic)

const smallest = Uint.min(Uint.from(5n), Uint.from(2n), Uint.from(8n));  // 2n
const largest = Uint.max(Uint.from(5n), Uint.from(2n), Uint.from(8n));   // 8n

​
Bitwise Operations

​
bitwiseAnd

const result = Uint.bitwiseAnd(
  Uint.from(0b11110000n),
  Uint.from(0b11001100n)
);  // 0b11000000n = 192n

​
bitwiseOr

const result = Uint.bitwiseOr(
  Uint.from(0b11110000n),
  Uint.from(0b00001111n)
);  // 0b11111111n = 255n

​
bitwiseXor

const result = Uint.bitwiseXor(
  Uint.from(0b11110000n),
  Uint.from(0b11001100n)
);  // 0b00111100n = 60n

​
bitwiseNot

const result = Uint.bitwiseNot(Uint.from(0n));
// MAX (all bits set)

​
shiftLeft / shiftRight

const left = Uint.shiftLeft(Uint.from(1n), Uint.from(8n));   // 256n
const right = Uint.shiftRight(Uint.from(256n), Uint.from(4n)); // 16n

​
Bit Analysis

​
bitLength

Number of bits needed to represent value: 
Uint.bitLength(Uint.from(0n));    // 0
Uint.bitLength(Uint.from(1n));    // 1
Uint.bitLength(Uint.from(255n));  // 8
Uint.bitLength(Uint.from(256n));  // 9

​
leadingZeros

Count leading zero bits: 
Uint.leadingZeros(Uint.from(1n));    // 255
Uint.leadingZeros(Uint.from(255n));  // 248

​
popCount

Count set bits (population count): 
Uint.popCount(Uint.from(0n));           // 0
Uint.popCount(Uint.from(255n));         // 8
Uint.popCount(Uint.from(0b10101010n));  // 4

​
isPowerOf2

Uint.isPowerOf2(Uint.from(1n));    // true
Uint.isPowerOf2(Uint.from(256n));  // true
Uint.isPowerOf2(Uint.from(255n));  // false

​
Number Theory

​
gcd

Greatest common divisor: 
const result = Uint.gcd(Uint.from(48n), Uint.from(18n));  // 6n

​
lcm

Least common multiple: 
const result = Uint.lcm(Uint.from(12n), Uint.from(18n));  // 36n

​
Validation

​
isValid

Uint.isValid(100n);   // true
Uint.isValid(0n);     // true
Uint.isValid(-1n);    // false
Uint.isValid(2n ** 256n);  // false

​
Use Cases

  • EVM stack values and memory words
  • Token amounts and balances
  • Storage slot values
  • Block numbers and timestamps
  • Gas calculations
  • Cryptographic operations

​
Example: Token Balance Calculation

import * as Uint from '@voltaire/primitives/Uint';

// Calculate token balance with 18 decimals
function formatTokenBalance(weiAmount: Uint.Uint256Type): string {
  const decimals = Uint.from(18n);
  const divisor = Uint.toPower(Uint.from(10n), decimals);

  const whole = Uint.dividedBy(weiAmount, divisor);
  const remainder = Uint.modulo(weiAmount, divisor);

  return `${Uint.toString(whole)}.${Uint.toString(remainder).padStart(18, '0')}`;
}

const balance = Uint.from("1500000000000000000000");  // 1500 tokens
console.log(formatTokenBalance(balance));  // "1500.000000000000000000"