> ## 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. # Uint64 > Type-safe 64-bit unsigned integer for large counters, timestamps, and nonces Run Uint examples in the interactive playground # Uint64 A branded type for 64-bit unsigned integers (0 to 18,446,744,073,709,551,615). Represented as JavaScript `bigint` to handle values beyond `Number.MAX_SAFE_INTEGER`. ## Overview `Uint64Type` provides: * Compile-time type branding * Range validation (0 to 2^64-1) * Full arithmetic and bitwise operations * Safe handling of large values via `bigint` ## Type Definition ```typescript theme={null} import type { brand } from '../../../brand.js'; export type Uint64Type = bigint & { readonly [brand]: "Uint64" }; ``` ## Range * **Minimum**: 0 * **Maximum**: 18,446,744,073,709,551,615 (2^64 - 1) * **Size**: 64 bits (8 bytes) ## Constants ```typescript theme={null} import * as Uint64 from '@voltaire/primitives/Uint64'; Uint64.MIN; // 0n Uint64.MAX; // 18446744073709551615n Uint64.ZERO; // 0n Uint64.ONE; // 1n Uint64.SIZE; // 8 (bytes) ``` ## Construction ### from Create from bigint, number, or string: ```typescript theme={null} import * as Uint64 from '@voltaire/primitives/Uint64'; const a = Uint64.from(100n); const b = Uint64.from(42); const c = Uint64.from("18446744073709551615"); const d = Uint64.from("0xffffffffffffffff"); ``` ### fromBigInt ```typescript theme={null} const value = Uint64.fromBigInt(1000000000000n); ``` ### fromNumber ```typescript theme={null} const value = Uint64.fromNumber(9007199254740991); // MAX_SAFE_INTEGER ``` ### fromHex ```typescript theme={null} const value = Uint64.fromHex("0xffffffffffffffff"); // MAX ``` ### fromBytes Create from Uint8Array (big-endian, up to 8 bytes): ```typescript theme={null} const bytes = new Uint8Array([0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00]); const value = Uint64.fromBytes(bytes); // 4294967296n ``` ### fromAbiEncoded Create from 32-byte ABI-encoded data: ```typescript theme={null} const encoded = new Uint8Array(32); encoded[31] = 100; const value = Uint64.fromAbiEncoded(encoded); // 100n ``` ### tryFrom Safe construction that returns undefined on invalid input: ```typescript theme={null} const valid = Uint64.tryFrom(100n); // Uint64Type const invalid = Uint64.tryFrom(-1n); // undefined ``` ## Conversion ### toBigInt ```typescript theme={null} const bigint = Uint64.toBigInt(Uint64.from(100n)); // 100n ``` ### toNumber ```typescript theme={null} const num = Uint64.toNumber(Uint64.from(100n)); // 100 // Throws if value > Number.MAX_SAFE_INTEGER ``` ### toHex ```typescript theme={null} const hex = Uint64.toHex(Uint64.from(255n)); // "0xff" ``` ### toBytes ```typescript theme={null} const bytes = Uint64.toBytes(Uint64.from(256n)); // Uint8Array ``` ### toAbiEncoded ```typescript theme={null} const encoded = Uint64.toAbiEncoded(Uint64.from(100n)); // 32-byte Uint8Array ``` ### toString ```typescript theme={null} const str = Uint64.toString(Uint64.from(18446744073709551615n)); // "18446744073709551615" ``` ## Arithmetic ### plus ```typescript theme={null} const sum = Uint64.plus(Uint64.from(100n), Uint64.from(50n)); // 150n // Throws on overflow ``` ### minus ```typescript theme={null} const diff = Uint64.minus(Uint64.from(100n), Uint64.from(50n)); // 50n // Throws on underflow ``` ### times ```typescript theme={null} const product = Uint64.times(Uint64.from(1000000n), Uint64.from(1000000n)); // 1000000000000n ``` ### dividedBy ```typescript theme={null} const quotient = Uint64.dividedBy(Uint64.from(100n), Uint64.from(7n)); // 14n ``` ### modulo ```typescript theme={null} const remainder = Uint64.modulo(Uint64.from(100n), Uint64.from(7n)); // 2n ``` ### toPower ```typescript theme={null} const result = Uint64.toPower(Uint64.from(2n), Uint64.from(32n)); // 4294967296n ``` ## Comparison ### equals ```typescript theme={null} Uint64.equals(Uint64.from(100n), Uint64.from(100n)); // true ``` ### lessThan / greaterThan ```typescript theme={null} Uint64.lessThan(Uint64.from(50n), Uint64.from(100n)); // true Uint64.greaterThan(Uint64.from(100n), Uint64.from(50n)); // true ``` ### isZero ```typescript theme={null} Uint64.isZero(Uint64.from(0n)); // true ``` ### minimum / maximum ```typescript theme={null} const min = Uint64.minimum(Uint64.from(100n), Uint64.from(50n)); // 50n const max = Uint64.maximum(Uint64.from(100n), Uint64.from(50n)); // 100n ``` ## Bitwise Operations ### bitwiseAnd / bitwiseOr / bitwiseXor ```typescript theme={null} const and = Uint64.bitwiseAnd(Uint64.from(0xff00n), Uint64.from(0x0ff0n)); const or = Uint64.bitwiseOr(Uint64.from(0xff00n), Uint64.from(0x00ffn)); const xor = Uint64.bitwiseXor(Uint64.from(0xff00n), Uint64.from(0xf0f0n)); ``` ### bitwiseNot ```typescript theme={null} const not = Uint64.bitwiseNot(Uint64.from(0n)); // MAX ``` ### shiftLeft / shiftRight ```typescript theme={null} const left = Uint64.shiftLeft(Uint64.from(1n), 32); // 4294967296n const right = Uint64.shiftRight(Uint64.from(4294967296n), 16); // 65536n ``` ## Bit Analysis ### bitLength ```typescript theme={null} Uint64.bitLength(Uint64.from(0n)); // 0 Uint64.bitLength(Uint64.from(255n)); // 8 Uint64.bitLength(Uint64.from(256n)); // 9 ``` ### leadingZeros ```typescript theme={null} Uint64.leadingZeros(Uint64.from(1n)); // 63 Uint64.leadingZeros(Uint64.from(256n)); // 55 ``` ### popCount ```typescript theme={null} Uint64.popCount(Uint64.from(0n)); // 0 Uint64.popCount(Uint64.from(255n)); // 8 Uint64.popCount(Uint64.from(0b10101010n)); // 4 ``` ## Validation ### isValid ```typescript theme={null} Uint64.isValid(100n); // true Uint64.isValid(18446744073709551615n); // true Uint64.isValid(-1n); // false Uint64.isValid(18446744073709551616n); // false ``` ## Use Cases * **Nanosecond timestamps**: High-precision timing * **File sizes**: Large file sizes in bytes * **Database IDs**: Auto-incrementing identifiers * **Counters**: Large event counters * **Cumulative gas**: Total gas across many transactions * **Token supply**: Tokens with high supply counts ## Example: High-Precision Timing ```typescript theme={null} import * as Uint64 from '@voltaire/primitives/Uint64'; // Nanosecond precision timestamp const nanos = Uint64.from(1735689600000000000n); // Jan 1, 2025 in nanoseconds // Convert to seconds const billion = Uint64.from(1000000000n); const seconds = Uint64.dividedBy(nanos, billion); // Calculate duration const startNanos = Uint64.from(1735689600000000000n); const endNanos = Uint64.from(1735689601500000000n); const durationNanos = Uint64.minus(endNanos, startNanos); // 1.5 billion nanoseconds ``` ## Example: Large File Handling ```typescript theme={null} import * as Uint64 from '@voltaire/primitives/Uint64'; // File size in bytes (10 TB) const fileSize = Uint64.from(10995116277760n); // Convert to human-readable const KB = Uint64.from(1024n); const MB = Uint64.times(KB, KB); const GB = Uint64.times(MB, KB); const TB = Uint64.times(GB, KB); const sizeInTB = Uint64.dividedBy(fileSize, TB); console.log(`${Uint64.toString(sizeInTB)} TB`); // "10 TB" ``` ## Why Uint64 Uses BigInt JavaScript's `Number` type can only safely represent integers up to 2^53-1 (9,007,199,254,740,991). Since Uint64's maximum value is 2^64-1, it requires `bigint` for accurate representation: ```typescript theme={null} // Number loses precision beyond MAX_SAFE_INTEGER const unsafe = 9007199254740993; // Actually stored as 9007199254740992 // BigInt maintains full precision const safe = 9007199254740993n; // Exactly 9007199254740993 ``` ## 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` |