Skip to main content

iota_core/authority/
authority_store.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::{collections::HashSet, iter, mem, sync::Arc, thread};
6
7use either::Either;
8use fastcrypto::hash::{HashFunction, Sha3_256};
9use futures::stream::FuturesUnordered;
10use iota_common::sync::notify_read::NotifyRead;
11use iota_config::migration_tx_data::MigrationTxData;
12use iota_genesis_common::MigrationTxDataExt;
13use iota_macros::fail_point_arg;
14use iota_sdk_types::{TransactionEffects, TransactionEvents, Version};
15use iota_storage::mutex_table::{MutexGuard, MutexTable};
16use iota_types::{
17    attestation::AttestationRecord,
18    base_types::VerifiedExecutionData,
19    error::UserInputError,
20    execution::TypeLayoutStore,
21    fp_bail, fp_ensure,
22    global_state_hash::GlobalStateHash,
23    iota_system_state::{
24        get_iota_system_state, iota_system_state_summary::IotaSystemStateSummaryV2,
25    },
26    messages_checkpoint::CheckpointContentsExt,
27    storage::{
28        BackingPackageStore, MarkerValue, ObjectKey, ObjectOrTombstone, ObjectStore, get_module,
29    },
30};
31use itertools::izip;
32use move_core_types::resolver::ModuleResolver;
33use tokio::time::Instant;
34use tracing::{debug, info, trace};
35use typed_store::{
36    DbIterator,
37    rocks::{DBBatch, DBMap},
38    traits::Map,
39};
40
41use super::{
42    authority_store_tables::{AuthorityPerpetualTables, LiveObject},
43    *,
44};
45use crate::{
46    authority::{
47        authority_per_epoch_store::{AuthorityPerEpochStore, LockDetails},
48        authority_store_tables::TotalIotaSupplyCheck,
49        authority_store_types::{StoreObject, StoreObjectWrapper, get_store_object},
50        epoch_markers::EpochMarkers,
51        epoch_start_configuration::{EpochFlag, EpochStartConfiguration},
52        historic_ledger::{HistoricLedger, HistoricLedgerBucket},
53        historic_objects::{HistoricObjects, HistoricObjectsBucket},
54    },
55    global_state_hasher::GlobalStateHashStore,
56    transaction_outputs::TransactionOutputs,
57};
58
59const NUM_SHARDS: usize = 4096;
60
61/// The epoch a database initialized from genesis starts in.
62const GENESIS_EPOCH: EpochId = 0;
63
64struct AuthorityStoreMetrics {
65    iota_conservation_check_latency: IntGauge,
66    iota_conservation_live_object_count: IntGauge,
67    iota_conservation_live_object_size: IntGauge,
68    iota_conservation_imbalance: IntGauge,
69    iota_conservation_storage_fund: IntGauge,
70    iota_conservation_storage_fund_imbalance: IntGauge,
71    epoch_flags: IntGaugeVec,
72}
73
74impl AuthorityStoreMetrics {
75    pub fn new(registry: &Registry) -> Self {
76        Self {
77            iota_conservation_check_latency: register_int_gauge_with_registry!(
78                "iota_conservation_check_latency",
79                "Number of seconds took to scan all live objects in the store for IOTA conservation check",
80                registry;
81                MetricLevel::Warn,
82            ).unwrap(),
83            iota_conservation_live_object_count: register_int_gauge_with_registry!(
84                "iota_conservation_live_object_count",
85                "Number of live objects in the store",
86                registry;
87                MetricLevel::Warn,
88            ).unwrap(),
89            iota_conservation_live_object_size: register_int_gauge_with_registry!(
90                "iota_conservation_live_object_size",
91                "Size in bytes of live objects in the store",
92                registry;
93                MetricLevel::Warn,
94            ).unwrap(),
95            iota_conservation_imbalance: register_int_gauge_with_registry!(
96                "iota_conservation_imbalance",
97                "Total amount of IOTA in the network - 10B * 10^9. This delta shows the amount of imbalance",
98                registry;
99                MetricLevel::Warn,
100            ).unwrap(),
101            iota_conservation_storage_fund: register_int_gauge_with_registry!(
102                "iota_conservation_storage_fund",
103                "Storage Fund pool balance (only includes the storage fund proper that represents object storage)",
104                registry;
105                MetricLevel::Warn,
106            ).unwrap(),
107            iota_conservation_storage_fund_imbalance: register_int_gauge_with_registry!(
108                "iota_conservation_storage_fund_imbalance",
109                "Imbalance of storage fund, computed with storage_fund_balance - total_object_storage_rebates",
110                registry;
111                MetricLevel::Warn,
112            ).unwrap(),
113            epoch_flags: register_int_gauge_vec_with_registry!(
114                "epoch_flags",
115                "Local flags of the currently running epoch",
116                &["flag"],
117                registry,
118            ).unwrap(),
119        }
120    }
121}
122
123/// The `AuthorityStore` manages the state and operations of an authority's
124/// store. It includes a `mutex_table` to handle concurrent writes to the
125/// database and references to various tables stored in
126/// `AuthorityPerpetualTables`. The struct provides mechanisms for initializing
127/// and accessing locks, managing objects and transactions, and performing
128/// epoch-specific operations. It also includes methods for recovering from
129/// crashes, checking IOTA conservation, and handling object markers and states
130/// during epoch transitions.
131pub struct AuthorityStore {
132    /// Internal vector of locks to manage concurrent writes to the database
133    mutex_table: MutexTable<ObjectDigest>,
134
135    pub(crate) perpetual_tables: Arc<AuthorityPerpetualTables>,
136
137    /// Superseded object versions, moved out of the live `objects` table in
138    /// the batch that commits the superseding transaction.
139    historic_objects: Arc<HistoricObjects>,
140
141    /// Transaction history, bucketed by the epoch that executed it.
142    historic_ledger: Arc<HistoricLedger>,
143    epoch_markers: Arc<EpochMarkers>,
144
145    pub(crate) root_state_notify_read:
146        NotifyRead<EpochId, (CheckpointSequenceNumber, GlobalStateHash)>,
147
148    /// Whether to enable expensive IOTA conservation check at epoch boundaries.
149    enable_epoch_iota_conservation_check: bool,
150
151    metrics: AuthorityStoreMetrics,
152}
153
154pub type ExecutionLockReadGuard<'a> = tokio::sync::RwLockReadGuard<'a, EpochId>;
155pub type ExecutionLockWriteGuard<'a> = tokio::sync::RwLockWriteGuard<'a, EpochId>;
156
157impl AuthorityStore {
158    /// Open an authority store by directory path.
159    /// If the store is empty, initialize it using genesis.
160    pub async fn open(
161        perpetual_tables: Arc<AuthorityPerpetualTables>,
162        historic_objects: Arc<HistoricObjects>,
163        historic_ledger: Arc<HistoricLedger>,
164        epoch_markers: Arc<EpochMarkers>,
165        genesis: &Genesis,
166        config: &NodeConfig,
167        registry: &Registry,
168        migration_tx_data: Option<&MigrationTxData>,
169    ) -> IotaResult<Arc<Self>> {
170        let enable_epoch_iota_conservation_check = config
171            .expensive_safety_check_config
172            .enable_epoch_iota_conservation_check();
173
174        let epoch_start_configuration = if perpetual_tables.database_is_empty()? {
175            info!("Creating new epoch start config from genesis");
176
177            #[cfg_attr(not(any(msim, fail_points)), expect(unused_mut))]
178            let mut initial_epoch_flags = EpochFlag::default_flags_for_new_epoch(config);
179            fail_point_arg!("initial_epoch_flags", |flags: Vec<EpochFlag>| {
180                info!("Setting initial epoch flags to {:?}", flags);
181                initial_epoch_flags = flags;
182            });
183
184            let epoch_start_configuration = EpochStartConfiguration::new(
185                genesis.iota_system_object().into_epoch_start_state(),
186                *genesis.checkpoint().digest(),
187                &genesis.objects(),
188                initial_epoch_flags,
189            )?;
190            perpetual_tables.set_epoch_start_configuration(&epoch_start_configuration)?;
191            epoch_start_configuration
192        } else {
193            info!("Loading epoch start config from DB");
194            perpetual_tables
195                .epoch_start_configuration
196                .get(&())?
197                .expect("Epoch start configuration must be set in non-empty DB")
198        };
199        let cur_epoch = perpetual_tables.get_recovery_epoch_at_restart()?;
200        info!("Epoch start config: {:?}", epoch_start_configuration);
201        info!("Cur epoch: {:?}", cur_epoch);
202        let this = Self::open_inner(
203            genesis,
204            perpetual_tables,
205            historic_objects,
206            historic_ledger,
207            epoch_markers,
208            enable_epoch_iota_conservation_check,
209            registry,
210            migration_tx_data,
211        )
212        .await?;
213        this.update_epoch_flags_metrics(&[], epoch_start_configuration.flags());
214        Ok(this)
215    }
216
217    pub fn update_epoch_flags_metrics(&self, old: &[EpochFlag], new: &[EpochFlag]) {
218        for flag in old {
219            self.metrics
220                .epoch_flags
221                .with_label_values(&[&flag.to_string()])
222                .set(0);
223        }
224        for flag in new {
225            self.metrics
226                .epoch_flags
227                .with_label_values(&[&flag.to_string()])
228                .set(1);
229        }
230    }
231
232    // NB: This must only be called at time of reconfiguration. We take the
233    // execution lock write guard as an argument to ensure that this is the
234    // case.
235    /// Drops the marker buckets of every epoch below `new_epoch`, after
236    /// opening the bucket of `new_epoch`.
237    pub fn expire_epoch_markers(
238        &self,
239        new_epoch: EpochId,
240        _execution_guard: &ExecutionLockWriteGuard<'_>,
241    ) -> IotaResult<()> {
242        self.epoch_markers.expire(new_epoch)?;
243        Ok(())
244    }
245
246    pub async fn open_with_committee_for_testing(
247        perpetual_tables: Arc<AuthorityPerpetualTables>,
248        historic_objects: Arc<HistoricObjects>,
249        historic_ledger: Arc<HistoricLedger>,
250        epoch_markers: Arc<EpochMarkers>,
251        committee: &Committee,
252        genesis: &Genesis,
253    ) -> IotaResult<Arc<Self>> {
254        // TODO: Since we always start at genesis, the committee should be technically
255        // the same as the genesis committee.
256        assert_eq!(committee.epoch, 0);
257        Self::open_inner(
258            genesis,
259            perpetual_tables,
260            historic_objects,
261            historic_ledger,
262            epoch_markers,
263            true,
264            &Registry::new(),
265            None,
266        )
267        .await
268    }
269
270    async fn open_inner(
271        genesis: &Genesis,
272        perpetual_tables: Arc<AuthorityPerpetualTables>,
273        historic_objects: Arc<HistoricObjects>,
274        historic_ledger: Arc<HistoricLedger>,
275        epoch_markers: Arc<EpochMarkers>,
276        enable_epoch_iota_conservation_check: bool,
277        registry: &Registry,
278        migration_tx_data: Option<&MigrationTxData>,
279    ) -> IotaResult<Arc<Self>> {
280        let store = Arc::new(Self {
281            mutex_table: MutexTable::new(NUM_SHARDS),
282            perpetual_tables,
283            historic_objects,
284            historic_ledger,
285            epoch_markers,
286            root_state_notify_read: NotifyRead::<
287                EpochId,
288                (CheckpointSequenceNumber, GlobalStateHash),
289            >::new(),
290            enable_epoch_iota_conservation_check,
291            metrics: AuthorityStoreMetrics::new(registry),
292        });
293        // Only initialize an empty database.
294        if store
295            .database_is_empty()
296            .expect("database read should not fail at init.")
297        {
298            // Initialize with genesis data
299            // First insert genesis objects
300            store
301                .bulk_insert_genesis_objects(genesis.objects())
302                .expect("cannot bulk insert genesis objects");
303
304            let bucket = store
305                .historic_ledger
306                .ensure(GENESIS_EPOCH)
307                .expect("cannot open the genesis epoch's ledger bucket");
308
309            // Then insert txn and effects of genesis
310            let transaction = VerifiedTransaction::new_unchecked(genesis.transaction().clone());
311            bucket
312                .transactions
313                .insert(transaction.digest(), transaction.serializable_ref())
314                .expect("cannot insert genesis transaction");
315            bucket
316                .effects
317                .insert(&genesis.effects().digest(), genesis.effects())
318                .expect("cannot insert genesis effects");
319
320            // In the previous step we don't insert the effects to executed_effects yet
321            // because the genesis tx hasn't but will be executed. This is
322            // important for fullnodes to be able to generate indexing data
323            // right now.
324            if genesis.effects().events_digest().is_some() {
325                bucket
326                    .events
327                    .insert(transaction.digest(), genesis.events())
328                    .unwrap();
329            }
330
331            // Initialize with migration data if genesis contained migration transactions
332            if let Some(migration_transactions) = migration_tx_data {
333                // This migration data was validated during the loading into the node (invoked
334                // by the caller of this function)
335                let txs_data = migration_transactions.txs_data();
336
337                // We iterate over the contents of the genesis checkpoint, that includes all
338                // migration transactions execution digest. Thus we cover all transactions that
339                // were considered during the creation of the genesis blob.
340                for (_, execution_digest) in genesis
341                    .checkpoint_contents()
342                    .enumerate_transactions(&genesis.checkpoint())
343                {
344                    let tx_digest = &execution_digest.transaction;
345                    // We can skip the genesis transaction and its data because above it was already
346                    // stored in the genesis epoch's bucket.
347                    if tx_digest == genesis.transaction().digest() {
348                        continue;
349                    }
350                    // Now we can store this migration transaction, together with
351                    // its effects, events and created objects.
352                    let Some((tx, effects, events)) = txs_data.get(tx_digest) else {
353                        panic!("tx digest not found in migrated objects blob");
354                    };
355                    let transaction = VerifiedTransaction::new_unchecked(tx.clone());
356                    let objects = migration_transactions
357                        .objects_by_tx_digest(*tx_digest)
358                        .expect("the migration data is corrupted");
359                    store
360                        .bulk_insert_genesis_objects(&objects)
361                        .expect("cannot bulk insert migrated objects");
362                    bucket
363                        .transactions
364                        .insert(transaction.digest(), transaction.serializable_ref())
365                        .expect("cannot insert migration transaction");
366                    bucket
367                        .effects
368                        .insert(&effects.digest(), effects)
369                        .expect("cannot insert migration effects");
370                    if effects.events_digest().is_some() {
371                        bucket.events.insert(transaction.digest(), events).unwrap();
372                    }
373                }
374            }
375        }
376
377        Ok(store)
378    }
379
380    /// Open authority store without any operations that require
381    /// genesis, such as constructing EpochStartConfiguration
382    /// or inserting genesis objects.
383    pub fn open_no_genesis(
384        perpetual_tables: Arc<AuthorityPerpetualTables>,
385        historic_objects: Arc<HistoricObjects>,
386        historic_ledger: Arc<HistoricLedger>,
387        epoch_markers: Arc<EpochMarkers>,
388        enable_epoch_iota_conservation_check: bool,
389        registry: &Registry,
390    ) -> IotaResult<Arc<Self>> {
391        let store = Arc::new(Self {
392            mutex_table: MutexTable::new(NUM_SHARDS),
393            perpetual_tables,
394            historic_objects,
395            historic_ledger,
396            epoch_markers,
397            root_state_notify_read: NotifyRead::<
398                EpochId,
399                (CheckpointSequenceNumber, GlobalStateHash),
400            >::new(),
401            enable_epoch_iota_conservation_check,
402            metrics: AuthorityStoreMetrics::new(registry),
403        });
404        Ok(store)
405    }
406
407    /// Superseded object versions, bucketed by the epoch that superseded them.
408    pub fn get_historic_objects(&self) -> &Arc<HistoricObjects> {
409        &self.historic_objects
410    }
411
412    /// Transaction history, bucketed by the epoch that executed it.
413    pub fn get_historic_ledger(&self) -> &Arc<HistoricLedger> {
414        &self.historic_ledger
415    }
416
417    pub fn get_epoch_markers(&self) -> &Arc<EpochMarkers> {
418        &self.epoch_markers
419    }
420
421    pub fn get_recovery_epoch_at_restart(&self) -> IotaResult<EpochId> {
422        self.perpetual_tables.get_recovery_epoch_at_restart()
423    }
424
425    pub fn get_effects(
426        &self,
427        effects_digest: &TransactionEffectsDigest,
428    ) -> IotaResult<Option<TransactionEffects>> {
429        self.historic_ledger.get_effects(effects_digest)
430    }
431
432    /// Returns true if we have an effects structure for this transaction digest
433    pub fn effects_exists(&self, effects_digest: &TransactionEffectsDigest) -> IotaResult<bool> {
434        self.historic_ledger.contains_effects(effects_digest)
435    }
436
437    pub fn get_events(&self, digest: &TransactionDigest) -> IotaResult<Option<TransactionEvents>> {
438        self.historic_ledger.get_events(digest)
439    }
440
441    pub fn multi_get_events(
442        &self,
443        event_digests: &[TransactionDigest],
444    ) -> IotaResult<Vec<Option<TransactionEvents>>> {
445        self.historic_ledger.multi_get_events(event_digests)
446    }
447
448    /// [`Self::multi_get_events`] read from `epoch`'s records alone; events
449    /// stored under another epoch are reported as absent.
450    pub fn multi_get_events_in_epoch(
451        &self,
452        epoch: EpochId,
453        tx_digests: &[TransactionDigest],
454    ) -> IotaResult<Vec<Option<TransactionEvents>>> {
455        self.historic_ledger
456            .multi_get_events_in_epoch(epoch, tx_digests)
457    }
458
459    pub fn multi_get_effects<'a>(
460        &self,
461        effects_digests: impl Iterator<Item = &'a TransactionEffectsDigest>,
462    ) -> IotaResult<Vec<Option<TransactionEffects>>> {
463        let effects_digests: Vec<_> = effects_digests.copied().collect();
464        self.historic_ledger.multi_get_effects(&effects_digests)
465    }
466
467    /// [`Self::multi_get_effects`] read from `epoch`'s records alone; effects
468    /// stored under another epoch are reported as absent.
469    pub fn multi_get_effects_in_epoch(
470        &self,
471        epoch: EpochId,
472        effects_digests: &[TransactionEffectsDigest],
473    ) -> IotaResult<Vec<Option<TransactionEffects>>> {
474        self.historic_ledger
475            .multi_get_effects_in_epoch(epoch, effects_digests)
476    }
477
478    /// Given a list of transaction digests, returns a list of the corresponding
479    /// effects only if they have been executed. For transactions that have
480    /// not been executed, None is returned.
481    pub fn multi_get_executed_effects_digests(
482        &self,
483        digests: &[TransactionDigest],
484    ) -> IotaResult<Vec<Option<TransactionEffectsDigest>>> {
485        self.historic_ledger
486            .multi_get_executed_effects_digests(digests)
487    }
488
489    /// [`Self::multi_get_executed_effects_digests`] for transactions that can
490    /// only have been executed in `epoch`: it reads that epoch's records
491    /// alone, and reports one executed in another epoch as not executed.
492    pub fn multi_get_executed_effects_digests_in_epoch(
493        &self,
494        epoch: EpochId,
495        digests: &[TransactionDigest],
496    ) -> IotaResult<Vec<Option<TransactionEffectsDigest>>> {
497        self.historic_ledger
498            .multi_get_executed_effects_digests_in_epoch(epoch, digests)
499    }
500
501    /// The attestation records of transactions that can only have been
502    /// executed in `epoch`, read from that epoch's records alone; `None` for
503    /// an unattested transaction or one executed in another epoch.
504    pub fn multi_get_attestation_records_in_epoch(
505        &self,
506        epoch: EpochId,
507        digests: &[TransactionDigest],
508    ) -> IotaResult<Vec<Option<AttestationRecord>>> {
509        self.historic_ledger
510            .multi_get_attestation_records_in_epoch(epoch, digests)
511    }
512
513    /// Given a list of transaction digests, returns a list of the corresponding
514    /// effects only if they have been executed. For transactions that have
515    /// not been executed, None is returned.
516    pub fn multi_get_executed_effects(
517        &self,
518        digests: &[TransactionDigest],
519    ) -> IotaResult<Vec<Option<TransactionEffects>>> {
520        self.historic_ledger.multi_get_executed_effects(digests)
521    }
522
523    pub fn is_tx_already_executed(&self, digest: &TransactionDigest) -> IotaResult<bool> {
524        Ok(self.historic_ledger.find_epoch(digest)?.is_some())
525    }
526
527    pub fn get_marker_value(
528        &self,
529        object_id: &ObjectId,
530        version: &Version,
531        epoch_id: EpochId,
532    ) -> IotaResult<Option<MarkerValue>> {
533        self.epoch_markers
534            .get_marker_value(object_id, version, epoch_id)
535    }
536
537    pub fn get_latest_marker(
538        &self,
539        object_id: &ObjectId,
540        epoch_id: EpochId,
541    ) -> IotaResult<Option<(Version, MarkerValue)>> {
542        self.epoch_markers.get_latest_marker(object_id, epoch_id)
543    }
544
545    /// Returns future containing the state hash for the given epoch
546    /// once available
547    pub async fn notify_read_root_state_hash(
548        &self,
549        epoch: EpochId,
550    ) -> IotaResult<(CheckpointSequenceNumber, GlobalStateHash)> {
551        // We need to register waiters _before_ reading from the database to avoid race
552        // conditions
553        let registration = self.root_state_notify_read.register_one(&epoch);
554        let hash = self.perpetual_tables.root_state_hash_by_epoch.get(&epoch)?;
555
556        let result = match hash {
557            // Note that Some() clause also drops registration that is already fulfilled
558            Some(ready) => Either::Left(futures::future::ready(ready)),
559            None => Either::Right(registration),
560        }
561        .await;
562
563        Ok(result)
564    }
565
566    // Implementation of the corresponding method of `CheckpointCache` trait.
567    pub(crate) fn insert_finalized_transactions_perpetual_checkpoints(
568        &self,
569        digests: &[TransactionDigest],
570        epoch: EpochId,
571        sequence: CheckpointSequenceNumber,
572    ) -> IotaResult {
573        // A transaction is finalized by a checkpoint of the epoch that
574        // executed it, so this row lands in the bucket holding its effects.
575        let bucket = self.historic_ledger.ensure(epoch)?;
576        let mut batch = bucket.tx_to_checkpoint.batch();
577        batch.insert_batch_tagged(
578            &bucket.tx_to_checkpoint,
579            digests.iter().map(|d| (*d, sequence)),
580        )?;
581        batch.write()?;
582        trace!("Transactions {digests:?} finalized at checkpoint {sequence} epoch {epoch}");
583        Ok(())
584    }
585
586    // Implementation of the corresponding method of `CheckpointCache` trait.
587    pub(crate) fn get_transaction_perpetual_checkpoint(
588        &self,
589        digest: &TransactionDigest,
590    ) -> IotaResult<Option<(EpochId, CheckpointSequenceNumber)>> {
591        self.historic_ledger.get_transaction_checkpoint(digest)
592    }
593
594    // Implementation of the corresponding method of `CheckpointCache` trait.
595    pub(crate) fn multi_get_transactions_perpetual_checkpoints(
596        &self,
597        digests: &[TransactionDigest],
598    ) -> IotaResult<Vec<Option<(EpochId, CheckpointSequenceNumber)>>> {
599        self.historic_ledger
600            .multi_get_transaction_checkpoints(digests)
601    }
602
603    /// Returns true if there are no objects in the database
604    pub fn database_is_empty(&self) -> IotaResult<bool> {
605        self.perpetual_tables.database_is_empty()
606    }
607
608    /// A function that acquires all locks associated with the objects (in order
609    /// to avoid deadlocks).
610    fn acquire_locks(&self, input_objects: &[ObjectReference]) -> Vec<MutexGuard> {
611        self.mutex_table
612            .acquire_locks(input_objects.iter().map(|object_ref| object_ref.digest))
613    }
614
615    pub fn object_exists_by_key(
616        &self,
617        object_id: &ObjectId,
618        version: VersionNumber,
619    ) -> IotaResult<bool> {
620        Ok(self
621            .perpetual_tables
622            .objects
623            .contains_key(&ObjectKey(*object_id, version))?)
624    }
625
626    pub fn multi_object_exists_by_key(&self, object_keys: &[ObjectKey]) -> IotaResult<Vec<bool>> {
627        Ok(self
628            .perpetual_tables
629            .objects
630            .multi_contains_keys(object_keys.to_vec())?
631            .into_iter()
632            .collect())
633    }
634
635    pub fn multi_get_objects_by_key(
636        &self,
637        object_keys: &[ObjectKey],
638    ) -> Result<Vec<Option<Object>>, IotaError> {
639        let wrappers = self
640            .perpetual_tables
641            .objects
642            .multi_get(object_keys.to_vec())?;
643        let mut ret = vec![];
644
645        for (idx, w) in wrappers.into_iter().enumerate() {
646            ret.push(
647                w.map(|object| self.perpetual_tables.object(&object_keys[idx], object))
648                    .transpose()?
649                    .flatten(),
650            );
651        }
652        Ok(ret)
653    }
654
655    /// Get many objects
656    pub fn get_objects(&self, objects: &[ObjectId]) -> Result<Vec<Option<Object>>, IotaError> {
657        let mut result = Vec::new();
658        for id in objects {
659            result.push(self.try_get_object(id)?);
660        }
661        Ok(result)
662    }
663
664    pub fn have_deleted_owned_object_at_version_or_after(
665        &self,
666        object_id: &ObjectId,
667        version: VersionNumber,
668        epoch_id: EpochId,
669    ) -> Result<bool, IotaError> {
670        // Find the most recent version of the object that was deleted or wrapped.
671        // Return true if the version is >= `version`. Otherwise return false.
672        match self.epoch_markers.get_latest_marker(object_id, epoch_id)? {
673            Some((marked_version, marker)) => {
674                Ok(marked_version >= version && marker == MarkerValue::OwnedDeleted)
675            }
676            None => Ok(false),
677        }
678    }
679
680    // Methods to mutate the store
681
682    /// Insert a genesis object.
683    /// TODO: delete this method entirely (still used by authority_tests.rs)
684    pub(crate) fn insert_genesis_object(&self, object: Object) -> IotaResult {
685        // We only side load objects with a genesis parent transaction.
686        debug_assert!(object.previous_transaction == TransactionDigest::GENESIS_MARKER);
687        let object_ref = object.object_ref();
688        self.insert_genesis_object_direct(object_ref, &object)
689    }
690
691    /// Insert an object directly into the store, and also update relevant
692    /// tables NOTE: does not handle transaction lock.
693    /// This is used to insert genesis objects
694    fn insert_genesis_object_direct(
695        &self,
696        object_ref: ObjectReference,
697        object: &Object,
698    ) -> IotaResult {
699        let mut write_batch = self.perpetual_tables.objects.batch();
700
701        // Genesis objects are produced by the genesis checkpoint (sequence 0).
702        let store_object = get_store_object(object.clone(), Some(0));
703        write_batch.insert_batch(
704            &self.perpetual_tables.objects,
705            std::iter::once((ObjectKey::from(object_ref), store_object)),
706        )?;
707
708        // Update the index
709        if object.single_owner().is_some() {
710            // Only initialize live object markers for address owned objects.
711            if !object.is_child_object() {
712                self.initialize_live_object_markers_impl(&mut write_batch, &[object_ref])?;
713            }
714        }
715
716        write_batch.write()?;
717
718        Ok(())
719    }
720
721    /// This function should only be used for initializing genesis and should
722    /// remain private.
723    #[instrument(level = "debug", skip_all)]
724    pub(crate) fn bulk_insert_genesis_objects(&self, objects: &[Object]) -> IotaResult<()> {
725        let mut batch = self.perpetual_tables.objects.batch();
726        let ref_and_objects: Vec<_> = objects.iter().map(|o| (o.object_ref(), o)).collect();
727
728        // Genesis objects are produced by the genesis checkpoint (sequence 0).
729        batch.insert_batch(
730            &self.perpetual_tables.objects,
731            ref_and_objects.iter().map(|(oref, o)| {
732                (
733                    ObjectKey::from(oref),
734                    get_store_object((*o).clone(), Some(0)),
735                )
736            }),
737        )?;
738
739        let non_child_object_refs: Vec<_> = ref_and_objects
740            .iter()
741            .filter(|(_, object)| !object.is_child_object())
742            .map(|(oref, _)| *oref)
743            .collect();
744
745        self.initialize_live_object_markers_impl(&mut batch, &non_child_object_refs)?;
746
747        batch.write()?;
748
749        Ok(())
750    }
751
752    pub fn bulk_insert_live_objects(
753        perpetual_db: &AuthorityPerpetualTables,
754        live_objects: impl Iterator<Item = LiveObject>,
755        expected_sha3_digest: &[u8; 32],
756    ) -> IotaResult<()> {
757        let mut hasher = Sha3_256::default();
758        let mut batch = perpetual_db.objects.batch();
759        for live_object in live_objects {
760            hasher.update(live_object.object_reference().digest.bytes());
761            let LiveObject {
762                object,
763                previous_transaction_checkpoint,
764            } = live_object;
765            let store_object_wrapper =
766                get_store_object(object.clone(), previous_transaction_checkpoint);
767            batch.insert_batch(
768                &perpetual_db.objects,
769                std::iter::once((ObjectKey::from(object.object_ref()), store_object_wrapper)),
770            )?;
771            if !object.is_child_object() {
772                Self::initialize_live_object_markers(
773                    &perpetual_db.live_owned_object_markers,
774                    &mut batch,
775                    &[object.object_ref()],
776                )?;
777            }
778        }
779        let sha3_digest = hasher.finalize().digest;
780        if *expected_sha3_digest != sha3_digest {
781            error!(
782                "Sha does not match! expected: {:?}, actual: {:?}",
783                expected_sha3_digest, sha3_digest
784            );
785            return Err(IotaError::from("Sha does not match"));
786        }
787        batch.write()?;
788        Ok(())
789    }
790
791    pub fn set_epoch_start_configuration(
792        &self,
793        epoch_start_configuration: &EpochStartConfiguration,
794    ) -> IotaResult {
795        self.perpetual_tables
796            .set_epoch_start_configuration(epoch_start_configuration)?;
797        Ok(())
798    }
799
800    pub fn get_epoch_start_configuration(&self) -> IotaResult<Option<EpochStartConfiguration>> {
801        Ok(self.perpetual_tables.epoch_start_configuration.get(&())?)
802    }
803
804    /// Updates the state resulting from the execution of a certificate.
805    ///
806    /// Internally it checks that all locks for active inputs are at the correct
807    /// version, and then writes objects, certificates, parents and clean up
808    /// locks atomically.
809    ///
810    /// `checkpoint_sequence_number` is stamped onto each newly written object's
811    /// `StoreObjectValueV2.previous_transaction_checkpoint` field.
812    ///
813    /// In the same batch, the versions these transactions superseded move from
814    /// the live `objects` table into `epoch_id`'s historic bucket, and each
815    /// transaction's body, effects, execution record and events go into
816    /// `epoch_id`'s ledger bucket. `cached` answers for the object versions
817    /// not committed yet, which the live table does not hold.
818    ///
819    /// **Invariant** Every `TransactionOutputs` in `tx_outputs` must belong to
820    /// the checkpoint identified by `checkpoint_sequence_number`.
821    #[instrument(level = "debug", skip_all)]
822    pub fn build_db_batch(
823        &self,
824        epoch_id: EpochId,
825        checkpoint_sequence_number: CheckpointSequenceNumber,
826        tx_outputs: &[Arc<TransactionOutputs>],
827        cached: &dyn Fn(&ObjectKey) -> Option<Object>,
828    ) -> IotaResult<DBBatch> {
829        let mut written = Vec::with_capacity(tx_outputs.len());
830        for outputs in tx_outputs {
831            written.extend(outputs.written.values().cloned());
832        }
833
834        let historic_bucket = self.historic_objects.ensure(epoch_id)?;
835        let ledger_bucket = self.historic_ledger.ensure(epoch_id)?;
836        let mut write_batch = self.perpetual_tables.objects.batch();
837        for outputs in tx_outputs {
838            let missed = self.missed_pre_images(outputs, cached)?;
839            self.write_one_transaction_outputs(
840                &mut write_batch,
841                epoch_id,
842                checkpoint_sequence_number,
843                (&historic_bucket, &ledger_bucket),
844                outputs,
845                &missed,
846            )?;
847        }
848        // test crashing before writing the batch
849        fail_point!("crash");
850
851        trace!(
852            "built batch for committed transactions: {:?}",
853            tx_outputs
854                .iter()
855                .map(|tx| tx.transaction.digest())
856                .collect::<Vec<_>>()
857        );
858
859        // test crashing before notifying
860        fail_point!("crash");
861
862        Ok(write_batch)
863    }
864
865    /// The versions `outputs` superseded whose pre-image execution did not
866    /// capture, read from where they still are: `cached` while the transaction
867    /// that wrote them is not committed, or else the live table.
868    ///
869    /// Left in the live table, such a version would be read as the newest one
870    /// at or below a bound, instead of a newer version that went into a
871    /// bucket.
872    fn missed_pre_images(
873        &self,
874        outputs: &TransactionOutputs,
875        cached: &dyn Fn(&ObjectKey) -> Option<Object>,
876    ) -> IotaResult<Vec<(ObjectKey, Object)>> {
877        if outputs.superseded.len() == outputs.effects.modified_at_versions().len() {
878            return Ok(Vec::new());
879        }
880        let captured: HashSet<ObjectKey> = outputs.superseded.iter().map(|(key, _)| *key).collect();
881        let mut missed = Vec::new();
882        for modified in outputs.effects.modified_at_versions() {
883            let key = ObjectKey(*modified.object_id(), modified.version());
884            if captured.contains(&key) {
885                continue;
886            }
887            // The commit writes to the live table before it drops a version
888            // from the cache, so asking the cache first misses no version.
889            let pre_image = match cached(&key) {
890                Some(object) => Some(object),
891                None => match self.perpetual_tables.objects.get(&key)? {
892                    Some(row) => self.perpetual_tables.object(&key, row)?,
893                    None => None,
894                },
895            };
896            match pre_image {
897                Some(object) => missed.push((key, object)),
898                None => warn!(
899                    ?key,
900                    tx_digest = ?outputs.transaction.digest(),
901                    "a superseded version has no pre-image to move into its bucket"
902                ),
903            }
904        }
905        Ok(missed)
906    }
907
908    /// `buckets` are `epoch_id`'s historic objects and ledger buckets.
909    fn write_one_transaction_outputs(
910        &self,
911        write_batch: &mut DBBatch,
912        epoch_id: EpochId,
913        checkpoint_sequence_number: CheckpointSequenceNumber,
914        (historic_bucket, ledger_bucket): (&HistoricObjectsBucket, &HistoricLedgerBucket),
915        tx_outputs: &TransactionOutputs,
916        missed_pre_images: &[(ObjectKey, Object)],
917    ) -> IotaResult {
918        let TransactionOutputs {
919            transaction,
920            effects,
921            markers,
922            wrapped,
923            deleted,
924            written,
925            events,
926            live_object_markers_to_delete,
927            new_live_object_markers_to_init,
928            superseded,
929            attestation_record,
930            ..
931        } = tx_outputs;
932
933        // Store the certificate indexed by transaction digest
934        let transaction_digest = transaction.digest();
935        write_batch.insert_batch_tagged(
936            &ledger_bucket.transactions,
937            iter::once((transaction_digest, transaction.serializable_ref())),
938        )?;
939
940        // Add batched writes for objects and locks.
941        let effects_digest = effects.digest();
942
943        let marker_bucket = self.epoch_markers.ensure(epoch_id)?;
944        write_batch.insert_batch(
945            &marker_bucket.markers,
946            markers
947                .iter()
948                .map(|(key, marker_value)| (*key, *marker_value)),
949        )?;
950
951        write_batch.insert_batch(
952            &self.perpetual_tables.objects,
953            deleted
954                .iter()
955                .map(|key| (key, StoreObject::Deleted))
956                .chain(wrapped.iter().map(|key| (key, StoreObject::Wrapped)))
957                .map(|(key, store_object)| (key, StoreObjectWrapper::from(store_object))),
958        )?;
959
960        // Insert each output object into the stores
961        let new_objects = written.iter().map(|(id, new_object)| {
962            let version = new_object.version();
963            trace!(?id, ?version, "writing object");
964            let store_object =
965                get_store_object(new_object.clone(), Some(checkpoint_sequence_number));
966            (ObjectKey(*id, version), store_object)
967        });
968
969        write_batch.insert_batch(&self.perpetual_tables.objects, new_objects)?;
970
971        // A delete survives only if nothing later in the batch writes the
972        // same key. Nothing does: a transaction never supersedes a version it
973        // writes, and `build_db_batch` appends transactions in checkpoint
974        // order, so the writer of a superseded version is earlier in the batch.
975        let superseded = superseded.iter().chain(missed_pre_images);
976        write_batch.insert_batch_tagged(
977            &historic_bucket.objects,
978            superseded
979                .clone()
980                .map(|(key, object)| (*key, object.clone())),
981        )?;
982        // Lets the bucket's expiry delete the tombstones written above from the
983        // live table.
984        write_batch.insert_batch_tagged(
985            &historic_bucket.tombstones,
986            deleted.iter().chain(wrapped.iter()).map(|key| (*key, ())),
987        )?;
988        write_batch.delete_batch(
989            &self.perpetual_tables.objects,
990            superseded.map(|(key, _)| *key),
991        )?;
992
993        // Write events into the epoch's bucket keyed off of transaction_digest
994        if effects.events_digest().is_some() {
995            write_batch
996                .insert_batch_tagged(&ledger_bucket.events, [(transaction_digest, events)])?;
997        }
998
999        self.initialize_live_object_markers_impl(write_batch, new_live_object_markers_to_init)?;
1000
1001        // Note: deletes live object markers for received objects as well (but not for
1002        // objects that were in `Receiving` arguments which were not received)
1003        self.delete_live_object_markers(write_batch, live_object_markers_to_delete)?;
1004
1005        write_batch
1006            .insert_batch_tagged(&ledger_bucket.effects, [(effects_digest, effects.clone())])?
1007            .insert_batch_tagged(
1008                &ledger_bucket.executed_effects,
1009                [(transaction_digest, effects_digest)],
1010            )?;
1011
1012        if let Some(record) = attestation_record {
1013            write_batch.insert_batch_tagged(
1014                &ledger_bucket.attestation_records,
1015                [(transaction_digest, *record)],
1016            )?;
1017        }
1018
1019        debug!(effects_digest = ?effects.digest(), "commit_transaction finished");
1020
1021        Ok(())
1022    }
1023
1024    /// Commits transactions only (not effects or other transaction outputs) to
1025    /// the db. See ExecutionCache::persist_transaction for more info
1026    ///
1027    /// The body goes into the ledger bucket of `tx.epoch()`, where its outputs
1028    /// land when it executes.
1029    pub(crate) fn persist_transaction(&self, tx: &VerifiedExecutableTransaction) -> IotaResult {
1030        let bucket = self.historic_ledger.ensure(tx.epoch())?;
1031        let mut batch = bucket.transactions.batch();
1032        batch.insert_batch_tagged(
1033            &bucket.transactions,
1034            [(tx.digest(), tx.clone().into_unsigned().serializable_ref())],
1035        )?;
1036        batch.write()?;
1037        Ok(())
1038    }
1039
1040    pub fn acquire_transaction_locks(
1041        &self,
1042        epoch_store: &AuthorityPerEpochStore,
1043        owned_input_objects: &[ObjectReference],
1044        transaction: VerifiedSignedTransaction,
1045    ) -> IotaResult {
1046        let tx_digest = *transaction.digest();
1047        // Other writers may be attempting to acquire locks on the same objects, so a
1048        // mutex is required.
1049        // TODO: replace with optimistic db_transactions (i.e. set lock to tx if none)
1050        let _mutexes = self.acquire_locks(owned_input_objects);
1051
1052        trace!(?owned_input_objects, "acquire_transaction_locks");
1053        let mut locks_to_write = Vec::new();
1054
1055        let live_object_markers = self
1056            .perpetual_tables
1057            .live_owned_object_markers
1058            .multi_get(owned_input_objects)?;
1059
1060        let epoch_tables = epoch_store.tables()?;
1061
1062        let locks = epoch_tables.multi_get_locked_transactions(owned_input_objects)?;
1063
1064        assert_eq!(locks.len(), live_object_markers.len());
1065
1066        for (live_marker, lock, obj_ref) in izip!(
1067            live_object_markers.into_iter(),
1068            locks.into_iter(),
1069            owned_input_objects
1070        ) {
1071            if live_marker.is_none() {
1072                // object at that version does not exist
1073                let latest_live_version =
1074                    self.get_latest_live_version_for_object_id(obj_ref.object_id)?;
1075                fp_bail!(
1076                    UserInputError::ObjectVersionUnavailableForConsumption {
1077                        provided_obj_ref: *obj_ref,
1078                        current_version: latest_live_version.version
1079                    }
1080                    .into()
1081                );
1082            };
1083
1084            if let Some(previous_tx_digest) = &lock {
1085                if previous_tx_digest == &tx_digest {
1086                    // no need to re-write lock
1087                    continue;
1088                } else {
1089                    // TODO: add metrics here
1090                    info!(prev_tx_digest = ?previous_tx_digest,
1091                          cur_tx_digest = ?tx_digest,
1092                          "Cannot acquire lock: conflicting transaction!");
1093                    return Err(IotaError::ObjectLockConflict {
1094                        obj_ref: *obj_ref,
1095                        pending_transaction: *previous_tx_digest,
1096                    });
1097                }
1098            }
1099
1100            locks_to_write.push((*obj_ref, tx_digest));
1101        }
1102
1103        if !locks_to_write.is_empty() {
1104            trace!(?locks_to_write, "Writing locks");
1105            epoch_tables.write_transaction_locks(transaction, locks_to_write.into_iter())?;
1106        }
1107
1108        Ok(())
1109    }
1110
1111    /// Gets ObjectLockInfo that represents state of lock on an object.
1112    /// Returns UserInputError::ObjectNotFound if cannot find lock record for
1113    /// this object
1114    pub(crate) fn get_lock(
1115        &self,
1116        obj_ref: ObjectReference,
1117        epoch_store: &AuthorityPerEpochStore,
1118    ) -> IotaLockResult {
1119        if self
1120            .perpetual_tables
1121            .live_owned_object_markers
1122            .get(&obj_ref)?
1123            .is_none()
1124        {
1125            // object at that version does not exist
1126            return Ok(ObjectLockStatus::LockedAtDifferentVersion {
1127                locked_ref: self.get_latest_live_version_for_object_id(obj_ref.object_id)?,
1128            });
1129        }
1130
1131        let tables = epoch_store.tables()?;
1132        if let Some(tx_digest) = tables.get_locked_transaction(&obj_ref)? {
1133            Ok(ObjectLockStatus::LockedToTx {
1134                locked_by_tx: tx_digest,
1135            })
1136        } else {
1137            Ok(ObjectLockStatus::Initialized)
1138        }
1139    }
1140
1141    /// Returns UserInputError::ObjectNotFound if no lock records found for this
1142    /// object.
1143    pub(crate) fn get_latest_live_version_for_object_id(
1144        &self,
1145        object_id: ObjectId,
1146    ) -> IotaResult<ObjectReference> {
1147        let mut iterator = self
1148            .perpetual_tables
1149            .live_owned_object_markers
1150            .safe_iter_with_prefix_reversed(&object_id);
1151        Ok(iterator
1152            .next()
1153            .transpose()?
1154            .filter(|&value| value.0.object_id == object_id)
1155            .ok_or_else(|| {
1156                IotaError::from(UserInputError::ObjectNotFound {
1157                    object_id,
1158                    version: None,
1159                })
1160            })?
1161            .0)
1162    }
1163
1164    /// Checks multiple object locks exist.
1165    /// Returns UserInputError::ObjectNotFound if cannot find lock record for at
1166    /// least one of the objects.
1167    /// Returns UserInputError::ObjectVersionUnavailableForConsumption if at
1168    /// least one object lock is not initialized     at the given version.
1169    pub fn check_owned_objects_are_live(&self, objects: &[ObjectReference]) -> IotaResult {
1170        let live_markers = self
1171            .perpetual_tables
1172            .live_owned_object_markers
1173            .multi_get(objects)?;
1174        for (live_marker, obj_ref) in live_markers.into_iter().zip(objects) {
1175            if live_marker.is_none() {
1176                // object at that version does not exist
1177                let latest_live_version =
1178                    self.get_latest_live_version_for_object_id(obj_ref.object_id)?;
1179                fp_bail!(
1180                    UserInputError::ObjectVersionUnavailableForConsumption {
1181                        provided_obj_ref: *obj_ref,
1182                        current_version: latest_live_version.version
1183                    }
1184                    .into()
1185                );
1186            }
1187        }
1188        Ok(())
1189    }
1190
1191    /// Initialize live object markers for a given list of ObjectRefs.
1192    fn initialize_live_object_markers_impl(
1193        &self,
1194        write_batch: &mut DBBatch,
1195        objects: &[ObjectReference],
1196    ) -> IotaResult {
1197        AuthorityStore::initialize_live_object_markers(
1198            &self.perpetual_tables.live_owned_object_markers,
1199            write_batch,
1200            objects,
1201        )
1202    }
1203
1204    pub fn initialize_live_object_markers(
1205        live_object_marker_table: &DBMap<ObjectReference, ()>,
1206        write_batch: &mut DBBatch,
1207        objects: &[ObjectReference],
1208    ) -> IotaResult {
1209        trace!(?objects, "initialize_live_object_markers");
1210
1211        write_batch.insert_batch(
1212            live_object_marker_table,
1213            objects.iter().map(|obj_ref| (obj_ref, ())),
1214        )?;
1215        Ok(())
1216    }
1217
1218    /// Removes locks for a given list of ObjectRefs.
1219    fn delete_live_object_markers(
1220        &self,
1221        write_batch: &mut DBBatch,
1222        objects: &[ObjectReference],
1223    ) -> IotaResult {
1224        trace!(?objects, "delete_live_object_markers");
1225        write_batch.delete_batch(
1226            &self.perpetual_tables.live_owned_object_markers,
1227            objects.iter(),
1228        )?;
1229        Ok(())
1230    }
1231
1232    #[cfg(test)]
1233    pub(crate) fn reset_locks_and_live_markers_for_test(
1234        &self,
1235        transactions: &[TransactionDigest],
1236        objects: &[ObjectReference],
1237        epoch_store: &AuthorityPerEpochStore,
1238    ) {
1239        for tx in transactions {
1240            epoch_store.delete_signed_transaction_for_test(tx);
1241            epoch_store.delete_object_locks_for_test(objects);
1242        }
1243
1244        let mut batch = self.perpetual_tables.live_owned_object_markers.batch();
1245        batch
1246            .delete_batch(
1247                &self.perpetual_tables.live_owned_object_markers,
1248                objects.iter(),
1249            )
1250            .unwrap();
1251        batch.write().unwrap();
1252
1253        let mut batch = self.perpetual_tables.live_owned_object_markers.batch();
1254        self.initialize_live_object_markers_impl(&mut batch, objects)
1255            .unwrap();
1256        batch.write().unwrap();
1257    }
1258
1259    /// The lowest version of `object_id` above `version` among the newest row
1260    /// of the live `objects` table and what `epoch`'s historic bucket holds.
1261    pub fn find_lowest_version_above_in_epoch(
1262        &self,
1263        object_id: &ObjectId,
1264        version: Version,
1265        epoch: EpochId,
1266    ) -> IotaResult<Option<Version>> {
1267        // Only the newest live row: a commit deletes the versions it
1268        // supersedes from the live table, and a seek from an older version
1269        // would step over every deletion. Read before the bucket; see
1270        // `HistoricObjectsBucket::tombstones`.
1271        let live = self
1272            .perpetual_tables
1273            .get_latest_object_or_tombstone(*object_id)?
1274            .map(|(key, _)| key.1)
1275            .filter(|live| *live > version);
1276        let relocated = self
1277            .historic_objects
1278            .lowest_version_above_in_epoch(epoch, object_id, version)?;
1279        Ok(live.into_iter().chain(relocated).min())
1280    }
1281
1282    /// The newest version of `object_id` at or below `version`, from the live
1283    /// `objects` table and the historic buckets together. `None` if the object
1284    /// was deleted or wrapped at or below the bound, or has no version in
1285    /// range.
1286    ///
1287    /// Safe for execution regardless of retention: what execution can observe
1288    /// is in the current epoch's bucket, which expiry never drops.
1289    pub fn find_object_lt_or_eq_version_with_historic_fallback(
1290        &self,
1291        object_id: ObjectId,
1292        version: Version,
1293    ) -> IotaResult<Option<Object>> {
1294        let live_tombstone = match self
1295            .perpetual_tables
1296            .find_object_lt_or_eq_version(object_id, version)?
1297        {
1298            Some((key, row)) => match self.perpetual_tables.object(&key, row)? {
1299                Some(object) => return Ok(Some(object)),
1300                None => Some(key.1),
1301            },
1302            None => None,
1303        };
1304        // Asked for a live tombstone too: an unwrap leaves one in the live
1305        // table below a newer relocated version. Read after the live table;
1306        // see `HistoricObjectsBucket::tombstones`.
1307        let relocated = self
1308            .historic_objects
1309            .find_lt_or_eq_version(object_id, version)?;
1310        Ok(match live_tombstone {
1311            Some(tombstone_version) => {
1312                relocated.filter(|relocated| tombstone_version < relocated.version())
1313            }
1314            None => relocated,
1315        })
1316    }
1317
1318    /// Returns the latest object reference we have for this object_id in the
1319    /// objects table.
1320    ///
1321    /// The method may also return the reference to a deleted object with a
1322    /// digest of ObjectDigest::deleted() or ObjectDigest::wrapped() and
1323    /// lamport version of a transaction that deleted the object.
1324    /// Note that a deleted object may re-appear if the deletion was the result
1325    /// of the object being wrapped in another object.
1326    ///
1327    /// If no entry for the object_id is found, return None.
1328    pub fn get_latest_object_ref_or_tombstone(
1329        &self,
1330        object_id: ObjectId,
1331    ) -> Result<Option<ObjectReference>, IotaError> {
1332        self.perpetual_tables
1333            .get_latest_object_ref_or_tombstone(object_id)
1334    }
1335
1336    /// Returns the latest object reference if and only if the object is still
1337    /// live (i.e. it does not return tombstones)
1338    pub fn get_latest_object_ref_if_alive(
1339        &self,
1340        object_id: ObjectId,
1341    ) -> Result<Option<ObjectReference>, IotaError> {
1342        match self.get_latest_object_ref_or_tombstone(object_id)? {
1343            Some(objref) if objref.digest.is_alive() => Ok(Some(objref)),
1344            _ => Ok(None),
1345        }
1346    }
1347
1348    /// Returns the latest object we have for this object_id in the objects
1349    /// table.
1350    ///
1351    /// If no entry for the object_id is found, return None.
1352    pub fn get_latest_object_or_tombstone(
1353        &self,
1354        object_id: ObjectId,
1355    ) -> Result<Option<(ObjectKey, ObjectOrTombstone)>, IotaError> {
1356        let Some((object_key, store_object)) = self
1357            .perpetual_tables
1358            .get_latest_object_or_tombstone(object_id)?
1359        else {
1360            return Ok(None);
1361        };
1362
1363        if let Some(object_ref) = self
1364            .perpetual_tables
1365            .tombstone_reference(&object_key, &store_object)?
1366        {
1367            return Ok(Some((object_key, ObjectOrTombstone::Tombstone(object_ref))));
1368        }
1369
1370        let object = self
1371            .perpetual_tables
1372            .object(&object_key, store_object)?
1373            .expect("Non tombstone store object could not be converted to object");
1374
1375        Ok(Some((object_key, ObjectOrTombstone::Object(object))))
1376    }
1377
1378    /// Records a transaction and its effects ahead of executing them, in the
1379    /// ledger bucket of the effects' epoch. Does nothing if that epoch has been
1380    /// expired.
1381    ///
1382    /// The epoch may be one this node has not begun executing; see
1383    /// [`HistoricLedger`].
1384    pub fn insert_transaction_and_effects(
1385        &self,
1386        transaction: &VerifiedTransaction,
1387        transaction_effects: &TransactionEffects,
1388    ) -> IotaResult {
1389        let Some(bucket) = self
1390            .historic_ledger
1391            .ensure_retained(transaction_effects.epoch())?
1392        else {
1393            debug!(
1394                epoch = transaction_effects.epoch(),
1395                "not filing transaction history whose epoch has been expired",
1396            );
1397            return Ok(());
1398        };
1399        let mut write_batch = bucket.transactions.batch();
1400        write_batch
1401            .insert_batch_tagged(
1402                &bucket.transactions,
1403                [(transaction.digest(), transaction.serializable_ref())],
1404            )?
1405            .insert_batch_tagged(
1406                &bucket.effects,
1407                [(transaction_effects.digest(), transaction_effects)],
1408            )?;
1409
1410        write_batch.write()?;
1411        Ok(())
1412    }
1413
1414    /// Like [`Self::insert_transaction_and_effects`], for each of
1415    /// `transactions`.
1416    pub fn multi_insert_transaction_and_effects<'a>(
1417        &self,
1418        transactions: impl Iterator<Item = &'a VerifiedExecutionData>,
1419    ) -> IotaResult {
1420        let mut write_batch = self.perpetual_tables.objects.batch();
1421        // A checkpoint's transactions all executed in its epoch, so the bucket
1422        // rarely changes.
1423        let mut current: Option<(EpochId, Option<Arc<HistoricLedgerBucket>>)> = None;
1424        for tx in transactions {
1425            let epoch = tx.effects.epoch();
1426            let bucket = match &current {
1427                Some((current_epoch, bucket)) if *current_epoch == epoch => bucket.clone(),
1428                _ => {
1429                    let bucket = self.historic_ledger.ensure_retained(epoch)?;
1430                    current = Some((epoch, bucket.clone()));
1431                    bucket
1432                }
1433            };
1434            // State sync can still carry a checkpoint whose epoch has since
1435            // been expired.
1436            let Some(bucket) = bucket else {
1437                debug!(
1438                    epoch,
1439                    "not filing transaction history whose epoch has been expired"
1440                );
1441                continue;
1442            };
1443            write_batch
1444                .insert_batch_tagged(
1445                    &bucket.transactions,
1446                    [(tx.transaction.digest(), tx.transaction.serializable_ref())],
1447                )?
1448                .insert_batch_tagged(&bucket.effects, [(tx.effects.digest(), &tx.effects)])?;
1449        }
1450
1451        write_batch.write()?;
1452        Ok(())
1453    }
1454
1455    pub fn multi_get_transaction_blocks(
1456        &self,
1457        tx_digests: &[TransactionDigest],
1458    ) -> IotaResult<Vec<Option<VerifiedTransaction>>> {
1459        Ok(self
1460            .historic_ledger
1461            .multi_get_transactions(tx_digests)?
1462            .into_iter()
1463            .map(|transaction| transaction.map(Into::into))
1464            .collect())
1465    }
1466
1467    /// [`Self::multi_get_transaction_blocks`] read from `epoch`'s records
1468    /// alone; transactions stored under another epoch are reported as absent.
1469    pub fn multi_get_transaction_blocks_in_epoch(
1470        &self,
1471        epoch: EpochId,
1472        tx_digests: &[TransactionDigest],
1473    ) -> IotaResult<Vec<Option<VerifiedTransaction>>> {
1474        Ok(self
1475            .historic_ledger
1476            .multi_get_transactions_in_epoch(epoch, tx_digests)?
1477            .into_iter()
1478            .map(|transaction| transaction.map(Into::into))
1479            .collect())
1480    }
1481
1482    pub fn get_transaction_block(
1483        &self,
1484        tx_digest: &TransactionDigest,
1485    ) -> IotaResult<Option<VerifiedTransaction>> {
1486        Ok(self
1487            .historic_ledger
1488            .get_transaction(tx_digest)?
1489            .map(|transaction| transaction.into()))
1490    }
1491
1492    /// This function reads the DB directly to get the system state object.
1493    /// If reconfiguration is happening at the same time, there is no guarantee
1494    /// whether we would be getting the old or the new system state object.
1495    /// Hence this function should only be called during RPC reads where data
1496    /// race is not a major concern. In general we should avoid this as much
1497    /// as possible. If the intent is for testing, you can use
1498    /// AuthorityState:: get_iota_system_state_object_for_testing.
1499    pub fn get_iota_system_state_object_unsafe(&self) -> IotaResult<IotaSystemState> {
1500        get_iota_system_state(self.perpetual_tables.as_ref())
1501    }
1502
1503    pub fn expensive_check_iota_conservation<T>(
1504        self: &Arc<Self>,
1505        type_layout_store: T,
1506        old_epoch_store: &AuthorityPerEpochStore,
1507        epoch_supply_change: Option<i64>,
1508    ) -> IotaResult
1509    where
1510        T: TypeLayoutStore + Send + Copy,
1511    {
1512        if !self.enable_epoch_iota_conservation_check {
1513            return Ok(());
1514        }
1515
1516        let executor = old_epoch_store.executor();
1517        info!("Starting IOTA conservation check. This may take a while..");
1518        let cur_time = Instant::now();
1519        let mut pending_objects = vec![];
1520        let mut count = 0;
1521        let mut size = 0;
1522        let totals: IotaResult<(u64, u64)> = thread::scope(|s| {
1523            let pending_tasks = FuturesUnordered::new();
1524            for o in self.iter_live_object_set() {
1525                let object = o?.object;
1526                size += object.object_size_for_gas_metering();
1527                count += 1;
1528                pending_objects.push(object);
1529                if count % 1_000_000 == 0 {
1530                    let mut task_objects = vec![];
1531                    mem::swap(&mut pending_objects, &mut task_objects);
1532                    pending_tasks.push(s.spawn(move || {
1533                        let mut layout_resolver =
1534                            executor.type_layout_resolver(Box::new(type_layout_store));
1535                        let mut total_storage_rebate = 0;
1536                        let mut total_iota = 0;
1537                        for object in task_objects {
1538                            total_storage_rebate += object.storage_rebate;
1539                            // get_total_iota includes storage rebate, however all storage rebate is
1540                            // also stored in the storage fund, so we need to subtract it here.
1541                            total_iota += object.get_total_iota(layout_resolver.as_mut()).unwrap()
1542                                - object.storage_rebate;
1543                        }
1544                        if count % 50_000_000 == 0 {
1545                            info!("Processed {} objects", count);
1546                        }
1547                        (total_iota, total_storage_rebate)
1548                    }));
1549                }
1550            }
1551            Ok(pending_tasks.into_iter().fold((0, 0), |init, result| {
1552                let result = result.join().unwrap();
1553                (init.0 + result.0, init.1 + result.1)
1554            }))
1555        });
1556        let (mut total_iota, mut total_storage_rebate) = totals?;
1557        let mut layout_resolver = executor.type_layout_resolver(Box::new(type_layout_store));
1558        for object in pending_objects {
1559            total_storage_rebate += object.storage_rebate;
1560            total_iota +=
1561                object.get_total_iota(layout_resolver.as_mut()).unwrap() - object.storage_rebate;
1562        }
1563        info!(
1564            "Scanned {} live objects, took {:?}",
1565            count,
1566            cur_time.elapsed()
1567        );
1568        self.metrics
1569            .iota_conservation_live_object_count
1570            .set(count as i64);
1571        self.metrics
1572            .iota_conservation_live_object_size
1573            .set(size as i64);
1574        self.metrics
1575            .iota_conservation_check_latency
1576            .set(cur_time.elapsed().as_secs() as i64);
1577
1578        // It is safe to call this function because we are in the middle of
1579        // reconfiguration.
1580        let system_state: IotaSystemStateSummaryV2 = self
1581            .get_iota_system_state_object_unsafe()
1582            .expect("Reading iota system state object cannot fail")
1583            .into_iota_system_state_summary()
1584            .try_into()?;
1585        let storage_fund_balance = system_state.storage_fund_total_object_storage_rebates;
1586        info!(
1587            "Total IOTA amount in the network: {}, storage fund balance: {}, total storage rebate: {} at beginning of epoch {}",
1588            total_iota, storage_fund_balance, total_storage_rebate, system_state.epoch
1589        );
1590
1591        let imbalance = (storage_fund_balance as i64) - (total_storage_rebate as i64);
1592        self.metrics
1593            .iota_conservation_storage_fund
1594            .set(storage_fund_balance as i64);
1595        self.metrics
1596            .iota_conservation_storage_fund_imbalance
1597            .set(imbalance);
1598        self.metrics
1599            .iota_conservation_imbalance
1600            .set((total_iota as i128 - system_state.iota_total_supply as i128) as i64);
1601
1602        if let Some(expected_imbalance) = self
1603            .perpetual_tables
1604            .expected_storage_fund_imbalance
1605            .get(&())
1606            .map_err(|err| {
1607                IotaError::from(
1608                    format!("failed to read expected storage fund imbalance: {err}").as_str(),
1609                )
1610            })?
1611        {
1612            fp_ensure!(
1613                imbalance == expected_imbalance,
1614                IotaError::from(
1615                    format!(
1616                        "Inconsistent state detected at epoch {}: total storage rebate: {}, storage fund balance: {}, expected imbalance: {}",
1617                        system_state.epoch, total_storage_rebate, storage_fund_balance, expected_imbalance
1618                    ).as_str()
1619                )
1620            );
1621        } else {
1622            self.perpetual_tables
1623                .expected_storage_fund_imbalance
1624                .insert(&(), &imbalance)
1625                .map_err(|err| {
1626                    IotaError::from(
1627                        format!("failed to write expected storage fund imbalance: {err}").as_str(),
1628                    )
1629                })?;
1630        }
1631
1632        let total_supply = self
1633            .perpetual_tables
1634            .total_iota_supply
1635            .get(&())
1636            .map_err(|err| {
1637                IotaError::from(format!("failed to read total iota supply: {err}").as_str())
1638            })?;
1639
1640        match total_supply.zip(epoch_supply_change) {
1641            // Only execute the check if both are set and the supply value was set in the last
1642            // epoch. We have to assume the supply changes every epoch and therefore we
1643            // cannot run the check with a supply value from any epoch earlier than the
1644            // last one. This can happen if the check was disabled for some time.
1645            Some((old_supply, epoch_supply_change))
1646                if old_supply.last_check_epoch + 1 == old_epoch_store.epoch() =>
1647            {
1648                let expected_new_supply = if epoch_supply_change >= 0 {
1649                    old_supply
1650                        .total_supply
1651                        .checked_add(epoch_supply_change.unsigned_abs())
1652                        .ok_or_else(|| {
1653                            IotaError::from(
1654                                format!(
1655                                    "Inconsistent state detected at epoch {}: old supply {} + supply change {} overflowed",
1656                                    system_state.epoch, old_supply.total_supply, epoch_supply_change
1657                                ).as_str())
1658                        })?
1659                } else {
1660                    old_supply.total_supply.checked_sub(epoch_supply_change.unsigned_abs()).ok_or_else(|| {
1661                        IotaError::from(
1662                            format!(
1663                                "Inconsistent state detected at epoch {}: old supply {} - supply change {} underflowed",
1664                                system_state.epoch, old_supply.total_supply, epoch_supply_change
1665                            ).as_str())
1666                    })?
1667                };
1668
1669                fp_ensure!(
1670                    total_iota == expected_new_supply,
1671                    IotaError::from(
1672                        format!(
1673                            "Inconsistent state detected at epoch {}: total iota: {}, expecting {}",
1674                            system_state.epoch, total_iota, expected_new_supply
1675                        )
1676                        .as_str()
1677                    )
1678                );
1679
1680                let new_supply = TotalIotaSupplyCheck {
1681                    total_supply: expected_new_supply,
1682                    last_check_epoch: old_epoch_store.epoch(),
1683                };
1684
1685                self.perpetual_tables
1686                    .total_iota_supply
1687                    .insert(&(), &new_supply)
1688                    .map_err(|err| {
1689                        IotaError::from(
1690                            format!("failed to write total iota supply: {err}").as_str(),
1691                        )
1692                    })?;
1693            }
1694            // If either one is None or if the last value is from an older epoch,
1695            // we update the value in the table since we're at genesis and cannot execute the check.
1696            _ => {
1697                info!("Skipping total supply check");
1698
1699                let supply = TotalIotaSupplyCheck {
1700                    total_supply: total_iota,
1701                    last_check_epoch: old_epoch_store.epoch(),
1702                };
1703
1704                self.perpetual_tables
1705                    .total_iota_supply
1706                    .insert(&(), &supply)
1707                    .map_err(|err| {
1708                        IotaError::from(
1709                            format!("failed to write total iota supply: {err}").as_str(),
1710                        )
1711                    })?;
1712
1713                return Ok(());
1714            }
1715        };
1716
1717        Ok(())
1718    }
1719
1720    /// Expires every historic bucket but the newest, deleting the tombstones
1721    /// those epochs recorded, and compacts the live `objects` table.
1722    #[cfg(any(test, feature = "test-utils"))]
1723    pub fn expire_historic_objects_and_compact_for_testing(&self) {
1724        let current_epoch = self
1725            .historic_objects
1726            .newest_bucket_epoch()
1727            .expect("a store with no bucket has nothing to expire");
1728        self.historic_objects
1729            .prune(current_epoch, 0)
1730            .expect("expiring the historic buckets should not fail");
1731        self.perpetual_tables
1732            .compact()
1733            .expect("compacting the live objects table should not fail");
1734    }
1735
1736    #[cfg(test)]
1737    pub async fn prune_objects_immediately_for_testing(
1738        &self,
1739        transaction_effects: Vec<TransactionEffects>,
1740    ) -> anyhow::Result<()> {
1741        let mut wb = self.perpetual_tables.objects.batch();
1742
1743        let mut object_keys_to_prune = vec![];
1744        for effects in &transaction_effects {
1745            for modified in effects.modified_at_versions() {
1746                let (object_id, version) = (modified.object_id(), modified.version());
1747                info!("Pruning object {object_id} version {version:?}");
1748                object_keys_to_prune.push(ObjectKey(*object_id, version));
1749            }
1750        }
1751
1752        wb.delete_batch(&self.perpetual_tables.objects, object_keys_to_prune)?;
1753        wb.write()?;
1754        Ok(())
1755    }
1756
1757    // Counts the number of versions exist in object store for `object_id`. This
1758    // includes tombstone.
1759    #[cfg(msim)]
1760    pub fn count_object_versions(&self, object_id: ObjectId) -> usize {
1761        self.perpetual_tables
1762            .objects
1763            .safe_iter_with_prefix(&object_id)
1764            .collect::<Result<Vec<_>, _>>()
1765            .unwrap()
1766            .len()
1767    }
1768}
1769
1770impl GlobalStateHashStore for AuthorityStore {
1771    fn get_root_state_hash_for_epoch(
1772        &self,
1773        epoch: EpochId,
1774    ) -> IotaResult<Option<(CheckpointSequenceNumber, GlobalStateHash)>> {
1775        self.perpetual_tables
1776            .root_state_hash_by_epoch
1777            .get(&epoch)
1778            .map_err(Into::into)
1779    }
1780
1781    fn insert_state_hash_for_epoch(
1782        &self,
1783        epoch: EpochId,
1784        last_checkpoint_of_epoch: &CheckpointSequenceNumber,
1785        acc: &GlobalStateHash,
1786    ) -> IotaResult {
1787        self.perpetual_tables
1788            .root_state_hash_by_epoch
1789            .insert(&epoch, &(*last_checkpoint_of_epoch, acc.clone()))?;
1790        self.root_state_notify_read
1791            .notify(&epoch, &(*last_checkpoint_of_epoch, acc.clone()));
1792
1793        Ok(())
1794    }
1795
1796    fn iter_live_object_set(&self) -> DbIterator<'_, LiveObject> {
1797        Box::new(self.perpetual_tables.iter_live_object_set())
1798    }
1799}
1800
1801impl ObjectStore for AuthorityStore {
1802    /// Read an object and return it, or Ok(None) if the object was not found.
1803    fn try_get_object(
1804        &self,
1805        object_id: &ObjectId,
1806    ) -> Result<Option<Object>, iota_types::storage::error::Error> {
1807        self.perpetual_tables.as_ref().try_get_object(object_id)
1808    }
1809
1810    fn try_get_object_by_key(
1811        &self,
1812        object_id: &ObjectId,
1813        version: VersionNumber,
1814    ) -> Result<Option<Object>, iota_types::storage::error::Error> {
1815        self.perpetual_tables
1816            .try_get_object_by_key(object_id, version)
1817    }
1818}
1819
1820/// A wrapper to make Orphan Rule happy
1821pub struct ResolverWrapper {
1822    pub resolver: Arc<dyn BackingPackageStore + Send + Sync>,
1823    pub metrics: Arc<ResolverMetrics>,
1824}
1825
1826impl ResolverWrapper {
1827    pub fn new(
1828        resolver: Arc<dyn BackingPackageStore + Send + Sync>,
1829        metrics: Arc<ResolverMetrics>,
1830    ) -> Self {
1831        metrics.module_cache_size.set(0);
1832        ResolverWrapper { resolver, metrics }
1833    }
1834
1835    fn inc_cache_size_gauge(&self) {
1836        // reset the gauge after a restart of the cache
1837        let current = self.metrics.module_cache_size.get();
1838        self.metrics.module_cache_size.set(current + 1);
1839    }
1840}
1841
1842impl ModuleResolver for ResolverWrapper {
1843    type Error = IotaError;
1844    fn get_module(&self, module_id: &ModuleId) -> Result<Option<Vec<u8>>, Self::Error> {
1845        self.inc_cache_size_gauge();
1846        get_module(&*self.resolver, module_id)
1847    }
1848}
1849
1850pub enum UpdateType {
1851    Transaction(TransactionEffectsDigest),
1852    Genesis,
1853}
1854
1855pub type IotaLockResult = IotaResult<ObjectLockStatus>;
1856
1857#[derive(Debug, PartialEq, Eq)]
1858pub enum ObjectLockStatus {
1859    Initialized,
1860    LockedToTx { locked_by_tx: LockDetails }, // no need to use wrapper, not stored or serialized
1861    LockedAtDifferentVersion { locked_ref: ObjectReference },
1862}