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

# Wei

> Smallest Ethereum denomination for precise calculations

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

# Wei

Smallest Ethereum denomination (10^-18 Ether) for precise value calculations.

## Overview

Wei is the atomic unit of Ether. All Ethereum values are ultimately represented in Wei internally. `Wei.Type` is a [branded](/getting-started/branded-types) `Uint256` preventing accidental unit mixing.

## Type Definition

```typescript theme={null}
import * as Wei from 'tevm/Wei'

// Wei.Type is branded Uint256 preventing unit mixing
const wei: Wei.Type = Wei(1_000_000_000n)

// Internal: Wei.Type = Uint.Type & { __brand: typeof weiSymbol }
```

## Construction

### `Wei.from(value)`

Create Wei from numeric value.

```typescript theme={null}
import * as Wei from 'tevm/Wei'

const wei1 = Wei(1_000_000_000n)              // 1 Gwei in Wei
const wei2 = Wei(1_000_000_000_000_000_000n)  // 1 Ether in Wei
const wei3 = Wei(21_000n)                     // Standard transfer gas
const wei4 = Wei("1000000000000000000")       // String input
const wei5 = Wei(42)                          // Number input
```

**Parameters:**

* `value: bigint | number | string` - Value to convert to Wei

**Returns:** `Wei.Type`

**Note:** Uses `Uint.from` internally for conversion.

Defined in: [primitives/Denomination/Wei.ts:10](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Wei.ts)

## Conversions From Other Units

### `Wei.fromGwei(gwei)`

Convert Gwei to Wei (multiply by 10^9).

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'
import * as Wei from 'tevm/Wei'

const gwei = Gwei(50n)  // 50 Gwei gas price
const wei = Wei.fromGwei(gwei)  // 50_000_000_000n Wei
```

**Parameters:**

* `gwei: Gwei.Type` - Gwei value

**Returns:** `Wei.Type`

**Formula:** `wei = gwei * 1_000_000_000`

Defined in: [primitives/Denomination/Wei.ts:14](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Wei.ts)

### `Wei.fromEther(ether)`

Convert Ether to Wei (multiply by 10^18).

```typescript theme={null}
import * as Ether from 'tevm/Ether'
import * as Wei from 'tevm/Wei'

const ether = Ether(1n)  // 1 Ether
const wei = Wei.fromEther(ether)  // 1_000_000_000_000_000_000n Wei
```

**Parameters:**

* `ether: Ether.Type` - Ether value

**Returns:** `Wei.Type`

**Formula:** `wei = ether * 1_000_000_000_000_000_000`

Defined in: [primitives/Denomination/Wei.ts:19](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Wei.ts)

## Conversions To Other Units

### `Wei.toGwei(wei)`

Convert Wei to Gwei (divide by 10^9).

```typescript theme={null}
import * as Wei from 'tevm/Wei'

const wei = Wei(50_000_000_000n)  // 50 Gwei in Wei
const gwei = Wei.toGwei(wei)  // 50n Gwei

// Fractional values truncate
const wei2 = Wei(50_000_000_001n)
const gwei2 = Wei.toGwei(wei2)  // 50n (truncates)
```

**Parameters:**

* `wei: Wei.Type` - Wei value

**Returns:** `Gwei.Type`

**Formula:** `gwei = wei / 1_000_000_000` (integer division)

Defined in: [primitives/Denomination/Wei.ts:24](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Wei.ts)

### `Wei.toEther(wei)`

Convert Wei to Ether (divide by 10^18).

```typescript theme={null}
import * as Wei from 'tevm/Wei'

const wei = Wei(1_000_000_000_000_000_000n)  // 1 Ether in Wei
const ether = Wei.toEther(wei)  // 1n Ether

// Fractional values truncate
const wei2 = Wei(500_000_000_000_000_000n)  // 0.5 Ether in Wei
const ether2 = Wei.toEther(wei2)  // 0n (truncates)
```

**Parameters:**

* `wei: Wei.Type` - Wei value

**Returns:** `Ether.Type`

**Formula:** `ether = wei / 1_000_000_000_000_000_000` (integer division)

Defined in: [primitives/Denomination/Wei.ts:29](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Wei.ts)

## Conversions To Base Type

### `Wei.toU256(wei)`

Convert Wei to raw Uint256 (removes branding).

```typescript theme={null}
import * as Wei from 'tevm/Wei'
import * as Uint from 'tevm/Uint'

const wei = Wei(1_000_000_000n)
const u256 = Wei.toU256(wei)  // Uint.Type (unbranded)

// Can now use with Uint operations
const doubled = Uint.times(u256, Uint(2n))
```

**Parameters:**

* `wei: Wei.Type` - Wei value

**Returns:** `Uint.Type`

**Note:** Removes type safety. Use for arithmetic operations requiring `Uint.Type`.

Defined in: [primitives/Denomination/Wei.ts:34](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Wei.ts)

## Usage Examples

### Gas Cost Calculation

```typescript theme={null}
import * as Wei from 'tevm/Wei'
import * as Gwei from 'tevm/Gwei'
import * as Uint from 'tevm/Uint'

const gasPrice = Gwei(50n)  // 50 Gwei
const gasUsed = Uint(21_000n)  // Standard transfer

// Convert to Wei for calculation
const gasPriceWei = Gwei.toWei(gasPrice)
const totalCostWei = Uint.times(gasPriceWei, gasUsed)

console.log(`Cost: ${totalCostWei} Wei`)  // 1_050_000_000_000_000 Wei
```

### Transaction Value

```typescript theme={null}
import * as Wei from 'tevm/Wei'
import * as Ether from 'tevm/Ether'

const valueEther = Ether(1n)  // User wants to send 1 ETH
const valueWei = Ether.toWei(valueEther)  // Convert to Wei

const tx = {
  to: "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e",
  value: valueWei,  // 1_000_000_000_000_000_000n Wei
}
```

### Precise Accounting

```typescript theme={null}
import * as Wei from 'tevm/Wei'
import * as Uint from 'tevm/Uint'

// Work in Wei to avoid rounding errors
const balance = Wei(1_234_567_890_123_456_789n)
const amount = Wei(234_567_890_123_456_789n)

const balanceU256 = Wei.toU256(balance)
const amountU256 = Wei.toU256(amount)

const remaining = Uint.minus(balanceU256, amountU256)
const remainingWei = Wei(remaining)

console.log(`Remaining: ${remainingWei} Wei`)
```

## Conversion Constants

```typescript theme={null}
// Wei per Gwei
const WEI_PER_GWEI = 1_000_000_000n  // 10^9

// Wei per Ether
const WEI_PER_ETHER = 1_000_000_000_000_000_000n  // 10^18
```

## Common Wei Values

```typescript theme={null}
import * as Wei from 'tevm/Wei'

// Gas costs
const TRANSFER_GAS = Wei(21_000n)  // Standard ETH transfer
const ERC20_TRANSFER = Wei(65_000n)  // Typical ERC20 transfer

// Gas prices (in Wei)
const CHEAP_GAS = Wei(1_000_000_000n)  // 1 Gwei
const NORMAL_GAS = Wei(20_000_000_000n)  // 20 Gwei
const HIGH_GAS = Wei(100_000_000_000n)  // 100 Gwei

// Common amounts
const ONE_ETHER = Wei(1_000_000_000_000_000_000n)
const HALF_ETHER = Wei(500_000_000_000_000_000n)
```

## Type Safety

Wei type prevents mixing with other denominations:

```typescript theme={null}
import * as Wei from 'tevm/Wei'
import * as Gwei from 'tevm/Gwei'

const wei = Wei(1_000_000_000n)
const gwei = Gwei(1n)

// ✗ Type error - cannot compare different denominations
if (wei === gwei) { }

// ✓ Correct - explicit conversion
if (wei === Gwei.toWei(gwei)) { }
```

## WASM Acceleration

Wei conversions available in WebAssembly for performance:

```typescript theme={null}
import * as WeiWasm from 'tevm/Wei.wasm'

const wei = WeiWasm(1_000_000_000n)
const gwei = WeiWasm.toGwei(wei)
```

See [WASM](/primitives/denomination/wasm) for details.

## Related

* [Gwei](/primitives/denomination/gwei) - Gas price denomination
* [Ether](/primitives/denomination/ether) - User-facing denomination
* [Conversions](/primitives/denomination/conversions) - Converting between units
* [Uint256](/primitives/uint) - Underlying numeric type