> ## 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 acceleration status for Hardfork operations

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

# WASM Implementation

WebAssembly acceleration status for Hardfork operations.

## Status: Not Implemented

WASM is **NOT** implemented for Hardfork operations and is **NOT** planned.

```typescript theme={null}
import { isWasmHardforkAvailable } from 'tevm/hardfork.wasm';

console.log(isWasmHardforkAvailable());  // false
```

## Why No WASM?

### Operations Are Already Optimal

Hardfork provides:

* Ethereum protocol version enum (constants)
* Simple comparison operations (array index comparisons)
* String parsing (hash table lookups)
* Feature detection (version comparisons)

These operations are:

* Already optimal in TypeScript
* Pure O(1) lookups and numeric comparisons
* No heavy computation or data processing
* Execution time less than 100ns per operation

**WASM overhead (\~1-2μs per call) would make operations 10-100x SLOWER.**

### Performance Characteristics

Pure TypeScript implementation benchmarks:

| Operation                  | Time        | Complexity                  |
| -------------------------- | ----------- | --------------------------- |
| isAtLeast/isBefore/isAfter | \~10-20ns   | O(1) array index comparison |
| fromString                 | \~50-100ns  | O(1) hash table lookup      |
| toString                   | \~20-40ns   | O(1) direct return          |
| hasEIP1559/hasEIP3855/etc  | \~15-30ns   | O(1) comparison + branch    |
| Feature detection          | \~20-50ns   | O(1) version check          |
| compare                    | \~10-20ns   | O(1) subtraction            |
| min/max                    | \~50-100ns  | O(n) iteration              |
| range                      | \~100-200ns | O(n) slice                  |

**WASM call overhead alone is 1000-2000ns** - operations would be 10-100x slower.

## When to Use WASM

WASM is beneficial for:

* **Heavy computation** (greater than 10μs)
* **Cryptographic operations** (hashing, signatures)
* **Large data processing** (RLP encoding, ABI encoding)
* **Batch operations** (processing many items)
* **CPU-intensive algorithms** (complex math, parsing)

### WASM Cost-Benefit

```
Break-even point = WASM overhead / speedup factor

For Hardfork:
- Operation time: 10-100ns
- WASM overhead: 1000-2000ns
- Required speedup: 10-20x faster
- Actual speedup: ~1x (same complexity)

Result: 10-20x SLOWER with WASM
```

### Good WASM Candidates

These primitives DO use WASM:

* **Keccak256**: \~50μs → \~5μs (10x speedup)
* **secp256k1**: \~100μs → \~10μs (10x speedup)
* **RLP encoding**: \~10μs → \~1μs (10x speedup)
* **ABI encoding**: \~20μs → \~2μs (10x speedup)

These operations are heavy enough that WASM overhead is negligible compared to computation cost.

## API Reference

### isWasmHardforkAvailable

Check if WASM implementation is available.

```typescript theme={null}
function isWasmHardforkAvailable(): boolean
```

**Returns:** Always `false`

**Example:**

```typescript theme={null}
import { isWasmHardforkAvailable } from 'tevm/hardfork.wasm';

if (isWasmHardforkAvailable()) {
  // Never reaches here
  console.log("Using WASM");
} else {
  console.log("Using pure TypeScript");  // Always this
}
```

***

### getHardforkImplementationStatus

Get detailed implementation status.

```typescript theme={null}
function getHardforkImplementationStatus(): {
  available: boolean;
  reason: string;
  recommendation: string;
  performance: {
    typescriptAvg: string;
    wasmOverhead: string;
    verdict: string;
  };
}
```

**Returns:**

```typescript theme={null}
{
  available: false,
  reason: "Pure TS optimal - WASM overhead exceeds benefit",
  recommendation: "Use pure TypeScript implementation - already optimal for enum lookups and comparisons",
  performance: {
    typescriptAvg: "10-100ns per operation",
    wasmOverhead: "1-2μs per WASM call",
    verdict: "TypeScript 10-100x faster for these operations"
  }
}
```

**Example:**

```typescript theme={null}
import { getHardforkImplementationStatus } from 'tevm/hardfork.wasm';

const status = getHardforkImplementationStatus();
console.log(status.available);       // false
console.log(status.reason);          // "Pure TS optimal - WASM overhead exceeds benefit"
console.log(status.recommendation);  // "Use pure TypeScript implementation..."
console.log(status.performance.verdict);  // "TypeScript 10-100x faster..."
```

***

## Import Behavior

### hardfork.wasm.js

```typescript theme={null}
// Re-exports pure TypeScript implementation
export * from './index.js';

// WASM-specific status functions
export { isWasmHardforkAvailable, getHardforkImplementationStatus };
```

**Usage:**

```typescript theme={null}
// Both imports identical at runtime
import { Hardfork, CANCUN } from 'tevm/hardfork';
import { Hardfork, CANCUN } from 'tevm/hardfork.wasm';

// Only difference: wasm export has status functions
import { isWasmHardforkAvailable } from 'tevm/hardfork.wasm';
```

## Performance Comparison

### TypeScript vs WASM (Hypothetical)

Assuming WASM implemented same logic:

| Operation  | TypeScript | WASM (with overhead) | Slower by |
| ---------- | ---------- | -------------------- | --------- |
| fromString | 50ns       | 1050ns               | 21x       |
| toString   | 20ns       | 1020ns               | 51x       |
| isAtLeast  | 10ns       | 1010ns               | 101x      |
| hasEIP1559 | 15ns       | 1015ns               | 67x       |
| compare    | 10ns       | 1010ns               | 101x      |

### Real-World Impact

```typescript theme={null}
// Check 1000 hardforks
for (let i = 0; i < 1000; i++) {
  Hardfork.isAtLeast(CANCUN, LONDON);
}

// TypeScript: 10μs total
// WASM: 1000μs total (100x slower)
```

## Architecture Decision

### Why This Matters

Hardfork is a **hot path** primitive:

* Called frequently in transaction processing
* Used in every EVM opcode execution gate
* Critical for gas calculation
* Needed for every smart contract call

**Performance requirements:**

* Must be less than 100ns per call
* No allocations
* Minimal branching
* Cache-friendly

**TypeScript implementation meets all requirements.** WASM would violate performance budget.

### Design Philosophy

**Use the right tool:**

* Simple operations → TypeScript
* Heavy computation → WASM
* Critical path → TypeScript (no overhead)
* Batch processing → WASM (amortize overhead)

**Hardfork fits "simple operations" category.**

## Benchmarking

### Running Benchmarks

```bash theme={null}
bun run src/primitives/Hardfork/BrandedHardfork/Hardfork.bench.ts
```

### Typical Results

```
Hardfork Benchmarks:
  fromString("cancun")     50-100 ns/op
  toString(CANCUN)         20-40 ns/op
  isAtLeast(CANCUN, LONDON) 10-20 ns/op
  hasEIP1559(CANCUN)       15-30 ns/op
  compare(CANCUN, LONDON)  10-20 ns/op
  range(BERLIN, CANCUN)    100-200 ns/op
```

**Interpretation:**

* All operations less than 100ns
* WASM overhead greater than 1000ns
* WASM would be 10-100x slower

## Alternative Optimizations

Instead of WASM, we optimize through:

### 1. Constant Folding

```typescript theme={null}
// Compiler optimizes these to constants
const LONDON_IDX = 11;
const CANCUN_IDX = 16;

function isAtLeast(current, target) {
  // JIT compiles to: return currentIdx >= targetIdx
  return HARDFORK_ORDER.indexOf(current) >= HARDFORK_ORDER.indexOf(target);
}
```

### 2. Hash Table Lookups

```typescript theme={null}
// O(1) lookup via object property access
const NAME_TO_HARDFORK = {
  cancun: CANCUN,
  shanghai: SHANGHAI,
  // ...
};

function fromString(name) {
  return NAME_TO_HARDFORK[name.toLowerCase()];
}
```

### 3. Inline Comparisons

```typescript theme={null}
// JIT optimizes to direct comparison
function hasEIP1559(fork) {
  return HARDFORK_ORDER.indexOf(fork) >= HARDFORK_ORDER.indexOf(LONDON);
}
```

### 4. Monomorphic Code

```typescript theme={null}
// Always returns same type = better JIT optimization
function fromString(name: string): BrandedHardfork | undefined {
  // ...
}
```

## Related Primitives with WASM

These primitives DO benefit from WASM:

### Address

* Keccak256 hashing for checksums (\~10x speedup)
* Public key derivation (\~10x speedup)

### Hash

* Keccak256 implementation (\~10x speedup)
* SHA256 implementation (\~8x speedup)

### RLP

* Encoding/decoding large structures (\~5-10x speedup)

### ABI

* Encoding/decoding complex types (\~5-10x speedup)

### secp256k1

* Signature operations (\~10x speedup)
* Public key recovery (\~10x speedup)

**Pattern:** Heavy computation (greater than 10μs) benefits from WASM. Simple lookups do not.

## Best Practices

### 1. Import from Main Module

```typescript theme={null}
// Good - use main module
import { Hardfork, CANCUN } from 'tevm';

// Unnecessary - wasm module is identical
import { Hardfork, CANCUN } from 'tevm/hardfork.wasm';
```

### 2. Don't Check for WASM

```typescript theme={null}
// Bad - unnecessary check
if (isWasmHardforkAvailable()) {
  // Never happens
}

// Good - just use TypeScript directly
Hardfork.isAtLeast(CANCUN, LONDON);
```

### 3. Trust the Implementation

```typescript theme={null}
// Implementation is already optimal
// No need to try to optimize further
const result = Hardfork("cancun");
```

## Future Considerations

### When Would WASM Be Added?

WASM might be considered if:

1. Hardfork operations become greater than 10μs per call
2. Batch operations on 1000+ hardforks become common
3. Heavy computation is added (unlikely for enum operations)

**None of these are expected.**

### Maintaining Zero Overhead

Current design maintains zero overhead:

* No WASM loading
* No WASM compilation
* No WASM call overhead
* No fallback logic
* Simpler codebase

**This is a feature, not a limitation.**

## Related

* [index.mdx](./index.mdx) - Main documentation
* [utilities.mdx](./utilities.mdx) - All operations are pure TypeScript
* [comparisons.mdx](./comparisons.mdx) - O(1) comparison operations
* [features.mdx](./features.mdx) - O(1) feature detection