> ## 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.

# Uint.fromHex

> Create Uint256 from hex string with or without 0x prefix

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/uint.ts">
  Run Uint examples in the interactive playground
</Card>

<Tabs>
  <Tab title="Effect Schema">
    ```ts theme={null}
    import { UintSchema } from '@tevm/voltaire/Uint/effect'

    const u = UintSchema.fromHex('0xde0b6b3a7640000')
    u.toBigInt() // 1000000000000000000n
    ```
  </Tab>
</Tabs>

## Hex String Format

Hex strings represent unsigned integers in hexadecimal (base 16).

### Valid Formats

```typescript theme={null}
// Lowercase
Uint("0xdeadbeef")

// Uppercase
Uint("0xDEADBEEF")

// Mixed case
Uint("0xDeAdBeEf")

// Without prefix
Uint("deadbeef")

// Leading zeros allowed
Uint("0x00ff")
Uint("0x0000000000000000000000000000000000000000000000000000000000000001")
```

### Prefix Handling

The `0x` prefix is **optional**:

```typescript theme={null}
Uint("ff")      // 255
Uint("0xff")    // 255
// Both produce identical results
```

<Tip>
  Always use `0x` prefix to make hex strings unambiguous, especially when debugging.
</Tip>

### Case Insensitivity

```typescript theme={null}
Uint("0xabcdef")  // Same as
Uint("0xABCDEF")  // Same as
Uint("0xAbCdEf")  // Same as
Uint("abcdef")    // Same
```

## Length and Range

### Maximum Length

Hex strings for Uint256 can have **up to 64 hex digits** (not including `0x` prefix):

```typescript theme={null}
// 64 hex digits = 256 bits
const max = "0x" + "f".repeat(64)
Uint(max)  // MAX (2^256 - 1)

// 65 hex digits - exceeds maximum
const tooLarge = "0x1" + "0".repeat(64)
Uint(tooLarge)  // Error: exceeds 2^256 - 1
```

### Minimum Length

No minimum - leading zeros are implicit:

```typescript theme={null}
Uint("0x0")      // 0
Uint("0x1")      // 1
Uint("0xff")     // 255
Uint("0x100")    // 256
```

## Common Values

### Powers of 2

```typescript theme={null}
Uint("0x1")        // 1 (2^0)
Uint("0x2")        // 2 (2^1)
Uint("0x4")        // 4 (2^2)
Uint("0x8")        // 8 (2^3)
Uint("0x10")       // 16 (2^4)
Uint("0x100")      // 256 (2^8)
Uint("0x10000")    // 65536 (2^16)
```

### Common Ethereum Values

```typescript theme={null}
// 1 wei
Uint("0x1")

// 1 gwei (10^9 wei)
Uint("0x3b9aca00")

// 1 ether (10^18 wei)
Uint("0xde0b6b3a7640000")

// Max uint256
Uint("0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
```

## Error Handling

### Invalid Characters

```typescript theme={null}
Uint("0xGG")       // Error: invalid hex character 'G'
Uint("0x12xy")     // Error: invalid hex character 'x'
Uint("0x 123")     // Error: invalid hex character ' '
```

### Overflow

```typescript theme={null}
// Exceeds 2^256 - 1
const overflow = "0x1" + "0".repeat(64)
Uint(overflow)  // Error: exceeds maximum

// Just at max
const max = "0x" + "f".repeat(64)
Uint(max)  // OK: exactly 2^256 - 1
```

### Empty String

```typescript theme={null}
Uint("")         // Error: invalid format
Uint("0x")       // Error: invalid format
Uint("  ")       // Error: invalid format
```

## Usage Patterns

### Parsing Ethereum Data

```typescript theme={null}
// Transaction value from RPC
const txValueHex = "0xde0b6b3a7640000"
const txValue = Uint(txValueHex)

// Block number
const blockNumberHex = "0x10d4f"
const blockNumber = Uint(blockNumberHex)

// Gas price
const gasPriceHex = "0x3b9aca00"
const gasPrice = Uint(gasPriceHex)
```

### Converting from Other Primitives

```typescript theme={null}
import { Hash, Address } from 'tevm'

// Hash to Uint
const hash = Hash("0x1234...")
const hashAsUint = Uint(hash)  // Or: Uint(Hash.toHex(hash))

// Address to Uint
const addr = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")
const addrAsUint = Uint(addr)
```

### Safe Parsing

```typescript theme={null}
function parseHexSafe(hex: string): BrandedUint256 | null {
  try {
    return Uint(hex)
  } catch {
    return null
  }
}

// Usage
const value = parseHexSafe(userInput)
if (value === null) {
  console.error("Invalid hex input")
}
```

## Performance

Hex parsing requires:

1. Character validation (each char must be 0-9, a-f, A-F)
2. Conversion to bytes
3. BigInt construction

For **performance-critical code**, prefer:

* `fromBytes` if you already have Uint8Array
* `from(bigint)` if you already have BigInt

## See Also

* [from](/primitives/uint256/from) - Universal constructor
* [toHex](/primitives/uint256/to-hex) - Convert to hex string
* [fromBytes](/primitives/uint256/from-bytes) - From byte array
* [Hex primitive](/primitives/hex) - Hex string utilities