Skip to main content

Try it Live

Run Uint examples in the interactive playground
 
import { UintSchema } from '@tevm/voltaire/Uint/effect'

// Universal constructor
const u1 = UintSchema.from(123n)
const u2 = UintSchema.from('0xff')
const u3 = UintSchema.from(42)

u1.toHex() // '0x7b'
u2.toBigInt() // 255n
u3.toNumber() // 42

​
Input Types

Uint.from accepts multiple input types for flexibility:

​
BigInt (JavaScript)

const max = Uint(2n ** 256n - 1n)
const large = Uint(115792089237316195423570985008687907853269984665640564039457584007913129639935n)
BigInt values must be in range [0, 2^256 - 1]. Negative values and values exceeding maximum will throw.

​
Number (JavaScript)

const small = Uint(255)
const zero = Uint(0)

// Throws on invalid
Uint(-1)      // Error: negative
Uint(3.14)    // Error: not integer
Uint(NaN)     // Error: invalid
Uint(Infinity) // Error: invalid
Numbers must be safe integers. Use bigint for values > Number.MAX_SAFE_INTEGER (2^53 - 1).

​
String - Decimal

const a = Uint("12345")
const b = Uint("0")
const c = Uint("115792089237316195423570985008687907853269984665640564039457584007913129639935")

​
String - Hexadecimal

Hex strings with or without 0x prefix: 
const a = Uint("0xff")
const b = Uint("FF")
const c = Uint("0x0000000000000000000000000000000000000000000000000000000000000001")

// Case insensitive
Uint("0xDEADBEEF")  // Same as 0xdeadbeef

​
Validation

All inputs validated before construction: Range checks: 
Uint(-1n)          // Error: Value cannot be negative
Uint(2n ** 256n)   // Error: Value exceeds 2^256 - 1
Format checks: 
Uint("invalid")    // Error: Invalid format
Uint("0xGG")       // Error: Invalid hex
Uint(3.14)         // Error: Must be integer
Type checks: 
Uint(null)         // Error: Invalid type
Uint(undefined)    // Error: Invalid type
Uint({})           // Error: Invalid type

​
Usage Patterns

​
Constructor Selection

// Known bigint - use from
const a = Uint(100n)

// Hex string - use fromHex (more explicit)
const b = Uint("0xff")

// User input - use tryFrom (safe)
const userInput = "12345"
const c = Uint.tryFrom(userInput)
if (c === undefined) {
  throw new Error("Invalid uint")
}

​
Safe Parsing

function parseUint(input: unknown): BrandedUint256 | null {
  try {
    if (typeof input === "bigint") {
      return Uint(input)
    }
    if (typeof input === "number") {
      return Uint(input)
    }
    if (typeof input === "string") {
      return Uint(input)
    }
  } catch {
    return null
  }
  return null
}

// Better: use tryFrom
function parseUintSafe(input: bigint | number | string): BrandedUint256 | null {
  return Uint.tryFrom(input) ?? null
}

​
Type Conversion

// From other primitives
import { Address, Hash } from 'tevm'

const addr = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")
const addrAsUint = Uint(addr)  // Address is Uint8Array(20)

const hash = Hash("0x1234...")
const hashAsUint = Uint(hash)  // Hash is Uint8Array(32)

​
Performance

Zero-copy for direct Uint8Array construction (fromBytes, fromAbiEncoded). Conversion required for strings (parses and allocates new Uint8Array). For performance-critical code, prefer passing bigint directly or using fromBytes.

​
See Also