Skip to main content

sui_core/execution_cache/
writeback_cache.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! MemoryCache is a cache for the transaction execution which delays writes to the database until
5//! transaction results are certified (i.e. they appear in a certified checkpoint, or an effects cert
6//! is observed by a fullnode). The cache also stores committed data in memory in order to serve
7//! future reads without hitting the database.
8//!
9//! For storing uncommitted transaction outputs, we cannot evict the data at all until it is written
10//! to disk. Committed data not only can be evicted, but it is also unbounded (imagine a stream of
11//! transactions that keep splitting a coin into smaller coins).
12//!
13//! We also want to be able to support negative cache hits (i.e. the case where we can determine an
14//! object does not exist without hitting the database).
15//!
16//! To achieve both of these goals, we split the cache data into two pieces, a dirty set and a cached
17//! set. The dirty set has no automatic evictions, data is only removed after being committed. The
18//! cached set is in a bounded-sized cache with automatic evictions. In order to support negative
19//! cache hits, we treat the two halves of the cache as FIFO queue. Newly written (dirty) versions are
20//! inserted to one end of the dirty queue. As versions are committed to disk, they are
21//! removed from the other end of the dirty queue and inserted into the cache queue. The cache queue
22//! is truncated if it exceeds its maximum size, by removing all but the N newest versions.
23//!
24//! This gives us the property that the sequence of versions in the dirty and cached queues are the
25//! most recent versions of the object, i.e. there can be no "gaps". This allows for the following:
26//!
27//!   - Negative cache hits: If the queried version is not in memory, but is higher than the smallest
28//!     version in the cached queue, it does not exist in the db either.
29//!   - Bounded reads: When reading the most recent version that is <= some version bound, we can
30//!     correctly satisfy this query from the cache, or determine that we must go to the db.
31//!
32//! Note that at any time, either or both the dirty or the cached queue may be non-existent. There may be no
33//! dirty versions of the objects, in which case there will be no dirty queue. And, the cached queue
34//! may be evicted from the cache, in which case there will be no cached queue. Because only the cached
35//! queue can be evicted (the dirty queue can only become empty by moving versions from it to the cached
36//! queue), the "highest versions" property still holds in all cases.
37//!
38//! The above design is used for both objects and markers.
39
40use crate::accumulators::funds_read::AccountFundsRead;
41use crate::authority::AuthorityStore;
42use crate::authority::authority_per_epoch_store::AuthorityPerEpochStore;
43use crate::authority::authority_store::ExecutionLockWriteGuard;
44#[cfg(test)]
45use crate::authority::authority_store::{LockDetailsDeprecated, ObjectLockStatus, SuiLockResult};
46use crate::authority::authority_store_tables::LiveObject;
47use crate::authority::backpressure::BackpressureManager;
48use crate::authority::epoch_start_configuration::{EpochFlag, EpochStartConfiguration};
49use crate::fallback_fetch::do_fallback_lookup;
50use crate::global_state_hasher::GlobalStateHashStore;
51use crate::transaction_outputs::TransactionOutputs;
52
53use dashmap::DashMap;
54use dashmap::mapref::entry::Entry as DashMapEntry;
55use futures::{FutureExt, future::BoxFuture};
56use moka::sync::SegmentedCache as MokaCache;
57use mysten_common::ZipDebugEqIteratorExt;
58use mysten_common::debug_fatal;
59use mysten_common::random_util::randomize_cache_capacity_in_tests;
60use mysten_common::sync::notify_read::NotifyRead;
61use parking_lot::Mutex;
62use rayon::prelude::*;
63use std::collections::{BTreeMap, HashSet};
64use std::hash::Hash;
65use std::sync::Arc;
66use std::sync::atomic::AtomicU64;
67use std::time::Instant;
68use sui_config::ExecutionCacheConfig;
69use sui_macros::fail_point;
70use sui_protocol_config::ProtocolVersion;
71use sui_types::SUI_ACCUMULATOR_ROOT_OBJECT_ID;
72use sui_types::accumulator_event::AccumulatorEvent;
73use sui_types::accumulator_root::{AccumulatorObjId, AccumulatorValue};
74use sui_types::base_types::{
75    ConsensusObjectVersion, EpochId, FullObjectID, ObjectID, ObjectRef, SequenceNumber,
76    VerifiedExecutionData,
77};
78use sui_types::bridge::{Bridge, get_bridge};
79use sui_types::digests::{ObjectDigest, TransactionDigest, TransactionEffectsDigest};
80use sui_types::effects::{TransactionEffects, TransactionEvents};
81#[cfg(test)]
82use sui_types::error::SuiError;
83use sui_types::error::{SuiErrorKind, SuiResult, UserInputError};
84use sui_types::executable_transaction::VerifiedExecutableTransaction;
85use sui_types::global_state_hash::GlobalStateHash;
86use sui_types::message_envelope::Message;
87use sui_types::messages_checkpoint::CheckpointSequenceNumber;
88use sui_types::object::Object;
89use sui_types::storage::{
90    FullObjectKey, InputKey, MarkerValue, ObjectKey, ObjectOrTombstone, ObjectStore, PackageObject,
91};
92use sui_types::sui_system_state::{SuiSystemState, get_sui_system_state};
93use sui_types::transaction::{TransactionDataAPI, VerifiedTransaction};
94use tap::TapOptional;
95use tracing::{debug, info, instrument, trace, warn};
96
97use super::ExecutionCacheAPI;
98use super::FoundObjectOrTombstone;
99use super::cache_types::Ticket;
100use super::{
101    Batch, CheckpointCache, ExecutionCacheCommit, ExecutionCacheMetrics, ExecutionCacheReconfigAPI,
102    ExecutionCacheWrite, ObjectCacheRead, StateSyncAPI, TestingAPI, TransactionCacheRead,
103    cache_types::{CacheResult, CachedVersionMap, IsNewer, MonotonicCache},
104    implement_passthrough_traits,
105    object_locks::ObjectLocks,
106};
107
108#[cfg(test)]
109#[path = "unit_tests/writeback_cache_tests.rs"]
110pub mod writeback_cache_tests;
111
112#[cfg(test)]
113#[path = "unit_tests/notify_read_input_objects_tests.rs"]
114mod notify_read_input_objects_tests;
115
116#[derive(Clone, PartialEq, Eq)]
117enum ObjectEntry {
118    Object(Object),
119    Deleted,
120    Wrapped,
121}
122
123impl ObjectEntry {
124    #[cfg(test)]
125    fn unwrap_object(&self) -> &Object {
126        match self {
127            ObjectEntry::Object(o) => o,
128            _ => panic!("unwrap_object called on non-Object"),
129        }
130    }
131
132    fn is_tombstone(&self) -> bool {
133        match self {
134            ObjectEntry::Deleted | ObjectEntry::Wrapped => true,
135            ObjectEntry::Object(_) => false,
136        }
137    }
138
139    /// This entry as the entry of `object_id` at `version`: the object, or the tombstone of the
140    /// deletion or wrap at `version`.
141    fn into_object_or_tombstone(
142        self,
143        object_id: ObjectID,
144        version: SequenceNumber,
145    ) -> ObjectOrTombstone {
146        match self {
147            ObjectEntry::Object(object) => ObjectOrTombstone::Object(object),
148            ObjectEntry::Deleted => ObjectOrTombstone::Tombstone((
149                object_id,
150                version,
151                ObjectDigest::OBJECT_DIGEST_DELETED,
152            )),
153            ObjectEntry::Wrapped => ObjectOrTombstone::Tombstone((
154                object_id,
155                version,
156                ObjectDigest::OBJECT_DIGEST_WRAPPED,
157            )),
158        }
159    }
160}
161
162impl std::fmt::Debug for ObjectEntry {
163    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
164        match self {
165            ObjectEntry::Object(o) => {
166                write!(f, "ObjectEntry::Object({:?})", o.compute_object_reference())
167            }
168            ObjectEntry::Deleted => write!(f, "ObjectEntry::Deleted"),
169            ObjectEntry::Wrapped => write!(f, "ObjectEntry::Wrapped"),
170        }
171    }
172}
173
174impl From<Object> for ObjectEntry {
175    fn from(object: Object) -> Self {
176        ObjectEntry::Object(object)
177    }
178}
179
180impl From<ObjectOrTombstone> for ObjectEntry {
181    fn from(object: ObjectOrTombstone) -> Self {
182        match object {
183            ObjectOrTombstone::Object(o) => o.into(),
184            ObjectOrTombstone::Tombstone(obj_ref) => {
185                if obj_ref.2.is_deleted() {
186                    ObjectEntry::Deleted
187                } else if obj_ref.2.is_wrapped() {
188                    ObjectEntry::Wrapped
189                } else {
190                    panic!("tombstone digest must either be deleted or wrapped");
191                }
192            }
193        }
194    }
195}
196
197#[derive(Debug, Clone, PartialEq, Eq)]
198enum LatestObjectCacheEntry {
199    Object(SequenceNumber, ObjectEntry),
200    NonExistent,
201}
202
203impl LatestObjectCacheEntry {
204    #[cfg(test)]
205    fn version(&self) -> Option<SequenceNumber> {
206        match self {
207            LatestObjectCacheEntry::Object(version, _) => Some(*version),
208            LatestObjectCacheEntry::NonExistent => None,
209        }
210    }
211
212    fn is_alive(&self) -> bool {
213        match self {
214            LatestObjectCacheEntry::Object(_, entry) => !entry.is_tombstone(),
215            LatestObjectCacheEntry::NonExistent => false,
216        }
217    }
218}
219
220impl IsNewer for LatestObjectCacheEntry {
221    fn is_newer_than(&self, other: &LatestObjectCacheEntry) -> bool {
222        match (self, other) {
223            (LatestObjectCacheEntry::Object(v1, _), LatestObjectCacheEntry::Object(v2, _)) => {
224                v1 > v2
225            }
226            (LatestObjectCacheEntry::Object(_, _), LatestObjectCacheEntry::NonExistent) => true,
227            _ => false,
228        }
229    }
230}
231
232type MarkerKey = (EpochId, FullObjectID);
233
234/// UncommittedData stores execution outputs that are not yet written to the db. Entries in this
235/// struct can only be purged after they are committed.
236struct UncommittedData {
237    /// The object dirty set. All writes go into this table first. After we flush the data to the
238    /// db, the data is removed from this table and inserted into the object_cache.
239    ///
240    /// This table may contain both live and dead objects, since we flush both live and dead
241    /// objects to the db in order to support past object queries on fullnodes.
242    ///
243    /// Further, we only remove objects in FIFO order, which ensures that the cached
244    /// sequence of objects has no gaps. In other words, if we have versions 4, 8, 13 of
245    /// an object, we can deduce that version 9 does not exist. This also makes child object
246    /// reads efficient. `object_cache` cannot contain a more recent version of an object than
247    /// `objects`, and neither can have any gaps. Therefore if there is any object <= the version
248    /// bound for a child read in objects, it is the correct object to return.
249    objects: DashMap<ObjectID, CachedVersionMap<ObjectEntry>>,
250
251    // Markers for received objects and deleted shared objects. This contains all of the dirty
252    // marker state, which is committed to the db at the same time as other transaction data.
253    // After markers are committed to the db we remove them from this table and insert them into
254    // marker_cache.
255    markers: DashMap<MarkerKey, CachedVersionMap<MarkerValue>>,
256
257    transaction_effects: DashMap<TransactionEffectsDigest, TransactionEffects>,
258
259    transaction_events: DashMap<TransactionDigest, TransactionEvents>,
260
261    unchanged_loaded_runtime_objects: DashMap<TransactionDigest, Vec<ObjectKey>>,
262
263    executed_effects_digests: DashMap<TransactionDigest, TransactionEffectsDigest>,
264
265    // Transaction outputs that have not yet been written to the DB. Items are removed from this
266    // table as they are flushed to the db.
267    pending_transaction_writes: DashMap<TransactionDigest, Arc<TransactionOutputs>>,
268
269    total_transaction_inserts: AtomicU64,
270    total_transaction_commits: AtomicU64,
271}
272
273impl UncommittedData {
274    fn new() -> Self {
275        Self {
276            objects: DashMap::with_shard_amount(2048),
277            markers: DashMap::with_shard_amount(2048),
278            transaction_effects: DashMap::with_shard_amount(2048),
279            executed_effects_digests: DashMap::with_shard_amount(2048),
280            pending_transaction_writes: DashMap::with_shard_amount(2048),
281            transaction_events: DashMap::with_shard_amount(2048),
282            unchanged_loaded_runtime_objects: DashMap::with_shard_amount(2048),
283            total_transaction_inserts: AtomicU64::new(0),
284            total_transaction_commits: AtomicU64::new(0),
285        }
286    }
287
288    fn clear(&self) {
289        self.objects.clear();
290        self.markers.clear();
291        self.transaction_effects.clear();
292        self.executed_effects_digests.clear();
293        self.pending_transaction_writes.clear();
294        self.transaction_events.clear();
295        self.unchanged_loaded_runtime_objects.clear();
296        self.total_transaction_inserts
297            .store(0, std::sync::atomic::Ordering::Relaxed);
298        self.total_transaction_commits
299            .store(0, std::sync::atomic::Ordering::Relaxed);
300    }
301
302    fn is_empty(&self) -> bool {
303        let empty = self.pending_transaction_writes.is_empty();
304        if empty && cfg!(debug_assertions) {
305            assert!(
306                self.objects.is_empty()
307                    && self.markers.is_empty()
308                    && self.transaction_effects.is_empty()
309                    && self.executed_effects_digests.is_empty()
310                    && self.transaction_events.is_empty()
311                    && self.unchanged_loaded_runtime_objects.is_empty()
312                    && self
313                        .total_transaction_inserts
314                        .load(std::sync::atomic::Ordering::Relaxed)
315                        == self
316                            .total_transaction_commits
317                            .load(std::sync::atomic::Ordering::Relaxed),
318            );
319        }
320        empty
321    }
322}
323
324// Point items (anything without a version number) can be negatively cached as None
325type PointCacheItem<T> = Option<T>;
326
327// PointCacheItem can only be used for insert-only collections, so a Some entry
328// is always newer than a None entry.
329impl<T: Eq + std::fmt::Debug> IsNewer for PointCacheItem<T> {
330    fn is_newer_than(&self, other: &PointCacheItem<T>) -> bool {
331        match (self, other) {
332            (Some(_), None) => true,
333
334            (Some(a), Some(b)) => {
335                // conflicting inserts should never happen
336                debug_assert_eq!(a, b);
337                false
338            }
339
340            _ => false,
341        }
342    }
343}
344
345/// CachedData stores data that has been committed to the db, but is likely to be read soon.
346struct CachedCommittedData {
347    // See module level comment for an explanation of caching strategy.
348    object_cache: MokaCache<ObjectID, Arc<Mutex<CachedVersionMap<ObjectEntry>>>>,
349
350    // See module level comment for an explanation of caching strategy.
351    marker_cache: MokaCache<MarkerKey, Arc<Mutex<CachedVersionMap<MarkerValue>>>>,
352
353    transactions: MonotonicCache<TransactionDigest, PointCacheItem<Arc<VerifiedTransaction>>>,
354
355    transaction_effects:
356        MonotonicCache<TransactionEffectsDigest, PointCacheItem<Arc<TransactionEffects>>>,
357
358    transaction_events: MonotonicCache<TransactionDigest, PointCacheItem<Arc<TransactionEvents>>>,
359
360    executed_effects_digests:
361        MonotonicCache<TransactionDigest, PointCacheItem<TransactionEffectsDigest>>,
362
363    transaction_executed_in_last_epoch:
364        MonotonicCache<(EpochId, TransactionDigest), PointCacheItem<()>>,
365
366    // Objects that were read at transaction signing time - allows us to access them again at
367    // execution time with a single lock / hash lookup
368    _transaction_objects: MokaCache<TransactionDigest, Vec<Object>>,
369}
370
371impl CachedCommittedData {
372    fn new(config: &ExecutionCacheConfig) -> Self {
373        let object_cache = MokaCache::builder(8)
374            .max_capacity(randomize_cache_capacity_in_tests(
375                config.object_cache_size(),
376            ))
377            .build();
378        let marker_cache = MokaCache::builder(8)
379            .max_capacity(randomize_cache_capacity_in_tests(
380                config.marker_cache_size(),
381            ))
382            .build();
383
384        let transactions = MonotonicCache::new(randomize_cache_capacity_in_tests(
385            config.transaction_cache_size(),
386        ));
387        let transaction_effects = MonotonicCache::new(randomize_cache_capacity_in_tests(
388            config.effect_cache_size(),
389        ));
390        let transaction_events = MonotonicCache::new(randomize_cache_capacity_in_tests(
391            config.events_cache_size(),
392        ));
393        let executed_effects_digests = MonotonicCache::new(randomize_cache_capacity_in_tests(
394            config.executed_effect_cache_size(),
395        ));
396
397        let transaction_objects = MokaCache::builder(8)
398            .max_capacity(randomize_cache_capacity_in_tests(
399                config.transaction_objects_cache_size(),
400            ))
401            .build();
402
403        let transaction_executed_in_last_epoch = MonotonicCache::new(
404            randomize_cache_capacity_in_tests(config.executed_effect_cache_size()),
405        );
406
407        Self {
408            object_cache,
409            marker_cache,
410            transactions,
411            transaction_effects,
412            transaction_events,
413            executed_effects_digests,
414            transaction_executed_in_last_epoch,
415            _transaction_objects: transaction_objects,
416        }
417    }
418
419    fn clear_and_assert_empty(&self) {
420        self.object_cache.invalidate_all();
421        self.marker_cache.invalidate_all();
422        self.transactions.invalidate_all();
423        self.transaction_effects.invalidate_all();
424        self.transaction_events.invalidate_all();
425        self.executed_effects_digests.invalidate_all();
426        self.transaction_executed_in_last_epoch.invalidate_all();
427        self._transaction_objects.invalidate_all();
428
429        assert_empty(&self.object_cache);
430        assert_empty(&self.marker_cache);
431        assert!(self.transactions.is_empty());
432        assert!(self.transaction_effects.is_empty());
433        assert!(self.transaction_events.is_empty());
434        assert!(self.executed_effects_digests.is_empty());
435        assert!(self.transaction_executed_in_last_epoch.is_empty());
436        assert_empty(&self._transaction_objects);
437    }
438}
439
440fn assert_empty<K, V>(cache: &MokaCache<K, V>)
441where
442    K: std::hash::Hash + std::cmp::Eq + std::cmp::PartialEq + Send + Sync + 'static,
443    V: std::clone::Clone + std::marker::Send + std::marker::Sync + 'static,
444{
445    if cache.iter().next().is_some() {
446        panic!("cache should be empty");
447    }
448}
449
450pub struct WritebackCache {
451    dirty: UncommittedData,
452    cached: CachedCommittedData,
453
454    // We separately cache the latest version of each object. Although this seems
455    // redundant, it is the only way to support populating the cache after a read.
456    // We cannot simply insert objects that we read off the disk into `object_cache`,
457    // since that may violate the no-missing-versions property.
458    // `object_by_id_cache` is also written to on writes so that it is always coherent.
459    // Hence it contains both committed and dirty object data.
460    object_by_id_cache: MonotonicCache<ObjectID, LatestObjectCacheEntry>,
461
462    // The packages cache is treated separately from objects, because they are immutable and can be
463    // used by any number of transactions. Additionally, many operations require loading large
464    // numbers of packages (due to dependencies), so we want to try to keep all packages in memory.
465    //
466    // Also, this cache can contain packages that are dirty or committed, so it does not live in
467    // UncachedData or CachedCommittedData. The cache is populated in two ways:
468    // - when packages are written (in which case they will also be present in the dirty set)
469    // - after a cache miss. Because package IDs are unique (only one version exists for each ID)
470    //   we do not need to worry about the contiguous version property.
471    // - note that we removed any unfinalized packages from the cache during revert_state_update().
472    packages: MokaCache<ObjectID, PackageObject>,
473
474    object_locks: ObjectLocks,
475
476    executed_effects_digests_notify_read: NotifyRead<TransactionDigest, TransactionEffectsDigest>,
477    object_notify_read: NotifyRead<InputKey, ()>,
478
479    store: Arc<AuthorityStore>,
480    backpressure_threshold: u64,
481    backpressure_manager: Arc<BackpressureManager>,
482    metrics: Arc<ExecutionCacheMetrics>,
483}
484
485macro_rules! check_cache_entry_by_version {
486    ($self: ident, $table: expr, $level: expr, $cache: expr, $version: expr) => {
487        $self.metrics.record_cache_request($table, $level);
488        if let Some(cache) = $cache {
489            if let Some(entry) = cache.get(&$version) {
490                $self.metrics.record_cache_hit($table, $level);
491                return CacheResult::Hit(entry.clone());
492            }
493
494            if let Some(least_version) = cache.get_least() {
495                if least_version.0 < $version {
496                    // If the version is greater than the least version in the cache, then we know
497                    // that the object does not exist anywhere
498                    $self.metrics.record_cache_negative_hit($table, $level);
499                    return CacheResult::NegativeHit;
500                }
501            }
502        }
503        $self.metrics.record_cache_miss($table, $level);
504    };
505}
506
507macro_rules! check_cache_entry_by_latest {
508    ($self: ident, $table: expr, $level: expr, $cache: expr) => {
509        $self.metrics.record_cache_request($table, $level);
510        if let Some(cache) = $cache {
511            if let Some((version, entry)) = cache.get_highest() {
512                $self.metrics.record_cache_hit($table, $level);
513                return CacheResult::Hit((*version, entry.clone()));
514            } else {
515                panic!("empty CachedVersionMap should have been removed");
516            }
517        }
518        $self.metrics.record_cache_miss($table, $level);
519    };
520}
521
522impl WritebackCache {
523    /// Load an implicitly read system object at the requested version.
524    /// In normal execution, this function can block wait until the object is available at the requested version,
525    /// and it is guaranteed to return an object with the requested version.
526    /// In dry-runs, this function will never block wait, but may return None if the requested version was pruned by this point.
527    pub(crate) fn load_implicitly_read_system_object(
528        &self,
529        object_id: &ObjectID,
530        version: ConsensusObjectVersion,
531    ) -> Option<Object> {
532        assert!(
533            sui_types::IMPLICITLY_READ_SYSTEM_OBJECTS.contains(object_id),
534            "{object_id} is not an implicitly read system object"
535        );
536        let ConsensusObjectVersion {
537            initial_shared_version,
538            version,
539        } = version;
540        if let Some(object) = ObjectCacheRead::get_object_by_key(self, object_id, version) {
541            return Some(object);
542        }
543        self.metrics
544            .implicit_system_object_read_waits
545            .with_label_values(&[object_id.to_string().as_str()])
546            .inc();
547        let wait_start = Instant::now();
548        let key = InputKey::VersionedObject {
549            id: FullObjectID::Consensus((*object_id, initial_shared_version)),
550            version,
551        };
552        // Block wait until the object is available at the requested version.
553        // Note that before blocking, we check if the latest version already passed the requested version,
554        // if so it must imply that we have already produced the requested version.
555        // We are doing this check instead of exact version comparison to handle the rare case during
556        // dry-runs where the requested version was pruned by this point.
557        // Also note that in the case of dry-run, this will never block wait.
558        self.object_notify_read.read_one_blocking(
559            "load_implicitly_read_system_object",
560            &key,
561            |_key| {
562                ObjectCacheRead::get_object(self, object_id)
563                    .is_some_and(|latest| latest.version() >= version)
564                    .then_some(())
565            },
566        );
567        self.metrics
568            .implicit_system_object_read_wait_latency
569            .with_label_values(&[object_id.to_string().as_str()])
570            .observe(wait_start.elapsed().as_secs_f64());
571        ObjectCacheRead::get_object_by_key(self, object_id, version)
572    }
573
574    pub fn new(
575        config: &ExecutionCacheConfig,
576        store: Arc<AuthorityStore>,
577        metrics: Arc<ExecutionCacheMetrics>,
578        backpressure_manager: Arc<BackpressureManager>,
579    ) -> Self {
580        let packages = MokaCache::builder(8)
581            .max_capacity(randomize_cache_capacity_in_tests(
582                config.package_cache_size(),
583            ))
584            .build();
585        Self {
586            dirty: UncommittedData::new(),
587            cached: CachedCommittedData::new(config),
588            object_by_id_cache: MonotonicCache::new(randomize_cache_capacity_in_tests(
589                config.object_by_id_cache_size(),
590            )),
591            packages,
592            object_locks: ObjectLocks::new(),
593            executed_effects_digests_notify_read: NotifyRead::new(),
594            object_notify_read: NotifyRead::new(),
595            store,
596            backpressure_manager,
597            backpressure_threshold: config.backpressure_threshold(),
598            metrics,
599        }
600    }
601
602    pub fn new_for_tests(store: Arc<AuthorityStore>) -> Self {
603        Self::new(
604            &Default::default(),
605            store,
606            ExecutionCacheMetrics::new(&prometheus::Registry::new()).into(),
607            BackpressureManager::new_for_tests(),
608        )
609    }
610
611    #[cfg(test)]
612    pub fn reset_for_test(&mut self) {
613        let mut new = Self::new(
614            &Default::default(),
615            self.store.clone(),
616            self.metrics.clone(),
617            self.backpressure_manager.clone(),
618        );
619        std::mem::swap(self, &mut new);
620    }
621
622    pub fn evict_executed_effects_from_cache_for_testing(&self, tx_digest: &TransactionDigest) {
623        self.cached.executed_effects_digests.invalidate(tx_digest);
624        self.cached.transaction_events.invalidate(tx_digest);
625        self.cached.transactions.invalidate(tx_digest);
626    }
627
628    fn write_object_entry(
629        &self,
630        object_id: &ObjectID,
631        version: SequenceNumber,
632        object: ObjectEntry,
633    ) {
634        trace!(?object_id, ?version, ?object, "inserting object entry");
635        self.metrics.record_cache_write("object");
636
637        // We must hold the lock for the object entry while inserting to the
638        // object_by_id_cache. Otherwise, a surprising bug can occur:
639        //
640        // 1. A thread executing TX1 can write object (O,1) to the dirty set and then pause.
641        // 2. TX2, which reads (O,1) can begin executing, because ExecutionScheduler immediately
642        //    schedules transactions if their inputs are available. It does not matter that TX1
643        //    hasn't finished executing yet.
644        // 3. TX2 can write (O,2) to both the dirty set and the object_by_id_cache.
645        // 4. The thread executing TX1 can resume and write (O,1) to the object_by_id_cache.
646        //
647        // Now, any subsequent attempt to get the latest version of O will return (O,1) instead of
648        // (O,2).
649        //
650        // This seems very unlikely, but it may be possible under the following circumstances:
651        // - While a thread is unlikely to pause for so long, moka cache uses optimistic
652        //   lock-free algorithms that have retry loops. Possibly, under high contention, this
653        //   code might spin for a surprisingly long time.
654        // - Additionally, many concurrent re-executions of the same tx could happen due to
655        //   the tx finalizer, plus checkpoint executor, consensus, and RPCs from fullnodes.
656        let mut entry = self.dirty.objects.entry(*object_id).or_default();
657
658        self.object_by_id_cache
659            .insert(
660                object_id,
661                LatestObjectCacheEntry::Object(version, object.clone()),
662                Ticket::Write,
663            )
664            // While Ticket::Write cannot expire, this insert may still fail.
665            // See the comment in `MonotonicCache::insert`.
666            .ok();
667
668        entry.insert(version, object.clone());
669
670        if let ObjectEntry::Object(object) = &object {
671            if object.is_package() {
672                self.object_notify_read
673                    .notify(&InputKey::Package { id: *object_id }, &());
674            } else if !object.is_child_object() {
675                self.object_notify_read.notify(
676                    &InputKey::VersionedObject {
677                        id: object.full_id(),
678                        version: object.version(),
679                    },
680                    &(),
681                );
682            }
683        }
684    }
685
686    fn write_marker_value(
687        &self,
688        epoch_id: EpochId,
689        object_key: FullObjectKey,
690        marker_value: MarkerValue,
691    ) {
692        tracing::trace!("inserting marker value {object_key:?}: {marker_value:?}",);
693        self.metrics.record_cache_write("marker");
694        self.dirty
695            .markers
696            .entry((epoch_id, object_key.id()))
697            .or_default()
698            .value_mut()
699            .insert(object_key.version(), marker_value);
700        // It is possible for a transaction to use a consensus stream ended
701        // object in the input, hence we must notify that it is now available
702        // at the assigned version, so that any transaction waiting for this
703        // object version can start execution.
704        if matches!(marker_value, MarkerValue::ConsensusStreamEnded(_)) {
705            self.object_notify_read.notify(
706                &InputKey::VersionedObject {
707                    id: object_key.id(),
708                    version: object_key.version(),
709                },
710                &(),
711            );
712        }
713    }
714
715    // lock both the dirty and committed sides of the cache, and then pass the entries to
716    // the callback. Written with the `with` pattern because any other way of doing this
717    // creates lifetime hell.
718    fn with_locked_cache_entries<K, V, R>(
719        dirty_map: &DashMap<K, CachedVersionMap<V>>,
720        cached_map: &MokaCache<K, Arc<Mutex<CachedVersionMap<V>>>>,
721        key: &K,
722        cb: impl FnOnce(Option<&CachedVersionMap<V>>, Option<&CachedVersionMap<V>>) -> R,
723    ) -> R
724    where
725        K: Copy + Eq + Hash + Send + Sync + 'static,
726        V: Send + Sync + 'static,
727    {
728        let dirty_entry = dirty_map.entry(*key);
729        let dirty_entry = match &dirty_entry {
730            DashMapEntry::Occupied(occupied) => Some(occupied.get()),
731            DashMapEntry::Vacant(_) => None,
732        };
733
734        let cached_entry = cached_map.get(key);
735        let cached_lock = cached_entry.as_ref().map(|entry| entry.lock());
736        let cached_entry = cached_lock.as_deref();
737
738        cb(dirty_entry, cached_entry)
739    }
740
741    // Attempt to get an object from the cache. The DB is not consulted.
742    // Can return Hit, Miss, or NegativeHit (if the object is known to not exist).
743    fn get_object_entry_by_key_cache_only(
744        &self,
745        object_id: &ObjectID,
746        version: SequenceNumber,
747    ) -> CacheResult<ObjectEntry> {
748        Self::with_locked_cache_entries(
749            &self.dirty.objects,
750            &self.cached.object_cache,
751            object_id,
752            |dirty_entry, cached_entry| {
753                check_cache_entry_by_version!(
754                    self,
755                    "object_by_version",
756                    "uncommitted",
757                    dirty_entry,
758                    version
759                );
760                check_cache_entry_by_version!(
761                    self,
762                    "object_by_version",
763                    "committed",
764                    cached_entry,
765                    version
766                );
767                CacheResult::Miss
768            },
769        )
770    }
771
772    fn get_object_by_key_cache_only(
773        &self,
774        object_id: &ObjectID,
775        version: SequenceNumber,
776    ) -> CacheResult<Object> {
777        match self.get_object_entry_by_key_cache_only(object_id, version) {
778            CacheResult::Hit(entry) => match entry {
779                ObjectEntry::Object(object) => CacheResult::Hit(object),
780                ObjectEntry::Deleted | ObjectEntry::Wrapped => CacheResult::NegativeHit,
781            },
782            CacheResult::Miss => CacheResult::Miss,
783            CacheResult::NegativeHit => CacheResult::NegativeHit,
784        }
785    }
786
787    fn get_object_entry_by_id_cache_only(
788        &self,
789        request_type: &'static str,
790        object_id: &ObjectID,
791    ) -> CacheResult<(SequenceNumber, ObjectEntry)> {
792        self.metrics
793            .record_cache_request(request_type, "object_by_id");
794        let entry = self.object_by_id_cache.get(object_id);
795
796        if cfg!(debug_assertions)
797            && let Some(entry) = &entry
798        {
799            // check that cache is coherent
800            let highest: Option<ObjectEntry> = self
801                .dirty
802                .objects
803                .get(object_id)
804                .and_then(|entry| entry.get_highest().map(|(_, o)| o.clone()))
805                .or_else(|| {
806                    let obj: Option<ObjectEntry> = self
807                        .store
808                        .get_latest_object_or_tombstone(*object_id)
809                        .unwrap()
810                        .map(|(_, o)| o.into());
811                    obj
812                });
813
814            let cache_entry = match &*entry.lock() {
815                LatestObjectCacheEntry::Object(_, entry) => Some(entry.clone()),
816                LatestObjectCacheEntry::NonExistent => None,
817            };
818
819            // If the cache entry is a tombstone, the db entry may be missing if it was pruned.
820            let tombstone_possibly_pruned = highest.is_none()
821                && cache_entry
822                    .as_ref()
823                    .map(|e| e.is_tombstone())
824                    .unwrap_or(false);
825
826            if highest != cache_entry && !tombstone_possibly_pruned {
827                tracing::error!(
828                    ?highest,
829                    ?cache_entry,
830                    ?tombstone_possibly_pruned,
831                    "object_by_id cache is incoherent for {:?}",
832                    object_id
833                );
834                panic!("object_by_id cache is incoherent for {:?}", object_id);
835            }
836        }
837
838        if let Some(entry) = entry {
839            let entry = entry.lock();
840            match &*entry {
841                LatestObjectCacheEntry::Object(latest_version, latest_object) => {
842                    self.metrics.record_cache_hit(request_type, "object_by_id");
843                    return CacheResult::Hit((*latest_version, latest_object.clone()));
844                }
845                LatestObjectCacheEntry::NonExistent => {
846                    self.metrics
847                        .record_cache_negative_hit(request_type, "object_by_id");
848                    return CacheResult::NegativeHit;
849                }
850            }
851        } else {
852            self.metrics.record_cache_miss(request_type, "object_by_id");
853        }
854
855        Self::with_locked_cache_entries(
856            &self.dirty.objects,
857            &self.cached.object_cache,
858            object_id,
859            |dirty_entry, cached_entry| {
860                check_cache_entry_by_latest!(self, request_type, "uncommitted", dirty_entry);
861                check_cache_entry_by_latest!(self, request_type, "committed", cached_entry);
862                CacheResult::Miss
863            },
864        )
865    }
866
867    fn get_marker_value_cache_only(
868        &self,
869        object_key: FullObjectKey,
870        epoch_id: EpochId,
871    ) -> CacheResult<MarkerValue> {
872        Self::with_locked_cache_entries(
873            &self.dirty.markers,
874            &self.cached.marker_cache,
875            &(epoch_id, object_key.id()),
876            |dirty_entry, cached_entry| {
877                check_cache_entry_by_version!(
878                    self,
879                    "marker_by_version",
880                    "uncommitted",
881                    dirty_entry,
882                    object_key.version()
883                );
884                check_cache_entry_by_version!(
885                    self,
886                    "marker_by_version",
887                    "committed",
888                    cached_entry,
889                    object_key.version()
890                );
891                CacheResult::Miss
892            },
893        )
894    }
895
896    fn get_latest_marker_value_cache_only(
897        &self,
898        object_id: FullObjectID,
899        epoch_id: EpochId,
900    ) -> CacheResult<(SequenceNumber, MarkerValue)> {
901        Self::with_locked_cache_entries(
902            &self.dirty.markers,
903            &self.cached.marker_cache,
904            &(epoch_id, object_id),
905            |dirty_entry, cached_entry| {
906                check_cache_entry_by_latest!(self, "marker_latest", "uncommitted", dirty_entry);
907                check_cache_entry_by_latest!(self, "marker_latest", "committed", cached_entry);
908                CacheResult::Miss
909            },
910        )
911    }
912
913    fn get_object_impl(&self, request_type: &'static str, id: &ObjectID) -> Option<Object> {
914        let ticket = self.object_by_id_cache.get_ticket_for_read(id);
915        match self.get_object_entry_by_id_cache_only(request_type, id) {
916            CacheResult::Hit((_, entry)) => match entry {
917                ObjectEntry::Object(object) => Some(object),
918                ObjectEntry::Deleted | ObjectEntry::Wrapped => None,
919            },
920            CacheResult::NegativeHit => None,
921            CacheResult::Miss => {
922                let obj = self
923                    .store
924                    .get_latest_object_or_tombstone(*id)
925                    .expect("db error");
926                match obj {
927                    Some((key, obj)) => {
928                        self.cache_latest_object_by_id(
929                            id,
930                            LatestObjectCacheEntry::Object(key.1, obj.clone().into()),
931                            ticket,
932                        );
933                        match obj {
934                            ObjectOrTombstone::Object(object) => Some(object),
935                            ObjectOrTombstone::Tombstone(_) => None,
936                        }
937                    }
938                    None => {
939                        self.cache_object_not_found(id, ticket);
940                        None
941                    }
942                }
943            }
944        }
945    }
946
947    fn record_db_get(&self, request_type: &'static str) -> &AuthorityStore {
948        self.metrics.record_cache_request(request_type, "db");
949        &self.store
950    }
951
952    fn record_db_multi_get(&self, request_type: &'static str, count: usize) -> &AuthorityStore {
953        self.metrics
954            .record_cache_multi_request(request_type, "db", count);
955        &self.store
956    }
957
958    #[instrument(level = "debug", skip_all)]
959    fn write_transaction_outputs(&self, epoch_id: EpochId, tx_outputs: Arc<TransactionOutputs>) {
960        let tx_digest = *tx_outputs.transaction.digest();
961        trace!(?tx_digest, "writing transaction outputs to cache");
962
963        assert!(
964            !self.transaction_executed_in_last_epoch(&tx_digest, epoch_id),
965            "Transaction {:?} was already executed in epoch {}",
966            tx_digest,
967            epoch_id.saturating_sub(1)
968        );
969
970        let TransactionOutputs {
971            transaction,
972            effects,
973            markers,
974            written,
975            deleted,
976            wrapped,
977            events,
978            unchanged_loaded_runtime_objects,
979            ..
980        } = &*tx_outputs;
981
982        // Deletions and wraps must be written first. The reason is that one of the deletes
983        // may be a child object, and if we write the parent object first, a reader may or may
984        // not see the previous version of the child object, instead of the deleted/wrapped
985        // tombstone, which would cause an execution fork
986        for ObjectKey(id, version) in deleted.iter() {
987            self.write_object_entry(id, *version, ObjectEntry::Deleted);
988        }
989
990        for ObjectKey(id, version) in wrapped.iter() {
991            self.write_object_entry(id, *version, ObjectEntry::Wrapped);
992        }
993
994        // Update all markers
995        for (object_key, marker_value) in markers.iter() {
996            self.write_marker_value(epoch_id, *object_key, *marker_value);
997        }
998
999        // Write children before parents to ensure that readers do not observe a parent object
1000        // before its most recent children are visible.
1001        for (object_id, object) in written.iter() {
1002            if object.is_child_object() {
1003                self.write_object_entry(object_id, object.version(), object.clone().into());
1004            }
1005        }
1006        for (object_id, object) in written.iter() {
1007            if !object.is_child_object() {
1008                self.write_object_entry(object_id, object.version(), object.clone().into());
1009                if object.is_package() {
1010                    debug!("caching package: {:?}", object.compute_object_reference());
1011                    self.packages
1012                        .insert(*object_id, PackageObject::new(object.clone()));
1013                }
1014            }
1015        }
1016
1017        let tx_digest = *transaction.digest();
1018        debug!(
1019            ?tx_digest,
1020            "Writing transaction output objects to cache: {:?}",
1021            written
1022                .values()
1023                .map(|o| (o.id(), o.version()))
1024                .collect::<Vec<_>>(),
1025        );
1026        let effects_digest = effects.digest();
1027
1028        self.metrics.record_cache_write("transaction_block");
1029        self.dirty
1030            .pending_transaction_writes
1031            .insert(tx_digest, tx_outputs.clone());
1032
1033        // insert transaction effects before executed_effects_digests so that there
1034        // are never dangling entries in executed_effects_digests
1035        self.metrics.record_cache_write("transaction_effects");
1036        self.dirty
1037            .transaction_effects
1038            .insert(effects_digest, effects.clone());
1039
1040        // note: if events.data.is_empty(), then there are no events for this transaction. We
1041        // store it anyway to avoid special cases in commint_transaction_outputs, and translate
1042        // an empty events structure to None when reading.
1043        self.metrics.record_cache_write("transaction_events");
1044        self.dirty
1045            .transaction_events
1046            .insert(tx_digest, events.clone());
1047
1048        self.metrics
1049            .record_cache_write("unchanged_loaded_runtime_objects");
1050        self.dirty
1051            .unchanged_loaded_runtime_objects
1052            .insert(tx_digest, unchanged_loaded_runtime_objects.clone());
1053
1054        self.metrics.record_cache_write("executed_effects_digests");
1055        self.dirty
1056            .executed_effects_digests
1057            .insert(tx_digest, effects_digest);
1058
1059        self.executed_effects_digests_notify_read
1060            .notify(&tx_digest, &effects_digest);
1061
1062        self.metrics
1063            .pending_notify_read
1064            .set(self.executed_effects_digests_notify_read.num_pending() as i64);
1065
1066        let prev = self
1067            .dirty
1068            .total_transaction_inserts
1069            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1070
1071        let pending_count = (prev + 1).saturating_sub(
1072            self.dirty
1073                .total_transaction_commits
1074                .load(std::sync::atomic::Ordering::Relaxed),
1075        );
1076
1077        self.set_backpressure(pending_count);
1078    }
1079
1080    fn build_db_batch(&self, epoch: EpochId, digests: &[TransactionDigest]) -> Batch {
1081        let _metrics_guard = mysten_metrics::monitored_scope("WritebackCache::build_db_batch");
1082        let mut all_outputs = Vec::with_capacity(digests.len());
1083        for tx in digests {
1084            let Some(outputs) = self
1085                .dirty
1086                .pending_transaction_writes
1087                .get(tx)
1088                .map(|o| o.clone())
1089            else {
1090                // This can happen in the following rare case:
1091                // All transactions in the checkpoint are committed to the db (by commit_transaction_outputs,
1092                // called in CheckpointExecutor::process_executed_transactions), but the process crashes before
1093                // the checkpoint water mark is bumped. We will then re-commit the checkpoint at startup,
1094                // despite that all transactions are already executed.
1095                warn!("Attempt to commit unknown transaction {:?}", tx);
1096                continue;
1097            };
1098            all_outputs.push(outputs);
1099        }
1100
1101        let batch = self
1102            .store
1103            .build_db_batch(epoch, &all_outputs)
1104            .expect("db error");
1105        (all_outputs, batch)
1106    }
1107
1108    // Commits dirty data for the given TransactionDigest to the db.
1109    #[instrument(level = "debug", skip_all)]
1110    fn commit_transaction_outputs(
1111        &self,
1112        epoch: EpochId,
1113        (all_outputs, db_batch): Batch,
1114        digests: &[TransactionDigest],
1115    ) {
1116        let _metrics_guard =
1117            mysten_metrics::monitored_scope("WritebackCache::commit_transaction_outputs");
1118        fail_point!("writeback-cache-commit");
1119        trace!(?digests);
1120
1121        // Flush writes to disk before removing anything from dirty set. otherwise,
1122        // a cache eviction could cause a value to disappear briefly, even if we insert to the
1123        // cache before removing from the dirty set.
1124        db_batch.write().expect("db error");
1125
1126        let _metrics_guard =
1127            mysten_metrics::monitored_scope("WritebackCache::commit_transaction_outputs::flush");
1128        // Parallel phase: tx-level metadata is keyed by unique tx_digest/effects_digest,
1129        // so there are no cross-transaction ordering constraints.
1130        all_outputs.par_iter().with_min_len(16).for_each(|outputs| {
1131            let tx_digest = outputs.transaction.digest();
1132            assert!(
1133                self.dirty
1134                    .pending_transaction_writes
1135                    .remove(tx_digest)
1136                    .is_some()
1137            );
1138            self.flush_tx_metadata_from_dirty_to_cached(*tx_digest, outputs);
1139        });
1140
1141        // Sequential phase: object/marker versions must be popped in causal order
1142        // (oldest first) per object_id. Multiple transactions in the batch can touch
1143        // the same shared object at consecutive versions, so this loop must preserve
1144        // the order of all_outputs.
1145        for outputs in all_outputs.iter() {
1146            self.flush_objects_from_dirty_to_cached(epoch, outputs);
1147        }
1148
1149        let num_outputs = all_outputs.len() as u64;
1150        let num_commits = self
1151            .dirty
1152            .total_transaction_commits
1153            .fetch_add(num_outputs, std::sync::atomic::Ordering::Relaxed)
1154            + num_outputs;
1155
1156        let pending_count = self
1157            .dirty
1158            .total_transaction_inserts
1159            .load(std::sync::atomic::Ordering::Relaxed)
1160            .saturating_sub(num_commits);
1161
1162        self.set_backpressure(pending_count);
1163    }
1164
1165    fn approximate_pending_transaction_count(&self) -> u64 {
1166        let num_commits = self
1167            .dirty
1168            .total_transaction_commits
1169            .load(std::sync::atomic::Ordering::Relaxed);
1170
1171        self.dirty
1172            .total_transaction_inserts
1173            .load(std::sync::atomic::Ordering::Relaxed)
1174            .saturating_sub(num_commits)
1175    }
1176
1177    fn set_backpressure(&self, pending_count: u64) {
1178        let backpressure = pending_count > self.backpressure_threshold;
1179        let backpressure_changed = self.backpressure_manager.set_backpressure(backpressure);
1180        if backpressure_changed {
1181            self.metrics.backpressure_toggles.inc();
1182        }
1183        self.metrics
1184            .backpressure_status
1185            .set(if backpressure { 1 } else { 0 });
1186    }
1187
1188    // Flushes tx-level metadata for a single transaction from dirty to cache.
1189    // All keys are unique per transaction (tx_digest, effects_digest), so this
1190    // is safe to call in parallel across transactions.
1191    fn flush_tx_metadata_from_dirty_to_cached(
1192        &self,
1193        tx_digest: TransactionDigest,
1194        outputs: &TransactionOutputs,
1195    ) {
1196        // TODO: outputs should have a strong count of 1 so we should be able to move out of it
1197        let TransactionOutputs {
1198            transaction,
1199            effects,
1200            events,
1201            ..
1202        } = outputs;
1203
1204        let effects_digest = effects.digest();
1205
1206        // Update cache before removing from self.dirty to avoid
1207        // unnecessary cache misses
1208        self.cached
1209            .transactions
1210            .insert(
1211                &tx_digest,
1212                PointCacheItem::Some(transaction.clone()),
1213                Ticket::Write,
1214            )
1215            .ok();
1216        self.cached
1217            .transaction_effects
1218            .insert(
1219                &effects_digest,
1220                PointCacheItem::Some(effects.clone().into()),
1221                Ticket::Write,
1222            )
1223            .ok();
1224        self.cached
1225            .executed_effects_digests
1226            .insert(
1227                &tx_digest,
1228                PointCacheItem::Some(effects_digest),
1229                Ticket::Write,
1230            )
1231            .ok();
1232        self.cached
1233            .transaction_events
1234            .insert(
1235                &tx_digest,
1236                PointCacheItem::Some(events.clone().into()),
1237                Ticket::Write,
1238            )
1239            .ok();
1240
1241        self.dirty
1242            .transaction_effects
1243            .remove(&effects_digest)
1244            .expect("effects must exist");
1245
1246        self.dirty
1247            .transaction_events
1248            .remove(&tx_digest)
1249            .expect("events must exist");
1250
1251        self.dirty
1252            .unchanged_loaded_runtime_objects
1253            .remove(&tx_digest)
1254            .expect("unchanged_loaded_runtime_objects must exist");
1255
1256        self.dirty
1257            .executed_effects_digests
1258            .remove(&tx_digest)
1259            .expect("executed effects must exist");
1260    }
1261
1262    // Flushes object and marker versions for a single transaction from dirty to cache.
1263    // Multiple transactions in the same batch can modify the same shared object at
1264    // consecutive versions, so callers must invoke this in causal (checkpoint) order.
1265    fn flush_objects_from_dirty_to_cached(&self, epoch: EpochId, outputs: &TransactionOutputs) {
1266        let TransactionOutputs {
1267            markers,
1268            written,
1269            deleted,
1270            wrapped,
1271            ..
1272        } = outputs;
1273
1274        for (object_key, marker_value) in markers.iter() {
1275            Self::move_version_from_dirty_to_cache(
1276                &self.dirty.markers,
1277                &self.cached.marker_cache,
1278                (epoch, object_key.id()),
1279                object_key.version(),
1280                marker_value,
1281            );
1282        }
1283
1284        for (object_id, object) in written.iter() {
1285            Self::move_version_from_dirty_to_cache(
1286                &self.dirty.objects,
1287                &self.cached.object_cache,
1288                *object_id,
1289                object.version(),
1290                &ObjectEntry::Object(object.clone()),
1291            );
1292        }
1293
1294        for ObjectKey(object_id, version) in deleted.iter() {
1295            Self::move_version_from_dirty_to_cache(
1296                &self.dirty.objects,
1297                &self.cached.object_cache,
1298                *object_id,
1299                *version,
1300                &ObjectEntry::Deleted,
1301            );
1302        }
1303
1304        for ObjectKey(object_id, version) in wrapped.iter() {
1305            Self::move_version_from_dirty_to_cache(
1306                &self.dirty.objects,
1307                &self.cached.object_cache,
1308                *object_id,
1309                *version,
1310                &ObjectEntry::Wrapped,
1311            );
1312        }
1313    }
1314
1315    // Move the oldest/least entry from the dirty queue to the cache queue.
1316    // This is called after the entry is committed to the db.
1317    fn move_version_from_dirty_to_cache<K, V>(
1318        dirty: &DashMap<K, CachedVersionMap<V>>,
1319        cache: &MokaCache<K, Arc<Mutex<CachedVersionMap<V>>>>,
1320        key: K,
1321        version: SequenceNumber,
1322        value: &V,
1323    ) where
1324        K: Eq + std::hash::Hash + Clone + Send + Sync + Copy + 'static,
1325        V: Send + Sync + Clone + Eq + std::fmt::Debug + 'static,
1326    {
1327        static MAX_VERSIONS: usize = 3;
1328
1329        // IMPORTANT: lock both the dirty set entry and the cache entry before modifying either.
1330        // this ensures that readers cannot see a value temporarily disappear.
1331        let dirty_entry = dirty.entry(key);
1332        let cache_entry = cache.entry(key).or_default();
1333        let mut cache_map = cache_entry.value().lock();
1334
1335        // insert into cache and drop old versions.
1336        cache_map.insert(version, value.clone());
1337        // TODO: make this automatic by giving CachedVersionMap an optional max capacity
1338        cache_map.truncate_to(MAX_VERSIONS);
1339
1340        let DashMapEntry::Occupied(mut occupied_dirty_entry) = dirty_entry else {
1341            panic!("dirty map must exist");
1342        };
1343
1344        let removed = occupied_dirty_entry.get_mut().pop_oldest(&version);
1345
1346        assert_eq!(removed.as_ref(), Some(value), "dirty version must exist");
1347
1348        // if there are no versions remaining, remove the map entry
1349        if occupied_dirty_entry.get().is_empty() {
1350            occupied_dirty_entry.remove();
1351        }
1352    }
1353
1354    // Updates the latest object id cache with an entry that was read from the db.
1355    fn cache_latest_object_by_id(
1356        &self,
1357        object_id: &ObjectID,
1358        object: LatestObjectCacheEntry,
1359        ticket: Ticket,
1360    ) {
1361        trace!("caching object by id: {:?} {:?}", object_id, object);
1362        if self
1363            .object_by_id_cache
1364            .insert(object_id, object, ticket)
1365            .is_ok()
1366        {
1367            self.metrics.record_cache_write("object_by_id");
1368        } else {
1369            trace!("discarded cache write due to expired ticket");
1370            self.metrics.record_ticket_expiry();
1371        }
1372    }
1373
1374    fn cache_object_not_found(&self, object_id: &ObjectID, ticket: Ticket) {
1375        self.cache_latest_object_by_id(object_id, LatestObjectCacheEntry::NonExistent, ticket);
1376    }
1377
1378    fn clear_state_end_of_epoch_impl(&self, execution_guard: &ExecutionLockWriteGuard<'_>) {
1379        info!("clearing state at end of epoch");
1380
1381        // Note: there cannot be any concurrent writes to self.dirty while we are in this function,
1382        // as all transaction execution is paused.
1383        for r in self.dirty.pending_transaction_writes.iter() {
1384            let outputs = r.value();
1385            if !outputs
1386                .transaction
1387                .transaction_data()
1388                .shared_input_objects()
1389                .is_empty()
1390            {
1391                debug_fatal!("transaction must be single writer");
1392            }
1393            info!(
1394                "clearing state for transaction {:?}",
1395                outputs.transaction.digest()
1396            );
1397            for (object_id, object) in outputs.written.iter() {
1398                if object.is_package() {
1399                    info!("removing non-finalized package from cache: {:?}", object_id);
1400                    self.packages.invalidate(object_id);
1401                }
1402                self.object_by_id_cache.invalidate(object_id);
1403                self.cached.object_cache.invalidate(object_id);
1404            }
1405
1406            for ObjectKey(object_id, _) in outputs.deleted.iter().chain(outputs.wrapped.iter()) {
1407                self.object_by_id_cache.invalidate(object_id);
1408                self.cached.object_cache.invalidate(object_id);
1409            }
1410        }
1411
1412        self.dirty.clear();
1413
1414        info!("clearing old transaction locks");
1415        self.object_locks.clear();
1416        info!("clearing object per epoch marker table");
1417        self.store
1418            .clear_object_per_epoch_marker_table(execution_guard)
1419            .expect("db error");
1420    }
1421
1422    fn bulk_insert_genesis_objects_impl(&self, objects: &[Object]) {
1423        self.store
1424            .bulk_insert_genesis_objects(objects)
1425            .expect("db error");
1426        for obj in objects {
1427            self.cached.object_cache.invalidate(&obj.id());
1428            self.object_by_id_cache.invalidate(&obj.id());
1429        }
1430    }
1431
1432    fn insert_genesis_object_impl(&self, object: Object) {
1433        self.object_by_id_cache.invalidate(&object.id());
1434        self.cached.object_cache.invalidate(&object.id());
1435        self.store.insert_genesis_object(object).expect("db error");
1436    }
1437
1438    pub fn clear_caches_and_assert_empty(&self) {
1439        info!("clearing caches");
1440        self.cached.clear_and_assert_empty();
1441        self.object_by_id_cache.invalidate_all();
1442        assert!(&self.object_by_id_cache.is_empty());
1443        self.packages.invalidate_all();
1444        assert_empty(&self.packages);
1445    }
1446}
1447
1448fn account_amount_from_object(account_obj: &Object) -> u128 {
1449    let (_, AccumulatorValue::U128(value)) =
1450        account_obj.data.try_as_move().unwrap().try_into().unwrap();
1451    value.value
1452}
1453
1454impl AccountFundsRead for WritebackCache {
1455    fn get_latest_account_amount(&self, account_id: &AccumulatorObjId) -> u128 {
1456        ObjectCacheRead::get_object(self, account_id.inner())
1457            .map(|account_obj| account_amount_from_object(&account_obj))
1458            .unwrap_or(0)
1459    }
1460
1461    fn get_consistent_latest_account_amount_and_version(
1462        &self,
1463        account_id: &AccumulatorObjId,
1464    ) -> (u128, SequenceNumber) {
1465        // Settlement is not atomic. A settlement transaction writes the accumulator
1466        // objects at version V+1 first, and then a later barrier transaction bumps the
1467        // root from V to V+1. A reader that observes the state in between sees
1468        // post-settlement account objects alongside the pre-settlement root version,
1469        // and reading the "latest" account can therefore disagree with the root we
1470        // just captured.
1471        //
1472        // We handle this with two pieces:
1473        //
1474        // 1. MVCC read capped at the captured root version (see the call site below).
1475        //    By construction of the settlement/barrier ordering, every account object's
1476        //    version is <= the root version after the corresponding barrier runs, so
1477        //    capping at the captured root strips away any newer-settlement writes that
1478        //    have raced ahead of the barrier. The returned amount is the balance at or
1479        //    before the captured root version, even if the account object has a newer
1480        //    latest version by the time this method returns.
1481        //
1482        // 2. Root-version stability check (pre == post). `get_account_amount_at_version`
1483        //    is only safe to call when the target version has not been pruned. Pruning
1484        //    is tied to root advancement, so by reading the root before and after the
1485        //    MVCC read and retrying on mismatch, we ensure that no root advance (and
1486        //    therefore no pruning of the version we read at) could have happened while
1487        //    we were reading — the data we read is still live in the system (memory or
1488        //    db) throughout the call.
1489        let mut pre_root_version =
1490            ObjectCacheRead::get_object(self, &SUI_ACCUMULATOR_ROOT_OBJECT_ID)
1491                .unwrap()
1492                .version();
1493        let starting_root_version = pre_root_version;
1494        let mut loop_iter = 0;
1495        loop {
1496            loop_iter += 1;
1497            // Safe because of (1) and (2) above: the stability check below bounds the
1498            // lifetime of `pre_root_version` to a window in which no pruning happens.
1499            let value = self.get_account_amount_at_version(account_id, pre_root_version);
1500            let post_root_version =
1501                ObjectCacheRead::get_object(self, &SUI_ACCUMULATOR_ROOT_OBJECT_ID)
1502                    .unwrap()
1503                    .version();
1504            if pre_root_version == post_root_version {
1505                if loop_iter > 10 {
1506                    debug!(
1507                        iterations = loop_iter,
1508                        starting_root_version = %starting_root_version,
1509                        ending_root_version = %post_root_version,
1510                        "Root version stabilized after multiple iterations during MVCC read"
1511                    );
1512                }
1513                return (value, pre_root_version);
1514            }
1515            debug!(
1516                "Root version changed from {} to {} during MVCC read, retrying",
1517                pre_root_version, post_root_version
1518            );
1519            pre_root_version = post_root_version;
1520        }
1521    }
1522
1523    fn get_account_amount_at_version(
1524        &self,
1525        account_id: &AccumulatorObjId,
1526        version: SequenceNumber,
1527    ) -> u128 {
1528        let account_obj = self.find_object_lt_or_eq_version(*account_id.inner(), version);
1529        account_obj
1530            .map(|account_obj| account_amount_from_object(&account_obj))
1531            .unwrap_or(0)
1532    }
1533}
1534
1535impl ExecutionCacheAPI for WritebackCache {}
1536
1537impl ExecutionCacheCommit for WritebackCache {
1538    fn build_db_batch(&self, epoch: EpochId, digests: &[TransactionDigest]) -> Batch {
1539        self.build_db_batch(epoch, digests)
1540    }
1541
1542    fn set_highest_committed_checkpoint_in_batch(
1543        &self,
1544        batch: &mut Batch,
1545        checkpoint: CheckpointSequenceNumber,
1546    ) {
1547        self.store
1548            .perpetual_tables
1549            .set_highest_committed_checkpoint(&mut batch.1, checkpoint)
1550            .expect("db error");
1551    }
1552
1553    fn commit_transaction_outputs(
1554        &self,
1555        epoch: EpochId,
1556        batch: Batch,
1557        digests: &[TransactionDigest],
1558    ) {
1559        WritebackCache::commit_transaction_outputs(self, epoch, batch, digests)
1560    }
1561
1562    fn persist_transaction(&self, tx: &VerifiedExecutableTransaction) {
1563        self.store.persist_transaction(tx).expect("db error");
1564    }
1565
1566    fn approximate_pending_transaction_count(&self) -> u64 {
1567        WritebackCache::approximate_pending_transaction_count(self)
1568    }
1569}
1570
1571impl ObjectCacheRead for WritebackCache {
1572    fn get_package_object(&self, package_id: &ObjectID) -> SuiResult<Option<PackageObject>> {
1573        self.metrics
1574            .record_cache_request("package", "package_cache");
1575        if let Some(p) = self.packages.get(package_id) {
1576            if cfg!(debug_assertions) {
1577                let canonical_package = self
1578                    .dirty
1579                    .objects
1580                    .get(package_id)
1581                    .and_then(|v| match v.get_highest().map(|v| v.1.clone()) {
1582                        Some(ObjectEntry::Object(object)) => Some(object),
1583                        _ => None,
1584                    })
1585                    .or_else(|| self.store.get_object(package_id));
1586
1587                if let Some(canonical_package) = canonical_package {
1588                    assert_eq!(
1589                        canonical_package.digest(),
1590                        p.object().digest(),
1591                        "Package object cache is inconsistent for package {:?}",
1592                        package_id
1593                    );
1594                }
1595            }
1596            self.metrics.record_cache_hit("package", "package_cache");
1597            return Ok(Some(p));
1598        } else {
1599            self.metrics.record_cache_miss("package", "package_cache");
1600        }
1601
1602        // We try the dirty objects cache as well before going to the database. This is necessary
1603        // because the package could be evicted from the package cache before it is committed
1604        // to the database.
1605        if let Some(p) = self.get_object_impl("package", package_id) {
1606            if p.is_package() {
1607                let p = PackageObject::new(p);
1608                tracing::trace!(
1609                    "caching package: {:?}",
1610                    p.object().compute_object_reference()
1611                );
1612                self.metrics.record_cache_write("package");
1613                self.packages.insert(*package_id, p.clone());
1614                Ok(Some(p))
1615            } else {
1616                Err(SuiErrorKind::UserInputError {
1617                    error: UserInputError::MoveObjectAsPackage {
1618                        object_id: *package_id,
1619                    },
1620                }
1621                .into())
1622            }
1623        } else {
1624            Ok(None)
1625        }
1626    }
1627
1628    fn force_reload_system_packages(&self, _system_package_ids: &[ObjectID]) {
1629        // This is a no-op because all writes go through the cache, therefore it can never
1630        // be incoherent
1631    }
1632
1633    // get_object and variants.
1634
1635    fn get_object(&self, id: &ObjectID) -> Option<Object> {
1636        self.get_object_impl("object_latest", id)
1637    }
1638
1639    fn get_object_by_key(&self, object_id: &ObjectID, version: SequenceNumber) -> Option<Object> {
1640        match self.get_object_by_key_cache_only(object_id, version) {
1641            CacheResult::Hit(object) => Some(object),
1642            CacheResult::NegativeHit => None,
1643            CacheResult::Miss => self
1644                .record_db_get("object_by_version")
1645                .get_object_by_key(object_id, version),
1646        }
1647    }
1648
1649    fn multi_get_objects_by_key(&self, object_keys: &[ObjectKey]) -> Vec<Option<Object>> {
1650        do_fallback_lookup(
1651            object_keys,
1652            |key| match self.get_object_by_key_cache_only(&key.0, key.1) {
1653                CacheResult::Hit(maybe_object) => CacheResult::Hit(Some(maybe_object)),
1654                CacheResult::NegativeHit => CacheResult::NegativeHit,
1655                CacheResult::Miss => CacheResult::Miss,
1656            },
1657            |remaining| {
1658                self.record_db_multi_get("object_by_version", remaining.len())
1659                    .multi_get_objects_by_key(remaining)
1660                    .expect("db error")
1661            },
1662        )
1663    }
1664
1665    fn object_exists_by_key(&self, object_id: &ObjectID, version: SequenceNumber) -> bool {
1666        match self.get_object_by_key_cache_only(object_id, version) {
1667            CacheResult::Hit(_) => true,
1668            CacheResult::NegativeHit => false,
1669            CacheResult::Miss => self
1670                .record_db_get("object_by_version")
1671                .object_exists_by_key(object_id, version)
1672                .expect("db error"),
1673        }
1674    }
1675
1676    fn multi_object_exists_by_key(&self, object_keys: &[ObjectKey]) -> Vec<bool> {
1677        do_fallback_lookup(
1678            object_keys,
1679            |key| match self.get_object_by_key_cache_only(&key.0, key.1) {
1680                CacheResult::Hit(_) => CacheResult::Hit(true),
1681                CacheResult::NegativeHit => CacheResult::Hit(false),
1682                CacheResult::Miss => CacheResult::Miss,
1683            },
1684            |remaining| {
1685                self.record_db_multi_get("object_by_version", remaining.len())
1686                    .multi_object_exists_by_key(remaining)
1687                    .expect("db error")
1688            },
1689        )
1690    }
1691
1692    fn get_latest_object_ref_or_tombstone(&self, object_id: ObjectID) -> Option<ObjectRef> {
1693        match self.get_object_entry_by_id_cache_only("latest_objref_or_tombstone", &object_id) {
1694            CacheResult::Hit((version, entry)) => Some(match entry {
1695                ObjectEntry::Object(object) => object.compute_object_reference(),
1696                ObjectEntry::Deleted => (object_id, version, ObjectDigest::OBJECT_DIGEST_DELETED),
1697                ObjectEntry::Wrapped => (object_id, version, ObjectDigest::OBJECT_DIGEST_WRAPPED),
1698            }),
1699            CacheResult::NegativeHit => None,
1700            CacheResult::Miss => self
1701                .record_db_get("latest_objref_or_tombstone")
1702                .get_latest_object_ref_or_tombstone(object_id)
1703                .expect("db error"),
1704        }
1705    }
1706
1707    fn get_latest_object_or_tombstone(
1708        &self,
1709        object_id: ObjectID,
1710    ) -> Option<(ObjectKey, ObjectOrTombstone)> {
1711        match self.get_object_entry_by_id_cache_only("latest_object_or_tombstone", &object_id) {
1712            CacheResult::Hit((version, entry)) => {
1713                let key = ObjectKey(object_id, version);
1714                Some(match entry {
1715                    ObjectEntry::Object(object) => (key, object.into()),
1716                    ObjectEntry::Deleted => (
1717                        key,
1718                        ObjectOrTombstone::Tombstone((
1719                            object_id,
1720                            version,
1721                            ObjectDigest::OBJECT_DIGEST_DELETED,
1722                        )),
1723                    ),
1724                    ObjectEntry::Wrapped => (
1725                        key,
1726                        ObjectOrTombstone::Tombstone((
1727                            object_id,
1728                            version,
1729                            ObjectDigest::OBJECT_DIGEST_WRAPPED,
1730                        )),
1731                    ),
1732                })
1733            }
1734            CacheResult::NegativeHit => None,
1735            CacheResult::Miss => self
1736                .record_db_get("latest_object_or_tombstone")
1737                .get_latest_object_or_tombstone(object_id)
1738                .expect("db error"),
1739        }
1740    }
1741
1742    fn multi_input_objects_available_cache_only(&self, keys: &[InputKey]) -> Vec<bool> {
1743        keys.iter()
1744            .map(|key| {
1745                if key.is_cancelled() {
1746                    true
1747                } else {
1748                    match key {
1749                        // See multi_input_objects_available: a consensus input is not satisfied
1750                        // by an object at the same version on a different stream.
1751                        InputKey::VersionedObject { id, version } => {
1752                            match self.get_object_by_key_cache_only(&id.id(), *version) {
1753                                CacheResult::Hit(object) => {
1754                                    !matches!(id, FullObjectID::Consensus(_))
1755                                        || object.full_id() == *id
1756                                }
1757                                _ => false,
1758                            }
1759                        }
1760                        InputKey::Package { id } => self.packages.contains_key(id),
1761                    }
1762                }
1763            })
1764            .collect()
1765    }
1766
1767    #[instrument(level = "trace", skip_all, fields(object_id, version_bound))]
1768    fn find_object_lt_or_eq_version(
1769        &self,
1770        object_id: ObjectID,
1771        version_bound: SequenceNumber,
1772    ) -> Option<Object> {
1773        macro_rules! check_cache_entry {
1774            ($level: expr, $objects: expr) => {
1775                self.metrics
1776                    .record_cache_request("object_lt_or_eq_version", $level);
1777                if let Some(objects) = $objects {
1778                    if let Some((_, object)) = objects
1779                        .all_versions_lt_or_eq_descending(&version_bound)
1780                        .next()
1781                    {
1782                        if let ObjectEntry::Object(object) = object {
1783                            self.metrics
1784                                .record_cache_hit("object_lt_or_eq_version", $level);
1785                            return Some(object.clone());
1786                        } else {
1787                            // if we find a tombstone, the object does not exist
1788                            self.metrics
1789                                .record_cache_negative_hit("object_lt_or_eq_version", $level);
1790                            return None;
1791                        }
1792                    } else {
1793                        self.metrics
1794                            .record_cache_miss("object_lt_or_eq_version", $level);
1795                    }
1796                }
1797            };
1798        }
1799
1800        // if we have the latest version cached, and it is within the bound, we are done
1801        self.metrics
1802            .record_cache_request("object_lt_or_eq_version", "object_by_id");
1803        let latest_cache_entry = self.object_by_id_cache.get(&object_id);
1804        if let Some(latest) = &latest_cache_entry {
1805            let latest = latest.lock();
1806            match &*latest {
1807                LatestObjectCacheEntry::Object(latest_version, object) => {
1808                    if *latest_version <= version_bound {
1809                        if let ObjectEntry::Object(object) = object {
1810                            self.metrics
1811                                .record_cache_hit("object_lt_or_eq_version", "object_by_id");
1812                            return Some(object.clone());
1813                        } else {
1814                            // object is a tombstone, but is still within the version bound
1815                            self.metrics.record_cache_negative_hit(
1816                                "object_lt_or_eq_version",
1817                                "object_by_id",
1818                            );
1819                            return None;
1820                        }
1821                    }
1822                    // latest object is not within the version bound. fall through.
1823                }
1824                // No object by this ID exists at all
1825                LatestObjectCacheEntry::NonExistent => {
1826                    self.metrics
1827                        .record_cache_negative_hit("object_lt_or_eq_version", "object_by_id");
1828                    return None;
1829                }
1830            }
1831        }
1832        self.metrics
1833            .record_cache_miss("object_lt_or_eq_version", "object_by_id");
1834
1835        Self::with_locked_cache_entries(
1836            &self.dirty.objects,
1837            &self.cached.object_cache,
1838            &object_id,
1839            |dirty_entry, cached_entry| {
1840                check_cache_entry!("committed", dirty_entry);
1841                check_cache_entry!("uncommitted", cached_entry);
1842
1843                // Much of the time, the query will be for the very latest object version, so
1844                // try that first. But we have to be careful:
1845                // 1. We must load the tombstone if it is present, because its version may exceed
1846                //    the version_bound, in which case we must do a scan.
1847                // 2. You might think we could just call `self.store.get_latest_object_or_tombstone` here.
1848                //    But we cannot, because there may be a more recent version in the dirty set, which
1849                //    we skipped over in check_cache_entry! because of the version bound. However, if we
1850                //    skipped it above, we will skip it here as well, again due to the version bound.
1851                // 3. Despite that, we really want to warm the cache here. Why? Because if the object is
1852                //    cold (not being written to), then we will very soon be able to start serving reads
1853                //    of it from the object_by_id cache, IF we can warm the cache. If we don't warm the
1854                //    the cache here, and no writes to the object occur, then we will always have to go
1855                //    to the db for the object.
1856                //
1857                // Lastly, it is important to understand the rationale for all this: If the object is
1858                // write-hot, we will serve almost all reads to it from the dirty set (or possibly the
1859                // cached set if it is only written to once every few checkpoints). If the object is
1860                // write-cold (or non-existent) and read-hot, then we will serve almost all reads to it
1861                // from the object_by_id cache check above.  Most of the apparently wasteful code here
1862                // exists only to ensure correctness in all the edge cases.
1863                let latest: Option<(SequenceNumber, ObjectEntry)> =
1864                    if let Some(dirty_set) = dirty_entry {
1865                        dirty_set
1866                            .get_highest()
1867                            .cloned()
1868                            .tap_none(|| panic!("dirty set cannot be empty"))
1869                    } else {
1870                        // TODO: we should try not to read from the db while holding the locks.
1871                        self.record_db_get("object_lt_or_eq_version_latest")
1872                            .get_latest_object_or_tombstone(object_id)
1873                            .expect("db error")
1874                            .map(|(ObjectKey(_, version), obj_or_tombstone)| {
1875                                (version, ObjectEntry::from(obj_or_tombstone))
1876                            })
1877                    };
1878
1879                if let Some((obj_version, obj_entry)) = latest {
1880                    // we can always cache the latest object (or tombstone), even if it is not within the
1881                    // version_bound. This is done in order to warm the cache in the case where a sequence
1882                    // of transactions all read the same child object without writing to it.
1883
1884                    // Note: no need to call with_object_by_id_cache_update here, because we are holding
1885                    // the lock on the dirty cache entry, and `latest` cannot become out-of-date
1886                    // while we hold that lock.
1887                    self.cache_latest_object_by_id(
1888                        &object_id,
1889                        LatestObjectCacheEntry::Object(obj_version, obj_entry.clone()),
1890                        // We can get a ticket at the last second, because we are holding the lock
1891                        // on dirty, so there cannot be any concurrent writes.
1892                        self.object_by_id_cache.get_ticket_for_read(&object_id),
1893                    );
1894
1895                    if obj_version <= version_bound {
1896                        match obj_entry {
1897                            ObjectEntry::Object(object) => Some(object),
1898                            ObjectEntry::Deleted | ObjectEntry::Wrapped => None,
1899                        }
1900                    } else {
1901                        // The latest object exceeded the bound, so now we have to do a scan
1902                        // But we already know there is no dirty entry within the bound,
1903                        // so we go to the db.
1904                        self.record_db_get("object_lt_or_eq_version_scan")
1905                            .find_object_lt_or_eq_version(object_id, version_bound)
1906                            .expect("db error")
1907                    }
1908
1909                // no object found in dirty set or db, object does not exist
1910                // When this is called from a read api (i.e. not the execution path) it is
1911                // possible that the object has been deleted and pruned. In this case,
1912                // there would be no entry at all on disk, but we may have a tombstone in the
1913                // cache
1914                } else if let Some(latest_cache_entry) = latest_cache_entry {
1915                    // If there is a latest cache entry, it had better not be a live object!
1916                    assert!(!latest_cache_entry.lock().is_alive());
1917                    None
1918                } else {
1919                    // If there is no latest cache entry, we can insert one.
1920                    let highest = cached_entry.and_then(|c| c.get_highest());
1921                    assert!(highest.is_none() || highest.unwrap().1.is_tombstone());
1922                    self.cache_object_not_found(
1923                        &object_id,
1924                        // okay to get ticket at last second - see above
1925                        self.object_by_id_cache.get_ticket_for_read(&object_id),
1926                    );
1927                    None
1928                }
1929            },
1930        )
1931    }
1932
1933    fn find_object_or_tombstone_lt_or_eq_version_unlocked(
1934        &self,
1935        object_id: ObjectID,
1936        version_bound: SequenceNumber,
1937    ) -> Option<FoundObjectOrTombstone> {
1938        // Copied out under the shard's read lock, which is released at the end of the statement,
1939        // before the store read.
1940        let uncommitted = self.dirty.objects.get(&object_id).and_then(|versions| {
1941            versions
1942                .all_versions_lt_or_eq_descending(&version_bound)
1943                .next()
1944                .map(|(version, entry)| (*version, entry.clone()))
1945        });
1946        // `commit_transaction_outputs` writes a version to the store before
1947        // `flush_objects_from_dirty_to_cached` removes it from the dirty set, so a version that
1948        // left the dirty set after the read above is in the store now.
1949        let committed = self
1950            .record_db_get("object_or_tombstone_lt_or_eq_version_unlocked")
1951            .perpetual_tables
1952            .find_object_or_tombstone_lt_or_eq_version(object_id, version_bound)
1953            .expect("db error");
1954        let committed_version = committed.as_ref().map(|committed| match committed {
1955            ObjectOrTombstone::Object(object) => object.version(),
1956            ObjectOrTombstone::Tombstone((_, version, _)) => *version,
1957        });
1958        match uncommitted {
1959            Some((version, entry))
1960                if committed_version.is_none_or(|committed| committed < version) =>
1961            {
1962                Some(FoundObjectOrTombstone {
1963                    entry: entry.into_object_or_tombstone(object_id, version),
1964                    committed: false,
1965                })
1966            }
1967            _ => committed.map(|entry| FoundObjectOrTombstone {
1968                entry,
1969                committed: true,
1970            }),
1971        }
1972    }
1973
1974    fn get_sui_system_state_object_unsafe(&self) -> SuiResult<SuiSystemState> {
1975        get_sui_system_state(self)
1976    }
1977
1978    fn get_bridge_object_unsafe(&self) -> SuiResult<Bridge> {
1979        get_bridge(self)
1980    }
1981
1982    fn get_marker_value(
1983        &self,
1984        object_key: FullObjectKey,
1985        epoch_id: EpochId,
1986    ) -> Option<MarkerValue> {
1987        match self.get_marker_value_cache_only(object_key, epoch_id) {
1988            CacheResult::Hit(marker) => Some(marker),
1989            CacheResult::NegativeHit => None,
1990            CacheResult::Miss => self
1991                .record_db_get("marker_by_version")
1992                .get_marker_value(object_key, epoch_id)
1993                .expect("db error"),
1994        }
1995    }
1996
1997    fn get_latest_marker(
1998        &self,
1999        object_id: FullObjectID,
2000        epoch_id: EpochId,
2001    ) -> Option<(SequenceNumber, MarkerValue)> {
2002        match self.get_latest_marker_value_cache_only(object_id, epoch_id) {
2003            CacheResult::Hit((v, marker)) => Some((v, marker)),
2004            CacheResult::NegativeHit => {
2005                panic!("cannot have negative hit when getting latest marker")
2006            }
2007            CacheResult::Miss => self
2008                .record_db_get("marker_latest")
2009                .get_latest_marker(object_id, epoch_id)
2010                .expect("db error"),
2011        }
2012    }
2013
2014    #[cfg(test)]
2015    fn get_lock(&self, obj_ref: ObjectRef, epoch_store: &AuthorityPerEpochStore) -> SuiLockResult {
2016        let cur_epoch = epoch_store.epoch();
2017        let Some(obj) = self.get_object_impl("lock", &obj_ref.0) else {
2018            return Err(SuiError::from(UserInputError::ObjectNotFound {
2019                object_id: obj_ref.0,
2020                // even though we know the requested version, we leave it as None to indicate
2021                // that the object does not exist at any version
2022                version: None,
2023            }));
2024        };
2025        let actual_objref = obj.compute_object_reference();
2026        if obj_ref != actual_objref {
2027            Ok(ObjectLockStatus::LockedAtDifferentVersion {
2028                locked_ref: actual_objref,
2029            })
2030        } else {
2031            // requested object ref is live, check if there is a lock
2032            Ok(
2033                match self
2034                    .object_locks
2035                    .get_transaction_lock(&obj_ref, epoch_store)?
2036                {
2037                    Some(tx_digest) => ObjectLockStatus::LockedToTx {
2038                        locked_by_tx: LockDetailsDeprecated {
2039                            epoch: cur_epoch,
2040                            tx_digest,
2041                        },
2042                    },
2043                    None => ObjectLockStatus::Initialized,
2044                },
2045            )
2046        }
2047    }
2048
2049    fn _get_live_objref(&self, object_id: ObjectID) -> SuiResult<ObjectRef> {
2050        let obj = self.get_object_impl("live_objref", &object_id).ok_or(
2051            UserInputError::ObjectNotFound {
2052                object_id,
2053                version: None,
2054            },
2055        )?;
2056        Ok(obj.compute_object_reference())
2057    }
2058
2059    fn object_versions_iter(
2060        &self,
2061        object_id: ObjectID,
2062        versions: std::ops::RangeInclusive<SequenceNumber>,
2063        descending: bool,
2064    ) -> SuiResult<Box<dyn Iterator<Item = SuiResult<ObjectOrTombstone>> + '_>> {
2065        let versions = self
2066            .store
2067            .perpetual_tables
2068            .object_versions_iter(object_id, versions, descending)?;
2069        Ok(Box::new(versions))
2070    }
2071
2072    fn get_highest_pruned_checkpoint(&self) -> Option<CheckpointSequenceNumber> {
2073        self.store
2074            .perpetual_tables
2075            .get_highest_pruned_checkpoint()
2076            .expect("db error")
2077    }
2078
2079    fn notify_read_input_objects<'a>(
2080        &'a self,
2081        input_and_receiving_keys: &'a [InputKey],
2082        receiving_keys: &'a HashSet<InputKey>,
2083        epoch: EpochId,
2084    ) -> BoxFuture<'a, ()> {
2085        self.object_notify_read
2086            .read(
2087                "notify_read_input_objects",
2088                input_and_receiving_keys,
2089                move |keys| {
2090                    self.multi_input_objects_available(keys, receiving_keys, epoch)
2091                        .into_iter()
2092                        .map(|available| if available { Some(()) } else { None })
2093                        .collect::<Vec<_>>()
2094                },
2095            )
2096            .map(|_| ())
2097            .boxed()
2098    }
2099}
2100
2101impl TransactionCacheRead for WritebackCache {
2102    fn multi_get_transaction_blocks(
2103        &self,
2104        digests: &[TransactionDigest],
2105    ) -> Vec<Option<Arc<VerifiedTransaction>>> {
2106        let digests_and_tickets: Vec<_> = digests
2107            .iter()
2108            .map(|d| (*d, self.cached.transactions.get_ticket_for_read(d)))
2109            .collect();
2110        do_fallback_lookup(
2111            &digests_and_tickets,
2112            |(digest, _)| {
2113                self.metrics
2114                    .record_cache_request("transaction_block", "uncommitted");
2115                if let Some(tx) = self.dirty.pending_transaction_writes.get(digest) {
2116                    self.metrics
2117                        .record_cache_hit("transaction_block", "uncommitted");
2118                    return CacheResult::Hit(Some(tx.transaction.clone()));
2119                }
2120                self.metrics
2121                    .record_cache_miss("transaction_block", "uncommitted");
2122
2123                self.metrics
2124                    .record_cache_request("transaction_block", "committed");
2125
2126                match self
2127                    .cached
2128                    .transactions
2129                    .get(digest)
2130                    .map(|l| l.lock().clone())
2131                {
2132                    Some(PointCacheItem::Some(tx)) => {
2133                        self.metrics
2134                            .record_cache_hit("transaction_block", "committed");
2135                        CacheResult::Hit(Some(tx))
2136                    }
2137                    Some(PointCacheItem::None) => CacheResult::NegativeHit,
2138                    None => {
2139                        self.metrics
2140                            .record_cache_miss("transaction_block", "committed");
2141
2142                        CacheResult::Miss
2143                    }
2144                }
2145            },
2146            |remaining| {
2147                let remaining_digests: Vec<_> = remaining.iter().map(|(d, _)| *d).collect();
2148                let results: Vec<_> = self
2149                    .record_db_multi_get("transaction_block", remaining.len())
2150                    .multi_get_transaction_blocks(&remaining_digests)
2151                    .expect("db error")
2152                    .into_iter()
2153                    .map(|o| o.map(Arc::new))
2154                    .collect();
2155                for ((digest, ticket), result) in remaining.iter().zip_debug_eq(results.iter()) {
2156                    if result.is_none() {
2157                        self.cached.transactions.insert(digest, None, *ticket).ok();
2158                    }
2159                }
2160                results
2161            },
2162        )
2163    }
2164
2165    fn multi_get_executed_effects_digests(
2166        &self,
2167        digests: &[TransactionDigest],
2168    ) -> Vec<Option<TransactionEffectsDigest>> {
2169        let digests_and_tickets: Vec<_> = digests
2170            .iter()
2171            .map(|d| {
2172                (
2173                    *d,
2174                    self.cached.executed_effects_digests.get_ticket_for_read(d),
2175                )
2176            })
2177            .collect();
2178        do_fallback_lookup(
2179            &digests_and_tickets,
2180            |(digest, _)| {
2181                self.metrics
2182                    .record_cache_request("executed_effects_digests", "uncommitted");
2183                if let Some(digest) = self.dirty.executed_effects_digests.get(digest) {
2184                    self.metrics
2185                        .record_cache_hit("executed_effects_digests", "uncommitted");
2186                    return CacheResult::Hit(Some(*digest));
2187                }
2188                self.metrics
2189                    .record_cache_miss("executed_effects_digests", "uncommitted");
2190
2191                self.metrics
2192                    .record_cache_request("executed_effects_digests", "committed");
2193                match self
2194                    .cached
2195                    .executed_effects_digests
2196                    .get(digest)
2197                    .map(|l| *l.lock())
2198                {
2199                    Some(PointCacheItem::Some(digest)) => {
2200                        self.metrics
2201                            .record_cache_hit("executed_effects_digests", "committed");
2202                        CacheResult::Hit(Some(digest))
2203                    }
2204                    Some(PointCacheItem::None) => CacheResult::NegativeHit,
2205                    None => {
2206                        self.metrics
2207                            .record_cache_miss("executed_effects_digests", "committed");
2208                        CacheResult::Miss
2209                    }
2210                }
2211            },
2212            |remaining| {
2213                let remaining_digests: Vec<_> = remaining.iter().map(|(d, _)| *d).collect();
2214                let results = self
2215                    .record_db_multi_get("executed_effects_digests", remaining.len())
2216                    .multi_get_executed_effects_digests(&remaining_digests)
2217                    .expect("db error");
2218                for ((digest, ticket), result) in remaining.iter().zip_debug_eq(results.iter()) {
2219                    if result.is_none() {
2220                        self.cached
2221                            .executed_effects_digests
2222                            .insert(digest, None, *ticket)
2223                            .ok();
2224                    }
2225                }
2226                results
2227            },
2228        )
2229    }
2230
2231    fn multi_get_effects(
2232        &self,
2233        digests: &[TransactionEffectsDigest],
2234    ) -> Vec<Option<TransactionEffects>> {
2235        let digests_and_tickets: Vec<_> = digests
2236            .iter()
2237            .map(|d| (*d, self.cached.transaction_effects.get_ticket_for_read(d)))
2238            .collect();
2239        do_fallback_lookup(
2240            &digests_and_tickets,
2241            |(digest, _)| {
2242                self.metrics
2243                    .record_cache_request("transaction_effects", "uncommitted");
2244                if let Some(effects) = self.dirty.transaction_effects.get(digest) {
2245                    self.metrics
2246                        .record_cache_hit("transaction_effects", "uncommitted");
2247                    return CacheResult::Hit(Some(effects.clone()));
2248                }
2249                self.metrics
2250                    .record_cache_miss("transaction_effects", "uncommitted");
2251
2252                self.metrics
2253                    .record_cache_request("transaction_effects", "committed");
2254                match self
2255                    .cached
2256                    .transaction_effects
2257                    .get(digest)
2258                    .map(|l| l.lock().clone())
2259                {
2260                    Some(PointCacheItem::Some(effects)) => {
2261                        self.metrics
2262                            .record_cache_hit("transaction_effects", "committed");
2263                        CacheResult::Hit(Some((*effects).clone()))
2264                    }
2265                    Some(PointCacheItem::None) => CacheResult::NegativeHit,
2266                    None => {
2267                        self.metrics
2268                            .record_cache_miss("transaction_effects", "committed");
2269                        CacheResult::Miss
2270                    }
2271                }
2272            },
2273            |remaining| {
2274                let remaining_digests: Vec<_> = remaining.iter().map(|(d, _)| *d).collect();
2275                let results = self
2276                    .record_db_multi_get("transaction_effects", remaining.len())
2277                    .multi_get_effects(remaining_digests.iter())
2278                    .expect("db error");
2279                for ((digest, ticket), result) in remaining.iter().zip_debug_eq(results.iter()) {
2280                    if result.is_none() {
2281                        self.cached
2282                            .transaction_effects
2283                            .insert(digest, None, *ticket)
2284                            .ok();
2285                    }
2286                }
2287                results
2288            },
2289        )
2290    }
2291
2292    fn transaction_executed_in_last_epoch(
2293        &self,
2294        digest: &TransactionDigest,
2295        current_epoch: EpochId,
2296    ) -> bool {
2297        if current_epoch == 0 {
2298            return false;
2299        }
2300        let last_epoch = current_epoch - 1;
2301        let cache_key = (last_epoch, *digest);
2302
2303        let ticket = self
2304            .cached
2305            .transaction_executed_in_last_epoch
2306            .get_ticket_for_read(&cache_key);
2307
2308        if let Some(cached) = self
2309            .cached
2310            .transaction_executed_in_last_epoch
2311            .get(&cache_key)
2312        {
2313            return cached.lock().is_some();
2314        }
2315
2316        let was_executed = self
2317            .store
2318            .perpetual_tables
2319            .was_transaction_executed_in_last_epoch(digest, current_epoch);
2320
2321        let value = if was_executed { Some(()) } else { None };
2322        self.cached
2323            .transaction_executed_in_last_epoch
2324            .insert(&cache_key, value, ticket)
2325            .ok();
2326
2327        was_executed
2328    }
2329
2330    fn notify_read_executed_effects_digests<'a>(
2331        &'a self,
2332        task_name: &'static str,
2333        digests: &'a [TransactionDigest],
2334    ) -> BoxFuture<'a, Vec<TransactionEffectsDigest>> {
2335        self.executed_effects_digests_notify_read
2336            .read(task_name, digests, |digests| {
2337                self.multi_get_executed_effects_digests(digests)
2338            })
2339            .boxed()
2340    }
2341
2342    fn multi_get_events(
2343        &self,
2344        event_digests: &[TransactionDigest],
2345    ) -> Vec<Option<TransactionEvents>> {
2346        fn map_events(events: TransactionEvents) -> Option<TransactionEvents> {
2347            if events.data.is_empty() {
2348                None
2349            } else {
2350                Some(events)
2351            }
2352        }
2353
2354        let digests_and_tickets: Vec<_> = event_digests
2355            .iter()
2356            .map(|d| (*d, self.cached.transaction_events.get_ticket_for_read(d)))
2357            .collect();
2358        do_fallback_lookup(
2359            &digests_and_tickets,
2360            |(digest, _)| {
2361                self.metrics
2362                    .record_cache_request("transaction_events", "uncommitted");
2363                if let Some(events) = self.dirty.transaction_events.get(digest).map(|e| e.clone()) {
2364                    self.metrics
2365                        .record_cache_hit("transaction_events", "uncommitted");
2366
2367                    return CacheResult::Hit(map_events(events));
2368                }
2369                self.metrics
2370                    .record_cache_miss("transaction_events", "uncommitted");
2371
2372                self.metrics
2373                    .record_cache_request("transaction_events", "committed");
2374                match self
2375                    .cached
2376                    .transaction_events
2377                    .get(digest)
2378                    .map(|l| l.lock().clone())
2379                {
2380                    Some(PointCacheItem::Some(events)) => {
2381                        self.metrics
2382                            .record_cache_hit("transaction_events", "committed");
2383                        CacheResult::Hit(map_events((*events).clone()))
2384                    }
2385                    Some(PointCacheItem::None) => CacheResult::NegativeHit,
2386                    None => {
2387                        self.metrics
2388                            .record_cache_miss("transaction_events", "committed");
2389
2390                        CacheResult::Miss
2391                    }
2392                }
2393            },
2394            |remaining| {
2395                let remaining_digests: Vec<_> = remaining.iter().map(|(d, _)| *d).collect();
2396                let results = self
2397                    .store
2398                    .multi_get_events(&remaining_digests)
2399                    .expect("db error");
2400                for ((digest, ticket), result) in remaining.iter().zip_debug_eq(results.iter()) {
2401                    if result.is_none() {
2402                        self.cached
2403                            .transaction_events
2404                            .insert(digest, None, *ticket)
2405                            .ok();
2406                    }
2407                }
2408                results
2409            },
2410        )
2411    }
2412
2413    fn get_unchanged_loaded_runtime_objects(
2414        &self,
2415        digest: &TransactionDigest,
2416    ) -> Option<Vec<ObjectKey>> {
2417        self.dirty
2418            .unchanged_loaded_runtime_objects
2419            .get(digest)
2420            .map(|b| b.clone())
2421            .or_else(|| {
2422                self.store
2423                    .get_unchanged_loaded_runtime_objects(digest)
2424                    .expect("db error")
2425            })
2426    }
2427
2428    fn multi_get_unchanged_loaded_runtime_objects(
2429        &self,
2430        digests: &[TransactionDigest],
2431    ) -> Vec<Option<Vec<ObjectKey>>> {
2432        do_fallback_lookup(
2433            digests,
2434            |digest| match self.dirty.unchanged_loaded_runtime_objects.get(digest) {
2435                Some(objects) => CacheResult::Hit(Some(objects.clone())),
2436                None => CacheResult::Miss,
2437            },
2438            |digests| {
2439                self.store
2440                    .multi_get_unchanged_loaded_runtime_objects(digests)
2441                    .expect("db error")
2442            },
2443        )
2444    }
2445
2446    fn get_highest_pruned_effects_checkpoint(&self) -> Option<CheckpointSequenceNumber> {
2447        self.store
2448            .perpetual_tables
2449            .get_highest_pruned_effects_checkpoint()
2450            .expect("db error")
2451    }
2452
2453    fn take_accumulator_events(&self, digest: &TransactionDigest) -> Option<Vec<AccumulatorEvent>> {
2454        self.dirty
2455            .pending_transaction_writes
2456            .get(digest)
2457            .map(|transaction_output| transaction_output.take_accumulator_events())
2458    }
2459}
2460
2461impl ExecutionCacheWrite for WritebackCache {
2462    fn validate_owned_object_versions(&self, owned_input_objects: &[ObjectRef]) -> SuiResult {
2463        ObjectLocks::validate_owned_object_versions(self, owned_input_objects)
2464    }
2465
2466    fn write_transaction_outputs(&self, epoch_id: EpochId, tx_outputs: Arc<TransactionOutputs>) {
2467        WritebackCache::write_transaction_outputs(self, epoch_id, tx_outputs);
2468    }
2469
2470    #[cfg(test)]
2471    fn write_object_entry_for_test(&self, object: Object) {
2472        self.write_object_entry(&object.id(), object.version(), object.into());
2473    }
2474}
2475
2476implement_passthrough_traits!(WritebackCache);
2477
2478impl GlobalStateHashStore for WritebackCache {
2479    fn get_object_ref_prior_to_key_deprecated(
2480        &self,
2481        object_id: &ObjectID,
2482        version: SequenceNumber,
2483    ) -> SuiResult<Option<ObjectRef>> {
2484        // There is probably a more efficient way to implement this, but since this is only used by
2485        // old protocol versions, it is better to do the simple thing that is obviously correct.
2486        // In this case we previous version from all sources and choose the highest
2487        let mut candidates = Vec::new();
2488
2489        let check_versions =
2490            |versions: &CachedVersionMap<ObjectEntry>| match versions.get_prior_to(&version) {
2491                Some((version, object_entry)) => match object_entry {
2492                    ObjectEntry::Object(object) => {
2493                        assert_eq!(object.version(), version);
2494                        Some(object.compute_object_reference())
2495                    }
2496                    ObjectEntry::Deleted => {
2497                        Some((*object_id, version, ObjectDigest::OBJECT_DIGEST_DELETED))
2498                    }
2499                    ObjectEntry::Wrapped => {
2500                        Some((*object_id, version, ObjectDigest::OBJECT_DIGEST_WRAPPED))
2501                    }
2502                },
2503                None => None,
2504            };
2505
2506        // first check dirty data
2507        if let Some(objects) = self.dirty.objects.get(object_id)
2508            && let Some(prior) = check_versions(&objects)
2509        {
2510            candidates.push(prior);
2511        }
2512
2513        if let Some(objects) = self.cached.object_cache.get(object_id)
2514            && let Some(prior) = check_versions(&objects.lock())
2515        {
2516            candidates.push(prior);
2517        }
2518
2519        if let Some(prior) = self
2520            .store
2521            .get_object_ref_prior_to_key_deprecated(object_id, version)?
2522        {
2523            candidates.push(prior);
2524        }
2525
2526        // sort candidates by version, and return the highest
2527        candidates.sort_by_key(|(_, version, _)| *version);
2528        Ok(candidates.pop())
2529    }
2530
2531    fn get_root_state_hash_for_epoch(
2532        &self,
2533        epoch: EpochId,
2534    ) -> SuiResult<Option<(CheckpointSequenceNumber, GlobalStateHash)>> {
2535        self.store.get_root_state_hash_for_epoch(epoch)
2536    }
2537
2538    fn insert_state_hash_for_epoch(
2539        &self,
2540        epoch: EpochId,
2541        checkpoint_seq_num: &CheckpointSequenceNumber,
2542        acc: &GlobalStateHash,
2543    ) -> SuiResult {
2544        self.store
2545            .insert_state_hash_for_epoch(epoch, checkpoint_seq_num, acc)
2546    }
2547
2548    fn iter_live_object_set(
2549        &self,
2550        include_wrapped_tombstone: bool,
2551    ) -> Box<dyn Iterator<Item = LiveObject> + '_> {
2552        // The only time it is safe to iterate the live object set is at an epoch boundary,
2553        // at which point the db is consistent and the dirty cache is empty. So this does
2554        // read the cache
2555        assert!(
2556            self.dirty.is_empty(),
2557            "cannot iterate live object set with dirty data"
2558        );
2559        self.store.iter_live_object_set(include_wrapped_tombstone)
2560    }
2561
2562    // A version of iter_live_object_set that reads the cache. Only use for testing. If used
2563    // on a live validator, can cause the server to block for as long as it takes to iterate
2564    // the entire live object set.
2565    fn iter_cached_live_object_set_for_testing(
2566        &self,
2567        include_wrapped_tombstone: bool,
2568    ) -> Box<dyn Iterator<Item = LiveObject> + '_> {
2569        // hold iter until we are finished to prevent any concurrent inserts/deletes
2570        let iter = self.dirty.objects.iter();
2571        let mut dirty_objects = BTreeMap::new();
2572
2573        // add everything from the store
2574        for obj in self.store.iter_live_object_set(include_wrapped_tombstone) {
2575            dirty_objects.insert(obj.object_id(), obj);
2576        }
2577
2578        // add everything from the cache, but also remove deletions
2579        for entry in iter {
2580            let id = *entry.key();
2581            let value = entry.value();
2582            match value.get_highest().unwrap() {
2583                (_, ObjectEntry::Object(object)) => {
2584                    dirty_objects.insert(id, LiveObject::Normal(object.clone()));
2585                }
2586                (version, ObjectEntry::Wrapped) => {
2587                    if include_wrapped_tombstone {
2588                        dirty_objects.insert(id, LiveObject::Wrapped(ObjectKey(id, *version)));
2589                    } else {
2590                        dirty_objects.remove(&id);
2591                    }
2592                }
2593                (_, ObjectEntry::Deleted) => {
2594                    dirty_objects.remove(&id);
2595                }
2596            }
2597        }
2598
2599        Box::new(dirty_objects.into_values())
2600    }
2601}
2602
2603// TODO: For correctness, we must at least invalidate the cache when items are written through this
2604// trait (since they could be negatively cached as absent). But it may or may not be optimal to
2605// actually insert them into the cache. For instance if state sync is running ahead of execution,
2606// they might evict other items that are about to be read. This could be an area for tuning in the
2607// future.
2608impl StateSyncAPI for WritebackCache {
2609    fn insert_transaction_and_effects(
2610        &self,
2611        transaction: &VerifiedTransaction,
2612        transaction_effects: &TransactionEffects,
2613    ) {
2614        self.store
2615            .insert_transaction_and_effects(transaction, transaction_effects)
2616            .expect("db error");
2617        self.cached
2618            .transactions
2619            .insert(
2620                transaction.digest(),
2621                PointCacheItem::Some(Arc::new(transaction.clone())),
2622                Ticket::Write,
2623            )
2624            .ok();
2625        self.cached
2626            .transaction_effects
2627            .insert(
2628                &transaction_effects.digest(),
2629                PointCacheItem::Some(Arc::new(transaction_effects.clone())),
2630                Ticket::Write,
2631            )
2632            .ok();
2633    }
2634
2635    fn multi_insert_transaction_and_effects(
2636        &self,
2637        transactions_and_effects: &[VerifiedExecutionData],
2638    ) {
2639        self.store
2640            .multi_insert_transaction_and_effects(transactions_and_effects.iter())
2641            .expect("db error");
2642        for VerifiedExecutionData {
2643            transaction,
2644            effects,
2645        } in transactions_and_effects
2646        {
2647            self.cached
2648                .transactions
2649                .insert(
2650                    transaction.digest(),
2651                    PointCacheItem::Some(Arc::new(transaction.clone())),
2652                    Ticket::Write,
2653                )
2654                .ok();
2655            self.cached
2656                .transaction_effects
2657                .insert(
2658                    &effects.digest(),
2659                    PointCacheItem::Some(Arc::new(effects.clone())),
2660                    Ticket::Write,
2661                )
2662                .ok();
2663        }
2664    }
2665}