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.
Try it Live 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 import type { brand } from '../../../brand.js' ; export type Uint64Type = bigint & { readonly [ brand ] : "Uint64" };
Range
Minimum : 0Maximum : 18,446,744,073,709,551,615 (2^64 - 1)Size : 64 bits (8 bytes)
Constants 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:
import * as Uint64 from '@voltaire/primitives/Uint64' ; const a = Uint64 . from ( 100 n ); const b = Uint64 . from ( 42 ); const c = Uint64 . from ( "18446744073709551615" ); const d = Uint64 . from ( "0xffffffffffffffff" );
fromBigInt const value = Uint64 . fromBigInt ( 1000000000000 n );
fromNumber const value = Uint64 . fromNumber ( 9007199254740991 ); // MAX_SAFE_INTEGER
fromHex const value = Uint64 . fromHex ( "0xffffffffffffffff" ); // MAX
fromBytes Create from Uint8Array (big-endian, up to 8 bytes):
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:
const encoded = new Uint8Array ( 32 ); encoded [ 31 ] = 100 ; const value = Uint64 . fromAbiEncoded ( encoded ); // 100n
tryFrom Safe construction that returns undefined on invalid input:
const valid = Uint64 . tryFrom ( 100 n ); // Uint64Type const invalid = Uint64 . tryFrom ( - 1 n ); // undefined
Conversion toBigInt const bigint = Uint64 . toBigInt ( Uint64 . from ( 100 n )); // 100n
toNumber const num = Uint64 . toNumber ( Uint64 . from ( 100 n )); // 100 // Throws if value > Number.MAX_SAFE_INTEGER
toHex const hex = Uint64 . toHex ( Uint64 . from ( 255 n )); // "0xff"
toBytes const bytes = Uint64 . toBytes ( Uint64 . from ( 256 n )); // Uint8Array
toAbiEncoded const encoded = Uint64 . toAbiEncoded ( Uint64 . from ( 100 n )); // 32-byte Uint8Array
toString const str = Uint64 . toString ( Uint64 . from ( 18446744073709551615 n )); // "18446744073709551615"
Arithmetic plus const sum = Uint64 . plus ( Uint64 . from ( 100 n ), Uint64 . from ( 50 n )); // 150n // Throws on overflow
minus const diff = Uint64 . minus ( Uint64 . from ( 100 n ), Uint64 . from ( 50 n )); // 50n // Throws on underflow
times const product = Uint64 . times ( Uint64 . from ( 1000000 n ), Uint64 . from ( 1000000 n )); // 1000000000000n
dividedBy const quotient = Uint64 . dividedBy ( Uint64 . from ( 100 n ), Uint64 . from ( 7 n )); // 14n
modulo const remainder = Uint64 . modulo ( Uint64 . from ( 100 n ), Uint64 . from ( 7 n )); // 2n
toPower const result = Uint64 . toPower ( Uint64 . from ( 2 n ), Uint64 . from ( 32 n )); // 4294967296n
Comparison equals Uint64 . equals ( Uint64 . from ( 100 n ), Uint64 . from ( 100 n )); // true
lessThan / greaterThan Uint64 . lessThan ( Uint64 . from ( 50 n ), Uint64 . from ( 100 n )); // true Uint64 . greaterThan ( Uint64 . from ( 100 n ), Uint64 . from ( 50 n )); // true
isZero Uint64 . isZero ( Uint64 . from ( 0 n )); // true
minimum / maximum const min = Uint64 . minimum ( Uint64 . from ( 100 n ), Uint64 . from ( 50 n )); // 50n const max = Uint64 . maximum ( Uint64 . from ( 100 n ), Uint64 . from ( 50 n )); // 100n
Bitwise Operations bitwiseAnd / bitwiseOr / bitwiseXor const and = Uint64 . bitwiseAnd ( Uint64 . from ( 0xff00 n ), Uint64 . from ( 0x0ff0 n )); const or = Uint64 . bitwiseOr ( Uint64 . from ( 0xff00 n ), Uint64 . from ( 0x00ff n )); const xor = Uint64 . bitwiseXor ( Uint64 . from ( 0xff00 n ), Uint64 . from ( 0xf0f0 n ));
bitwiseNot const not = Uint64 . bitwiseNot ( Uint64 . from ( 0 n )); // MAX
shiftLeft / shiftRight const left = Uint64 . shiftLeft ( Uint64 . from ( 1 n ), 32 ); // 4294967296n const right = Uint64 . shiftRight ( Uint64 . from ( 4294967296 n ), 16 ); // 65536n
Bit Analysis bitLength Uint64 . bitLength ( Uint64 . from ( 0 n )); // 0 Uint64 . bitLength ( Uint64 . from ( 255 n )); // 8 Uint64 . bitLength ( Uint64 . from ( 256 n )); // 9
leadingZeros Uint64 . leadingZeros ( Uint64 . from ( 1 n )); // 63 Uint64 . leadingZeros ( Uint64 . from ( 256 n )); // 55
popCount Uint64 . popCount ( Uint64 . from ( 0 n )); // 0 Uint64 . popCount ( Uint64 . from ( 255 n )); // 8 Uint64 . popCount ( Uint64 . from ( 0b10101010 n )); // 4
Validation isValid Uint64 . isValid ( 100 n ); // true Uint64 . isValid ( 18446744073709551615 n ); // true Uint64 . isValid ( - 1 n ); // false Uint64 . isValid ( 18446744073709551616 n ); // false
Use Cases
Nanosecond timestamps : High-precision timingFile sizes : Large file sizes in bytesDatabase IDs : Auto-incrementing identifiersCounters : Large event countersCumulative gas : Total gas across many transactionsToken supply : Tokens with high supply counts
Example: High-Precision Timing import * as Uint64 from '@voltaire/primitives/Uint64' ; // Nanosecond precision timestamp const nanos = Uint64 . from ( 1735689600000000000 n ); // Jan 1, 2025 in nanoseconds // Convert to seconds const billion = Uint64 . from ( 1000000000 n ); const seconds = Uint64 . dividedBy ( nanos , billion ); // Calculate duration const startNanos = Uint64 . from ( 1735689600000000000 n ); const endNanos = Uint64 . from ( 1735689601500000000 n ); const durationNanos = Uint64 . minus ( endNanos , startNanos ); // 1.5 billion nanoseconds
Example: Large File Handling import * as Uint64 from '@voltaire/primitives/Uint64' ; // File size in bytes (10 TB) const fileSize = Uint64 . from ( 10995116277760 n ); // Convert to human-readable const KB = Uint64 . from ( 1024 n ); 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:
// Number loses precision beyond MAX_SAFE_INTEGER const unsafe = 9007199254740993 ; // Actually stored as 9007199254740992 // BigInt maintains full precision const safe = 9007199254740993 n ; // Exactly 9007199254740993
API Reference Category Methods Construction from, fromNumber, fromBigInt, fromHex, fromBytes, fromAbiEncoded, tryFromConversion toNumber, toBigInt, toHex, toBytes, toAbiEncoded, toString, cloneArithmetic plus, minus, times, dividedBy, modulo, toPowerComparison equals, lessThan, greaterThan, isZero, minimum, maximumBitwise bitwiseAnd, bitwiseOr, bitwiseXor, bitwiseNot, shiftLeft, shiftRightBit Analysis bitLength, leadingZeros, popCountValidation isValid
