Overview

Try it Live

Run Uint examples in the interactive playground

New to unsigned integers? Start with Fundamentals for guided examples and concepts.

Type Definition

Branded bigint representing unsigned 256-bit integer (0 to 2^256-1). Supports tree-shakeable namespace methods and class instances with automatic wrapping on overflow.

export type BrandedUint256 = bigint & {
  readonly __tag: "Uint256"
}

Quick Reference

Effect Schema

import { UintSchema } from '@tevm/voltaire/Uint/effect'
import * as Effect from 'effect/Effect'

// Schema-validated construction
const u = new UintSchema({ value: 123n })

// Effect composition
const program = Effect.gen(function* () {
  const x = yield* Effect.sync(() => UintSchema.from(123n))
  return x.toHex()
})

await Effect.runPromise(program)

API Methods

Constructors

from(value) - Universal constructor from bigint, number, or string
fromHex(hex) - Parse hex string (with or without 0x prefix)
fromBigInt(value) - Create from bigint with validation
fromNumber(value) - Create from number (throws if out of range)
fromBytes(bytes) - Parse from Uint8Array (big-endian)
fromAbiEncoded(bytes) - Parse ABI-encoded uint256
tryFrom(value) - Safe constructor returning undefined on error

Conversions

toHex(uint, padded?) - Convert to hex string with optional padding
toBigInt(uint) - Convert to bigint
toNumber(uint) - Convert to number (throws if > MAX_SAFE_INTEGER)
toBytes(uint) - Convert to Uint8Array (32 bytes, big-endian)
toAbiEncoded(uint) - Convert to ABI-encoded bytes
toString(uint, radix?) - Convert to string with optional radix (2-36)

Arithmetic

plus(a, b) - Addition with wrapping on overflow
minus(a, b) - Subtraction with wrapping on underflow
times(a, b) - Multiplication with wrapping on overflow
dividedBy(a, b) - Division (throws on divide by zero)
modulo(a, b) - Modulo operation
toPower(base, exponent) - Exponentiation with wrapping on overflow

Bitwise

bitwiseAnd(a, b) - Bitwise AND operation
bitwiseOr(a, b) - Bitwise OR operation
bitwiseXor(a, b) - Bitwise XOR operation
bitwiseNot(value) - Bitwise NOT (one’s complement)
shiftLeft(value, bits) - Left shift with wrapping
shiftRight(value, bits) - Right shift (logical)

Comparisons

equals(a, b) - Check equality
lessThan(a, b) - Check if a < b
greaterThan(a, b) - Check if a > b

Validation

isValid(value) - Check if value is valid uint256

Utilities

isZero(value) - Check if value is zero
minimum(a, b) - Return smaller of two values
maximum(a, b) - Return larger of two values
bitLength(value) - Count significant bits (1-256)
leadingZeros(value) - Count leading zero bits
popCount(value) - Count number of 1 bits

Types

class Uint
type BrandedUint256

class Uint {
  // Constructors
  constructor(value: bigint | number | string): BrandedUint256
  static from(value: bigint | number | string): BrandedUint256
  static fromHex(hex: string): BrandedUint256
  static fromBigInt(value: bigint): BrandedUint256
  static fromNumber(value: number | bigint): BrandedUint256
  static fromBytes(bytes: Uint8Array): BrandedUint256
  static fromAbiEncoded(bytes: Uint8Array): BrandedUint256
  static tryFrom(value: bigint | number | string): BrandedUint256 | undefined

  // Conversions
  toHex(padded?: boolean): string
  toBigInt(): bigint
  toNumber(): number
  toBytes(): Uint8Array
  toAbiEncoded(): Uint8Array
  toString(radix?: number): string

  // Arithmetic
  plus(other: BrandedUint256): BrandedUint256
  minus(other: BrandedUint256): BrandedUint256
  times(other: BrandedUint256): BrandedUint256
  dividedBy(other: BrandedUint256): BrandedUint256
  modulo(other: BrandedUint256): BrandedUint256
  toPower(exponent: BrandedUint256): BrandedUint256

  // Bitwise
  bitwiseAnd(other: BrandedUint256): BrandedUint256
  bitwiseOr(other: BrandedUint256): BrandedUint256
  bitwiseXor(other: BrandedUint256): BrandedUint256
  bitwiseNot(): BrandedUint256
  shiftLeft(bits: number): BrandedUint256
  shiftRight(bits: number): BrandedUint256

  // Comparisons
  equals(other: BrandedUint256): boolean
  notEquals(other: BrandedUint256): boolean
  lessThan(other: BrandedUint256): boolean
  lessThanOrEqual(other: BrandedUint256): boolean
  greaterThan(other: BrandedUint256): boolean
  greaterThanOrEqual(other: BrandedUint256): boolean

  // Utilities
  isZero(): boolean
  minimum(other: BrandedUint256): BrandedUint256
  maximum(other: BrandedUint256): BrandedUint256
  bitLength(): number
  leadingZeros(): number
  popCount(): number

  // Constants
  static MAX: BrandedUint256
  static MIN: BrandedUint256
  static ZERO: BrandedUint256
  static ONE: BrandedUint256
  static SIZE: number
}

Source: UintConstructor.ts:68-114

export type BrandedUint256 = bigint & {
  readonly __tag: "Uint256"
}

Branded type wrapping bigint, runtime validated to 0 <= value <= 2^256-1. Used as underlying type for Uint class and tree-shakeable functions.Source: BrandedUint256.ts:1-4

Constants

Uint module exports constants for validation and arithmetic:

import { Uint } from 'tevm'

// Boundary values
Uint.MAX   // 2^256 - 1 (largest Uint256)
Uint.MIN   // 0 (smallest Uint256)
Uint.ZERO  // 0
Uint.ONE   // 1

// Size constant
Uint.SIZE  // 32 (bytes)

// Usage examples
const maxValue = Uint.MAX
const isMax = value.equals(Uint.MAX)
const isZero = value.equals(Uint.ZERO)
const increment = value.plus(Uint.ONE)
const buffer = new Uint8Array(Uint.SIZE)  // 32-byte buffer

Available constants:

Uint.MAX = 2^256 - 1 - Maximum Uint256 value (115792089237316195423570985008687907853269984665640564039457584007913129639935n)
Uint.MIN = 0 - Minimum Uint256 value
Uint.ZERO = 0 - Zero constant
Uint.ONE = 1 - One constant
Uint.SIZE = 32 - Size in bytes

Source: constants.ts

Wrapping Arithmetic

All arithmetic wraps on overflow (mod 2^256), matching EVM behavior:

import { Uint } from 'tevm';

// Overflow wraps to 0
const max = Uint.MAX;
const overflow = max.plus(Uint.ONE);
console.log(overflow.equals(Uint.ZERO));  // true

// Underflow wraps to MAX
const underflow = Uint.ZERO.minus(Uint.ONE);
console.log(underflow.equals(Uint.MAX));  // true

See Fundamentals for overflow examples and Arithmetic for detailed operations.

Tree-Shaking

Import only what you need for optimal bundle size:

// Import specific functions (tree-shakeable)
import { fromHex, plus, toHex } from 'tevm/Uint';

const a = fromHex("0x64");
const b = fromHex("0x32");
const sum = plus(a, b);
const hex = toHex(sum);

// Only these 3 functions included in bundle

Fundamentals - Learn unsigned integers and EVM types
Hex - Hex string encoding and decoding
Keccak256 - Keccak256 hashing
Branded Types - Zero-overhead type branding pattern

Specification

Solidity Types - Unsigned integer documentation
EVM Opcodes - ADD, MUL, DIV, MOD, EXP operations
Ethereum Yellow Paper - Formal arithmetic specification (Section 9.1)

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Overview

Try it Live

Type Definition

Quick Reference

Effect Schema

API Methods

Constructors

Conversions

Arithmetic

Bitwise

Comparisons

Validation

Utilities

Types

Constants

Wrapping Arithmetic

Tree-Shaking

Specification

Try it Live

​Type Definition

​Quick Reference

​Effect Schema

​API Methods

​Constructors

​Conversions

​Arithmetic

​Bitwise

​Comparisons

​Validation

​Utilities

​Types

​Constants

​Wrapping Arithmetic

​Tree-Shaking

​Related

​Specification

Type Definition

Quick Reference

Effect Schema

API Methods

Constructors

Conversions

Arithmetic

Bitwise

Comparisons

Validation

Utilities

Types

Constants

Wrapping Arithmetic

Tree-Shaking

Related

Specification