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

# WASM Implementation

> WebAssembly-accelerated denomination conversions compiled from Zig

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

# WASM Implementation

WebAssembly-accelerated implementations of denomination conversions, compiled from Zig using ReleaseSmall mode.

## Overview

WASM implementations provide performance-critical denomination operations using compiled Zig code targeting WebAssembly. These are **purely opt-in** replacements for the JavaScript implementations with identical APIs.

All WASM methods are compiled from [denomination.zig](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/denomination.zig) with `ReleaseSmall` optimization targeting minimal bundle size.

## Quick Start

<Tabs>
  <Tab title="Direct Import">
    ```typescript theme={null}
    // Import WASM implementation instead of JS version
    import * as Wei from 'tevm/Wei.wasm'
    import * as Gwei from 'tevm/Gwei.wasm'
    import * as Ether from 'tevm/Ether.wasm'

    // API is identical to JS version
    const gwei = Gwei(50n)
    const wei = Gwei.toWei(gwei)  // Uses WASM acceleration
    const ether = Wei.toEther(wei)  // Uses WASM acceleration
    ```
  </Tab>

  <Tab title="Selective Import">
    ```typescript theme={null}
    import * as Wei from 'tevm/Wei'
    import * as WeiWasm from 'tevm/Wei.wasm'

    // Override specific methods with WASM versions
    const weiToGwei = WeiWasm.toGwei
    const weiToEther = WeiWasm.toEther

    // Use WASM versions
    const wei = Wei(1_000_000_000n)
    const gwei = weiToGwei(wei)
    ```
  </Tab>
</Tabs>

## Performance

WASM implementations provide significant speedup for:

* **U256 arithmetic** - Compiled Zig multiplication and division
* **Bulk conversions** - Processing many values in tight loops
* **Constant-time operations** - No JavaScript overhead

<Tip title="When to use WASM">
  Use WASM when processing many denomination conversions (gas calculations, bulk balance conversions). For single operations, JS overhead may outweigh WASM benefits.
</Tip>

## API Reference

WASM implementations match the standard Denomination API. See main documentation:

* [Wei](/primitives/denomination/wei) - `from`, `fromGwei`, `fromEther`, `toGwei`, `toEther`, `toU256`
* [Gwei](/primitives/denomination/gwei) - `from`, `fromWei`, `fromEther`, `toWei`, `toEther`, `toU256`
* [Ether](/primitives/denomination/ether) - `from`, `fromWei`, `fromGwei`, `toWei`, `toGwei`, `toU256`

## WASM-Accelerated Methods

All denomination conversions implemented in Zig:

### Wei

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

// Construction
const wei = WeiWasm(1_000_000_000n)

// Conversions
const gwei = WeiWasm.toGwei(wei)      // Wei → Gwei (division)
const ether = WeiWasm.toEther(wei)    // Wei → Ether (division)
const u256 = WeiWasm.toU256(wei)      // Wei → Uint256 (unwrap)

// From other units
const wei2 = WeiWasm.fromGwei(gwei)   // Gwei → Wei (multiplication)
const wei3 = WeiWasm.fromEther(ether) // Ether → Wei (multiplication)
```

### Gwei

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

// Construction
const gwei = GweiWasm(50n)

// Conversions
const wei = GweiWasm.toWei(gwei)      // Gwei → Wei (multiplication)
const ether = GweiWasm.toEther(gwei)  // Gwei → Ether (division)
const u256 = GweiWasm.toU256(gwei)    // Gwei → Uint256 (unwrap)

// From other units
const gwei2 = GweiWasm.fromWei(wei)   // Wei → Gwei (division)
const gwei3 = GweiWasm.fromEther(ether) // Ether → Gwei (multiplication)
```

### Ether

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

// Construction
const ether = EtherWasm(1n)

// Conversions
const wei = EtherWasm.toWei(ether)    // Ether → Wei (multiplication)
const gwei = EtherWasm.toGwei(ether)  // Ether → Gwei (multiplication)
const u256 = EtherWasm.toU256(ether)  // Ether → Uint256 (unwrap)

// From other units
const ether2 = EtherWasm.fromWei(wei)   // Wei → Ether (division)
const ether3 = EtherWasm.fromGwei(gwei) // Gwei → Ether (division)
```

## Usage Examples

### Bulk Gas Calculations

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

const gasPrices = [
  GweiWasm(10n),
  GweiWasm(30n),
  GweiWasm(50n),
  GweiWasm(100n),
]

const gasUsed = Uint(21_000n)

// Process all in WASM (faster for bulk operations)
const costs = gasPrices.map(price => {
  const priceWei = GweiWasm.toWei(price)
  return Uint.times(priceWei, gasUsed)
})
```

### Balance Conversions

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

const balancesWei = [
  WeiWasm(1_000_000_000_000_000_000n),
  WeiWasm(2_500_000_000_000_000_000n),
  WeiWasm(500_000_000_000_000_000n),
]

// Convert all to Ether using WASM
const balancesEther = balancesWei.map(WeiWasm.toEther)
```

### Real-Time Gas Price Tracking

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

interface GasEstimate {
  fast: bigint
  standard: bigint
  slow: bigint
}

function estimateCost(
  estimate: GasEstimate,
  gasUsed: bigint
): GasEstimate {
  // Convert all Gwei prices to Wei costs using WASM
  const fast = GweiWasm.toWei(GweiWasm(estimate.fast))
  const standard = GweiWasm.toWei(GweiWasm(estimate.standard))
  const slow = GweiWasm.toWei(GweiWasm(estimate.slow))

  return {
    fast: fast * gasUsed,
    standard: standard * gasUsed,
    slow: slow * gasUsed,
  }
}
```

## Performance Characteristics

### Multiplication (Upscaling)

Conversions that multiply are memory-bound:

* `Gwei.toWei` - multiply by 10^9
* `Ether.toWei` - multiply by 10^18
* `Ether.toGwei` - multiply by 10^9

**WASM benefit:** Moderate (10-30% faster) - limited by memory access.

### Division (Downscaling)

Conversions that divide are compute-bound:

* `Wei.toGwei` - divide by 10^9
* `Wei.toEther` - divide by 10^18
* `Gwei.toEther` - divide by 10^9

**WASM benefit:** Significant (2-5x faster) - Zig division highly optimized.

## Files

* **denomination.zig** - Zig source implementation
  * Location: [src/primitives/Denomination/denomination.zig](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/denomination.zig)
  * Defines `Wei`, `Gwei`, `Ether` structs
  * Implements all conversion methods
  * Includes test suite

* **Wei.wasm.ts** - TypeScript WASM bindings for Wei

* **Gwei.wasm.ts** - TypeScript WASM bindings for Gwei

* **Ether.wasm.ts** - TypeScript WASM bindings for Ether

## Zig Tests

The Zig implementation includes comprehensive tests:

```zig theme={null}
test "wei to gwei conversion" {
    const w = Wei.from_u256(U256.from_u64(1_000_000_000))
    const g = w.to_gwei()
    try testing.expect(g.value.eq(U256.from_u64(1)))
}

test "wei to ether conversion" {
    const limbs: [4]u64 = .{ 0xde0b6b3a7640000, 0, 0, 0 }
    const w = Wei.from_u256(U256.from_limbs(limbs))
    const e = w.to_ether()
    try testing.expect(e.value.eq(U256.from_u64(1)))
}

test "round trip conversions" {
    const original = Wei.from_u256(U256.from_u64(5_000_000_000))
    const g = original.to_gwei()
    const back = g.to_wei()
    try testing.expect(back.value.eq(U256.from_u64(5_000_000_000)))
}
```

Run tests:

```bash theme={null}
zig build test -Dtest-filter="denomination"
```

## Benchmarking

Compare JS vs WASM performance:

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

const iterations = 100_000
const gwei = Gwei(50n)

// Benchmark JS
console.time('JS')
for (let i = 0; i < iterations; i++) {
  Gwei.toWei(gwei)
}
console.timeEnd('JS')

// Benchmark WASM
console.time('WASM')
for (let i = 0; i < iterations; i++) {
  GweiWasm.toWei(gwei)
}
console.timeEnd('WASM')
```

## Limitations

WASM implementations have same behavior as JS:

* **Integer division** - Fractional results truncate
* **No overflow checks** - U256 operations wrap
* **Same API** - Drop-in replacement

## Related

* [Wei](/primitives/denomination/wei) - Wei API reference
* [Gwei](/primitives/denomination/gwei) - Gwei API reference
* [Ether](/primitives/denomination/ether) - Ether API reference
* [Conversions](/primitives/denomination/conversions) - Conversion details
* [Uint WASM](/primitives/uint/wasm) - Underlying U256 WASM implementation