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

# Runtime Implementations

> Choose between TypeScript, WASM, and Native FFI based on your environment

Voltaire provides three entrypoints with **identical APIs**. All implement the [`VoltaireAPI` interface](https://github.com/evmts/voltaire/blob/main/src/api-interface.ts), ensuring compile-time errors if APIs diverge.

## Three Entrypoints

| Entrypoint | Import                  | Runtime                  | Use Case                         |
| ---------- | ----------------------- | ------------------------ | -------------------------------- |
| **JS**     | `@tevm/voltaire`        | Any JS runtime           | Default, universal compatibility |
| **WASM**   | `@tevm/voltaire/wasm`   | Browser, Node, Bun, Deno | High performance, portable       |
| **Native** | `@tevm/voltaire/native` | Bun                      | Maximum performance via FFI      |

```typescript theme={null}
// All three have the SAME API
import { Address, Keccak256 } from '@tevm/voltaire'        // JS (default)
import { Address, Keccak256 } from '@tevm/voltaire/wasm'   // WASM
import { Address, Keccak256 } from '@tevm/voltaire/native' // Native FFI
```

<Note>
  All three entrypoints export identical namespaces and types. Switch implementations by changing the import path - no code changes required.
</Note>

## JS (Default)

Pure TypeScript/JavaScript. Works everywhere JavaScript runs.

<Note>
  Shares the [ox](https://oxlib.sh) peer dependency for amortized bundle costs.
</Note>

```typescript theme={null}
import { Keccak256, Address, Hex } from '@tevm/voltaire'

const hash = Keccak256.hash(Hex.toBytes(Hex.fromString('hello')))
const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
```

A useful default - easy to debug and performant enough for most use cases.

## WASM

WebAssembly bindings to Zig implementations. Portable high-performance.

<Note>
  The WASM entrypoint exports the **same API** as JS. Switch by changing the import path.
</Note>

```typescript theme={null}
import { Keccak256, Secp256k1, Hex, Address } from '@tevm/voltaire/wasm'

// Same API as JS entrypoint
const hash = Keccak256.hash(data)
const recovered = Secp256k1.recoverAddress(hash, signature)
const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')

// All namespaces work identically
Secp256k1.sign(message, privateKey)
```

We recommend WASM for crypto operations - usually faster and smaller bundle size than JS equivalents. Best for applications needing maximum performance.

<Note>
  Design trade-off: Voltaire’s published WASM builds target a balance of strong performance and small bundle size. If you need maximum raw speed for specific workloads, build from source using the performance-optimized target (ReleaseFast). See `/dev/build-system#typescript-targets` and `/dev/wasm#build-modes`.
</Note>

## Native FFI (Bun)

Direct bindings to Zig via Bun FFI. Maximum performance.

<Note>
  The Native entrypoint exports the **same API** as JS. Switch by changing the import path.
</Note>

```typescript theme={null}
import { Keccak256, Address, Secp256k1 } from '@tevm/voltaire/native'

// Same API as JS entrypoint
const hash = Keccak256.hash(data)
const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
const signature = Secp256k1.sign(message, privateKey)
```

<Warning>
  Runtime support: Native FFI is <strong>Bun-only</strong>. In <strong>Node.js</strong>, use the JS or WASM entrypoint. Ensure the compiled `.dylib`/`.so`/`.dll` is available (run `zig build build-ts-native`).
</Warning>

## Per-Module Imports

For fine-grained control, import specific implementations:

```typescript theme={null}
// Keccak256 variants
import { Keccak256 } from '@tevm/voltaire/Keccak256'           // JS (default)
import { Keccak256 } from '@tevm/voltaire/Keccak256/wasm'      // WASM
import { Keccak256 } from '@tevm/voltaire/Keccak256/native'    // Native FFI
```

## Performance Considerations

<Warning>
  Performance is nuanced. WASM/Native aren't always faster than TypeScript.
</Warning>

**Bridging overhead**: Crossing the JS↔WASM or JS↔FFI boundary has constant overhead (\~1-10μs). For cheap operations (simple math, short string manipulation), this overhead can exceed the operation itself.

**When WASM/Native wins**:

* Cryptographic operations (keccak256, secp256k1, BLS) - 5-15x faster
* Large data encoding/decoding (RLP, ABI with big payloads)
* Batch operations that amortize bridging cost

**When JS wins**:

* Simple operations (hex encoding small values, address validation)
* String/hex formatting helpers that map to JS built-ins (for example, `toHex()`)
* Very small, trivial conversions where JS↔WASM overhead dominates
* Single-item operations with low computational cost
* When avoiding async overhead matters

**Bundle size**: For cryptography specifically, WASM is often *smaller* than equivalent pure-JS implementations. A full JS secp256k1 library can be 50-100KB, while WASM crypto modules are typically 20-40KB.

| Operation         | JS | WASM   | Native | Default |
| ----------------- | -- | ------ | ------ | ------- |
| keccak256         | 1x | \~5x   | \~10x  | JS      |
| secp256k1 sign    | 1x | \~8x   | \~15x  | JS      |
| secp256k1 recover | 1x | \~8x   | \~15x  | JS      |
| RLP encode        | 1x | \~1.2x | \~1.5x | JS      |
| Hex encode        | 1x | \~1.1x | \~1.2x | JS      |

<Tip>
  Benchmark your actual workload. Default implementations are chosen for common use cases, but your specific access patterns may differ.
</Tip>

## WASM Limitations

| Module                 | WASM Status     | Reason                             | Alternative                 |
| ---------------------- | --------------- | ---------------------------------- | --------------------------- |
| **BIP-39 / HD Wallet** | ❌ Not available | Requires libwally-core (C library) | Use native or JS entrypoint |

All other modules including BLS12-381, KZG, and BN254 work in WASM.