Enum StateUpdate 

#[non_exhaustive]
pub enum StateUpdate {
    Slot {
        address: Address,
        slot: U256,
        value: U256,
    },
    SlotDelta {
        address: Address,
        slot: U256,
        delta: SlotDelta,
    },
    BalanceDelta {
        address: Address,
        delta: SlotDelta,
    },
    SlotMasked {
        address: Address,
        slot: U256,
        mask: U256,
        value: U256,
    },
    Account {
        address: Address,
        patch: AccountPatch,
    },
    AccountUpsert {
        address: Address,
        patch: AccountPatch,
    },
    Purge {
        address: Address,
        scope: PurgeScope,
    },
}

A single targeted mutation to cached EVM state.

The vocabulary an event decoder (Phase 4) emits and EvmCache::apply_update consumes. Generic: carries no protocol or event knowledge.

The enum is #[non_exhaustive]: new variants (e.g. a code-only convenience) may be added pre-1.0 without a breaking change.

use alloy_primitives::{Address, U256};
use evm_fork_cache::{AccountPatch, PurgeScope, StateUpdate};

let contract = Address::repeat_byte(0x01);

// A storage-slot write (authoritative across both cache layers).
let slot = StateUpdate::slot(contract, U256::from(0), U256::from(42));

// A balance-only account patch (nonce and code left untouched).
let bal = StateUpdate::balance(contract, U256::from(1_000));
assert_eq!(
    bal,
    StateUpdate::Account { address: contract, patch: AccountPatch::default().balance(U256::from(1_000)) },
);

// Drop just two storage slots so the next read re-fetches them.
let purge = StateUpdate::purge(contract, PurgeScope::Slots(vec![U256::from(0), U256::from(1)]));

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Slot

Set one storage slot to value, authoritative across both cache layers.

Fields

address: Address

Contract whose storage is written.

slot: U256

Storage slot key.

value: U256

New slot value.

SlotDelta

Apply a relative (saturating) mutation to one storage slot.

Read-modify-write: the current value is read, the SlotDelta applied, and the result written back through both layers. Cold-aware — a delta on a slot absent from both layers is not applied; it is surfaced in StateDiff::skipped instead (see the module docs).

Fields

address: Address

Contract whose storage is written.

slot: U256

Storage slot key.

delta: SlotDelta

The relative, saturating mutation to apply to the current value.

BalanceDelta

Apply a relative (saturating) mutation to an account’s native balance.

Read-modify-write: the current AccountInfo::balance is read, the SlotDelta applied, and the result written back through both layers (nonce and code preserved). Cold-aware — “cold” here means the account’s info is unknown to the EVM: absent from both layers, or present in the overlay as revm NotExisting (which the internal account read also treats as cold, mirroring DbAccount::info()). A BalanceDelta on a cold account is not applied; it is surfaced in StateDiff::skipped_balances instead (so no default account is materialized to mask the real on-chain one — see the module docs).

Fields

address: Address

Account whose native balance is mutated.

delta: SlotDelta

The relative, saturating mutation to apply to the current balance.

SlotMasked

Set only the mask bits of a storage slot to the corresponding bits of value, preserving the rest: new = (old & !mask) | (value & mask).

A masked read-modify-write: it lets a pure decoder express a partial update to a packed storage word without knowing or clobbering the bits it does not own.

Cold-aware — a masked write to a slot absent from both cache layers is not applied (the un-masked bits are unknown, so the result cannot be computed); it is surfaced in StateDiff::skipped_masks as a SkippedMask instead. A masked write with mask == U256::MAX equals an absolute Slot write on a hot slot, but still skips on a cold one (unlike Slot, which writes unconditionally). Use Slot for an unconditional absolute write; use SlotMasked when neighbouring bits must be preserved.

Fields

address: Address

Contract whose storage is written.

slot: U256

Storage slot key.

mask: U256

Which bits of the slot to overwrite (1 = take from value).

value: U256

The bits to write (only the bits selected by mask are applied).

Account

Patch an already-known account’s balance/nonce/code (partial — see AccountPatch).

Cold-aware: if the account’s info is unknown to the EVM (absent from both layers, or present in the overlay as revm NotExisting), the patch is not applied and is surfaced in StateDiff::skipped_accounts as a SkippedAccountPatch. Use StateUpdate::AccountUpsert when materializing a cold/default account is intentional.

Fields

address: Address

Account to patch.

patch: AccountPatch

The partial mutation: each Some field overwrites, None leaves it.

AccountUpsert

Apply an AccountPatch, materializing a cold account when needed.

This is the explicit escape hatch for callers that really do want a default account to become authoritative in the backend (for example a synthetic test account). Normal event-derived account patches should use StateUpdate::Account so a cold account is skipped instead of masking a future RPC fetch.

Fields

address: Address

Account to patch or create.

patch: AccountPatch

The partial mutation: each Some field overwrites, None leaves it.

Purge

Purge cached state for address at scope; the next read re-fetches.

Fields

address: Address

Account whose cached state is purged.

scope: PurgeScope

What part of the cached state to remove.

Implementations

impl StateUpdate

pub fn slot(address: Address, slot: U256, value: U256) -> Self

Construct a StateUpdate::Slot that sets (address, slot) to value.

pub fn slot_delta(address: Address, slot: U256, delta: SlotDelta) -> Self

Construct a StateUpdate::SlotDelta that applies delta relative to the current value of (address, slot).

pub fn slot_masked( address: Address, slot: U256, mask: U256, value: U256, ) -> Self

Construct a StateUpdate::SlotMasked that sets only the mask bits of (address, slot) to the corresponding bits of value.

pub fn balance_delta(address: Address, delta: SlotDelta) -> Self

Construct a StateUpdate::BalanceDelta that applies delta relative to the account’s current native balance.

pub fn balance(address: Address, value: U256) -> Self

Construct a StateUpdate::Account that patches only the balance.

pub fn nonce(address: Address, nonce: u64) -> Self

Construct a StateUpdate::Account that patches only the nonce.

pub fn code(address: Address, code: Bytes) -> Self

Construct a StateUpdate::Account that patches only the runtime code (the code hash is recomputed from code when applied).

pub fn account(address: Address, patch: AccountPatch) -> Self

Construct a StateUpdate::Account from a prebuilt AccountPatch.

pub fn account_upsert(address: Address, patch: AccountPatch) -> Self

Construct a StateUpdate::AccountUpsert from a prebuilt AccountPatch.

Use this only when materializing an account absent from both layers is the desired behavior. For normal patches to known accounts, use account.

pub fn purge(address: Address, scope: PurgeScope) -> Self

Construct a StateUpdate::Purge for address at scope.

Trait Implementations

impl Clone for StateUpdate

fn clone(&self) -> StateUpdate

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StateUpdate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StateUpdate

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for StateUpdate

impl PartialEq for StateUpdate

fn eq(&self, other: &StateUpdate) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for StateUpdate

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for StateUpdate