@tevm/voltaire / primitives/State

primitives/State

Type Aliases

StorageKeyLike

StorageKeyLike = StorageKeyType | { address: AddressType; slot: bigint; }

Defined in: src/primitives/State/StorageKeyType.ts:57 Inputs that can be converted to StorageKeyType

StorageKeyType

StorageKeyType = object

Defined in: src/primitives/State/StorageKeyType.ts:35 Composite key for EVM storage operations combining address and slot. The StorageKey uniquely identifies a storage location within the EVM by combining a contract address with a 256-bit storage slot number. This is fundamental to how the EVM organizes persistent contract storage.

Design Rationale

Each smart contract has its own isolated storage space addressed by 256-bit slots. To track storage across multiple contracts in a single VM instance, we need a composite key that includes both the contract address and the slot number.

Storage Model

In the EVM:

Each contract has 2^256 storage slots
Each slot can store a 256-bit value
Slots are initially zero and only consume gas when first written

Example

const key: StorageKeyType = {
  address: myContractAddress,
  slot: 0n, // First storage slot
};

// Use in maps for storage tracking
const storage = new Map<string, bigint>();
const keyStr = StorageKey.toString(key);
storage.set(keyStr, value);

Properties

address

readonly address: AddressType

Defined in: src/primitives/State/StorageKeyType.ts:40 The contract address that owns this storage slot. Standard 20-byte Ethereum address.

slot

readonly slot: bigint

Defined in: src/primitives/State/StorageKeyType.ts:46 The 256-bit storage slot number within the contract’s storage space. Slots are sparsely allocated - most remain at zero value.

Variables

create()

const create: (address, slot) => StorageKeyType

Defined in: src/primitives/State/index.ts:15

Parameters

address

AddressType

slot

bigint

Returns

StorageKeyType

EMPTY_CODE_HASH

const EMPTY_CODE_HASH: HashType

Defined in: src/primitives/State/constants.js:21 Hash of empty EVM bytecode (Keccak256 of empty bytes). This is a well-known constant in Ethereum representing the Keccak256 hash of an empty byte array. It’s used to identify accounts with no associated contract code. Value: Keccak256("") = 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Example

import { EMPTY_CODE_HASH } from './primitives/State/index.js';
if (codeHash.equals(EMPTY_CODE_HASH)) {
  // Account has no code
}

EMPTY_TRIE_ROOT

const EMPTY_TRIE_ROOT: HashType

Defined in: src/primitives/State/constants.js:50 Root hash of an empty Merkle Patricia Trie. This is the root hash of an empty trie structure in Ethereum, used as the initial value for account storage roots and state roots when they contain no data. Value: Keccak256(RLP(null)) = 0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Example

import { EMPTY_TRIE_ROOT } from './primitives/State/index.js';
if (storageRoot.equals(EMPTY_TRIE_ROOT)) {
  // Account has no storage
}

equals()

const equals: (a, b) => boolean

Defined in: src/primitives/State/index.ts:24

Parameters

a

StorageKeyLike

b

StorageKeyLike

Returns

boolean

from()

const from: (value) => StorageKeyType

Defined in: src/primitives/State/index.ts:20

Parameters

value

StorageKeyLike

Returns

StorageKeyType

fromString()

const fromString: (str) => StorageKeyType | undefined

Defined in: src/primitives/State/index.ts:32

Parameters

str

string

Returns

StorageKeyType | undefined

hashCode()

const hashCode: (key) => number

Defined in: src/primitives/State/index.ts:36

Parameters

key

StorageKeyLike

Returns

number

is()

const is: (value) => value is StorageKeyType

Defined in: src/primitives/State/index.ts:22

Parameters

value

unknown

Returns

value is StorageKeyType

StorageKey

const StorageKey: object

Defined in: src/primitives/State/index.ts:50

Type Declaration

create()

create: (address, slot) => StorageKeyType

Parameters

address

AddressType

slot

bigint

Returns

StorageKeyType

equals()

equals: (a, b) => boolean

Parameters

a

StorageKeyLike

b

StorageKeyLike

Returns

boolean

from()

from: (value) => StorageKeyType

Parameters

value

StorageKeyLike

Returns

StorageKeyType

fromString()

fromString: (str) => StorageKeyType | undefined

Parameters

str

string

Returns

StorageKeyType | undefined

hashCode()

hashCode: (key) => number

Parameters

key

StorageKeyLike

Returns

number

is()

is: (value) => value is StorageKeyType

Parameters

value

unknown

Returns

value is StorageKeyType

toString()

toString: (key) => string

Parameters

key

StorageKeyLike

Returns

string

toString()

const toString: (key) => string

Defined in: src/primitives/State/index.ts:30

Parameters

key

StorageKeyLike

Returns

string

Functions

_create()

_create(address, slot): StorageKeyType

Defined in: src/primitives/State/create.js:18 Create a new StorageKey

Parameters

address

AddressType Contract address

slot

bigint Storage slot number

Returns

StorageKeyType A new StorageKey

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Throws

Example

import * as State from './primitives/State/index.js';
import * as Address from './primitives/Address/index.js';
const contractAddr = Address.fromHex('0x...');
const key = State.create(contractAddr, 0n);

_equals()

_equals(a, b): boolean

Defined in: src/primitives/State/equals.js:23 Check equality between two storage keys. Two storage keys are equal if and only if both their address and slot number match exactly.

Parameters

a

StorageKeyLike First storage key

b

StorageKeyLike Second storage key

Returns

boolean True if both address and slot match

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Throws

Example

import * as State from './primitives/State/index.js';
const key1 = { address: addr, slot: 0n };
const key2 = { address: addr, slot: 0n };
State.equals(key1, key2); // true

_from()

_from(value): StorageKeyType

Defined in: src/primitives/State/from.js:15 Convert StorageKeyLike to StorageKey

Parameters

value

StorageKeyLike Value to convert

Returns

StorageKeyType StorageKey

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Throws

Example

import * as State from './primitives/State/index.js';
const key = State.from({ address: addr, slot: 0n });

_fromString()

_fromString(str): StorageKeyType | undefined

Defined in: src/primitives/State/fromString.js:18 Parse a StorageKey from its string representation

Parameters

str

string String representation from toString()

Returns

StorageKeyType | undefined Parsed StorageKey or undefined if invalid

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Throws

Example

import * as State from './primitives/State/index.js';
const key = State.fromString(str);
if (key) {
  // Use key
}

_hashCode()

_hashCode(key): number

Defined in: src/primitives/State/hashCode.js:17 Compute a hash code for the storage key for use in hash-based collections

Parameters

key

StorageKeyLike Storage key to hash

Returns

number Hash code as a number

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Throws

Example

import * as State from './primitives/State/index.js';
const hash = State.hashCode(key);

_is()

_is(value): value is StorageKeyType

Defined in: src/primitives/State/is.js:18 Type guard to check if a value is a valid StorageKey

Parameters

value

unknown Value to check

Returns

value is StorageKeyType True if value is a valid StorageKey

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Throws

Example

import * as State from './primitives/State/index.js';
const key = { address: addr, slot: 0n };
if (State.is(key)) {
  // key is StorageKey
}

_toString()

_toString(key): string

Defined in: src/primitives/State/toString.js:23 Convert StorageKey to a string representation for use as Map key The string format is: address_hex + ”_” + slot_hex

Parameters

key

StorageKeyLike Storage key to convert

Returns

string String representation (address_hex + ”_” + slot_hex)

See

https://voltaire.tevm.sh/primitives/state for State documentation

Since

0.0.0

Throws

Example

import * as State from './primitives/State/index.js';
const key = { address: addr, slot: 42n };
const str = State.toString(key);
// Use as Map key
map.set(str, value);

StorageKeyFactory()

StorageKeyFactory(address, slot): StorageKeyType

Defined in: src/primitives/State/index.ts:63 Factory function for creating StorageKey instances

Parameters

address

AddressType

slot

bigint

Returns

StorageKeyType

References

default

Renames and re-exports StorageKeyFactory

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

​primitives/State

​Type Aliases

​StorageKeyLike

​StorageKeyType

​Design Rationale

​Storage Model

​Example

​Properties

address

slot

​Variables

​create()

​Parameters

address

slot

​Returns

​EMPTY_CODE_HASH

​See

​Since

​Example

​EMPTY_TRIE_ROOT

​See

​Since

​Example

​equals()

​Parameters

a

b

​Returns

​from()

​Parameters

value

​Returns

​fromString()

​Parameters

str

​Returns

​hashCode()

​Parameters

key

​Returns

​is()

​Parameters

value

​Returns

​StorageKey

​Type Declaration

create()

Parameters

address

slot

Returns

equals()

Parameters

a

b

Returns

from()

Parameters

value

Returns

fromString()

Parameters

str

primitives/State

Type Aliases

StorageKeyLike

StorageKeyType

Design Rationale

Storage Model

Example

Properties

Variables

create()

Parameters

Returns

EMPTY_CODE_HASH

See

Since

Example

EMPTY_TRIE_ROOT

See

Since

Example

equals()

Parameters

Returns

from()

Parameters

Returns

fromString()

Parameters

Returns

hashCode()

Parameters

Returns

is()

Parameters

Returns

StorageKey

Type Declaration

toString()

Parameters

Returns

Functions

_create()

Parameters

Returns

See

Since

Throws

Example

_equals()

Parameters

Returns

See

Since

Throws

Example

_from()

Parameters

Returns

See

Since

Throws

Example

_fromString()

Parameters

Returns

See

Since

Throws

Example

_hashCode()

Parameters

Returns

See

Since

Throws

Example

_is()

Parameters

Returns

See