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"

Uint (Effect) - Effect.ts integration with Schema validation

Documentation Index

Try it Live

​Uint (Uint256)

​Overview

​Type Definition

​Range

​Constants

​Construction

​from

​fromBigInt

​fromNumber

​fromHex

​fromBytes

​fromAbiEncoded

​tryFrom

​Conversion

​toBigInt

​toNumber

​toHex

​toBytes

​toAbiEncoded

​toString

​Arithmetic

​plus

​minus

​times

​dividedBy

​modulo

​toPower

​sum (variadic)

​product (variadic)

​Comparison

​equals / notEquals

​lessThan / lessThanOrEqual

​greaterThan / greaterThanOrEqual

​isZero

​minimum / maximum

​min / max (variadic)

​Bitwise Operations

​bitwiseAnd

​bitwiseOr

​bitwiseXor

​bitwiseNot

​shiftLeft / shiftRight

​Bit Analysis

​bitLength

​leadingZeros

​popCount

​isPowerOf2

​Number Theory

​gcd

​lcm

​Validation

​isValid

​Use Cases

​Example: Token Balance Calculation

​Related