> ## 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. # 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 ```typescript theme={null} 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 ```typescript theme={null} 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: ```typescript theme={null} 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 ```typescript theme={null} const value = Uint32.fromNumber(21000); // Gas limit ``` ### fromBigInt ```typescript theme={null} const value = Uint32.fromBigInt(12345678n); ``` ### fromHex ```typescript theme={null} const value = Uint32.fromHex("0xffffffff"); // MAX ``` ### fromBytes Create from Uint8Array (big-endian, up to 4 bytes): ```typescript theme={null} const bytes = new Uint8Array([0x01, 0x00, 0x00, 0x00]); const value = Uint32.fromBytes(bytes); // 16777216 ``` ### fromAbiEncoded Create from 32-byte ABI-encoded data: ```typescript theme={null} const encoded = new Uint8Array(32); encoded[31] = 100; const value = Uint32.fromAbiEncoded(encoded); // 100 ``` ### tryFrom Safe construction that returns undefined on invalid input: ```typescript theme={null} const valid = Uint32.tryFrom(100); // Uint32Type const invalid = Uint32.tryFrom(-1); // undefined const tooBig = Uint32.tryFrom(2**33); // undefined ``` ## Conversion ### toNumber ```typescript theme={null} const num = Uint32.toNumber(Uint32.from(100)); // 100 ``` ### toBigInt ```typescript theme={null} const bigint = Uint32.toBigInt(Uint32.from(100)); // 100n ``` ### toHex ```typescript theme={null} const hex = Uint32.toHex(Uint32.from(255)); // "0xff" ``` ### toBytes ```typescript theme={null} const bytes = Uint32.toBytes(Uint32.from(256)); // Uint8Array ``` ### toAbiEncoded ```typescript theme={null} const encoded = Uint32.toAbiEncoded(Uint32.from(100)); // 32-byte Uint8Array ``` ### toString ```typescript theme={null} const str = Uint32.toString(Uint32.from(255)); // "255" ``` ## Arithmetic ### plus ```typescript theme={null} const sum = Uint32.plus(Uint32.from(100), Uint32.from(50)); // 150 // Throws on overflow ``` ### minus ```typescript theme={null} const diff = Uint32.minus(Uint32.from(100), Uint32.from(50)); // 50 // Throws on underflow ``` ### times ```typescript theme={null} const product = Uint32.times(Uint32.from(1000), Uint32.from(1000)); // 1000000 // Throws on overflow ``` ### dividedBy ```typescript theme={null} const quotient = Uint32.dividedBy(Uint32.from(100), Uint32.from(7)); // 14 ``` ### modulo ```typescript theme={null} const remainder = Uint32.modulo(Uint32.from(100), Uint32.from(7)); // 2 ``` ### toPower ```typescript theme={null} const result = Uint32.toPower(Uint32.from(2), Uint32.from(10)); // 1024 ``` ## Comparison ### equals ```typescript theme={null} Uint32.equals(Uint32.from(100), Uint32.from(100)); // true ``` ### lessThan / greaterThan ```typescript theme={null} Uint32.lessThan(Uint32.from(50), Uint32.from(100)); // true Uint32.greaterThan(Uint32.from(100), Uint32.from(50)); // true ``` ### isZero ```typescript theme={null} Uint32.isZero(Uint32.from(0)); // true ``` ### minimum / maximum ```typescript theme={null} 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 ```typescript theme={null} 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 ```typescript theme={null} const not = Uint32.bitwiseNot(Uint32.from(0)); // 4294967295 (MAX) ``` ### shiftLeft / shiftRight ```typescript theme={null} const left = Uint32.shiftLeft(Uint32.from(1), 8); // 256 const right = Uint32.shiftRight(Uint32.from(256), 4); // 16 ``` ## Bit Analysis ### bitLength ```typescript theme={null} Uint32.bitLength(Uint32.from(0)); // 0 Uint32.bitLength(Uint32.from(255)); // 8 Uint32.bitLength(Uint32.from(256)); // 9 ``` ### leadingZeros ```typescript theme={null} Uint32.leadingZeros(Uint32.from(1)); // 31 Uint32.leadingZeros(Uint32.from(256)); // 23 ``` ### popCount ```typescript theme={null} Uint32.popCount(Uint32.from(0)); // 0 Uint32.popCount(Uint32.from(255)); // 8 Uint32.popCount(Uint32.from(0b10101010)); // 4 ``` ## Validation ### isValid ```typescript theme={null} 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 ```typescript theme={null} 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 ```typescript theme={null} 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` |