> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Uint (Uint256)

> Type-safe 256-bit unsigned integer with full arithmetic and bitwise operations

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/uint256.ts">
  Run Uint256 examples in the interactive playground
</Card>

# 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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
const value = Uint.fromBigInt(1000000000000000000n);  // 1 ETH in wei
```

### fromNumber

Create from number:

```typescript theme={null}
const value = Uint.fromNumber(21000);  // Gas limit
```

### fromHex

Create from hex string:

```typescript theme={null}
const value = Uint.fromHex("0xde0b6b3a7640000");  // 1 ETH in wei
```

### fromBytes

Create from Uint8Array (big-endian):

```typescript theme={null}
const bytes = new Uint8Array([0x01, 0x00]);  // 256 in big-endian
const value = Uint.fromBytes(bytes);
```

### fromAbiEncoded

Create from 32-byte ABI-encoded data:

```typescript theme={null}
const encoded = new Uint8Array(32);
encoded[31] = 0x64;  // 100
const value = Uint.fromAbiEncoded(encoded);
```

### tryFrom

Safe construction that returns undefined on invalid input:

```typescript theme={null}
const valid = Uint.tryFrom(100n);    // Uint256Type
const invalid = Uint.tryFrom(-1n);   // undefined
```

## Conversion

### toBigInt

```typescript theme={null}
const bigint = Uint.toBigInt(Uint.from(100n));  // 100n
```

### toNumber

```typescript theme={null}
const num = Uint.toNumber(Uint.from(100n));  // 100
// Throws if value > Number.MAX_SAFE_INTEGER
```

### toHex

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

### toBytes

```typescript theme={null}
const bytes = Uint.toBytes(Uint.from(256n));       // Minimal bytes
const fixed = Uint.toBytes(Uint.from(256n), 32);   // 32 bytes, zero-padded
```

### toAbiEncoded

```typescript theme={null}
const encoded = Uint.toAbiEncoded(Uint.from(100n));  // 32-byte Uint8Array
```

### toString

```typescript theme={null}
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

```typescript theme={null}
const sum = Uint.plus(Uint.from(100n), Uint.from(50n));  // 150n
// Throws on overflow
```

### minus

```typescript theme={null}
const diff = Uint.minus(Uint.from(100n), Uint.from(50n));  // 50n
// Throws on underflow
```

### times

```typescript theme={null}
const product = Uint.times(Uint.from(10n), Uint.from(5n));  // 50n
// Throws on overflow
```

### dividedBy

```typescript theme={null}
const quotient = Uint.dividedBy(Uint.from(100n), Uint.from(7n));  // 14n (integer division)
```

### modulo

```typescript theme={null}
const remainder = Uint.modulo(Uint.from(100n), Uint.from(7n));  // 2n
```

### toPower

```typescript theme={null}
const result = Uint.toPower(Uint.from(2n), Uint.from(10n));  // 1024n
```

### sum (variadic)

```typescript theme={null}
const total = Uint.sum(Uint.from(1n), Uint.from(2n), Uint.from(3n));  // 6n
```

### product (variadic)

```typescript theme={null}
const result = Uint.product(Uint.from(2n), Uint.from(3n), Uint.from(4n));  // 24n
```

## Comparison

### equals / notEquals

```typescript theme={null}
Uint.equals(Uint.from(100n), Uint.from(100n));     // true
Uint.notEquals(Uint.from(100n), Uint.from(50n));   // true
```

### lessThan / lessThanOrEqual

```typescript theme={null}
Uint.lessThan(Uint.from(50n), Uint.from(100n));         // true
Uint.lessThanOrEqual(Uint.from(100n), Uint.from(100n)); // true
```

### greaterThan / greaterThanOrEqual

```typescript theme={null}
Uint.greaterThan(Uint.from(100n), Uint.from(50n));         // true
Uint.greaterThanOrEqual(Uint.from(100n), Uint.from(100n)); // true
```

### isZero

```typescript theme={null}
Uint.isZero(Uint.from(0n));   // true
Uint.isZero(Uint.from(1n));   // false
```

### minimum / maximum

```typescript theme={null}
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)

```typescript theme={null}
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

```typescript theme={null}
const result = Uint.bitwiseAnd(
  Uint.from(0b11110000n),
  Uint.from(0b11001100n)
);  // 0b11000000n = 192n
```

### bitwiseOr

```typescript theme={null}
const result = Uint.bitwiseOr(
  Uint.from(0b11110000n),
  Uint.from(0b00001111n)
);  // 0b11111111n = 255n
```

### bitwiseXor

```typescript theme={null}
const result = Uint.bitwiseXor(
  Uint.from(0b11110000n),
  Uint.from(0b11001100n)
);  // 0b00111100n = 60n
```

### bitwiseNot

```typescript theme={null}
const result = Uint.bitwiseNot(Uint.from(0n));
// MAX (all bits set)
```

### shiftLeft / shiftRight

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
Uint.leadingZeros(Uint.from(1n));    // 255
Uint.leadingZeros(Uint.from(255n));  // 248
```

### popCount

Count set bits (population count):

```typescript theme={null}
Uint.popCount(Uint.from(0n));           // 0
Uint.popCount(Uint.from(255n));         // 8
Uint.popCount(Uint.from(0b10101010n));  // 4
```

### isPowerOf2

```typescript theme={null}
Uint.isPowerOf2(Uint.from(1n));    // true
Uint.isPowerOf2(Uint.from(256n));  // true
Uint.isPowerOf2(Uint.from(255n));  // false
```

## Number Theory

### gcd

Greatest common divisor:

```typescript theme={null}
const result = Uint.gcd(Uint.from(48n), Uint.from(18n));  // 6n
```

### lcm

Least common multiple:

```typescript theme={null}
const result = Uint.lcm(Uint.from(12n), Uint.from(18n));  // 36n
```

## Validation

### isValid

```typescript theme={null}
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

```typescript theme={null}
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"
```

## Related

* [Uint (Effect)](https://voltaire-effect.tevm.sh/primitives/uint) - Effect.ts integration with Schema validation