AccessList - Voltaire

Access lists (EIP-2930) specify which addresses and storage slots a transaction will access, enabling gas savings by pre-warming these locations before execution.

Overview

AccessList is a branded array type representing EIP-2930 access lists. Each entry contains a contract address and the storage keys that will be accessed at that address.

Type Definition
Gas Constants

export type Item = {
  address: AddressType;
  storageKeys: readonly HashType[];
};

export type BrandedAccessList = readonly Item[] & {
  readonly __brand?: typeof accessListSymbol;
};

// EIP-2930 costs
ADDRESS_COST = 2400n;           // Per address in access list
STORAGE_KEY_COST = 1900n;       // Per storage key in access list

// Cold access costs (without access list)
COLD_ACCOUNT_ACCESS_COST = 2600n;
COLD_STORAGE_ACCESS_COST = 2100n;

// Warm access cost (after first access)
WARM_STORAGE_ACCESS_COST = 100n;

Quick Start

Create Access List
Calculate Gas Savings
Build Incrementally

import * as AccessList from '@tevm/voltaire/AccessList';
import * as Address from '@tevm/voltaire/Address';
import * as Hash from '@tevm/voltaire/Hash';

// Create empty access list
const empty = AccessList.create();

// Create from items
const list = AccessList.from([
  {
    address: Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"),
    storageKeys: [
      Hash("0x0000000000000000000000000000000000000000000000000000000000000001"),
      Hash("0x0000000000000000000000000000000000000000000000000000000000000002"),
    ]
  }
]);

import * as AccessList from '@tevm/voltaire/AccessList';

const list = AccessList.from([
  { address, storageKeys: [key1, key2] }
]);

// Calculate total access list cost
const cost = AccessList.gasCost(list);
// = ADDRESS_COST + (2 * STORAGE_KEY_COST)
// = 2400n + 3800n = 6200n

// Calculate net savings vs cold access
const savings = AccessList.gasSavings(list);
// Savings per address: 2600n - 2400n = 200n
// Savings per key: 2100n - 1900n = 200n
// Total: 200n + (2 * 200n) = 600n

// Check if access list is beneficial
if (AccessList.hasSavings(list)) {
  // Include access list in transaction
}

import * as AccessList from '@tevm/voltaire/AccessList';

let list = AccessList.create();

// Add addresses
list = AccessList.withAddress(list, contractAddress);
list = AccessList.withAddress(list, tokenAddress);

// Add storage keys for specific address
list = AccessList.withStorageKey(list, contractAddress, slot0);
list = AccessList.withStorageKey(list, contractAddress, slot1);

// Merge multiple access lists
const merged = AccessList.merge(list1, list2, list3);

API Reference

Constructors

Method	Description
`create()`	Create empty access list
`from(items \| bytes)`	Create from array of items or RLP bytes
`fromBytes(bytes)`	Decode from RLP-encoded bytes

Gas Calculation

Method	Description
`gasCost(list)`	Total gas cost of access list itself
`gasSavings(list)`	Net gas savings vs cold access
`hasSavings(list)`	Returns `true` if access list saves gas

Queries

Method	Description
`includesAddress(list, address)`	Check if address is in list
`includesStorageKey(list, address, key)`	Check if storage key is accessible
`keysFor(list, address)`	Get all storage keys for address
`addressCount(list)`	Count of addresses in list
`storageKeyCount(list)`	Total storage keys across all addresses
`isEmpty(list)`	Check if list has no entries

Manipulation

Method	Description
`withAddress(list, address)`	Add address (returns new list)
`withStorageKey(list, address, key)`	Add storage key (returns new list)
`merge(...lists)`	Combine multiple access lists
`deduplicate(list)`	Remove duplicate addresses and keys

Validation & Conversion

Method	Description
`is(value)`	Type guard for AccessList
`isItem(value)`	Type guard for AccessList Item
`assertValid(list)`	Throws if list is invalid
`toBytes(list)`	RLP-encode to bytes

Constants

Constant	Value	Description
`ADDRESS_COST`	`2400n`	Gas per address in access list
`STORAGE_KEY_COST`	`1900n`	Gas per storage key
`COLD_ACCOUNT_ACCESS_COST`	`2600n`	Gas for cold account access
`COLD_STORAGE_ACCESS_COST`	`2100n`	Gas for cold storage access
`WARM_STORAGE_ACCESS_COST`	`100n`	Gas for warm storage access

Practical Examples

Transaction with Access List

import * as AccessList from '@tevm/voltaire/AccessList';
import * as Transaction from '@tevm/voltaire/Transaction';
import * as Address from '@tevm/voltaire/Address';

// Build access list for Uniswap swap
const accessList = AccessList.from([
  {
    address: Address("0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45"), // Router
    storageKeys: []
  },
  {
    address: Address("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"), // WETH
    storageKeys: [
      Hash("0x..."), // balanceOf[sender]
      Hash("0x..."), // balanceOf[pair]
    ]
  },
  {
    address: Address("0x..."), // Token
    storageKeys: [
      Hash("0x..."), // balanceOf[sender]
      Hash("0x..."), // balanceOf[pair]
      Hash("0x..."), // allowance[sender][router]
    ]
  }
]);

// Verify savings before including
if (AccessList.hasSavings(accessList)) {
  const tx = Transaction.create({
    type: 1, // EIP-2930
    accessList,
    // ... other fields
  });
}

Merging Access Lists from Simulation

import * as AccessList from '@tevm/voltaire/AccessList';

// Simulate multiple calls and collect access lists
const swap1Access = await simulateSwap(tokenA, tokenB, amount1);
const swap2Access = await simulateSwap(tokenB, tokenC, amount2);

// Merge and deduplicate
const combined = AccessList.merge(swap1Access, swap2Access);

console.log(`Combined: ${AccessList.addressCount(combined)} addresses`);
console.log(`Storage keys: ${AccessList.storageKeyCount(combined)}`);
console.log(`Net savings: ${AccessList.gasSavings(combined)} gas`);

Finding Accessed Storage

import * as AccessList from '@tevm/voltaire/AccessList';

const list = AccessList.from(simulatedAccessList);

// Check if specific contract is accessed
if (AccessList.includesAddress(list, proxyContract)) {
  const keys = AccessList.keysFor(list, proxyContract);
  console.log(`Proxy accesses ${keys?.length ?? 0} storage slots`);
}

// Check for specific storage slot access
const balanceSlot = Hash("0x...");
if (AccessList.includesStorageKey(list, tokenContract, balanceSlot)) {
  console.log("Transaction reads token balance");
}

When to Use Access Lists

Access lists provide net gas savings when:

Multiple cold accesses: Accessing the same address/slot multiple times
Complex DeFi operations: Swaps, lending, multi-hop transactions
Batch operations: Multiple transfers or contract interactions
Contract calls with many SLOAD: Storage-heavy operations

The break-even point:

Address: Saves 200 gas per address (2600 - 2400)
Storage key: Saves 200 gas per key (2100 - 1900)

Use hasSavings() to verify before including in transactions.

RLP Encoding

Access lists encode as RLP for transaction serialization:

// Format: [[address, [storageKey1, storageKey2, ...]], ...]
const bytes = AccessList.toBytes(list);
const decoded = AccessList.fromBytes(bytes);

Transaction

Ethereum transactions with access list support

Address

Ethereum addresses for access list entries

Hash

32-byte storage keys

RLP

Recursive Length Prefix encoding

Documentation Index

​Overview

​Quick Start

​API Reference

​Constructors

​Gas Calculation

​Queries

​Manipulation

​Validation & Conversion

​Constants

​Practical Examples

​Transaction with Access List

​Merging Access Lists from Simulation

​Finding Accessed Storage

​When to Use Access Lists

​RLP Encoding

​Related