Struct SlotObservationTracker 

pub struct SlotObservationTracker { /* private fields */ }

Tracks per-slot change frequency to drive intelligent purge decisions.

Before purging a slot, check should_refetch(). Slots that rarely change are kept in the EVM cache, avoiding unnecessary RPC calls. On simulation revert, take_skipped() returns all slots that were kept, allowing a full-refresh fallback.

Implementations

impl SlotObservationTracker

pub fn new() -> Self

Create an empty tracker with no recorded observations.

pub fn load(path: &Path) -> Self

Load persisted observations from disk (versioned binary format).

Returns a fresh tracker if the file doesn’t exist, has an unrecognized magic/version header, or can’t be decoded. Legacy unversioned bincode is treated as a cache miss.

pub fn save(&mut self, path: &Path) -> Result<(), PersistenceError>

Persist observations to disk using the versioned binary format. Called at end of cycle or on shutdown.

pub fn should_refetch( &self, addr: Address, slot: U256, now: u64, params: &FreshnessParams, ) -> bool

Core decision: should we re-fetch this slot from RPC?

Returns true if the slot should be purged and re-fetched. Returns false if the cached value is likely still valid.

now is the current clock value (block number or unix seconds) and params carries the (clock-unit) thresholds — see crate::freshness::FreshnessParams.

The heuristic is fully deterministic (no randomness): a never-observed slot always refetches, as does one with fewer than min_observations; once enough observations accrue, a never-changed slot is reused until the max_reuse window elapses, while changing slots refetch once the probabilistic expected-change estimate crosses staleness_threshold.

Examples

The deterministic threshold edges around a stable (never-changed) slot:

use alloy_primitives::{Address, U256};
use evm_fork_cache::cache::SlotObservationTracker;
use evm_fork_cache::freshness::FreshnessParams;

let params = FreshnessParams::default();
let mut tracker = SlotObservationTracker::new();
let addr = Address::repeat_byte(0x01);
let slot = U256::from(0);

// An unobserved slot must always be fetched.
assert!(tracker.should_refetch(addr, slot, 0, &params));

// Record fewer than `min_observations` of the same value: still refetches
// because there is not enough data to trust the change frequency.
for now in 0..(params.min_observations - 1) {
    tracker.observe(addr, slot, U256::from(42), now as u64);
}
assert!(tracker.should_refetch(addr, slot, params.min_observations as u64, &params));

// One more identical observation reaches `min_observations`; the slot has
// never changed, so within the reuse window it is now reused (no refetch).
let last = params.min_observations as u64 - 1;
tracker.observe(addr, slot, U256::from(42), last);
assert!(!tracker.should_refetch(addr, slot, last, &params));

pub fn observe( &mut self, addr: Address, slot: U256, value: U256, now: u64, ) -> bool

Record a fresh observation after re-fetch or injection.

now is the current clock value (block number or unix seconds). Returns true if the value changed from the last observation.

pub fn record_skip(&mut self, addr: Address, slot: U256)

Record that a slot was skipped (not purged) this cycle. Used for revert fallback: if simulation fails, these slots need re-fetching.

pub fn take_skipped(&mut self) -> Vec<(Address, U256)>

Take all slots skipped this cycle (for revert recovery). Clears the internal list.

pub fn reset_contract(&mut self, addr: Address)

Reset all observations for a contract address. Called after a simulation revert to force full refresh next cycle.

pub fn begin_cycle(&mut self)

Clear cycle-specific state. Call at the start of each cycle.

pub fn len(&self) -> usize

Number of tracked slot observations.

pub fn is_empty(&self) -> bool

Returns true if no slots are being tracked.

pub fn last_value(&self, addr: Address, slot: U256) -> Option<U256>

Returns the last observed value for a slot, if any.

Trait Implementations

impl Default for SlotObservationTracker

fn default() -> Self

Returns the “default value” for a type.