Skip to main content

sui_rpc_api/
reader.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use std::collections::{BTreeSet, HashMap};
5use std::sync::Arc;
6
7use mysten_common::ZipDebugEqIteratorExt;
8use sui_package_resolver::{SyncPackageStore, SyncResolver};
9use sui_sdk_types::{EpochId, ValidatorCommittee};
10use sui_types::base_types::ObjectID;
11use sui_types::base_types::SequenceNumber;
12use sui_types::base_types::TransactionDigest;
13use sui_types::effects::TransactionEffectsAPI;
14use sui_types::storage::ObjectKey;
15use sui_types::storage::error::{Error as StorageError, Result};
16use sui_types::storage::{RpcIndexes, RpcStateReader};
17use tap::Pipe;
18
19use crate::ErrorDetails;
20use crate::ErrorReason;
21use crate::ledger_history::query_options::{
22    above_latest_available, below_serving_floor, ledger_error_info,
23};
24
25#[derive(Clone)]
26pub struct StateReader {
27    inner: Arc<dyn RpcStateReader>,
28}
29
30impl StateReader {
31    pub fn new(inner: Arc<dyn RpcStateReader>) -> Self {
32        Self { inner }
33    }
34
35    pub fn inner(&self) -> &Arc<dyn RpcStateReader> {
36        &self.inner
37    }
38
39    #[tracing::instrument(skip(self))]
40    pub fn get_committee(&self, epoch: EpochId) -> Option<ValidatorCommittee> {
41        self.inner
42            .get_committee(epoch)
43            .map(|committee| (*committee).clone().into())
44    }
45
46    #[tracing::instrument(skip(self))]
47    pub fn get_system_state(&self) -> Result<sui_types::sui_system_state::SuiSystemState> {
48        sui_types::sui_system_state::get_sui_system_state(self.inner())
49            .map_err(StorageError::custom)
50            .map_err(StorageError::custom)
51    }
52
53    #[tracing::instrument(skip(self))]
54    pub fn get_display_object_v2_by_type(
55        &self,
56        object_type: &move_core_types::language_storage::StructTag,
57    ) -> Option<sui_types::display_registry::Display> {
58        let object_id =
59            sui_types::display_registry::display_object_id(object_type.clone().into()).ok()?;
60
61        let object = self.inner.get_object(&object_id)?;
62
63        let move_object = object.data.try_as_move()?;
64
65        bcs::from_bytes(move_object.contents()).ok()
66    }
67
68    #[tracing::instrument(skip(self))]
69    pub fn get_system_state_summary(
70        &self,
71    ) -> Result<sui_types::sui_system_state::sui_system_state_summary::SuiSystemStateSummary> {
72        use sui_types::sui_system_state::SuiSystemStateTrait;
73
74        let system_state = self.get_system_state()?;
75        let summary = system_state.into_sui_system_state_summary();
76
77        Ok(summary)
78    }
79
80    pub fn get_authenticator_state(
81        &self,
82    ) -> Result<Option<sui_types::authenticator_state::AuthenticatorStateInner>> {
83        sui_types::authenticator_state::get_authenticator_state(self.inner())
84            .map_err(StorageError::custom)
85    }
86
87    #[tracing::instrument(skip(self))]
88    pub fn get_address_aliases(
89        &self,
90        address: sui_types::base_types::SuiAddress,
91    ) -> Result<Option<sui_types::address_alias::AddressAliases>> {
92        let object_id = sui_types::address_alias::address_aliases_object_id(address)
93            .map_err(StorageError::custom)?;
94
95        let Some(object) = self.inner.get_object(&object_id) else {
96            return Ok(None);
97        };
98
99        let move_object = object
100            .data
101            .try_as_move()
102            .ok_or_else(|| StorageError::custom("address aliases object is not a Move object"))?;
103
104        bcs::from_bytes(move_object.contents())
105            .map(Some)
106            .map_err(StorageError::custom)
107    }
108
109    #[tracing::instrument(skip(self))]
110    pub fn get_transaction(
111        &self,
112        digest: sui_sdk_types::Digest,
113    ) -> crate::Result<(
114        sui_types::transaction::TransactionData,
115        Vec<sui_types::signature::GenericSignature>,
116        sui_types::effects::TransactionEffects,
117        Option<sui_types::effects::TransactionEvents>,
118    )> {
119        let transaction_digest = digest.into();
120
121        let transaction = (*self
122            .inner()
123            .get_transaction(&transaction_digest)
124            .ok_or(TransactionNotFoundError(digest))?)
125        .clone()
126        .into_inner();
127        let effects = self
128            .inner()
129            .get_transaction_effects(&transaction_digest)
130            .ok_or(TransactionNotFoundError(digest))?;
131        let events = if effects.events_digest().is_some() {
132            self.inner()
133                .get_events(effects.transaction_digest())
134                .ok_or(TransactionNotFoundError(digest))?
135                .pipe(Some)
136        } else {
137            None
138        };
139
140        let transaction = transaction.into_data().into_inner();
141        let signatures = transaction.tx_signatures;
142        let transaction = transaction.intent_message.value;
143
144        Ok((transaction, signatures, effects, events))
145    }
146
147    /// Fetch transaction reads using checkpoints supplied by the ledger index rows.
148    pub fn multi_get_transaction_reads(
149        &self,
150        items: &[(sui_sdk_types::Digest, u64)],
151    ) -> crate::Result<Vec<TransactionRead>> {
152        let transaction_digests = items
153            .iter()
154            .map(|(digest, _)| (*digest).into())
155            .collect::<Vec<TransactionDigest>>();
156        let transactions = self.inner().multi_get_transactions(&transaction_digests);
157        let effects = self
158            .inner()
159            .multi_get_transaction_effects(&transaction_digests);
160        let events = self.inner().multi_get_events(&transaction_digests);
161        let unchanged_loaded_runtime_objects = self
162            .inner()
163            .multi_get_unchanged_loaded_runtime_objects(&transaction_digests);
164        let timestamps = dedup_checkpoint_timestamps(
165            items.iter().map(|(_, checkpoint)| *checkpoint),
166            |unique| {
167                self.inner()
168                    .multi_get_checkpoint_by_sequence_number(unique)
169                    .into_iter()
170                    .map(|checkpoint| checkpoint.map(|checkpoint| checkpoint.timestamp_ms))
171                    .collect()
172            },
173        );
174
175        let mut reads = Vec::with_capacity(items.len());
176        for (
177            ((((digest, checkpoint), _transaction_digest), transaction), (effects, events)),
178            unchanged_loaded_runtime_objects,
179        ) in items
180            .iter()
181            .copied()
182            .zip_debug_eq(transaction_digests)
183            .zip_debug_eq(transactions)
184            .zip_debug_eq(effects.into_iter().zip_debug_eq(events))
185            .zip_debug_eq(unchanged_loaded_runtime_objects)
186        {
187            let transaction = (*transaction.ok_or(TransactionNotFoundError(digest))?)
188                .clone()
189                .into_inner();
190            let effects = effects.ok_or(TransactionNotFoundError(digest))?;
191            let events = if effects.events_digest().is_some() {
192                events.ok_or(TransactionNotFoundError(digest))?.pipe(Some)
193            } else {
194                None
195            };
196
197            let transaction = transaction.into_data().into_inner();
198            let signatures = transaction.tx_signatures;
199            let transaction = transaction.intent_message.value;
200            let timestamp_ms = timestamps[&checkpoint];
201
202            reads.push(TransactionRead {
203                digest,
204                transaction,
205                signatures,
206                effects,
207                events,
208                timestamp_ms,
209                unchanged_loaded_runtime_objects,
210            });
211        }
212
213        Ok(reads)
214    }
215
216    pub fn multi_get_events(
217        &self,
218        digests: &[TransactionDigest],
219    ) -> Vec<Option<sui_types::effects::TransactionEvents>> {
220        self.inner().multi_get_events(digests)
221    }
222
223    #[tracing::instrument(skip(self))]
224    pub fn get_transaction_read(
225        &self,
226        digest: sui_sdk_types::Digest,
227    ) -> crate::Result<TransactionRead> {
228        let (transaction, signatures, effects, events) = self.get_transaction(digest)?;
229
230        let checkpoint = self.inner().get_transaction_checkpoint(&(digest.into()));
231        let timestamp_ms =
232            checkpoint.and_then(|checkpoint| self.checkpoint_timestamp_ms(checkpoint));
233
234        let unchanged_loaded_runtime_objects = self
235            .inner()
236            .get_unchanged_loaded_runtime_objects(&(digest.into()));
237
238        Ok(TransactionRead {
239            digest,
240            transaction,
241            signatures,
242            effects,
243            events,
244            timestamp_ms,
245            unchanged_loaded_runtime_objects,
246        })
247    }
248
249    /// Timestamp of the checkpoint summary, if it is still in the store.
250    fn checkpoint_timestamp_ms(&self, checkpoint: u64) -> Option<u64> {
251        self.inner()
252            .get_checkpoint_by_sequence_number(checkpoint)
253            .map(|checkpoint| checkpoint.timestamp_ms)
254    }
255
256    pub fn lookup_address_balance(
257        &self,
258        owner: sui_types::base_types::SuiAddress,
259        coin_type: move_core_types::language_storage::StructTag,
260    ) -> Option<u64> {
261        use sui_types::MoveTypeTagTraitGeneric;
262        use sui_types::SUI_ACCUMULATOR_ROOT_OBJECT_ID;
263        use sui_types::accumulator_root::AccumulatorKey;
264        use sui_types::dynamic_field::DynamicFieldKey;
265
266        let balance_type = sui_types::balance::Balance::type_tag(coin_type.into());
267
268        let key = AccumulatorKey { owner };
269        let key_type_tag = AccumulatorKey::get_type_tag(&[balance_type]);
270
271        DynamicFieldKey(SUI_ACCUMULATOR_ROOT_OBJECT_ID, key, key_type_tag)
272            .into_unbounded_id()
273            .unwrap()
274            .load_object(self.inner())
275            .and_then(|o| o.load_value::<u128>().ok())
276            .map(|balance| balance as u64)
277    }
278
279    // Return the lowest available checkpoint watermark for which the RPC service can return proper
280    // responses for.
281    pub fn get_lowest_available_checkpoint(&self) -> Result<u64, crate::RpcError> {
282        // This is the lowest lowest_available_checkpoint from the checkpoint store
283        let lowest_available_checkpoint = self.inner().get_lowest_available_checkpoint()?;
284        // This is the lowest lowest_available_checkpoint from the perpetual store
285        let lowest_available_checkpoint_objects =
286            self.inner().get_lowest_available_checkpoint_objects()?;
287
288        // Return the higher of the two for our lower watermark
289        Ok(lowest_available_checkpoint.max(lowest_available_checkpoint_objects))
290    }
291
292    /// The upper bound for checkpoint-pinned reads ([`Self::get_object_version_at_checkpoint`]
293    /// and `GetPackage`'s `at_checkpoint`): the highest checkpoint every rpc index has committed.
294    ///
295    /// Read it before the reads. It only grows, and the indexes only add data above it, so it
296    /// stays valid for reads made after it was read. The lower bound is the opposite; see
297    /// [`Self::at_checkpoint_lower_bound`].
298    ///
299    /// Fails as [`Self::require_rpc_index_history`] does, or with `UNAVAILABLE` (`NOT_READY`,
300    /// cause `index_empty`) if the rpc indexes have not committed a checkpoint yet.
301    pub fn at_checkpoint_upper_bound(&self) -> Result<AtCheckpointUpperBound, crate::RpcError> {
302        let highest_indexed = self
303            .require_rpc_index_history()?
304            .get_highest_indexed_checkpoint_seq_number()
305            .map_err(index_error)?
306            .ok_or_else(index_empty)?;
307        Ok(AtCheckpointUpperBound { highest_indexed })
308    }
309
310    /// The rpc indexes, for reads that need the history they record: checkpoint-pinned reads,
311    /// and `max_version` reads, which on a pruned node check the version they find against the
312    /// indexes (see [`RpcStateReader::get_object_lt_or_eq_version`]).
313    ///
314    /// `UNIMPLEMENTED` (`NOT_SERVED_HERE`, cause `no_rpc_indexes`) if the rpc indexes are
315    /// disabled. `UNAVAILABLE` (`NOT_READY`, cause `restore_backfill`) while they are still
316    /// backfilling history after a restore: until every history index reaches the restore
317    /// checkpoint, a checkpoint-pinned read can be wrong at any checkpoint the indexes cover
318    /// (restore of a pruned node), the highest indexed checkpoint lies far below the restored
319    /// live state (restore with nothing pruned), and the version the indexes record at the end
320    /// of a checkpoint can be a later one, which would refuse `max_version` reads of versions
321    /// this node holds.
322    pub fn require_rpc_index_history(&self) -> Result<&dyn RpcIndexes, crate::RpcError> {
323        let indexes = self.inner().indexes().ok_or_else(indexes_disabled)?;
324        if indexes.is_history_backfill_pending().map_err(index_error)? {
325            return Err(not_ready(
326                NotReadyCause::RestoreBackfill,
327                "rpc index history is still backfilling after a restore",
328            ));
329        }
330        Ok(indexes)
331    }
332
333    /// [`version_not_retained`] if this node does not keep object versions once they are replaced
334    /// (see [`RpcStateReader::retains_object_version_history`]): reads that depend on an object's
335    /// replaced versions would find them gone and answer `NotFound`. The refusal depends only on
336    /// the node's configuration, so check it before anything that depends on the node's state.
337    pub fn require_object_version_history(&self) -> Result<(), crate::RpcError> {
338        if self.inner().retains_object_version_history() {
339            return Ok(());
340        }
341        Err(version_not_retained())
342    }
343
344    /// The lower bound for checkpoint-pinned reads: the checkpoint just below the higher of
345    /// [`RpcStateReader::get_lowest_available_checkpoint_objects`] and
346    /// [`RpcStateReader::get_lowest_checkpoint_with_index_history`]. The lowest available
347    /// checkpoint's input objects are available, and they are the object state at the end of the
348    /// checkpoint before: pruning through a checkpoint deletes only the object versions and index
349    /// rows replaced at or before it. Likewise, index rows loaded without history hold the state
350    /// at the end of the checkpoint before the first one with index history.
351    ///
352    /// Read it after the reads, and answer every read at a checkpoint below it as pruned,
353    /// whatever the read returned. Pruning can raise the floor while the reads run, and a read
354    /// below the new floor may have seen pruned data. Pruning raises the floor no later than it
355    /// deletes data (the rpc-store commits its retractions and floor before the object versions
356    /// are deleted), only deletes data that reads below the new floor need, and never lowers the
357    /// floor, so a read at a checkpoint this bound accepts saw no pruned data.
358    pub fn at_checkpoint_lower_bound(&self) -> Result<AtCheckpointLowerBound, crate::RpcError> {
359        let lowest_available_objects = self.inner().get_lowest_available_checkpoint_objects()?;
360        let lowest_with_index_history = self.inner().get_lowest_checkpoint_with_index_history()?;
361        Ok(AtCheckpointLowerBound {
362            lowest_available: lowest_available_objects.max(lowest_with_index_history),
363        })
364    }
365
366    /// The version the rpc index records for `object_id` at the end of `checkpoint`: its newest
367    /// version written at or before `checkpoint`, or, if that change deleted or wrapped it, the
368    /// version the index records for the removal. For a removal with V1 effects that is
369    /// `TransactionEffectsAPI::lamport_version`, which can be below the tombstone's version in
370    /// the object store, though no version of the object lies between the two. Every live version
371    /// above this one was written after `checkpoint`. `None` if the object did not exist yet, or
372    /// if it was deleted or wrapped in a checkpoint this node pruned, whose pruning removes every
373    /// index row of the object.
374    /// `OutOfRange` (`ABOVE_LATEST_AVAILABLE`) if `checkpoint` is above `upper_bound`; check the
375    /// lower bound after the read with [`Self::at_checkpoint_lower_bound`].
376    pub fn get_object_version_at_checkpoint(
377        &self,
378        object_id: ObjectID,
379        checkpoint: u64,
380        upper_bound: &AtCheckpointUpperBound,
381    ) -> Result<Option<SequenceNumber>, crate::RpcError> {
382        upper_bound.check(checkpoint)?;
383
384        let indexes = self.inner().indexes().ok_or_else(indexes_disabled)?;
385        indexes
386            .get_object_version_at_checkpoint(object_id, checkpoint)
387            .map_err(index_error)
388    }
389}
390
391/// See `StateReader::at_checkpoint_upper_bound`. Read once per request so that a batch checks
392/// every item against the same bound. Other implementors of the rpc services build it with
393/// [`Self::new`] from the height they serve (e.g. sui-kv-rpc's served height), so every backend
394/// applies the same check.
395#[derive(Clone, Copy, Debug)]
396pub struct AtCheckpointUpperBound {
397    /// The highest checkpoint every rpc index has committed.
398    highest_indexed: u64,
399}
400
401impl AtCheckpointUpperBound {
402    /// The bound of a backend whose indexes have all committed `highest_indexed`.
403    pub fn new(highest_indexed: u64) -> Self {
404        Self { highest_indexed }
405    }
406
407    /// The highest checkpoint every rpc index has committed.
408    pub fn highest_indexed(&self) -> u64 {
409        self.highest_indexed
410    }
411
412    /// `OutOfRange` (`ABOVE_LATEST_AVAILABLE`, for the request field `at_checkpoint`) if
413    /// `checkpoint` is above the bound: the indexes may not have caught up to it, so an answer
414    /// could be wrong.
415    pub fn check(&self, checkpoint: u64) -> Result<(), crate::RpcError> {
416        if checkpoint > self.highest_indexed {
417            return Err(above_latest_available(
418                "at_checkpoint",
419                checkpoint,
420                self.highest_indexed.saturating_add(1),
421            ));
422        }
423        Ok(())
424    }
425
426    /// `OutOfRange` (`ABOVE_LATEST_AVAILABLE`, for a cursor) if a cursor recording `checkpoint`
427    /// names a position above the bound, which the indexes have not caught up to.
428    pub fn check_cursor(&self, checkpoint: u64) -> Result<(), crate::RpcError> {
429        if checkpoint > self.highest_indexed {
430            return Err(above_latest_available(
431                "cursor",
432                checkpoint,
433                self.highest_indexed.saturating_add(1),
434            ));
435        }
436        Ok(())
437    }
438
439    /// The error for a cursor or page token naming a position the indexes have not reached whose
440    /// checkpoint is not known, such as a version this backend has no row for: `OutOfRange` with
441    /// an `ABOVE_LATEST_AVAILABLE` [`ErrorInfo`](crate::proto::google::rpc::ErrorInfo) for the
442    /// bound "cursor", placing the cursor at the lowest checkpoint it can be at, the first one
443    /// above the bound.
444    pub fn unindexed_cursor_error(&self) -> crate::RpcError {
445        let first_unindexed = self.highest_indexed.saturating_add(1);
446        above_latest_available("cursor", first_unindexed, first_unindexed)
447    }
448}
449
450/// See `StateReader::at_checkpoint_lower_bound`.
451#[derive(Clone, Copy, Debug)]
452pub struct AtCheckpointLowerBound {
453    /// The lowest checkpoint whose input objects are available and covered by the rpc indexes'
454    /// history. The object state at the end of the checkpoint before it is intact.
455    lowest_available: u64,
456}
457
458impl AtCheckpointLowerBound {
459    /// The bound of a node whose lowest available checkpoint, for object data and index history
460    /// alike, is `lowest_available`.
461    #[cfg(test)]
462    pub(crate) fn new(lowest_available: u64) -> Self {
463        Self { lowest_available }
464    }
465
466    /// `OutOfRange` (`BELOW_EARLIEST_AVAILABLE`) if `checkpoint` is below the bound: its history
467    /// may have been pruned, so an answer could be wrong.
468    pub fn check(&self, checkpoint: u64) -> Result<(), crate::RpcError> {
469        if checkpoint < self.lowest_intact() {
470            return Err(self.pruned());
471        }
472        Ok(())
473    }
474
475    /// `OutOfRange` (`BELOW_EARLIEST_AVAILABLE`) for data this node has pruned, such as a
476    /// replaced version of an object named by its version rather than a checkpoint.
477    pub fn pruned(&self) -> crate::RpcError {
478        below_serving_floor(self.lowest_intact())
479    }
480
481    /// The lowest checkpoint whose object state is intact, if history below it is gone: object
482    /// versions replaced at or before its end are pruned, or the indexes never had them. `None`
483    /// when the history is complete from genesis.
484    pub fn pruned_floor(&self) -> Option<u64> {
485        self.lowest_available.checked_sub(1)
486    }
487
488    /// The lowest checkpoint whose object state is intact: the one just below
489    /// `lowest_available`, or 0.
490    fn lowest_intact(&self) -> u64 {
491        self.lowest_available.saturating_sub(1)
492    }
493}
494
495/// The `cause` of a `NOT_SERVED_HERE` refusal: why this node does not serve a request. The
496/// same request to the same node always fails the same way, so clients do not retry it there.
497#[derive(Clone, Copy, Debug, PartialEq, Eq)]
498pub enum NotServedHereCause {
499    /// The node runs without rpc indexes.
500    NoRpcIndexes,
501    /// A kv-rpc `enable-*` flag the request needs is off.
502    DisabledByConfig,
503    /// The node's live state includes data the network has not certified yet, and the request
504    /// asks for certified data: a validator's live-state read at the `certified` finality level.
505    UncertifiedLiveState,
506}
507
508impl NotServedHereCause {
509    /// The value of the refusal's `cause` metadata.
510    pub fn as_str(self) -> &'static str {
511        match self {
512            Self::NoRpcIndexes => "no_rpc_indexes",
513            Self::DisabledByConfig => "disabled_by_config",
514            Self::UncertifiedLiveState => "uncertified_live_state",
515        }
516    }
517}
518
519/// The `cause` of a `NOT_READY` refusal: the temporary state that keeps this node from serving a
520/// request it will serve once the state clears.
521#[derive(Clone, Copy, Debug, PartialEq, Eq)]
522pub enum NotReadyCause {
523    /// The rpc indexes have not committed a checkpoint yet.
524    IndexEmpty,
525    /// The rpc indexes are still backfilling history after a restore from a snapshot.
526    RestoreBackfill,
527    /// The rpc indexes have not yet reached data this node's live state already holds.
528    HistoryCatchingUp,
529}
530
531impl NotReadyCause {
532    /// The value of the refusal's `cause` metadata.
533    pub fn as_str(self) -> &'static str {
534        match self {
535            Self::IndexEmpty => "index_empty",
536            Self::RestoreBackfill => "restore_backfill",
537            Self::HistoryCatchingUp => "history_catching_up",
538        }
539    }
540}
541
542/// A refusal for a request this node is not set up for: `Unimplemented` with a `NOT_SERVED_HERE`
543/// [`ErrorInfo`](crate::proto::google::rpc::ErrorInfo) whose `cause` metadata is `cause`.
544pub fn not_served_here(cause: NotServedHereCause, message: impl Into<String>) -> crate::RpcError {
545    refusal(
546        tonic::Code::Unimplemented,
547        ErrorReason::NotServedHere,
548        cause.as_str(),
549        message,
550    )
551}
552
553/// A refusal for a request this node cannot serve now but will: `Unavailable` with a `NOT_READY`
554/// [`ErrorInfo`](crate::proto::google::rpc::ErrorInfo) whose `cause` metadata is `cause`.
555pub fn not_ready(cause: NotReadyCause, message: impl Into<String>) -> crate::RpcError {
556    refusal(
557        tonic::Code::Unavailable,
558        ErrorReason::NotReady,
559        cause.as_str(),
560        message,
561    )
562}
563
564fn refusal(
565    code: tonic::Code,
566    reason: ErrorReason,
567    cause: &str,
568    message: impl Into<String>,
569) -> crate::RpcError {
570    let error_info = ledger_error_info(reason, [("cause", cause.to_owned())]);
571    crate::RpcError::new(code, message)
572        .with_details(ErrorDetails::new().with_error_info(error_info))
573}
574
575/// [`not_served_here`] with cause `no_rpc_indexes`: this node runs without rpc indexes, so reads
576/// that need them cannot be answered.
577pub(crate) fn indexes_disabled() -> crate::RpcError {
578    not_served_here(NotServedHereCause::NoRpcIndexes, "rpc indexes are disabled")
579}
580
581/// The refusal for a read of an object version that this node, which keeps only each object's
582/// latest version, deleted when a later version replaced it: `OutOfRange` with a
583/// `VERSION_NOT_RETAINED` [`ErrorInfo`](crate::proto::google::rpc::ErrorInfo) and no metadata.
584/// The same request fails the same way on this node; a node that keeps object version history
585/// may serve it.
586pub(crate) fn version_not_retained() -> crate::RpcError {
587    crate::RpcError::new(
588        tonic::Code::OutOfRange,
589        "this node keeps only the latest version of each object, so it cannot answer reads of \
590         earlier versions",
591    )
592    .with_details(
593        ErrorDetails::new().with_error_info(ledger_error_info(ErrorReason::VersionNotRetained, [])),
594    )
595}
596
597/// [`not_ready`] with cause `index_empty`: the rpc indexes have not committed a checkpoint yet.
598pub(crate) fn index_empty() -> crate::RpcError {
599    not_ready(NotReadyCause::IndexEmpty, "rpc index is empty")
600}
601
602fn index_error(error: StorageError) -> crate::RpcError {
603    crate::RpcError::new(tonic::Code::Internal, error.to_string())
604}
605
606fn dedup_checkpoint_timestamps(
607    checkpoints: impl IntoIterator<Item = u64>,
608    fetch: impl FnOnce(&[u64]) -> Vec<Option<u64>>,
609) -> HashMap<u64, Option<u64>> {
610    let unique_checkpoints = checkpoints
611        .into_iter()
612        .collect::<BTreeSet<_>>()
613        .into_iter()
614        .collect::<Vec<_>>();
615    if unique_checkpoints.is_empty() {
616        return HashMap::new();
617    }
618
619    let timestamps = fetch(&unique_checkpoints);
620    unique_checkpoints
621        .into_iter()
622        .zip_debug_eq(timestamps)
623        .collect()
624}
625
626#[derive(Debug)]
627pub struct TransactionRead {
628    pub digest: sui_sdk_types::Digest,
629    pub transaction: sui_types::transaction::TransactionData,
630    pub signatures: Vec<sui_types::signature::GenericSignature>,
631    pub effects: sui_types::effects::TransactionEffects,
632    pub events: Option<sui_types::effects::TransactionEvents>,
633    pub timestamp_ms: Option<u64>,
634    pub unchanged_loaded_runtime_objects: Option<Vec<ObjectKey>>,
635}
636
637#[derive(Debug)]
638pub struct TransactionNotFoundError(pub sui_sdk_types::Digest);
639
640impl std::fmt::Display for TransactionNotFoundError {
641    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
642        write!(f, "Transaction {} not found", self.0)
643    }
644}
645
646impl std::error::Error for TransactionNotFoundError {}
647
648impl From<TransactionNotFoundError> for crate::RpcError {
649    fn from(value: TransactionNotFoundError) -> Self {
650        Self::new(tonic::Code::NotFound, value.to_string())
651    }
652}
653
654pub struct DisplayStore<'s, S> {
655    state: &'s StateReader,
656    resolver: &'s SyncResolver<S>,
657}
658
659impl<'s, S> DisplayStore<'s, S> {
660    pub fn new(state: &'s StateReader, resolver: &'s SyncResolver<S>) -> Self {
661        Self { state, resolver }
662    }
663}
664
665#[async_trait::async_trait]
666impl<S: SyncPackageStore + Sync> sui_display::v2::Store for DisplayStore<'_, S> {
667    async fn latest(
668        &self,
669        id: move_core_types::account_address::AccountAddress,
670    ) -> anyhow::Result<Option<(move_core_types::annotated_value::MoveTypeLayout, Vec<u8>)>> {
671        let Some(object) = self.state.inner().get_object(&id.into()) else {
672            return Ok(None);
673        };
674
675        let Some(move_object) = object.data.try_as_move() else {
676            return Ok(None);
677        };
678
679        let object_type = move_object.type_().clone().into();
680
681        let layout = self.resolver.datatype_layout(&object_type)?.into_layout();
682
683        Ok(Some((layout, move_object.contents().to_vec())))
684    }
685}
686
687/// Asserts `error` is `code` with exactly one [`ErrorInfo`](crate::proto::google::rpc::ErrorInfo):
688/// `reason` in the [`ErrorReason::DOMAIN`] domain, whose only metadata is `cause`.
689#[cfg(test)]
690pub(crate) fn assert_refusal(
691    error: crate::RpcError,
692    code: tonic::Code,
693    reason: ErrorReason,
694    cause: &str,
695) {
696    assert_status_refusal(&error.into_status_proto(), code, reason, cause);
697}
698
699/// [`assert_refusal`] for a status already converted to its proto, such as a per-item error of a
700/// batch response.
701#[cfg(test)]
702pub(crate) fn assert_status_refusal(
703    status: &crate::proto::google::rpc::Status,
704    code: tonic::Code,
705    reason: ErrorReason,
706    cause: &str,
707) {
708    use crate::proto::google::rpc::ErrorInfo;
709
710    assert_eq!(status.code, code as i32, "{status:?}");
711    let error_infos: Vec<ErrorInfo> = status
712        .details
713        .iter()
714        .filter_map(|detail| detail.to_msg::<ErrorInfo>().ok())
715        .collect();
716    let [error_info] = error_infos.as_slice() else {
717        panic!("expected exactly one ErrorInfo in {status:?}");
718    };
719    assert_eq!(error_info.reason, reason.as_str_name(), "{status:?}");
720    assert_eq!(error_info.domain, ErrorReason::DOMAIN, "{status:?}");
721    assert_eq!(
722        error_info.metadata,
723        [("cause".to_owned(), cause.to_owned())].into(),
724        "{status:?}"
725    );
726}
727
728/// [`assert_refusal`] for [`not_served_here`] with `cause`.
729#[cfg(test)]
730pub(crate) fn assert_not_served_here(error: crate::RpcError, cause: NotServedHereCause) {
731    assert_status_not_served_here(&error.into_status_proto(), cause);
732}
733
734/// [`assert_not_served_here`] for a status already converted to its proto.
735#[cfg(test)]
736pub(crate) fn assert_status_not_served_here(
737    status: &crate::proto::google::rpc::Status,
738    cause: NotServedHereCause,
739) {
740    assert_status_refusal(
741        status,
742        tonic::Code::Unimplemented,
743        ErrorReason::NotServedHere,
744        cause.as_str(),
745    );
746}
747
748/// Asserts `error` is [`version_not_retained`]: `OutOfRange` with exactly one
749/// [`ErrorInfo`](crate::proto::google::rpc::ErrorInfo), `VERSION_NOT_RETAINED` in the
750/// [`ErrorReason::DOMAIN`] domain, without metadata.
751#[cfg(test)]
752pub(crate) fn assert_version_not_retained(error: crate::RpcError) {
753    use crate::proto::google::rpc::ErrorInfo;
754
755    let status = error.into_status_proto();
756    assert_eq!(status.code, tonic::Code::OutOfRange as i32, "{status:?}");
757    let error_infos: Vec<ErrorInfo> = status
758        .details
759        .iter()
760        .filter_map(|detail| detail.to_msg::<ErrorInfo>().ok())
761        .collect();
762    let [error_info] = error_infos.as_slice() else {
763        panic!("expected exactly one ErrorInfo in {status:?}");
764    };
765    assert_eq!(
766        error_info.reason,
767        ErrorReason::VersionNotRetained.as_str_name(),
768        "{status:?}"
769    );
770    assert_eq!(error_info.domain, ErrorReason::DOMAIN, "{status:?}");
771    assert!(error_info.metadata.is_empty(), "{status:?}");
772}
773
774#[cfg(test)]
775pub(crate) mod tests {
776    use std::cell::Cell;
777
778    use super::*;
779    // Tests in other modules import the helpers from here.
780    pub(crate) use super::assert_refusal;
781
782    #[test]
783    fn dedup_checkpoint_timestamps_fetches_sorted_unique_checkpoints_once() {
784        let fetch_calls = Cell::new(0);
785        let timestamps = dedup_checkpoint_timestamps([5, 5, 3, 5, 3], |checkpoints| {
786            fetch_calls.set(fetch_calls.get() + 1);
787            assert_eq!(checkpoints, &[3, 5]);
788            vec![Some(300), Some(500)]
789        });
790
791        assert_eq!(fetch_calls.get(), 1);
792        assert_eq!(timestamps.len(), 2);
793        assert_eq!(timestamps[&3], Some(300));
794        assert_eq!(timestamps[&5], Some(500));
795    }
796
797    #[test]
798    fn dedup_checkpoint_timestamps_skips_fetch_for_empty_input() {
799        let fetch_calls = Cell::new(0);
800        let timestamps = dedup_checkpoint_timestamps([], |_| {
801            fetch_calls.set(fetch_calls.get() + 1);
802            Vec::new()
803        });
804
805        assert_eq!(fetch_calls.get(), 0);
806        assert!(timestamps.is_empty());
807    }
808
809    #[test]
810    fn dedup_checkpoint_timestamps_preserves_missing_summary() {
811        let timestamps = dedup_checkpoint_timestamps([2, 1], |checkpoints| {
812            assert_eq!(checkpoints, &[1, 2]);
813            vec![None, Some(200)]
814        });
815
816        assert_eq!(timestamps[&1], None);
817        assert_eq!(timestamps[&2], Some(200));
818    }
819
820    /// A [`StateReader`] over a fresh rpc-store that registers the embedded fullnode's pipelines.
821    pub(crate) fn rpc_store_state_reader()
822    -> (tempfile::TempDir, sui_consistent_store::Db, StateReader) {
823        let dir = tempfile::tempdir().unwrap();
824        let (db, schema) = sui_consistent_store::Db::open::<sui_rpc_store::RpcStoreSchema>(
825            dir.path(),
826            sui_consistent_store::DbOptions::default(),
827        )
828        .unwrap();
829        let store = sui_rpc_store::RpcStoreReader::new(db.clone(), Arc::new(schema));
830        (dir, db, StateReader::new(Arc::new(store)))
831    }
832
833    /// Commits `checkpoint` as the watermark of every pipeline the store registers.
834    pub(crate) fn commit_every_pipeline(db: &sui_consistent_store::Db, checkpoint: u64) {
835        let framework = sui_consistent_store::FrameworkSchema::new(db.clone());
836        let mut batch = db.batch();
837        for name in sui_rpc_store::LIVE_COHORT
838            .iter()
839            .chain(sui_rpc_store::HISTORY_COHORT)
840        {
841            batch
842                .put(
843                    &framework.watermarks,
844                    &sui_consistent_store::PipelineTaskKey::new(*name),
845                    &sui_consistent_store::Watermark::for_checkpoint(checkpoint),
846                )
847                .unwrap();
848        }
849        batch.commit().unwrap();
850    }
851
852    /// Records `state` as the restore state of each of `pipelines`.
853    pub(crate) fn record_restore_state(
854        db: &sui_consistent_store::Db,
855        pipelines: &[&str],
856        state: sui_consistent_store::restore_state::State,
857    ) {
858        let framework = sui_consistent_store::FrameworkSchema::new(db.clone());
859        let mut batch = db.batch();
860        for name in pipelines {
861            batch
862                .put(
863                    &framework.restore,
864                    &sui_consistent_store::PipelineTaskKey::new(*name),
865                    &sui_consistent_store::RestoreState {
866                        state: Some(state.clone()),
867                    },
868                )
869                .unwrap();
870        }
871        batch.commit().unwrap();
872    }
873
874    /// Checkpoint-pinned reads are refused as not ready while the indexes are empty and while a
875    /// restore that loaded history floor rows is pending, both before the restore completes and
876    /// after, until the backfill commits the restore checkpoint; then the bound is the indexed tip.
877    #[test]
878    fn upper_bound_waits_for_index_and_restore_backfill() {
879        use sui_consistent_store::restore_state;
880
881        let (_dir, db, reader) = rpc_store_state_reader();
882        assert_refusal(
883            reader.at_checkpoint_upper_bound().unwrap_err(),
884            tonic::Code::Unavailable,
885            ErrorReason::NotReady,
886            "index_empty",
887        );
888
889        commit_every_pipeline(&db, 10);
890        record_restore_state(
891            &db,
892            &["object_version_by_checkpoint"],
893            restore_state::State::InProgress(restore_state::InProgress::default()),
894        );
895        assert_refusal(
896            reader.at_checkpoint_upper_bound().unwrap_err(),
897            tonic::Code::Unavailable,
898            ErrorReason::NotReady,
899            "restore_backfill",
900        );
901
902        record_restore_state(
903            &db,
904            &["object_version_by_checkpoint"],
905            restore_state::State::Complete(restore_state::Complete { restored_at: 20 }),
906        );
907        assert_refusal(
908            reader.at_checkpoint_upper_bound().unwrap_err(),
909            tonic::Code::Unavailable,
910            ErrorReason::NotReady,
911            "restore_backfill",
912        );
913
914        commit_every_pipeline(&db, 20);
915        let bound = reader.at_checkpoint_upper_bound().unwrap();
916        assert_eq!(bound.highest_indexed(), 20);
917        bound.check(20).unwrap();
918        bound.check(21).unwrap_err();
919    }
920
921    /// After a restore of the live cohort alone, the history cohort backfills from genesis with no
922    /// restore rows of its own; checkpoint-pinned reads wait until it reaches the restore target
923    /// rather than answer at the backfill's height.
924    #[test]
925    fn upper_bound_waits_for_history_backfill_after_live_only_restore() {
926        use sui_consistent_store::restore_state;
927
928        let (_dir, db, reader) = rpc_store_state_reader();
929        record_restore_state(
930            &db,
931            sui_rpc_store::LIVE_COHORT,
932            restore_state::State::Complete(restore_state::Complete { restored_at: 20 }),
933        );
934        commit_every_pipeline(&db, 10);
935        assert_refusal(
936            reader.at_checkpoint_upper_bound().unwrap_err(),
937            tonic::Code::Unavailable,
938            ErrorReason::NotReady,
939            "restore_backfill",
940        );
941
942        commit_every_pipeline(&db, 20);
943        assert_eq!(
944            reader
945                .at_checkpoint_upper_bound()
946                .unwrap()
947                .highest_indexed(),
948            20
949        );
950    }
951
952    /// The lowest available checkpoint's input objects are available, so the state at the end of
953    /// the checkpoint before it is served, and only history below that one is pruned.
954    #[test]
955    fn lower_bound_serves_the_checkpoint_before_the_lowest_available() {
956        use crate::ledger_history::query_options::assert_below_serving_floor_error;
957
958        let unpruned = AtCheckpointLowerBound::new(0);
959        unpruned.check(0).unwrap();
960        assert_eq!(unpruned.pruned_floor(), None);
961
962        let genesis_pruned = AtCheckpointLowerBound::new(1);
963        genesis_pruned.check(0).unwrap();
964        assert_eq!(genesis_pruned.pruned_floor(), Some(0));
965
966        let pruned = AtCheckpointLowerBound::new(10);
967        pruned.check(9).unwrap();
968        assert_below_serving_floor_error(pruned.check(8).unwrap_err(), 9);
969        assert_below_serving_floor_error(pruned.pruned(), 9);
970        assert_eq!(pruned.pruned_floor(), Some(9));
971    }
972}