Uint32

Type-safe 32-bit unsigned integer for block numbers, gas limits, and timestamps

Uint32

A branded type for 32-bit unsigned integers (0 to 4,294,967,295). Represented as JavaScript number with compile-time type safety.

Overview

Uint32Type provides:

• Compile-time type branding
• Range validation (0 to 2^32-1)
• Full arithmetic and bitwise operations
• Efficient number representation (fits in JavaScript safe integer range)

Type Definition

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

export type Uint32Type = number & { readonly [brand]: "Uint32" };

Range

• Minimum: 0
• Maximum: 4,294,967,295 (2^32 - 1)
• Size: 32 bits (4 bytes)

Constants

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

Uint32.MIN;   // 0
Uint32.MAX;   // 4294967295
Uint32.ZERO;  // 0
Uint32.ONE;   // 1
Uint32.SIZE;  // 4 (bytes)

Construction

from

Create from number, bigint, or string:

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

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

fromNumber

const value = Uint32.fromNumber(21000);  // Gas limit

fromBigInt

const value = Uint32.fromBigInt(12345678n);

fromHex

const value = Uint32.fromHex("0xffffffff");  // MAX

fromBytes

Create from Uint8Array (big-endian, up to 4 bytes):

const bytes = new Uint8Array([0x01, 0x00, 0x00, 0x00]);
const value = Uint32.fromBytes(bytes);  // 16777216

fromAbiEncoded

Create from 32-byte ABI-encoded data:

const encoded = new Uint8Array(32);
encoded[31] = 100;
const value = Uint32.fromAbiEncoded(encoded);  // 100

tryFrom

Safe construction that returns undefined on invalid input:

const valid = Uint32.tryFrom(100);      // Uint32Type
const invalid = Uint32.tryFrom(-1);     // undefined
const tooBig = Uint32.tryFrom(2**33);   // undefined

Conversion

toNumber

const num = Uint32.toNumber(Uint32.from(100));  // 100

toBigInt

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

toHex

const hex = Uint32.toHex(Uint32.from(255));  // "0xff"

toBytes

const bytes = Uint32.toBytes(Uint32.from(256));  // Uint8Array

toAbiEncoded

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

toString

const str = Uint32.toString(Uint32.from(255));  // "255"

Arithmetic

plus

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

minus

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

times

const product = Uint32.times(Uint32.from(1000), Uint32.from(1000));  // 1000000
// Throws on overflow

dividedBy

const quotient = Uint32.dividedBy(Uint32.from(100), Uint32.from(7));  // 14

modulo

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

toPower

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

Comparison

equals

Uint32.equals(Uint32.from(100), Uint32.from(100));  // true

lessThan / greaterThan

Uint32.lessThan(Uint32.from(50), Uint32.from(100));     // true
Uint32.greaterThan(Uint32.from(100), Uint32.from(50));  // true

isZero

Uint32.isZero(Uint32.from(0));  // true

minimum / maximum

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

Bitwise Operations

bitwiseAnd / bitwiseOr / bitwiseXor

const and = Uint32.bitwiseAnd(Uint32.from(0xff00), Uint32.from(0x0ff0));  // 0x0f00
const or = Uint32.bitwiseOr(Uint32.from(0xff00), Uint32.from(0x00ff));    // 0xffff
const xor = Uint32.bitwiseXor(Uint32.from(0xff00), Uint32.from(0xf0f0));  // 0x0ff0

bitwiseNot

const not = Uint32.bitwiseNot(Uint32.from(0));  // 4294967295 (MAX)

shiftLeft / shiftRight

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

Bit Analysis

bitLength

Uint32.bitLength(Uint32.from(0));    // 0
Uint32.bitLength(Uint32.from(255));  // 8
Uint32.bitLength(Uint32.from(256));  // 9

leadingZeros

Uint32.leadingZeros(Uint32.from(1));    // 31
Uint32.leadingZeros(Uint32.from(256));  // 23

popCount

Uint32.popCount(Uint32.from(0));           // 0
Uint32.popCount(Uint32.from(255));         // 8
Uint32.popCount(Uint32.from(0b10101010));  // 4

Validation

isValid

Uint32.isValid(100);         // true
Uint32.isValid(4294967295);  // true
Uint32.isValid(-1);          // false
Uint32.isValid(4294967296);  // false
Uint32.isValid(1.5);         // false

Use Cases

• Block numbers: Ethereum block numbers fit in 32 bits until ~year 2100
• Gas limits: Transaction and block gas limits
• Timestamps: Unix timestamps (valid until year 2106)
• Nonces: Transaction nonces
• Indices: Array indices, loop counters
• IP addresses: IPv4 addresses

Example: Block Number Operations

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

// Current block and confirmations
const currentBlock = Uint32.from(18500000);
const confirmations = Uint32.from(12);

// Calculate confirmed block
const confirmedBlock = Uint32.minus(currentBlock, confirmations);
console.log(Uint32.toNumber(confirmedBlock));  // 18499988

// Check if block is finalized (32+ confirmations)
const minConfirmations = Uint32.from(32);
const isFinalized = Uint32.greaterThan(confirmations, minConfirmations);

Example: Timestamp Handling

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

// Current Unix timestamp
const now = Uint32.from(Math.floor(Date.now() / 1000));

// Add 1 hour (3600 seconds)
const oneHour = Uint32.from(3600);
const future = Uint32.plus(now, oneHour);

// Check expiry
const expiry = Uint32.from(1735689600);  // Jan 1, 2025
const isExpired = Uint32.greaterThan(now, expiry);

API Reference

Category	Methods
Construction	from, fromNumber, fromBigInt, fromHex, fromBytes, fromAbiEncoded, tryFrom
Conversion	toNumber, toBigInt, toHex, toBytes, toAbiEncoded, toString, clone
Arithmetic	plus, minus, times, dividedBy, modulo, toPower
Comparison	equals, lessThan, greaterThan, isZero, minimum, maximum
Bitwise	bitwiseAnd, bitwiseOr, bitwiseXor, bitwiseNot, shiftLeft, shiftRight
Bit Analysis	bitLength, leadingZeros, popCount
Validation	isValid