Uint Fundamentals

Try it Live

Run Uint examples in the interactive playground

Conceptual Guide - For API reference and method documentation, see Uint API.

Unsigned integers are non-negative whole numbers used throughout Ethereum for amounts, balances, timestamps, and more. This guide teaches uint fundamentals using Tevm.

What Are Unsigned Integers?

An unsigned integer is a whole number (0, 1, 2, 3, …) with no negative values. The EVM uses unsigned integers for:

Token amounts and balances
Gas prices and limits
Block numbers and timestamps
Nonces and counters
Storage slot indices

EVM Integer Types

The EVM supports unsigned integers from 8 to 256 bits in 8-bit increments:

import { Uint } from 'tevm';

// Tevm provides uint256 (256-bit) by default
const value = Uint(100n);  // uint256

// Other sizes require masking:
// uint8:   0 to 2^8-1   (255)
// uint16:  0 to 2^16-1  (65535)
// uint32:  0 to 2^32-1  (4294967295)
// uint64:  0 to 2^64-1  (18446744073709551615)
// uint128: 0 to 2^128-1 (340282366920938463463374607431768211455)
// uint256: 0 to 2^256-1 (largest - 115792089237316195423570985008687907853269984665640564039457584007913129639935)

Why uint256?

Most Ethereum operations use uint256 (32 bytes) because:

EVM stack operates on 256-bit words
Efficient for large numbers (token amounts, wei)
Storage slots are 32 bytes
Cryptographic operations use 256-bit values

Creating Uints

From Bigint
From Hex
From Number
From Bytes

import { Uint } from 'tevm';

// Direct construction (recommended for known values)
const amount = Uint(1000000000000000000n);  // 1 ETH in wei
const small = Uint(42n);
const zero = Uint.ZERO;  // Constant for 0
const one = Uint.ONE;    // Constant for 1

// Constructor (same as from)
const value = Uint(100n);

import { Uint } from 'tevm';

// Parse hex strings
const fromHex = Uint("0xff");         // 255
const padded = Uint("0x00000064");    // 100
const large = Uint("0x" + "ff".repeat(32));  // MAX

// Hex strings can be padded or unpadded
const a = Uint("0x1");
const b = Uint("0x0001");
console.log(a.equals(b));  // true

import { Uint } from 'tevm';

// From JavaScript numbers (safe up to Number.MAX_SAFE_INTEGER)
const count = Uint(42);
const timestamp = Uint(Date.now());

// WARNING: JavaScript numbers lose precision above 2^53-1
const safe = Uint(Number.MAX_SAFE_INTEGER);      // ✅ Safe
// const unsafe = Uint(1e20);                    // ❌ Precision loss

// Use bigint for large values
const large = Uint(10n ** 20n);  // ✅ Correct

import { Uint } from 'tevm';

// From Uint8Array (32 bytes, big-endian)
const bytes = Bytes32();
bytes[31] = 0xff;  // Last byte = 255
const value = Uint(bytes);

// ABI-encoded format (same as bytes for uint256)
const abiEncoded = Bytes32();
const decoded = Uint(abiEncoded);

Big-Endian Encoding

The EVM stores unsigned integers in big-endian format: most significant byte first.

import { Uint } from 'tevm';

// Example: 255 (0xff) in big-endian
const value = Uint(255n);
const bytes = value.toBytes();

console.log(bytes.length);  // 32 bytes
console.log(bytes[0]);      // 0 (most significant)
console.log(bytes[31]);     // 255 (least significant)

// Hex representation shows big-endian
console.log(value.toHex());
// "0x00000000000000000000000000000000000000000000000000000000000000ff"
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ zeros
//                                                                    ^^ value

This matches EVM memory/storage layout and ABI encoding.

Arithmetic Operations

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

Basic Arithmetic
Overflow Wrapping
Safe Arithmetic

import { Uint } from 'tevm';

const a = Uint(100n);
const b = Uint(50n);

// Addition
const sum = a.plus(b);                    // 150
console.log(sum.toBigInt());              // 150n

// Subtraction
const diff = a.minus(b);                  // 50
console.log(diff.toBigInt());             // 50n

// Multiplication
const product = a.times(b);               // 5000
console.log(product.toBigInt());          // 5000n

// Division (throws on divide by zero)
const quotient = a.dividedBy(b);          // 2
console.log(quotient.toBigInt());         // 2n

// Modulo
const remainder = a.modulo(b);            // 0
console.log(remainder.toBigInt());        // 0n

// Exponentiation
const power = Uint(2n).toPower(Uint(8n));  // 256
console.log(power.toBigInt());            // 256n

import { Uint } from 'tevm';

// Addition overflow wraps around
const max = Uint.MAX;  // 2^256 - 1
const overflow = max.plus(Uint.ONE);
console.log(overflow.equals(Uint.ZERO));  // true (wraps to 0)

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

// Multiplication overflow
const large = Uint(2n ** 200n);
const product = large.times(large);  // Result is (2^400 mod 2^256)
console.log(product.lessThan(Uint.MAX));  // true (wrapped)

// This matches Solidity unchecked arithmetic

import { Uint } from 'tevm';

// Check before operations to avoid wrapping
function safeAdd(a: Uint, b: Uint): Uint | null {
  // Check if a + b > MAX
  const remaining = Uint.MAX.minus(a);
  if (b.greaterThan(remaining)) {
    return null;  // Would overflow
  }
  return a.plus(b);
}

const a = Uint.MAX.minus(Uint(10n));
const b = Uint(20n);

const result = safeAdd(a, b);
console.log(result === null);  // true (would overflow)

// Solidity equivalent: SafeMath library (pre-0.8.0)
// Solidity 0.8.0+ reverts on overflow by default

Comparisons

Equality
Ordering
Sorting

import { Uint } from 'tevm';

const a = Uint(100n);
const b = Uint(100n);
const c = Uint(200n);

// Equality
console.log(a.equals(b));         // true
console.log(a.notEquals(c));      // true

// Special checks
console.log(Uint.ZERO.isZero());  // true
console.log(a.isZero());          // false

import { Uint } from 'tevm';

const a = Uint(100n);
const b = Uint(200n);

// Less than
console.log(a.lessThan(b));           // true
console.log(a.lessThanOrEqual(b));    // true
console.log(a.lessThanOrEqual(a));    // true

// Greater than
console.log(b.greaterThan(a));        // true
console.log(b.greaterThanOrEqual(a)); // true
console.log(b.greaterThanOrEqual(b)); // true

import { Uint } from 'tevm';

// Sort array of uints
const values = [
  Uint(300n),
  Uint(100n),
  Uint(200n),
];

values.sort((a, b) => {
  if (a.lessThan(b)) return -1;
  if (a.greaterThan(b)) return 1;
  return 0;
});

console.log(values.map(v => v.toBigInt()));
// [100n, 200n, 300n]

Bitwise Operations

Logical Operations
Bit Shifts
Bit Manipulation

import { Uint } from 'tevm';

const a = Uint("0xff00");  // 0xff00
const b = Uint("0x00ff");  // 0x00ff

// Bitwise AND
const and = a.bitwiseAnd(b);
console.log(and.toHex(false));  // "0x0"

// Bitwise OR
const or = a.bitwiseOr(b);
console.log(or.toHex(false));   // "0xffff"

// Bitwise XOR
const xor = a.bitwiseXor(b);
console.log(xor.toHex(false));  // "0xffff"

// Bitwise NOT
const not = a.bitwiseNot();
console.log(not.toHex().slice(0, 10));  // "0x000000..." (inverted bits)

import { Uint } from 'tevm';

const value = Uint(1n);

// Left shift (multiply by powers of 2)
const shifted = value.shiftLeft(8);
console.log(shifted.toBigInt());  // 256n (2^8)

// Right shift (divide by powers of 2)
const original = shifted.shiftRight(8);
console.log(original.toBigInt());  // 1n

// Overflow wrapping on left shift
const large = Uint(2n ** 250n);
const overflow = large.shiftLeft(10);  // Wraps (keeps lower 256 bits)

import { Uint } from 'tevm';

const value = Uint("0xff00ff");

// Count bits
console.log(value.bitLength());    // Number of bits needed (24)
console.log(value.leadingZeros()); // Leading zero bits (232)
console.log(value.popCount());     // Number of 1 bits (16)

// Extract specific bits using masks
const mask = Uint("0xff");
const lowerByte = value.bitwiseAnd(mask);
console.log(lowerByte.toHex(false));  // "0xff"

Size Variants and Padding

While Tevm focuses on uint256, you can work with smaller sizes:

import { Uint } from 'tevm';

// Simulate uint8 (0-255)
function toUint8(value: Uint): Uint {
  const mask = Uint(0xFFn);
  return value.bitwiseAnd(mask);
}

// Simulate uint16 (0-65535)
function toUint16(value: Uint): Uint {
  const mask = Uint(0xFFFFn);
  return value.bitwiseAnd(mask);
}

// Usage
const large = Uint(1000n);
const u8 = toUint8(large);
console.log(u8.toBigInt());  // 232n (1000 mod 256)

const u16 = toUint16(large);
console.log(u16.toBigInt()); // 1000n (fits in uint16)

Common Use Cases

Token Amounts
Wei/Ether Conversions
Gas Calculations
Timestamps

import { Uint } from 'tevm';

// ERC20 token with 18 decimals
const tokenDecimals = 18n;
const amount = Uint(1000n * 10n ** tokenDecimals);  // 1000 tokens

// Convert to display value
function toDisplayValue(amount: Uint, decimals: bigint): string {
  const value = amount.toBigInt();
  const divisor = 10n ** decimals;
  const whole = value / divisor;
  const fraction = value % divisor;
  return `${whole}.${fraction.toString().padStart(Number(decimals), '0')}`;
}

console.log(toDisplayValue(amount, tokenDecimals));  // "1000.000000000000000000"

import { Uint } from 'tevm';

// 1 ether = 10^18 wei
const weiPerEther = 10n ** 18n;

// Convert ether to wei
function etherToWei(ether: bigint): Uint {
  return Uint(ether * weiPerEther);
}

// Convert wei to ether
function weiToEther(wei: Uint): bigint {
  return wei.toBigInt() / weiPerEther;
}

const twoEther = etherToWei(2n);
console.log(twoEther.toBigInt());  // 2000000000000000000n

const backToEther = weiToEther(twoEther);
console.log(backToEther);  // 2n

import { Uint } from 'tevm';

// Calculate transaction cost
function calculateGasCost(gasLimit: Uint, gasPrice: Uint): Uint {
  return gasLimit.times(gasPrice);
}

const gasLimit = Uint(21000n);     // Standard transfer
const gasPrice = Uint(50n * 10n ** 9n);  // 50 gwei

const cost = calculateGasCost(gasLimit, gasPrice);
console.log(cost.toBigInt());  // 1050000000000000n (0.00105 ETH)

// Check if wallet has enough balance
function canAfford(balance: Uint, cost: Uint): boolean {
  return balance.greaterThanOrEqual(cost);
}

const balance = Uint(10n ** 18n);  // 1 ETH
console.log(canAfford(balance, cost));  // true

import { Uint } from 'tevm';

// Block timestamps (Unix time in seconds)
const now = Uint(Math.floor(Date.now() / 1000));

// Check if timestamp is in future
function isFuture(timestamp: Uint): boolean {
  const currentTime = Uint(Math.floor(Date.now() / 1000));
  return timestamp.greaterThan(currentTime);
}

// Add duration (e.g., 1 day)
const oneDay = Uint(86400n);  // 60 * 60 * 24
const tomorrow = now.plus(oneDay);

console.log(isFuture(tomorrow));  // true

JavaScript Number Limitations

CRITICAL: JavaScript numbers are 64-bit floats, only precise up to 2^53-1 (9,007,199,254,740,991).

import { Uint } from 'tevm';

// ❌ WRONG: Precision loss with large numbers
const wrong = Uint(1e20);
console.log(wrong.toBigInt());  // Incorrect value (precision lost)

// ✅ CORRECT: Use bigint for large values
const correct = Uint(10n ** 20n);
console.log(correct.toBigInt());  // Exact value

// Safe conversions
const safeNumber = Uint(1000n).toNumber();  // 1000 (safe)

// Throws if exceeds safe integer range
try {
  const large = Uint(2n ** 100n);
  large.toNumber();  // Throws: value exceeds Number.MAX_SAFE_INTEGER
} catch (e) {
  console.error('Value too large for JavaScript number');
}

// Always use toBigInt() for large values
const large = Uint(2n ** 100n);
const bigint = large.toBigInt();  // Safe

Conversions

To Hex
To Number/BigInt
To Bytes
To String

import { Uint } from 'tevm';

const value = Uint(100n);

// Padded (32 bytes, 64 hex chars + 0x prefix)
console.log(value.toHex());
// "0x0000000000000000000000000000000000000000000000000000000000000064"

// Unpadded (minimal hex)
console.log(value.toHex(false));
// "0x64"

// Always includes 0x prefix

import { Uint } from 'tevm';

const value = Uint(42n);

// To bigint (always safe)
console.log(value.toBigInt());  // 42n

// To number (throws if too large)
console.log(value.toNumber());  // 42

// Check if safe first
const large = Uint(2n ** 100n);
try {
  large.toNumber();
} catch (e) {
  console.log('Use toBigInt() instead');
}

import { Uint } from 'tevm';

const value = Uint(255n);

// To Uint8Array (32 bytes, big-endian)
const bytes = value.toBytes();
console.log(bytes.length);  // 32
console.log(bytes[31]);     // 255 (least significant)

// ABI encoding (same as toBytes for uint256)
const abiEncoded = value.toAbiEncoded();
console.log(abiEncoded.length);  // 32

import { Uint } from 'tevm';

const value = Uint(255n);

// Decimal (default)
console.log(value.toString());     // "255"
console.log(value.toString(10));   // "255"

// Hexadecimal (without 0x prefix)
console.log(value.toString(16));   // "ff"

// Binary
console.log(value.toString(2));    // "11111111"

// Octal
console.log(value.toString(8));    // "377"

Resources

Solidity Types - Solidity unsigned integer documentation
EVM Integer Opcodes - ADD, MUL, DIV, MOD, EXP, etc.
Ethereum Yellow Paper - Formal arithmetic specifications (Section 9.1)
MDN BigInt - JavaScript BigInt reference

Next Steps

Overview - Type definition and API reference
Arithmetic - Detailed arithmetic operations
Bitwise - Bitwise operations and bit manipulation
Comparisons - Equality and ordering
Conversions - Format conversions

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Uint Fundamentals

Try it Live

What Are Unsigned Integers?

EVM Integer Types

Why uint256?

Creating Uints

Big-Endian Encoding

Arithmetic Operations

Comparisons

Bitwise Operations

Size Variants and Padding

Common Use Cases

JavaScript Number Limitations

Conversions

Resources

Next Steps

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Try it Live

​What Are Unsigned Integers?

​EVM Integer Types

​Why uint256?

​Creating Uints

​Big-Endian Encoding

​Arithmetic Operations

​Comparisons

​Bitwise Operations

​Size Variants and Padding

​Common Use Cases

​JavaScript Number Limitations

​Conversions

​Resources

​Next Steps

What Are Unsigned Integers?

EVM Integer Types

Why uint256?

Creating Uints

Big-Endian Encoding

Arithmetic Operations

Comparisons

Bitwise Operations

Size Variants and Padding

Common Use Cases

JavaScript Number Limitations

Conversions

Resources

Next Steps