Skip to main content

Try it Live

Run Uint examples in the interactive playground

    ​
    Number Limitations

    JavaScript numbers are 64-bit floating point (IEEE 754 double precision):
    Only use numbers within safe integer range: -2^53 + 1 to 2^53 - 1For larger values, use BigInt instead.

    ​
    Safe Integer Range

    // Maximum safe integer
Number.MAX_SAFE_INTEGER  // 9007199254740991 (2^53 - 1)

// Safe values
Uint(0)                        // OK
Uint(1000000)                  // OK
Uint(Number.MAX_SAFE_INTEGER)  // OK

// Unsafe values (loss of precision)
Uint(Number.MAX_SAFE_INTEGER + 1)  // Unreliable
Uint(10 ** 18)                     // Unreliable (exceeds safe range)

    ​
    Use BigInt for Large Values

    // Don't do this (unsafe)
const largeNumber = 1000000000000000000  // 10^18
Uint(largeNumber)  // May lose precision!

// Do this instead (safe)
const largeBigInt = 1000000000000000000n
Uint.fromBigInt(largeBigInt)  // Accurate

// Or use string
Uint("1000000000000000000")  // Accurate

    ​
    Validation

    ​
    Integer Check

    // Must be integer
Uint(100)    // OK
Uint(0)      // OK

// Decimal values throw
Uint(3.14)   // Error: Must be integer
Uint(1.5)    // Error: Must be integer
Uint(100.1)  // Error: Must be integer

    ​
    Special Values

    // Invalid numbers throw
Uint(NaN)       // Error: Invalid value
Uint(Infinity)  // Error: Invalid value
Uint(-Infinity) // Error: Invalid value

    ​
    Negative Values

    // Must be non-negative
Uint(0)    // OK
Uint(1)    // OK

Uint(-1)   // Error: Cannot be negative
Uint(-100) // Error: Cannot be negative

    ​
    Usage Patterns

    ​
    Small Constants

    // Good for small constants
const ZERO = Uint(0)
const ONE = Uint(1)
const TEN = Uint(10)
const HUNDRED = Uint(100)

    ​
    Array Indices

    function getElement(index: number): BrandedUint256 {
  return Uint(index)
}

// Converting array index to Uint
const items = [1, 2, 3, 4, 5]
items.forEach((_, index) => {
  const indexAsUint = Uint(index)
  // ...
})

    ​
    Type Conversion

    // When you have number but need Uint
function processNumber(n: number): void {
  if (n < 0 || !Number.isInteger(n)) {
    throw new Error("Invalid number")
  }

  const uint = Uint(n)
  // Use uint...
}

    ​
    Best Practices

    ​
    Prefer BigInt for Ethereum Values

    // Bad: Loses precision
const weiAmount = Uint(1000000000000000000)  // 10^18

// Good: Accurate
const weiAmount = Uint.fromBigInt(1000000000000000000n)

// Good: From string
const weiAmount = Uint("1000000000000000000")

    ​
    Check Safe Integer Range

    function safeFromNumber(n: number): BrandedUint256 {
  if (!Number.isSafeInteger(n)) {
    throw new Error("Number exceeds safe integer range - use BigInt")
  }
  if (n < 0) {
    throw new Error("Number must be non-negative")
  }
  return Uint(n)
}

    ​
    See Also