Skip to main content

sui_core/authority/
authority_store_tables.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use super::*;
5#[cfg(tidehunter)]
6use crate::authority::epoch_marker_key::EPOCH_MARKER_KEY_SIZE;
7use crate::authority::epoch_marker_key::EpochMarkerKey;
8use serde::{Deserialize, Serialize};
9use std::ops::RangeInclusive;
10use std::path::Path;
11use std::sync::atomic::AtomicU64;
12use sui_types::base_types::SequenceNumber;
13use sui_types::effects::{TransactionEffects, TransactionEvents};
14use sui_types::global_state_hash::GlobalStateHash;
15use sui_types::messages_consensus::SharedTransactionDenyConfig;
16use sui_types::storage::{MarkerValue, ObjectOrTombstone};
17use typed_store::metrics::SamplingInterval;
18use typed_store::rocks::{DBBatch, DBMap, MetricConf};
19#[cfg(not(tidehunter))]
20use typed_store::rocks::{DBMapTableConfigMap, DBOptions, default_db_options, read_size_from_env};
21use typed_store::traits::Map;
22
23use crate::authority::authority_store_types::{
24    StoreObject, StoreObjectValue, StoreObjectWrapper, get_store_object, try_construct_object,
25};
26use crate::authority::epoch_start_configuration::EpochStartConfiguration;
27use typed_store::{DBMapUtils, DbIterator};
28
29#[cfg(not(tidehunter))]
30const ENV_VAR_OBJECTS_BLOCK_CACHE_SIZE: &str = "OBJECTS_BLOCK_CACHE_MB";
31#[cfg(not(tidehunter))]
32pub(crate) const ENV_VAR_LOCKS_BLOCK_CACHE_SIZE: &str = "LOCKS_BLOCK_CACHE_MB";
33#[cfg(not(tidehunter))]
34const ENV_VAR_TRANSACTIONS_BLOCK_CACHE_SIZE: &str = "TRANSACTIONS_BLOCK_CACHE_MB";
35#[cfg(not(tidehunter))]
36const ENV_VAR_EFFECTS_BLOCK_CACHE_SIZE: &str = "EFFECTS_BLOCK_CACHE_MB";
37
38/// Options to apply to every column family of the `perpetual` DB.
39#[derive(Default)]
40pub struct AuthorityPerpetualTablesOptions {
41    /// Whether to enable write stalling on all column families.
42    pub enable_write_stall: bool,
43    /// On tidehunter, attach the per-keyspace objects compactor that retains
44    /// only the latest version per ObjectID. Mutually exclusive with the
45    /// object pruner — see `AuthorityStorePruner::new`.
46    pub enable_objects_compactor: bool,
47}
48
49impl AuthorityPerpetualTablesOptions {
50    /// Whether a node runs the tidehunter objects compactor: validators, which never prune, and
51    /// any node configured with `num_epochs_to_retain = 0`, the setting the compactor replaces.
52    /// Always `false` on RocksDB builds, which have no compactor.
53    pub fn objects_compactor_enabled(is_validator: bool, num_epochs_to_retain: u64) -> bool {
54        cfg!(tidehunter) && (is_validator || num_epochs_to_retain == 0)
55    }
56
57    #[cfg(not(tidehunter))]
58    fn apply_to(&self, mut db_options: DBOptions) -> DBOptions {
59        if !self.enable_write_stall {
60            db_options = db_options.disable_write_throttling();
61        }
62        db_options
63    }
64}
65
66/// AuthorityPerpetualTables contains data that must be preserved from one epoch to the next.
67#[derive(DBMapUtils)]
68#[cfg_attr(tidehunter, tidehunter)]
69pub struct AuthorityPerpetualTables {
70    /// This is a map between the object (ID, version) and the latest state of the object, namely the
71    /// state that is needed to process new transactions.
72    /// State is represented by `StoreObject` enum, which is either a move module or a move object.
73    ///
74    /// Note that while this map can store all versions of an object, we will eventually
75    /// prune old object versions from the db.
76    ///
77    /// IMPORTANT: object versions must *only* be pruned if they appear as inputs in some
78    /// TransactionEffects. Simply pruning all objects but the most recent is an error!
79    /// This is because there can be partially executed transactions whose effects have not yet
80    /// been written out, and which must be retried. But, they cannot be retried unless their input
81    /// objects are still accessible!
82    pub(crate) objects: DBMap<ObjectKey, StoreObjectWrapper>,
83
84    /// This is a map between the transaction digest and the corresponding transaction that's known to be
85    /// executable. This means that it may have been executed locally, or it may have been synced through
86    /// state-sync but hasn't been executed yet.
87    pub(crate) transactions: DBMap<TransactionDigest, TrustedTransaction>,
88
89    /// A map between the transaction digest of a certificate to the effects of its execution.
90    /// We store effects into this table in two different cases:
91    /// 1. When a transaction is synced through state_sync, we store the effects here. These effects
92    ///    are known to be final in the network, but may not have been executed locally yet.
93    /// 2. When the transaction is executed locally on this node, we store the effects here. This means that
94    ///    it's possible to store the same effects twice (once for the synced transaction, and once for the executed).
95    ///
96    /// It's also possible for the effects to be reverted if the transaction didn't make it into the epoch.
97    pub(crate) effects: DBMap<TransactionEffectsDigest, TransactionEffects>,
98
99    /// Transactions that have been executed locally on this node. We need this table since the `effects` table
100    /// doesn't say anything about the execution status of the transaction on this node. When we wait for transactions
101    /// to be executed, we wait for them to appear in this table. When we revert transactions, we remove them from both
102    /// tables.
103    pub(crate) executed_effects: DBMap<TransactionDigest, TransactionEffectsDigest>,
104
105    // Events keyed by the digest of the transaction that produced them.
106    pub(crate) events_2: DBMap<TransactionDigest, TransactionEvents>,
107
108    // Loaded (and unchanged) runtime object references.
109    pub(crate) unchanged_loaded_runtime_objects: DBMap<TransactionDigest, Vec<ObjectKey>>,
110
111    /// DEPRECATED in favor of the table of the same name in authority_per_epoch_store.
112    /// Please do not add new accessors/callsites.
113    /// When transaction is executed via checkpoint executor, we store association here
114    pub(crate) executed_transactions_to_checkpoint:
115        DBMap<TransactionDigest, (EpochId, CheckpointSequenceNumber)>,
116
117    // Finalized root state hash for epoch, to be included in CheckpointSummary
118    // of last checkpoint of epoch. These values should only ever be written once
119    // and never changed
120    pub(crate) root_state_hash_by_epoch:
121        DBMap<EpochId, (CheckpointSequenceNumber, GlobalStateHash)>,
122
123    /// Parameters of the system fixed at the epoch start
124    pub(crate) epoch_start_configuration: DBMap<(), EpochStartConfiguration>,
125
126    /// A singleton table that stores latest pruned checkpoint. Used to keep objects pruner progress
127    pub(crate) pruned_checkpoint: DBMap<(), CheckpointSequenceNumber>,
128
129    /// Expected total amount of SUI in the network. This is expected to remain constant
130    /// throughout the lifetime of the network. We check it at the end of each epoch if
131    /// expensive checks are enabled. We cannot use 10B today because in tests we often
132    /// inject extra gas objects into genesis.
133    pub(crate) expected_network_sui_amount: DBMap<(), u64>,
134
135    /// Expected imbalance between storage fund balance and the sum of storage rebate of all live objects.
136    /// This could be non-zero due to bugs in earlier protocol versions.
137    /// This number is the result of storage_fund_balance - sum(storage_rebate).
138    pub(crate) expected_storage_fund_imbalance: DBMap<(), i64>,
139
140    /// Table that stores the set of received objects and deleted objects and the version at
141    /// which they were received. This is used to prevent possible race conditions around receiving
142    /// objects (since they are not locked by the transaction manager) and for tracking shared
143    /// objects that have been deleted. This table is meant to be pruned per-epoch, and all
144    /// previous epochs other than the current epoch may be pruned safely.
145    pub(crate) object_per_epoch_marker_table: DBMap<(EpochId, ObjectKey), MarkerValue>,
146    pub(crate) object_per_epoch_marker_table_v2: DBMap<EpochMarkerKey, MarkerValue>,
147
148    /// Tracks executed transaction digests across epochs.
149    /// Used to support address balance gas payments feature.
150    /// This table uses epoch-prefixed keys to support efficient pruning via range delete.
151    pub(crate) executed_transaction_digests: DBMap<(EpochId, TransactionDigest), ()>,
152
153    /// A singleton table recording the highest checkpoint whose transaction
154    /// outputs (objects, effects, etc.) are durably committed to this store.
155    /// It is written in the *same* atomic batch as those outputs (see
156    /// `AuthorityStore::build_db_batch` and the checkpoint executor), so it is
157    /// always consistent with the live object set even after an unclean stop.
158    ///
159    /// This differs from the checkpoint store's `highest_executed` watermark,
160    /// which is bumped in a separate write after the outputs are committed: an
161    /// abrupt stop can leave the object writes durable while `highest_executed`
162    /// still lags. Consumers that read the live object set directly (e.g. the
163    /// embedded rpc-store's bulk restore) use this watermark instead, so they
164    /// never observe objects beyond the checkpoint they think they are at.
165    ///
166    /// IMPORTANT: TideHunter keyspaces are order-sensitive once written to disk.
167    /// Keep new keyspaces append-only to preserve compatibility with existing DBs.
168    pub(crate) highest_committed_checkpoint: DBMap<(), CheckpointSequenceNumber>,
169
170    /// Most recent `UpdateTransactionDenyConfig` consensus message accepted from each
171    /// allowlisted peer authority. Persisted across epochs so we can rebuild the
172    /// merged effective deny config after a node restart. Pruned at epoch transitions
173    /// when a peer is no longer in the active committee.
174    pub(crate) shared_transaction_deny_configs: DBMap<AuthorityName, SharedTransactionDenyConfig>,
175
176    /// Singleton: the highest generation this node has ever broadcast in an
177    /// `UpdateTransactionDenyConfig` message.
178    pub(crate) last_broadcast_deny_generation: DBMap<(), u64>,
179
180    /// A singleton table recording the highest checkpoint whose transactions,
181    /// effects, events and unchanged loaded runtime objects the checkpoint
182    /// pruner (`prune_checkpoints`) has deleted. It is written in the same
183    /// atomic batch as those deletes, so it never lags them. Tidehunter
184    /// relocation filters remove these rows by epoch separately and do not
185    /// advance it.
186    ///
187    /// The checkpoint store's `HighestPruned` watermark is written in a later,
188    /// separate batch (it lives in another database), so it can briefly, or
189    /// after an unclean stop, trail the deletes. Readers that judge whether a
190    /// checkpoint's transaction data is still available take the maximum of
191    /// both. The pruner itself resumes from `HighestPruned`, so a crash
192    /// between the two writes re-runs the deletes, which are idempotent.
193    pub(crate) pruned_effects_checkpoint: DBMap<(), CheckpointSequenceNumber>,
194}
195
196impl AuthorityPerpetualTables {
197    pub fn path(parent_path: &Path) -> PathBuf {
198        parent_path.join("perpetual")
199    }
200
201    #[cfg(not(tidehunter))]
202    pub fn open(
203        parent_path: &Path,
204        db_options_override: Option<AuthorityPerpetualTablesOptions>,
205        _pruner_watermark: Option<Arc<AtomicU64>>,
206    ) -> Self {
207        let db_options_override = db_options_override.unwrap_or_default();
208        let db_options = db_options_override
209            .apply_to(default_db_options().optimize_db_for_write_throughput(4, false));
210        let table_options = DBMapTableConfigMap::new(BTreeMap::from([
211            (
212                "objects".to_string(),
213                objects_table_config(db_options.clone()),
214            ),
215            (
216                "transactions".to_string(),
217                transactions_table_config(db_options.clone()),
218            ),
219            (
220                "effects".to_string(),
221                effects_table_config(db_options.clone()),
222            ),
223        ]));
224
225        Self::open_tables_read_write(
226            Self::path(parent_path),
227            MetricConf::new("perpetual")
228                .with_sampling(SamplingInterval::new(Duration::from_secs(60), 0)),
229            Some(db_options.options),
230            Some(table_options),
231        )
232    }
233
234    #[cfg(tidehunter)]
235    pub fn open(
236        parent_path: &Path,
237        db_options_override: Option<AuthorityPerpetualTablesOptions>,
238        pruner_watermark: Option<Arc<AtomicU64>>,
239    ) -> Self {
240        use crate::authority::authority_store_pruner::apply_relocation_filter;
241        tracing::warn!("AuthorityPerpetualTables using tidehunter");
242        use typed_store::tidehunter_util::{
243            Bytes, Decision, KeyIndexing, KeySpaceConfig, KeyType, ThConfig,
244            default_cells_per_mutex, default_max_dirty_keys, default_mutex_count,
245            default_value_cache_size,
246        };
247        let mutexes = default_mutex_count() * 2;
248        let transaction_mutexes = mutexes * 4;
249        let value_cache_size = default_value_cache_size();
250        // effectively disables pruning if not set
251        let pruner_watermark = pruner_watermark.unwrap_or(Arc::new(AtomicU64::new(0)));
252
253        let bloom_config = KeySpaceConfig::new().with_bloom_filter(0.001, 32_000);
254        let objects_compactor = |iter: &mut dyn DoubleEndedIterator<Item = &Bytes>| {
255            let mut retain = HashSet::new();
256            let mut previous: Option<&[u8]> = None;
257            const OID_SIZE: usize = 32;
258            for key in iter.rev() {
259                if let Some(prev) = previous
260                    && prev == &key[..OID_SIZE]
261                {
262                    continue;
263                }
264                previous = Some(&key[..OID_SIZE]);
265                retain.insert(key.clone());
266            }
267            retain
268        };
269        let mut digest_prefix = vec![0; 8];
270        digest_prefix[7] = 32;
271        let uniform_key = KeyType::uniform(default_cells_per_mutex());
272        let epoch_prefix_key = KeyType::from_prefix_bits(9 * 8 + 4);
273        // TransactionDigest is serialized with an 8-byte prefix, so we include it in the key calculation
274        let epoch_tx_digest_prefix_key =
275            KeyType::from_prefix_bits((8/*EpochId*/ + 8/*TransactionDigest prefix*/) * 8 + 12);
276        let object_indexing = KeyIndexing::fixed(32 + 8); //  KeyIndexing::key_reduction(32 + 8, 16..(32 + 8));
277        let mut objects_config = KeySpaceConfig::new()
278            .with_max_dirty_keys(16 * default_max_dirty_keys())
279            .with_value_cache_size(2 * value_cache_size);
280        if matches!(db_options_override, Some(options) if options.enable_objects_compactor) {
281            objects_config = objects_config.with_compactor(Box::new(objects_compactor));
282        }
283
284        let configs = vec![
285            (
286                "objects".to_string(),
287                ThConfig::new_with_config_indexing(
288                    object_indexing,
289                    mutexes * 4,
290                    KeyType::uniform(1),
291                    objects_config,
292                ),
293            ),
294            (
295                "transactions".to_string(),
296                ThConfig::new_with_rm_prefix_indexing(
297                    KeyIndexing::key_reduction(32, 0..16),
298                    transaction_mutexes,
299                    uniform_key,
300                    KeySpaceConfig::new()
301                        .with_value_cache_size(2 * value_cache_size)
302                        .with_relocation_filter(|_, _| Decision::Remove),
303                    digest_prefix.clone(),
304                ),
305            ),
306            (
307                "effects".to_string(),
308                ThConfig::new_with_rm_prefix_indexing(
309                    KeyIndexing::key_reduction(32, 0..16),
310                    transaction_mutexes,
311                    uniform_key,
312                    apply_relocation_filter(
313                        bloom_config.clone().with_value_cache_size(value_cache_size),
314                        pruner_watermark.clone(),
315                        |effects: TransactionEffects| effects.executed_epoch(),
316                        false,
317                    ),
318                    digest_prefix.clone(),
319                ),
320            ),
321            (
322                "executed_effects".to_string(),
323                ThConfig::new_with_rm_prefix_indexing(
324                    KeyIndexing::key_reduction(32, 0..16),
325                    transaction_mutexes,
326                    uniform_key,
327                    bloom_config
328                        .clone()
329                        .with_value_cache_size(value_cache_size)
330                        .with_relocation_filter(|_, _| Decision::Remove),
331                    digest_prefix.clone(),
332                ),
333            ),
334            (
335                "events".to_string(),
336                ThConfig::new_with_rm_prefix(
337                    32 + 8,
338                    mutexes,
339                    uniform_key,
340                    KeySpaceConfig::default().with_relocation_filter(|_, _| Decision::Remove),
341                    digest_prefix.clone(),
342                ),
343            ),
344            (
345                "events_2".to_string(),
346                ThConfig::new_with_rm_prefix(
347                    32,
348                    mutexes,
349                    uniform_key,
350                    KeySpaceConfig::default().with_relocation_filter(|_, _| Decision::Remove),
351                    digest_prefix.clone(),
352                ),
353            ),
354            (
355                "unchanged_loaded_runtime_objects".to_string(),
356                ThConfig::new_with_rm_prefix(
357                    32,
358                    mutexes,
359                    uniform_key,
360                    KeySpaceConfig::default().with_relocation_filter(|_, _| Decision::Remove),
361                    digest_prefix.clone(),
362                ),
363            ),
364            (
365                "executed_transactions_to_checkpoint".to_string(),
366                ThConfig::new_with_rm_prefix(
367                    32,
368                    mutexes,
369                    uniform_key,
370                    apply_relocation_filter(
371                        KeySpaceConfig::default(),
372                        pruner_watermark.clone(),
373                        |(epoch_id, _): (EpochId, CheckpointSequenceNumber)| epoch_id,
374                        false,
375                    ),
376                    digest_prefix.clone(),
377                ),
378            ),
379            (
380                "root_state_hash_by_epoch".to_string(),
381                ThConfig::new(8, 1, KeyType::uniform(1)),
382            ),
383            (
384                "epoch_start_configuration".to_string(),
385                ThConfig::new(0, 1, KeyType::uniform(1)),
386            ),
387            (
388                "pruned_checkpoint".to_string(),
389                ThConfig::new(0, 1, KeyType::uniform(1)),
390            ),
391            (
392                "expected_network_sui_amount".to_string(),
393                ThConfig::new(0, 1, KeyType::uniform(1)),
394            ),
395            (
396                "expected_storage_fund_imbalance".to_string(),
397                ThConfig::new(0, 1, KeyType::uniform(1)),
398            ),
399            (
400                "object_per_epoch_marker_table".to_string(),
401                ThConfig::new_with_config_indexing(
402                    KeyIndexing::VariableLength,
403                    mutexes,
404                    epoch_prefix_key,
405                    apply_relocation_filter(
406                        KeySpaceConfig::default(),
407                        pruner_watermark.clone(),
408                        |(epoch_id, _): (EpochId, ObjectKey)| epoch_id,
409                        true,
410                    ),
411                ),
412            ),
413            (
414                "object_per_epoch_marker_table_v2".to_string(),
415                ThConfig::new_with_config_indexing(
416                    KeyIndexing::fixed(EPOCH_MARKER_KEY_SIZE),
417                    mutexes,
418                    epoch_prefix_key,
419                    apply_relocation_filter(
420                        bloom_config.clone(),
421                        pruner_watermark.clone(),
422                        |k: EpochMarkerKey| k.0,
423                        true,
424                    ),
425                ),
426            ),
427            (
428                "executed_transaction_digests".to_string(),
429                ThConfig::new_with_config_indexing(
430                    // EpochId + (TransactionDigest)
431                    KeyIndexing::fixed(8 + (32 + 8)),
432                    transaction_mutexes,
433                    epoch_tx_digest_prefix_key,
434                    apply_relocation_filter(
435                        bloom_config.clone(),
436                        pruner_watermark.clone(),
437                        |(epoch_id, _): (EpochId, TransactionDigest)| epoch_id,
438                        true,
439                    ),
440                ),
441            ),
442            (
443                "highest_committed_checkpoint".to_string(),
444                ThConfig::new(0, 1, KeyType::uniform(1)),
445            ),
446            (
447                "shared_transaction_deny_configs".to_string(),
448                // AuthorityName encodes to 104 bytes via BCS (8-byte tuple-struct
449                // prefix + 96-byte BLS12381 pubkey), matching authority_capabilities_v2.
450                // Tiny table (one row per allowlisted committee member).
451                ThConfig::new(104, 1, KeyType::uniform(1)),
452            ),
453            (
454                "last_broadcast_deny_generation".to_string(),
455                ThConfig::new(0, 1, KeyType::uniform(1)),
456            ),
457            (
458                "pruned_effects_checkpoint".to_string(),
459                ThConfig::new(0, 1, KeyType::uniform(1)),
460            ),
461        ];
462        Self::open_tables_read_write(
463            Self::path(parent_path),
464            MetricConf::new("perpetual")
465                .with_sampling(SamplingInterval::new(Duration::from_secs(60), 0)),
466            configs.into_iter().collect(),
467        )
468    }
469
470    #[cfg(not(tidehunter))]
471    pub fn open_readonly(parent_path: &Path) -> AuthorityPerpetualTablesReadOnly {
472        Self::get_read_only_handle(
473            Self::path(parent_path),
474            None,
475            None,
476            MetricConf::new("perpetual_readonly"),
477        )
478    }
479
480    #[cfg(tidehunter)]
481    pub fn open_readonly(parent_path: &Path) -> Self {
482        Self::open(parent_path, None, None)
483    }
484
485    #[cfg(tidehunter)]
486    pub fn force_rebuild_control_region(&self) -> anyhow::Result<()> {
487        self.objects.db.force_rebuild_control_region()
488    }
489
490    /// Wait for tidehunter background threads to finish before allowing the caller
491    /// to e.g. rename the database directory. Consumes `Arc<Self>` so all internal
492    /// `Arc<Database>` clones held by the column family `DBMap`s are released as
493    /// part of the drop, leaving only the `Arc<Database>` extracted here.
494    #[cfg(tidehunter)]
495    pub fn wait_for_tidehunter_background_threads(self: Arc<Self>) {
496        let strong = Arc::strong_count(&self);
497        if strong != 1 {
498            println!(
499                "WARNING: wait_for_tidehunter_background_threads called with Arc<AuthorityPerpetualTables> strong_count={} (expected 1); other clones will keep DBMap.db Arc<Database> alive past drop(self) and the inner Database wait will warn/timeout",
500                strong,
501            );
502        }
503        let db = self.objects.db.clone();
504        drop(self);
505        db.wait_for_tidehunter_background_threads();
506    }
507
508    // This is used by indexer to find the correct version of dynamic field child object.
509    // We do not store the version of the child object, but because of lamport timestamp,
510    // we know the child must have version number less then or eq to the parent.
511    pub fn find_object_lt_or_eq_version(
512        &self,
513        object_id: ObjectID,
514        version: SequenceNumber,
515    ) -> SuiResult<Option<Object>> {
516        let mut iter = self.objects.reversed_safe_iter_with_bounds(
517            Some(ObjectKey::min_for_id(&object_id)),
518            Some(ObjectKey(object_id, version)),
519        )?;
520        match iter.next() {
521            Some(Ok((key, o))) => self.object(&key, o),
522            Some(Err(e)) => Err(e.into()),
523            None => Ok(None),
524        }
525    }
526
527    /// The newest row of `object_id` at or below `version`: the object, or the tombstone if it
528    /// was deleted or wrapped there. Reads the table directly, so it sees only versions the
529    /// writeback cache has committed.
530    ///
531    /// The pruner deletes the versions it prunes with range deletes, which the table's read
532    /// options ignore, so a range-deleted version stays readable until compaction drops it.
533    /// Compaction can drop a newer one before an older one, so this can return a pruned version
534    /// older than the one that replaced it. Callers tell a pruned version apart.
535    pub fn find_object_or_tombstone_lt_or_eq_version(
536        &self,
537        object_id: ObjectID,
538        version: SequenceNumber,
539    ) -> SuiResult<Option<ObjectOrTombstone>> {
540        let mut iter = self.objects.reversed_safe_iter_with_bounds(
541            Some(ObjectKey::min_for_id(&object_id)),
542            Some(ObjectKey(object_id, version)),
543        )?;
544        let Some((key, value)) = iter.next().transpose()? else {
545            return Ok(None);
546        };
547        if let Some(tombstone) = self.tombstone_reference(&key, &value)? {
548            return Ok(Some(ObjectOrTombstone::Tombstone(tombstone)));
549        }
550        Ok(self.object(&key, value)?.map(ObjectOrTombstone::Object))
551    }
552
553    /// Iterate the versions of `object_id` within `versions`, oldest first, or newest first if
554    /// `descending`, each a live object or the tombstone at which the object was deleted or
555    /// wrapped. Reads the table directly, so it sees only versions the writeback cache has
556    /// committed.
557    pub fn object_versions_iter(
558        &self,
559        object_id: ObjectID,
560        versions: RangeInclusive<SequenceNumber>,
561        descending: bool,
562    ) -> SuiResult<impl Iterator<Item = SuiResult<ObjectOrTombstone>> + '_> {
563        let low = ObjectKey(object_id, *versions.start());
564        let high = ObjectKey(object_id, *versions.end());
565        let rows = if descending {
566            self.objects
567                .reversed_safe_iter_with_bounds(Some(low), Some(high))?
568        } else {
569            self.objects.safe_range_iter(low..=high)
570        };
571        Ok(rows.map(|row| {
572            let (key, value) = row?;
573            if let Some(tombstone) = self.tombstone_reference(&key, &value)? {
574                return Ok(ObjectOrTombstone::Tombstone(tombstone));
575            }
576            let object = self
577                .object(&key, value)?
578                .expect("Non tombstone store object could not be converted to object");
579            Ok(ObjectOrTombstone::Object(object))
580        }))
581    }
582
583    fn construct_object(
584        &self,
585        object_key: &ObjectKey,
586        store_object: StoreObjectValue,
587    ) -> Result<Object, SuiError> {
588        try_construct_object(object_key, store_object)
589    }
590
591    // Constructs `sui_types::object::Object` from `StoreObjectWrapper`.
592    // Returns `None` if object was deleted/wrapped
593    pub fn object(
594        &self,
595        object_key: &ObjectKey,
596        store_object: StoreObjectWrapper,
597    ) -> Result<Option<Object>, SuiError> {
598        let StoreObject::Value(store_object) = store_object.migrate().into_inner() else {
599            return Ok(None);
600        };
601        Ok(Some(self.construct_object(object_key, *store_object)?))
602    }
603
604    pub fn object_reference(
605        &self,
606        object_key: &ObjectKey,
607        store_object: StoreObjectWrapper,
608    ) -> Result<ObjectRef, SuiError> {
609        let obj_ref = match store_object.migrate().into_inner() {
610            StoreObject::Value(object) => self
611                .construct_object(object_key, *object)?
612                .compute_object_reference(),
613            StoreObject::Deleted => (
614                object_key.0,
615                object_key.1,
616                ObjectDigest::OBJECT_DIGEST_DELETED,
617            ),
618            StoreObject::Wrapped => (
619                object_key.0,
620                object_key.1,
621                ObjectDigest::OBJECT_DIGEST_WRAPPED,
622            ),
623        };
624        Ok(obj_ref)
625    }
626
627    pub fn tombstone_reference(
628        &self,
629        object_key: &ObjectKey,
630        store_object: &StoreObjectWrapper,
631    ) -> Result<Option<ObjectRef>, SuiError> {
632        let obj_ref = match store_object.inner() {
633            StoreObject::Deleted => Some((
634                object_key.0,
635                object_key.1,
636                ObjectDigest::OBJECT_DIGEST_DELETED,
637            )),
638            StoreObject::Wrapped => Some((
639                object_key.0,
640                object_key.1,
641                ObjectDigest::OBJECT_DIGEST_WRAPPED,
642            )),
643            _ => None,
644        };
645        Ok(obj_ref)
646    }
647
648    pub fn get_latest_object_ref_or_tombstone(
649        &self,
650        object_id: ObjectID,
651    ) -> Result<Option<ObjectRef>, SuiError> {
652        let mut iterator = self.objects.reversed_safe_iter_with_bounds(
653            Some(ObjectKey::min_for_id(&object_id)),
654            Some(ObjectKey::max_for_id(&object_id)),
655        )?;
656
657        if let Some(Ok((object_key, value))) = iterator.next()
658            && object_key.0 == object_id
659        {
660            return Ok(Some(self.object_reference(&object_key, value)?));
661        }
662        Ok(None)
663    }
664
665    pub fn get_latest_object_or_tombstone(
666        &self,
667        object_id: ObjectID,
668    ) -> Result<Option<(ObjectKey, StoreObjectWrapper)>, SuiError> {
669        let mut iterator = self.objects.reversed_safe_iter_with_bounds(
670            Some(ObjectKey::min_for_id(&object_id)),
671            Some(ObjectKey::max_for_id(&object_id)),
672        )?;
673
674        if let Some(Ok((object_key, value))) = iterator.next()
675            && object_key.0 == object_id
676        {
677            return Ok(Some((object_key, value)));
678        }
679        Ok(None)
680    }
681
682    pub fn get_recovery_epoch_at_restart(&self) -> SuiResult<EpochId> {
683        Ok(self
684            .epoch_start_configuration
685            .get(&())?
686            .expect("Must have current epoch.")
687            .epoch_start_state()
688            .epoch())
689    }
690
691    pub fn set_epoch_start_configuration(
692        &self,
693        epoch_start_configuration: &EpochStartConfiguration,
694    ) -> SuiResult {
695        let mut wb = self.epoch_start_configuration.batch();
696        wb.insert_batch(
697            &self.epoch_start_configuration,
698            std::iter::once(((), epoch_start_configuration)),
699        )?;
700        wb.write()?;
701        Ok(())
702    }
703
704    pub fn get_highest_pruned_checkpoint(
705        &self,
706    ) -> Result<Option<CheckpointSequenceNumber>, TypedStoreError> {
707        self.pruned_checkpoint.get(&())
708    }
709
710    pub fn set_highest_pruned_checkpoint(
711        &self,
712        wb: &mut DBBatch,
713        checkpoint_number: CheckpointSequenceNumber,
714    ) -> SuiResult {
715        wb.insert_batch(&self.pruned_checkpoint, [((), checkpoint_number)])?;
716        Ok(())
717    }
718
719    pub fn get_highest_committed_checkpoint(
720        &self,
721    ) -> Result<Option<CheckpointSequenceNumber>, TypedStoreError> {
722        self.highest_committed_checkpoint.get(&())
723    }
724
725    /// Stage the highest-committed-checkpoint watermark into `wb`. Must be
726    /// called on the same batch that commits the checkpoint's transaction
727    /// outputs so the watermark and the outputs land atomically.
728    pub fn set_highest_committed_checkpoint(
729        &self,
730        wb: &mut DBBatch,
731        checkpoint_number: CheckpointSequenceNumber,
732    ) -> SuiResult {
733        wb.insert_batch(
734            &self.highest_committed_checkpoint,
735            [((), checkpoint_number)],
736        )?;
737        Ok(())
738    }
739
740    pub fn get_highest_pruned_effects_checkpoint(
741        &self,
742    ) -> Result<Option<CheckpointSequenceNumber>, TypedStoreError> {
743        self.pruned_effects_checkpoint.get(&())
744    }
745
746    /// Stage the pruned-effects watermark into `wb`. Must be called on the
747    /// same batch that deletes the checkpoints' transaction data.
748    pub fn set_highest_pruned_effects_checkpoint(
749        &self,
750        wb: &mut DBBatch,
751        checkpoint_number: CheckpointSequenceNumber,
752    ) -> SuiResult {
753        wb.insert_batch(&self.pruned_effects_checkpoint, [((), checkpoint_number)])?;
754        Ok(())
755    }
756
757    pub fn get_transaction(
758        &self,
759        digest: &TransactionDigest,
760    ) -> SuiResult<Option<TrustedTransaction>> {
761        let Some(transaction) = self.transactions.get(digest)? else {
762            return Ok(None);
763        };
764        Ok(Some(transaction))
765    }
766
767    pub fn list_transactions_from(
768        &self,
769        start: Option<TransactionDigest>,
770        limit: usize,
771    ) -> Result<Vec<TransactionDigest>, typed_store::TypedStoreError> {
772        let iter = self.transactions.safe_iter_with_bounds(start, None);
773        let mut result = Vec::with_capacity(limit);
774        for item in iter.take(limit) {
775            let (digest, _) = item?;
776            result.push(digest);
777        }
778        Ok(result)
779    }
780
781    pub fn get_executed_effects_digest(
782        &self,
783        tx_digest: &TransactionDigest,
784    ) -> Result<Option<TransactionEffectsDigest>, typed_store::TypedStoreError> {
785        self.executed_effects.get(tx_digest)
786    }
787
788    pub fn get_effects_by_digest(
789        &self,
790        effects_digest: &TransactionEffectsDigest,
791    ) -> Result<Option<TransactionEffects>, typed_store::TypedStoreError> {
792        self.effects.get(effects_digest)
793    }
794
795    /// Batch insert executed transaction digests for a given epoch.
796    /// Used by formal snapshot restore to backfill transaction digests from the previous epoch.
797    pub fn insert_executed_transaction_digests_batch(
798        &self,
799        epoch: EpochId,
800        digests: impl Iterator<Item = TransactionDigest>,
801    ) -> SuiResult {
802        let mut batch = self.executed_transaction_digests.batch();
803        batch.insert_batch(
804            &self.executed_transaction_digests,
805            digests.map(|digest| ((epoch, digest), ())),
806        )?;
807        batch.write()?;
808        Ok(())
809    }
810
811    pub fn get_effects(&self, digest: &TransactionDigest) -> SuiResult<Option<TransactionEffects>> {
812        let Some(effect_digest) = self.executed_effects.get(digest)? else {
813            return Ok(None);
814        };
815        Ok(self.effects.get(&effect_digest)?)
816    }
817
818    pub(crate) fn was_transaction_executed_in_last_epoch(
819        &self,
820        digest: &TransactionDigest,
821        current_epoch: EpochId,
822    ) -> bool {
823        if current_epoch == 0 {
824            return false;
825        }
826        self.executed_transaction_digests
827            .contains_key(&(current_epoch - 1, *digest))
828            .expect("db error")
829    }
830
831    // DEPRECATED as the backing table has been moved to authority_per_epoch_store.
832    // Please do not add new accessors/callsites.
833    pub fn get_checkpoint_sequence_number(
834        &self,
835        digest: &TransactionDigest,
836    ) -> SuiResult<Option<(EpochId, CheckpointSequenceNumber)>> {
837        Ok(self.executed_transactions_to_checkpoint.get(digest)?)
838    }
839
840    pub fn set_highest_pruned_checkpoint_without_wb(
841        &self,
842        checkpoint_number: CheckpointSequenceNumber,
843    ) -> SuiResult {
844        let mut wb = self.pruned_checkpoint.batch();
845        self.set_highest_pruned_checkpoint(&mut wb, checkpoint_number)?;
846        wb.write()?;
847        Ok(())
848    }
849
850    pub fn database_is_empty(&self) -> SuiResult<bool> {
851        Ok(self.objects.safe_iter().next().is_none())
852    }
853
854    pub fn iter_live_object_set(&self, include_wrapped_object: bool) -> LiveSetIter<'_> {
855        LiveSetIter {
856            iter: Box::new(self.objects.safe_iter()),
857            tables: self,
858            prev: None,
859            include_wrapped_object,
860        }
861    }
862
863    pub fn range_iter_live_object_set(
864        &self,
865        lower_bound: Option<ObjectID>,
866        upper_bound: Option<ObjectID>,
867        include_wrapped_object: bool,
868    ) -> LiveSetIter<'_> {
869        let lower_bound = lower_bound.as_ref().map(ObjectKey::min_for_id);
870        let upper_bound = upper_bound.as_ref().map(ObjectKey::max_for_id);
871
872        LiveSetIter {
873            iter: Box::new(self.objects.safe_iter_with_bounds(lower_bound, upper_bound)),
874            tables: self,
875            prev: None,
876            include_wrapped_object,
877        }
878    }
879
880    pub fn checkpoint_db(&self, path: &Path) -> SuiResult {
881        // This checkpoints the entire db and not just objects table
882        self.objects.checkpoint_db(path).map_err(Into::into)
883    }
884
885    pub fn insert_root_state_hash(
886        &self,
887        epoch: EpochId,
888        last_checkpoint_of_epoch: CheckpointSequenceNumber,
889        hash: GlobalStateHash,
890    ) -> SuiResult {
891        self.root_state_hash_by_epoch
892            .insert(&epoch, &(last_checkpoint_of_epoch, hash))?;
893        Ok(())
894    }
895
896    pub fn insert_object_test_only(&self, object: Object) -> SuiResult {
897        let object_reference = object.compute_object_reference();
898        let wrapper = get_store_object(object);
899        let mut wb = self.objects.batch();
900        wb.insert_batch(
901            &self.objects,
902            std::iter::once((ObjectKey::from(object_reference), wrapper)),
903        )?;
904        wb.write()?;
905        Ok(())
906    }
907
908    // fallible get object methods for sui-tool, which may need to attempt to read a corrupted database
909    pub fn get_object_fallible(&self, object_id: &ObjectID) -> SuiResult<Option<Object>> {
910        let obj_entry = self
911            .objects
912            .reversed_safe_iter_with_bounds(None, Some(ObjectKey::max_for_id(object_id)))?
913            .next();
914
915        match obj_entry.transpose()? {
916            Some((ObjectKey(obj_id, version), obj)) if obj_id == *object_id => {
917                Ok(self.object(&ObjectKey(obj_id, version), obj)?)
918            }
919            _ => Ok(None),
920        }
921    }
922
923    pub fn get_object_by_key_fallible(
924        &self,
925        object_id: &ObjectID,
926        version: VersionNumber,
927    ) -> SuiResult<Option<Object>> {
928        Ok(self
929            .objects
930            .get(&ObjectKey(*object_id, version))?
931            .and_then(|object| {
932                self.object(&ObjectKey(*object_id, version), object)
933                    .expect("object construction error")
934            }))
935    }
936}
937
938impl ObjectStore for AuthorityPerpetualTables {
939    /// Read an object and return it, or Ok(None) if the object was not found.
940    fn get_object(&self, object_id: &ObjectID) -> Option<Object> {
941        self.get_object_fallible(object_id).expect("db error")
942    }
943
944    fn get_object_by_key(&self, object_id: &ObjectID, version: VersionNumber) -> Option<Object> {
945        self.get_object_by_key_fallible(object_id, version)
946            .expect("db error")
947    }
948}
949
950pub struct LiveSetIter<'a> {
951    iter: DbIterator<'a, (ObjectKey, StoreObjectWrapper)>,
952    tables: &'a AuthorityPerpetualTables,
953    prev: Option<(ObjectKey, StoreObjectWrapper)>,
954    /// Whether a wrapped object is considered as a live object.
955    include_wrapped_object: bool,
956}
957
958#[derive(Eq, PartialEq, Debug, Clone, Deserialize, Serialize, Hash)]
959pub enum LiveObject {
960    Normal(Object),
961    Wrapped(ObjectKey),
962}
963
964impl LiveObject {
965    pub fn object_id(&self) -> ObjectID {
966        match self {
967            LiveObject::Normal(obj) => obj.id(),
968            LiveObject::Wrapped(key) => key.0,
969        }
970    }
971
972    pub fn version(&self) -> SequenceNumber {
973        match self {
974            LiveObject::Normal(obj) => obj.version(),
975            LiveObject::Wrapped(key) => key.1,
976        }
977    }
978
979    pub fn object_reference(&self) -> ObjectRef {
980        match self {
981            LiveObject::Normal(obj) => obj.compute_object_reference(),
982            LiveObject::Wrapped(key) => (key.0, key.1, ObjectDigest::OBJECT_DIGEST_WRAPPED),
983        }
984    }
985}
986
987impl LiveSetIter<'_> {
988    fn store_object_wrapper_to_live_object(
989        &self,
990        object_key: ObjectKey,
991        store_object: StoreObjectWrapper,
992    ) -> Option<LiveObject> {
993        match store_object.migrate().into_inner() {
994            StoreObject::Value(object) => {
995                let object = self
996                    .tables
997                    .construct_object(&object_key, *object)
998                    .expect("Constructing object from store cannot fail");
999                Some(LiveObject::Normal(object))
1000            }
1001            StoreObject::Wrapped => {
1002                if self.include_wrapped_object {
1003                    Some(LiveObject::Wrapped(object_key))
1004                } else {
1005                    None
1006                }
1007            }
1008            StoreObject::Deleted => None,
1009        }
1010    }
1011}
1012
1013impl Iterator for LiveSetIter<'_> {
1014    type Item = LiveObject;
1015
1016    fn next(&mut self) -> Option<Self::Item> {
1017        loop {
1018            if let Some(Ok((next_key, next_value))) = self.iter.next() {
1019                let prev = self.prev.take();
1020                self.prev = Some((next_key, next_value));
1021
1022                if let Some((prev_key, prev_value)) = prev
1023                    && prev_key.0 != next_key.0
1024                {
1025                    let live_object =
1026                        self.store_object_wrapper_to_live_object(prev_key, prev_value);
1027                    if live_object.is_some() {
1028                        return live_object;
1029                    }
1030                }
1031                continue;
1032            }
1033            if let Some((key, value)) = self.prev.take() {
1034                let live_object = self.store_object_wrapper_to_live_object(key, value);
1035                if live_object.is_some() {
1036                    return live_object;
1037                }
1038            }
1039            return None;
1040        }
1041    }
1042}
1043
1044// These functions are used to initialize the DB tables
1045#[cfg(not(tidehunter))]
1046fn objects_table_config(db_options: DBOptions) -> DBOptions {
1047    db_options
1048        .optimize_for_write_throughput()
1049        .optimize_for_read(read_size_from_env(ENV_VAR_OBJECTS_BLOCK_CACHE_SIZE).unwrap_or(5 * 1024))
1050}
1051
1052#[cfg(not(tidehunter))]
1053fn transactions_table_config(db_options: DBOptions) -> DBOptions {
1054    db_options
1055        .optimize_for_write_throughput()
1056        .optimize_for_point_lookup(
1057            read_size_from_env(ENV_VAR_TRANSACTIONS_BLOCK_CACHE_SIZE).unwrap_or(512),
1058        )
1059}
1060
1061#[cfg(not(tidehunter))]
1062fn effects_table_config(db_options: DBOptions) -> DBOptions {
1063    db_options
1064        .optimize_for_write_throughput()
1065        .optimize_for_point_lookup(
1066            read_size_from_env(ENV_VAR_EFFECTS_BLOCK_CACHE_SIZE).unwrap_or(1024),
1067        )
1068}
1069
1070#[cfg(test)]
1071pub(crate) mod tests {
1072    use super::*;
1073    #[cfg(not(tidehunter))]
1074    use sui_types::base_types::SuiAddress;
1075    #[cfg(not(tidehunter))]
1076    use sui_types::object::Owner;
1077
1078    #[test]
1079    fn objects_compactor_enabled_only_on_tidehunter() {
1080        let enabled = AuthorityPerpetualTablesOptions::objects_compactor_enabled;
1081        // RocksDB has no compactor, so its full nodes may combine retention 0 with rpc indexing.
1082        assert_eq!(enabled(false, 0), cfg!(tidehunter));
1083        assert_eq!(enabled(true, 2), cfg!(tidehunter));
1084        // Full nodes that retain old object versions keep the object pruner.
1085        assert!(!enabled(false, 2));
1086    }
1087
1088    /// Version `version` of `id`, written by `previous_transaction`.
1089    #[cfg(not(tidehunter))]
1090    pub(crate) fn object_version(
1091        id: ObjectID,
1092        version: u64,
1093        previous_transaction: TransactionDigest,
1094    ) -> Object {
1095        let mut object = Object::with_id_owner_version_for_testing(
1096            id,
1097            SequenceNumber::from_u64(version),
1098            Owner::AddressOwner(SuiAddress::ZERO),
1099        )
1100        .into_inner();
1101        object.previous_transaction = previous_transaction;
1102        object.into()
1103    }
1104
1105    /// Write `versions` of one object, oldest first, and range-delete all but the newest, as the
1106    /// pruner does once the newest replaces them. The oldest is flushed to an SST file first; the
1107    /// others share the range delete's memtable, so the flush after it drops them while the
1108    /// oldest survives until compaction. The table's scans, which ignore range deletions, then
1109    /// read the oldest for a bound between the second one and the newest. `flush_dir` is a
1110    /// directory the two database checkpoints that flush the memtables are written under.
1111    #[cfg(not(tidehunter))]
1112    pub(crate) fn write_and_prune_all_but_newest(
1113        tables: &AuthorityPerpetualTables,
1114        flush_dir: &Path,
1115        versions: &[Object],
1116    ) {
1117        let [oldest, rest @ ..] = versions else {
1118            panic!("no versions to write");
1119        };
1120        let newest = rest.last().expect("one version cannot be pruned");
1121        let insert = |object: &Object| {
1122            tables
1123                .objects
1124                .insert(
1125                    &ObjectKey(object.id(), object.version()),
1126                    &get_store_object(object.clone()),
1127                )
1128                .unwrap();
1129        };
1130        // A database checkpoint flushes every column family's memtable; `DBMap::flush` flushes
1131        // only the default one.
1132        let flush = |name: &str| {
1133            tables.objects.checkpoint_db(&flush_dir.join(name)).unwrap();
1134        };
1135        insert(oldest);
1136        flush("first");
1137        rest.iter().for_each(insert);
1138        let mut batch = tables.objects.batch();
1139        batch
1140            .schedule_delete_range(
1141                &tables.objects,
1142                &ObjectKey(oldest.id(), oldest.version()),
1143                &ObjectKey(newest.id(), newest.version()),
1144            )
1145            .unwrap();
1146        batch.write().unwrap();
1147        flush("second");
1148    }
1149}