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

# Primitives Reference

> Complete inventory of all 100+ primitive types currently implemented

# Primitives Reference

All primitives in `src/primitives/`. Each is a branded type with colocated TypeScript and Zig implementations.

## Core Types

### Address

20-byte Ethereum address with EIP-55 checksumming.

```typescript theme={null}
import * as Address from "@voltaire/primitives/Address";

const addr = Address.fromHex("0x742d35Cc6634C0532925a3b844Bc9e7595f251e3");
Address.toChecksummed(addr);  // "0x742d35Cc6634C0532925a3b844Bc9e7595f251e3"
Address.isZero(addr);         // false
```

**Methods**: `fromHex`, `fromBytes`, `fromPublicKey`, `toHex`, `toChecksummed`, `toBytes`, `equals`, `isZero`, `isValid`, `calculateCreateAddress`, `calculateCreate2Address`

### Hash

32-byte hash type used for block hashes, transaction hashes, storage roots.

```typescript theme={null}
import * as Hash from "@voltaire/primitives/Hash";

const hash = Hash.fromHex("0xabc...");
Hash.toHex(hash);
Hash.equals(hash1, hash2);
```

### Hex

Hexadecimal string encoding/decoding utilities.

```typescript theme={null}
import * as Hex from "@voltaire/primitives/Hex";

Hex.fromBytes(bytes);      // "0x..."
Hex.toBytes("0xabcd");     // Uint8Array
Hex.concat(hex1, hex2);    // Combined hex
Hex.slice(hex, 0, 10);     // Substring
```

### Bytes / Bytes32

Fixed-size byte arrays. `Bytes32` is 32 bytes, commonly used for storage keys.

```typescript theme={null}
import * as Bytes32 from "@voltaire/primitives/Bytes32";

const key = Bytes32.fromHex("0x...");
Bytes32.toHex(key);
```

Also: `Bytes1` through `Bytes8`, `Bytes16`, `Bytes20`, `Bytes32`

***

## Numeric Types

### Uint256 (Uint)

256-bit unsigned integer as branded `bigint`.

```typescript theme={null}
import * as Uint256 from "@voltaire/primitives/Uint256";

const value = Uint256.from(1000n);
Uint256.plus(a, b);
Uint256.times(a, b);
Uint256.shiftLeft(value, 8n);
Uint256.toHex(value);
```

**40+ methods**: `from`, `fromHex`, `toHex`, `toBigInt`, `plus`, `minus`, `times`, `dividedBy`, `modulo`, `power`, `shiftLeft`, `shiftRight`, `and`, `or`, `xor`, `not`, `equals`, `lt`, `gt`, `lte`, `gte`, `min`, `max`, `clamp`, `abs`, `bitLength`, `popCount`, `isPowerOf2`, `gcd`, `lcm`, `isEven`, `isOdd`, `isZero`

### Other Integer Types

| Type      | Size    | Signed |
| --------- | ------- | ------ |
| `Uint8`   | 8-bit   | No     |
| `Uint16`  | 16-bit  | No     |
| `Uint32`  | 32-bit  | No     |
| `Uint64`  | 64-bit  | No     |
| `Uint128` | 128-bit | No     |
| `Uint256` | 256-bit | No     |
| `Int8`    | 8-bit   | Yes    |
| `Int16`   | 16-bit  | Yes    |
| `Int32`   | 32-bit  | Yes    |
| `Int64`   | 64-bit  | Yes    |
| `Int128`  | 128-bit | Yes    |
| `Int256`  | 256-bit | Yes    |

***

## Encoding

### Rlp

Recursive Length Prefix encoding for Ethereum serialization.

```typescript theme={null}
import * as Rlp from "@voltaire/primitives/Rlp";

const encoded = Rlp.encode([address, nonce, value]);
const decoded = Rlp.decode(encoded);
Rlp.encodeLength(data);
```

### Abi

Application Binary Interface encoding/decoding for contract calls.

```typescript theme={null}
import * as Abi from "@voltaire/primitives/Abi";

// Encode function call
const calldata = Abi.encodeFunctionData({
  abi: contractAbi,
  functionName: "transfer",
  args: [to, amount]
});

// Decode return value
const result = Abi.decodeFunctionResult({
  abi: contractAbi,
  functionName: "balanceOf",
  data: returnData
});

// Get function selector
Abi.getFunctionSelector("transfer(address,uint256)");  // "0xa9059cbb"
```

### Base64

Base64 encoding/decoding.

```typescript theme={null}
import * as Base64 from "@voltaire/primitives/Base64";

Base64.encode(bytes);
Base64.decode(base64String);
```

### Ssz

Simple Serialize - beacon chain serialization format.

Located in `src/primitives/Ssz/` with:

* `basicTypes.ts` - Primitive SSZ types
* `container.ts` - Container types
* `merkle.ts` - Merkle tree operations
* `variableTypes.ts` - Variable-length types

***

## Transaction Types

### Transaction

All Ethereum transaction types with full serialization support.

```typescript theme={null}
import * as Transaction from "@voltaire/primitives/Transaction";

// Create EIP-1559 transaction
const tx = Transaction.from({
  type: "eip1559",
  to: address,
  value: 1000000000000000000n,
  maxFeePerGas: 20000000000n,
  maxPriorityFeePerGas: 1000000000n,
  gasLimit: 21000n,
  nonce: 0n,
  chainId: 1n,
});

// Serialize
const serialized = Transaction.serialize(tx);

// Get hash
const hash = Transaction.hash(tx);

// Sign
const signed = Transaction.sign(tx, privateKey);
```

**Transaction Types**:

* `Legacy` - Pre-EIP-2718 transactions
* `EIP2930` - Access list transactions
* `EIP1559` - Fee market transactions
* `EIP4844` - Blob transactions
* `EIP7702` - Account abstraction transactions

### AccessList

EIP-2930 access list for gas optimization.

```typescript theme={null}
import * as AccessList from "@voltaire/primitives/AccessList";

const accessList = AccessList.from([
  { address: "0x...", storageKeys: ["0x..."] }
]);
```

### Authorization

EIP-7702 authorization for account abstraction.

```typescript theme={null}
import * as Authorization from "@voltaire/primitives/Authorization";

const auth = Authorization.from({
  chainId: 1n,
  address: "0x...",
  nonce: 0n,
});
const signed = Authorization.sign(auth, privateKey);
```

### Blob

EIP-4844 blob data (128KB).

```typescript theme={null}
import * as Blob from "@voltaire/primitives/Blob";

const blob = Blob.from(data);
Blob.toCommitment(blob);  // KZG commitment
```

***

## Block Types

### Block

Complete block structure.

```typescript theme={null}
import * as Block from "@voltaire/primitives/Block";

Block.hash(block);
Block.number(block);
Block.transactions(block);
```

### BlockHeader

Block header fields.

```typescript theme={null}
import * as BlockHeader from "@voltaire/primitives/BlockHeader";

BlockHeader.parentHash(header);
BlockHeader.stateRoot(header);
BlockHeader.transactionsRoot(header);
```

### BlockBody

Block body (transactions and uncles).

### BlockHash / BlockNumber

Block identifiers.

```typescript theme={null}
import * as BlockHash from "@voltaire/primitives/BlockHash";
import * as BlockNumber from "@voltaire/primitives/BlockNumber";

const hash = BlockHash.fromHex("0x...");
const num = BlockNumber.from(12345678n);
```

***

## Receipt & Logs

### Receipt

Transaction receipt with status, logs, gas used.

```typescript theme={null}
import * as Receipt from "@voltaire/primitives/Receipt";

Receipt.status(receipt);     // 1 = success, 0 = failure
Receipt.gasUsed(receipt);
Receipt.logs(receipt);
```

### EventLog

Contract event log entry.

```typescript theme={null}
import * as EventLog from "@voltaire/primitives/EventLog";

EventLog.address(log);
EventLog.topics(log);
EventLog.data(log);
EventLog.decode(log, eventAbi);
```

### LogFilter / TopicFilter / BlockFilter

Event filtering.

```typescript theme={null}
import * as LogFilter from "@voltaire/primitives/LogFilter";

const filter = LogFilter.from({
  address: "0x...",
  topics: [eventSignature],
  fromBlock: 1000000n,
  toBlock: "latest",
});
```

***

## EVM Types

### Bytecode

EVM bytecode with analysis capabilities.

```typescript theme={null}
import * as Bytecode from "@voltaire/primitives/Bytecode";

const code = Bytecode.fromHex("0x6080604052...");
Bytecode.jumpDestinations(code);
Bytecode.isValidJumpDest(code, pc);
Bytecode.getOpcode(code, pc);
```

### Opcode

EVM opcode enum and metadata.

```typescript theme={null}
import * as Opcode from "@voltaire/primitives/Opcode";

Opcode.name(0x60);           // "PUSH1"
Opcode.gas(0x60);            // 3
Opcode.stackInputs(0x60);    // 0
Opcode.stackOutputs(0x60);   // 1
```

### Gas Types

| Type                   | Purpose                     |
| ---------------------- | --------------------------- |
| `Gas`                  | Generic gas value           |
| `GasLimit`             | Transaction/block gas limit |
| `GasUsed`              | Actual gas consumed         |
| `GasEstimate`          | Estimated gas               |
| `GasRefund`            | Refunded gas                |
| `GasPrice`             | Legacy gas price            |
| `BaseFeePerGas`        | EIP-1559 base fee           |
| `MaxFeePerGas`         | EIP-1559 max fee            |
| `MaxPriorityFeePerGas` | EIP-1559 priority fee       |
| `EffectiveGasPrice`    | Actual price paid           |

### GasConstants

EVM gas cost constants.

```typescript theme={null}
import * as GasConstants from "@voltaire/primitives/GasConstants";

GasConstants.G_ZERO;          // 0
GasConstants.G_BASE;          // 2
GasConstants.G_VERYLOW;       // 3
GasConstants.G_SLOAD;         // 2100 (post-Berlin)
GasConstants.G_SSTORE_SET;    // 20000
```

### Storage / StorageKey / StorageValue

Contract storage types.

```typescript theme={null}
import * as StorageKey from "@voltaire/primitives/StorageKey";
import * as StorageValue from "@voltaire/primitives/StorageValue";

const key = StorageKey.from(0n);
const value = StorageValue.from(bytes32);
```

***

## Protocol Types

### Chain

Chain metadata and configuration.

```typescript theme={null}
import * as Chain from "@voltaire/primitives/Chain";

Chain.mainnet;
Chain.sepolia;
Chain.byId(1n);
Chain.nativeCurrency(chain);
Chain.rpcUrls(chain);
```

### ChainId / NetworkId

Network identifiers.

```typescript theme={null}
import * as ChainId from "@voltaire/primitives/ChainId";

const chainId = ChainId.from(1n);  // Mainnet
ChainId.isMainnet(chainId);        // true
```

### Hardfork

Ethereum hardfork enum and feature detection.

```typescript theme={null}
import * as Hardfork from "@voltaire/primitives/Hardfork";

Hardfork.LONDON;
Hardfork.SHANGHAI;
Hardfork.CANCUN;
Hardfork.hasEIP1559(Hardfork.LONDON);  // true
Hardfork.hasEIP4844(Hardfork.CANCUN);  // true
```

### ForkId

EIP-2124 fork identifier.

### FeeMarket

EIP-1559 fee market calculations.

```typescript theme={null}
import * as FeeMarket from "@voltaire/primitives/FeeMarket";

FeeMarket.calculateBaseFee(parentGasUsed, parentGasLimit, parentBaseFee);
FeeMarket.estimateMaxFee(baseFee, priorityFee);
```

### Denomination

Wei/Gwei/Ether conversions.

```typescript theme={null}
import * as Denomination from "@voltaire/primitives/Denomination";

Denomination.toWei("1.5", "ether");   // 1500000000000000000n
Denomination.fromWei(wei, "gwei");    // "1500000000"
Denomination.parseEther("1.5");       // 1500000000000000000n
Denomination.formatEther(wei);        // "1.5"
```

***

## Signature Types

### Signature

ECDSA signature with r, s, v components.

```typescript theme={null}
import * as Signature from "@voltaire/primitives/Signature";

const sig = Signature.from({ r, s, v });
Signature.toHex(sig);
Signature.toCompact(sig);     // 64-byte compact format
Signature.recover(sig, hash); // Recover public key
```

### PrivateKey / PublicKey

Key types.

```typescript theme={null}
import * as PrivateKey from "@voltaire/primitives/PrivateKey";
import * as PublicKey from "@voltaire/primitives/PublicKey";

const pk = PrivateKey.generate();
const pubkey = PublicKey.fromPrivateKey(pk);
PublicKey.toAddress(pubkey);
```

***

## Standards

### Siwe

Sign-In with Ethereum (EIP-4361).

```typescript theme={null}
import * as Siwe from "@voltaire/primitives/Siwe";

const message = Siwe.createMessage({
  domain: "example.com",
  address: "0x...",
  statement: "Sign in",
  uri: "https://example.com",
  version: "1",
  chainId: 1n,
  nonce: "abc123",
});

Siwe.verify(message, signature);
```

### Ens

ENS name normalization (ENSIP-15).

```typescript theme={null}
import * as Ens from "@voltaire/primitives/Ens";

Ens.normalize("Vitalik.eth");  // "vitalik.eth"
Ens.namehash("vitalik.eth");   // 0x...
Ens.isValidName(name);
```

### Domain / DomainSeparator

EIP-712 typed data domain.

```typescript theme={null}
import * as Domain from "@voltaire/primitives/Domain";

const domain = Domain.from({
  name: "MyContract",
  version: "1",
  chainId: 1n,
  verifyingContract: "0x...",
});
Domain.separator(domain);
```

### Permit

EIP-2612 permit support.

### StealthAddress

ERC-5564 stealth address support.

***

## Account Abstraction (ERC-4337)

### UserOperation

User operation for ERC-4337.

```typescript theme={null}
import * as UserOperation from "@voltaire/primitives/UserOperation";

const userOp = UserOperation.from({
  sender: "0x...",
  nonce: 0n,
  initCode: "0x",
  callData: "0x...",
  callGasLimit: 100000n,
  verificationGasLimit: 100000n,
  preVerificationGas: 21000n,
  maxFeePerGas: 20000000000n,
  maxPriorityFeePerGas: 1000000000n,
  paymasterAndData: "0x",
  signature: "0x",
});

UserOperation.hash(userOp, entryPoint, chainId);
```

### PackedUserOperation

Packed format for ERC-4337 v0.7+.

### EntryPoint / Paymaster / Bundler

Account abstraction infrastructure types.

***

## Beacon Chain Types

### Slot / Epoch

Beacon chain timing.

```typescript theme={null}
import * as Slot from "@voltaire/primitives/Slot";
import * as Epoch from "@voltaire/primitives/Epoch";

const slot = Slot.from(1000000n);
Slot.toEpoch(slot);  // Epoch containing this slot
```

### ValidatorIndex / WithdrawalIndex

Validator identifiers.

### Withdrawal

Staking withdrawals.

### BeaconBlockRoot

Beacon block reference (EIP-4788).

***

## Tracing Types

### TraceConfig

Debug trace configuration.

### StructLog / OpStep

EVM execution trace.

### CallTrace

Call hierarchy trace.

### TraceResult

Complete trace result.

### MemoryDump / StorageDiff / StateDiff

State inspection types.

***

## Selectors

### Selector

4-byte function selector.

```typescript theme={null}
import * as Selector from "@voltaire/primitives/Selector";

Selector.fromSignature("transfer(address,uint256)");  // "0xa9059cbb"
```

### FunctionSignature / EventSignature / ErrorSignature

Full signatures for ABI items.

***

## Proxy Types

### Proxy

ERC-1167 minimal proxy utilities.

```typescript theme={null}
import * as Proxy from "@voltaire/primitives/Proxy";

Proxy.isMinimalProxy(bytecode);
Proxy.getImplementation(bytecode);  // Extract implementation address
Proxy.create(implementationAddress); // Generate proxy bytecode
```

***

## Data Structures

### BloomFilter

2048-bit bloom filter for log filtering.

```typescript theme={null}
import * as BloomFilter from "@voltaire/primitives/BloomFilter";

BloomFilter.add(bloom, topic);
BloomFilter.contains(bloom, topic);
BloomFilter.merge(bloom1, bloom2);
```

### BinaryTree

Binary tree utilities for Merkle proofs.

```typescript theme={null}
import * as BinaryTree from "@voltaire/primitives/BinaryTree";

BinaryTree.root(leaves);
BinaryTree.proof(leaves, index);
BinaryTree.verify(root, leaf, proof, index);
```

***

## Complete Primitive Count

| Category            | Count      |
| ------------------- | ---------- |
| Core types          | 6          |
| Numeric             | 12         |
| Encoding            | 4          |
| Transaction         | 5          |
| Block               | 6          |
| Receipt/Logs        | 8          |
| EVM                 | 15         |
| Protocol            | 8          |
| Signature           | 4          |
| Standards           | 6          |
| Account Abstraction | 6          |
| Beacon Chain        | 5          |
| Tracing             | 10         |
| Selectors           | 4          |
| Data Structures     | 3          |
| **Total**           | **\~100+** |