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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

import * as AccessList from "@voltaire/primitives/AccessList";

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

Authorization

EIP-7702 authorization for account abstraction.

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

import * as Blob from "@voltaire/primitives/Blob";

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

---

Block Types

Block

Complete block structure.

import * as Block from "@voltaire/primitives/Block";

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

BlockHeader

Block header fields.

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.

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.

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.

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.

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.

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.

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.

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.

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.

import * as Chain from "@voltaire/primitives/Chain";

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

ChainId / NetworkId

Network identifiers.

import * as ChainId from "@voltaire/primitives/ChainId";

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

Hardfork

Ethereum hardfork enum and feature detection.

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.

import * as FeeMarket from "@voltaire/primitives/FeeMarket";

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

Denomination

Wei/Gwei/Ether conversions.

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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+