iota_types/storage/
mod.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5pub mod error;
6mod object_store_trait;
7mod read_store;
8mod shared_in_memory_store;
9mod write_store;
10
11use std::{
12    cell::RefCell,
13    collections::{BTreeMap, BTreeSet},
14    fmt::{Display, Formatter},
15    rc::Rc,
16    sync::Arc,
17};
18
19use iota_sdk_types::{
20    Address, MovePackage, ObjectId, ObjectReference, SenderSignedTransaction, TransactionDigest,
21    TransactionEffects, Version, WriteKind,
22};
23use itertools::Itertools;
24use move_binary_format::CompiledModule;
25use move_core_types::language_storage::ModuleId;
26pub use object_store_trait::ObjectStore;
27pub use read_store::{
28    AccountOwnedObjectInfo, CoinInfo, DynamicFieldIteratorItem, DynamicFieldKey, EpochInfo,
29    EpochInfoV1Entry, EpochInfoV2, OwnedObjectCursor, OwnedObjectIteratorItem, PackageVersionInfo,
30    PackageVersionIteratorItem, PackageVersionKey, ReadStore, TransactionInfo,
31};
32use serde::{Deserialize, Serialize};
33use serde_with::serde_as;
34pub use shared_in_memory_store::{SharedInMemoryStore, SingleCheckpointSharedInMemoryStore};
35pub use write_store::WriteStore;
36
37use crate::{
38    auth_context::AuthContext,
39    base_types::VersionNumber,
40    committee::EpochId,
41    effects::{TransactionEffectsAPI, TransactionEffectsExt},
42    error::{ExecutionError, IotaError, IotaResult},
43    execution::{DynamicallyLoadedObjectMetadata, ExecutionResults},
44    iota_sdk_types_conversions::identifier_core_to_sdk,
45    object::Object,
46    storage::error::Error as StorageError,
47    transaction::{SenderSignedTransactionAPI, TransactionAPI},
48};
49
50/// A potential input to a transaction.
51#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
52pub enum InputKey {
53    VersionedObject { id: ObjectId, version: Version },
54    Package { id: ObjectId },
55}
56
57impl InputKey {
58    pub fn id(&self) -> ObjectId {
59        match self {
60            InputKey::VersionedObject { id, .. } => *id,
61            InputKey::Package { id } => *id,
62        }
63    }
64
65    pub fn version(&self) -> Option<Version> {
66        match self {
67            InputKey::VersionedObject { version, .. } => Some(*version),
68            InputKey::Package { .. } => None,
69        }
70    }
71
72    pub fn is_cancelled(&self) -> bool {
73        match self {
74            InputKey::VersionedObject { version, .. } => version.is_canceled(),
75            InputKey::Package { .. } => false,
76        }
77    }
78}
79
80impl From<&Object> for InputKey {
81    fn from(obj: &Object) -> Self {
82        if obj.is_package() {
83            InputKey::Package { id: obj.id() }
84        } else {
85            InputKey::VersionedObject {
86                id: obj.id(),
87                version: obj.version(),
88            }
89        }
90    }
91}
92
93#[derive(Debug, PartialEq, Eq, Clone, Copy, Serialize, Deserialize)]
94pub enum DeleteKind {
95    /// An object is provided in the call input, and gets deleted.
96    Normal,
97    /// An object is not provided in the call input, but gets unwrapped
98    /// from another object, and then gets deleted.
99    UnwrapThenDelete,
100    /// An object is provided in the call input, and gets wrapped into another
101    /// object.
102    Wrap,
103}
104
105#[derive(Debug, PartialEq, Eq, Clone, Copy, Serialize, Deserialize)]
106pub enum MarkerValue {
107    /// An object was received at the given version in the transaction and is no
108    /// longer able to be received at that version in subsequent
109    /// transactions.
110    Received,
111    /// An owned object was deleted (or wrapped) at the given version, and is no
112    /// longer able to be accessed or used in subsequent transactions.
113    OwnedDeleted,
114    /// A shared object was deleted by the transaction and is no longer able to
115    /// be accessed or used in subsequent transactions.
116    SharedDeleted(TransactionDigest),
117}
118
119/// DeleteKind together with the old sequence number prior to the deletion, if
120/// available. For normal deletion and wrap, we always will consult the object
121/// store to obtain the old sequence number. For UnwrapThenDelete however,
122/// we will not consult the object store,
123/// and hence won't have the old sequence number.
124#[derive(Debug)]
125pub enum DeleteKindWithOldVersion {
126    Normal(Version),
127    UnwrapThenDelete,
128    Wrap(Version),
129}
130
131impl DeleteKindWithOldVersion {
132    pub fn old_version(&self) -> Option<Version> {
133        match self {
134            DeleteKindWithOldVersion::Normal(version) | DeleteKindWithOldVersion::Wrap(version) => {
135                Some(*version)
136            }
137            DeleteKindWithOldVersion::UnwrapThenDelete => None,
138        }
139    }
140
141    pub fn to_delete_kind(&self) -> DeleteKind {
142        match self {
143            DeleteKindWithOldVersion::Normal(_) => DeleteKind::Normal,
144            DeleteKindWithOldVersion::UnwrapThenDelete => DeleteKind::UnwrapThenDelete,
145            DeleteKindWithOldVersion::Wrap(_) => DeleteKind::Wrap,
146        }
147    }
148}
149
150#[derive(Debug)]
151pub enum ObjectChange {
152    Write(Object, WriteKind),
153    // DeleteKind together with the old sequence number prior to the deletion, if available.
154    Delete(DeleteKindWithOldVersion),
155}
156
157pub trait StorageView: Storage + ChildObjectResolver {}
158impl<T: Storage + ChildObjectResolver> StorageView for T {}
159
160/// An abstraction of the (possibly distributed) store for objects. This
161/// API only allows for the retrieval of objects, not any state changes
162pub trait ChildObjectResolver {
163    /// `child` must have an `Object` ownership equal to `parent`.
164    fn read_child_object(
165        &self,
166        parent: &ObjectId,
167        child: &ObjectId,
168        child_version_upper_bound: Version,
169    ) -> IotaResult<Option<Object>>;
170
171    /// `receiving_object_id` must have an `Address` ownership equal to
172    /// `owner`. `get_object_received_at_version` must be the exact version
173    /// at which the object will be received, and it cannot have been
174    /// previously received at that version. NB: An object not existing at
175    /// that version, and not having valid access to the object will be treated
176    /// exactly the same and `Ok(None)` must be returned.
177    fn get_object_received_at_version(
178        &self,
179        owner: &ObjectId,
180        receiving_object_id: &ObjectId,
181        receive_object_at_version: Version,
182        epoch_id: EpochId,
183    ) -> IotaResult<Option<Object>>;
184}
185
186pub struct DenyListResult {
187    /// Ok if all regulated coin owners are allowed.
188    /// Err if any regulated coin owner is denied (returning the error for first
189    /// one denied).
190    pub result: Result<(), ExecutionError>,
191    /// The number of non-gas-coin owners in the transaction results
192    pub num_non_gas_coin_owners: u64,
193}
194
195/// An abstraction of the (possibly distributed) store for objects, and (soon)
196/// events and transactions
197pub trait Storage {
198    fn reset(&mut self);
199
200    fn read_object(&self, id: &ObjectId) -> Option<&Object>;
201
202    fn record_execution_results(&mut self, results: ExecutionResults);
203
204    fn save_loaded_runtime_objects(
205        &mut self,
206        loaded_runtime_objects: BTreeMap<ObjectId, DynamicallyLoadedObjectMetadata>,
207    );
208
209    fn save_wrapped_object_containers(
210        &mut self,
211        wrapped_object_containers: BTreeMap<ObjectId, ObjectId>,
212    );
213
214    /// Check coin denylist during execution,
215    /// and the number of non-gas-coin owners.
216    fn check_coin_deny_list(&self, written_objects: &BTreeMap<ObjectId, Object>) -> DenyListResult;
217
218    /// Fails if `sender` is denied for one of `coin_types`, or one of them is
219    /// paused for every address, reading the deny list as settled before this
220    /// epoch. `coin_types` are the types of the coins the Move code received.
221    fn check_received_coin_deny_list(
222        &self,
223        sender: Address,
224        coin_types: BTreeSet<String>,
225    ) -> Result<(), ExecutionError>;
226
227    fn read_auth_context(&self) -> Option<Rc<RefCell<AuthContext>>>;
228}
229
230pub type PackageFetchResults<Package> = Result<Vec<Package>, Vec<ObjectId>>;
231
232#[derive(Clone, Debug)]
233pub struct PackageObject {
234    package_object: Object,
235}
236
237impl PackageObject {
238    pub fn new(package_object: Object) -> Self {
239        assert!(package_object.is_package());
240        Self { package_object }
241    }
242
243    pub fn object(&self) -> &Object {
244        &self.package_object
245    }
246
247    pub fn move_package(&self) -> &MovePackage {
248        self.package_object.data.as_opt_package().unwrap()
249    }
250}
251
252impl From<PackageObject> for Object {
253    fn from(package_object_arc: PackageObject) -> Self {
254        package_object_arc.package_object
255    }
256}
257
258pub trait BackingPackageStore {
259    fn get_package_object(&self, package_id: &ObjectId) -> IotaResult<Option<PackageObject>>;
260}
261
262impl<S: ?Sized + BackingPackageStore> BackingPackageStore for Box<S> {
263    fn get_package_object(&self, package_id: &ObjectId) -> IotaResult<Option<PackageObject>> {
264        BackingPackageStore::get_package_object(self.as_ref(), package_id)
265    }
266}
267
268impl<S: ?Sized + BackingPackageStore> BackingPackageStore for Arc<S> {
269    fn get_package_object(&self, package_id: &ObjectId) -> IotaResult<Option<PackageObject>> {
270        BackingPackageStore::get_package_object(self.as_ref(), package_id)
271    }
272}
273
274impl<S: ?Sized + BackingPackageStore> BackingPackageStore for &S {
275    fn get_package_object(&self, package_id: &ObjectId) -> IotaResult<Option<PackageObject>> {
276        BackingPackageStore::get_package_object(*self, package_id)
277    }
278}
279
280impl<S: ?Sized + BackingPackageStore> BackingPackageStore for &mut S {
281    fn get_package_object(&self, package_id: &ObjectId) -> IotaResult<Option<PackageObject>> {
282        BackingPackageStore::get_package_object(*self, package_id)
283    }
284}
285
286pub fn load_package_object_from_object_store(
287    store: &impl ObjectStore,
288    package_id: &ObjectId,
289) -> IotaResult<Option<PackageObject>> {
290    let package = store.try_get_object(package_id)?;
291    if let Some(obj) = &package {
292        fp_ensure!(
293            obj.is_package(),
294            IotaError::BadObjectType {
295                error: format!("Package expected, Move object found: {package_id}"),
296            }
297        );
298    }
299    Ok(package.map(PackageObject::new))
300}
301
302/// Returns Ok(<package object for each package id in `package_ids`>) if all
303/// package IDs in `package_id` were found. If any package in `package_ids` was
304/// not found it returns a list of any package ids that are unable to be
305/// found>).
306pub fn get_package_objects<'a>(
307    store: &impl BackingPackageStore,
308    package_ids: impl IntoIterator<Item = &'a ObjectId>,
309) -> IotaResult<PackageFetchResults<PackageObject>> {
310    let packages: Vec<Result<_, _>> = package_ids
311        .into_iter()
312        .map(|id| match store.get_package_object(id) {
313            Ok(None) => Ok(Err(*id)),
314            Ok(Some(o)) => Ok(Ok(o)),
315            Err(x) => Err(x),
316        })
317        .collect::<IotaResult<_>>()?;
318
319    let (fetched, failed_to_fetch): (Vec<_>, Vec<_>) = packages.into_iter().partition_result();
320    if !failed_to_fetch.is_empty() {
321        Ok(Err(failed_to_fetch))
322    } else {
323        Ok(Ok(fetched))
324    }
325}
326
327pub fn get_module(
328    store: impl BackingPackageStore,
329    module_id: &ModuleId,
330) -> Result<Option<Vec<u8>>, IotaError> {
331    Ok(store
332        .get_package_object(&ObjectId::new(module_id.address().into_bytes()))?
333        .and_then(|package| {
334            package
335                .move_package()
336                .serialized_module_map()
337                .get(&identifier_core_to_sdk(module_id.name()))
338                .cloned()
339        }))
340}
341
342pub fn get_module_by_id<S: BackingPackageStore>(
343    store: &S,
344    id: &ModuleId,
345) -> anyhow::Result<Option<CompiledModule>, IotaError> {
346    Ok(get_module(store, id)?
347        .map(|bytes| CompiledModule::deserialize_with_defaults(&bytes).unwrap()))
348}
349
350/// A `BackingPackageStore` that resolves packages from a backing store, but
351/// also includes any packages that were published in the current transaction
352/// execution. This can be used to resolve Move modules right after transaction
353/// execution, but newly published packages have not yet been committed to the
354/// backing store on a fullnode.
355pub struct PostExecutionPackageResolver {
356    backing_store: Arc<dyn BackingPackageStore>,
357    new_packages: BTreeMap<ObjectId, PackageObject>,
358}
359
360impl PostExecutionPackageResolver {
361    pub fn new(
362        backing_store: Arc<dyn BackingPackageStore>,
363        output_objects: &Option<Vec<Object>>,
364    ) -> Self {
365        let new_packages = output_objects
366            .iter()
367            .flatten()
368            .filter_map(|o| {
369                if o.is_package() {
370                    Some((o.id(), PackageObject::new(o.clone())))
371                } else {
372                    None
373                }
374            })
375            .collect();
376        Self {
377            backing_store,
378            new_packages,
379        }
380    }
381}
382
383impl BackingPackageStore for PostExecutionPackageResolver {
384    fn get_package_object(&self, package_id: &ObjectId) -> IotaResult<Option<PackageObject>> {
385        if let Some(package) = self.new_packages.get(package_id) {
386            Ok(Some(package.clone()))
387        } else {
388            self.backing_store.get_package_object(package_id)
389        }
390    }
391}
392
393impl<S: ChildObjectResolver> ChildObjectResolver for std::sync::Arc<S> {
394    fn read_child_object(
395        &self,
396        parent: &ObjectId,
397        child: &ObjectId,
398        child_version_upper_bound: Version,
399    ) -> IotaResult<Option<Object>> {
400        ChildObjectResolver::read_child_object(
401            self.as_ref(),
402            parent,
403            child,
404            child_version_upper_bound,
405        )
406    }
407    fn get_object_received_at_version(
408        &self,
409        owner: &ObjectId,
410        receiving_object_id: &ObjectId,
411        receive_object_at_version: Version,
412        epoch_id: EpochId,
413    ) -> IotaResult<Option<Object>> {
414        ChildObjectResolver::get_object_received_at_version(
415            self.as_ref(),
416            owner,
417            receiving_object_id,
418            receive_object_at_version,
419            epoch_id,
420        )
421    }
422}
423
424impl<S: ChildObjectResolver> ChildObjectResolver for &S {
425    fn read_child_object(
426        &self,
427        parent: &ObjectId,
428        child: &ObjectId,
429        child_version_upper_bound: Version,
430    ) -> IotaResult<Option<Object>> {
431        ChildObjectResolver::read_child_object(*self, parent, child, child_version_upper_bound)
432    }
433    fn get_object_received_at_version(
434        &self,
435        owner: &ObjectId,
436        receiving_object_id: &ObjectId,
437        receive_object_at_version: Version,
438        epoch_id: EpochId,
439    ) -> IotaResult<Option<Object>> {
440        ChildObjectResolver::get_object_received_at_version(
441            *self,
442            owner,
443            receiving_object_id,
444            receive_object_at_version,
445            epoch_id,
446        )
447    }
448}
449
450impl<S: ChildObjectResolver> ChildObjectResolver for &mut S {
451    fn read_child_object(
452        &self,
453        parent: &ObjectId,
454        child: &ObjectId,
455        child_version_upper_bound: Version,
456    ) -> IotaResult<Option<Object>> {
457        ChildObjectResolver::read_child_object(*self, parent, child, child_version_upper_bound)
458    }
459    fn get_object_received_at_version(
460        &self,
461        owner: &ObjectId,
462        receiving_object_id: &ObjectId,
463        receive_object_at_version: Version,
464        epoch_id: EpochId,
465    ) -> IotaResult<Option<Object>> {
466        ChildObjectResolver::get_object_received_at_version(
467            *self,
468            owner,
469            receiving_object_id,
470            receive_object_at_version,
471            epoch_id,
472        )
473    }
474}
475
476// The primary key type for object storage.
477#[serde_as]
478#[derive(Eq, PartialEq, Clone, Copy, PartialOrd, Ord, Hash, Serialize, Deserialize, Debug)]
479pub struct ObjectKey(pub ObjectId, pub VersionNumber);
480
481impl ObjectKey {
482    pub const ZERO: ObjectKey = ObjectKey(ObjectId::ZERO, VersionNumber::MIN_VALID_INCL);
483
484    pub fn max_for_id(id: &ObjectId) -> Self {
485        Self(*id, VersionNumber::MAX_VALID_EXCL)
486    }
487
488    pub fn min_for_id(id: &ObjectId) -> Self {
489        Self(*id, VersionNumber::MIN_VALID_INCL)
490    }
491}
492
493impl From<ObjectReference> for ObjectKey {
494    fn from(object_ref: ObjectReference) -> Self {
495        ObjectKey::from(&object_ref)
496    }
497}
498
499impl From<&ObjectReference> for ObjectKey {
500    fn from(object_ref: &ObjectReference) -> Self {
501        Self(object_ref.object_id, object_ref.version)
502    }
503}
504
505#[derive(Clone)]
506pub enum ObjectOrTombstone {
507    Object(Object),
508    Tombstone(ObjectReference),
509}
510
511impl ObjectOrTombstone {
512    pub fn as_objref(&self) -> ObjectReference {
513        match self {
514            ObjectOrTombstone::Object(obj) => obj.object_ref(),
515            ObjectOrTombstone::Tombstone(obref) => *obref,
516        }
517    }
518}
519
520impl From<Object> for ObjectOrTombstone {
521    fn from(object: Object) -> Self {
522        ObjectOrTombstone::Object(object)
523    }
524}
525
526/// Fetch the `ObjectKey`s (IDs and versions) for non-shared input objects.
527/// Includes owned, and immutable objects as well as the gas objects, but not
528/// move packages or shared objects.
529pub fn transaction_non_shared_input_object_keys(
530    tx: &SenderSignedTransaction,
531) -> IotaResult<Vec<ObjectKey>> {
532    use crate::transaction::InputObjectKind as I;
533    Ok(tx
534        .input_objects()?
535        .into_iter()
536        .filter_map(|object| match object {
537            I::MovePackage(_) | I::SharedMoveObject { .. } => None,
538            I::ImmOrOwnedMoveObject(obj) => Some(obj.into()),
539        })
540        .collect())
541}
542
543pub fn transaction_receiving_object_keys(tx: &SenderSignedTransaction) -> Vec<ObjectKey> {
544    tx.transaction()
545        .receiving_objects()
546        .into_iter()
547        .map(|oref| oref.into())
548        .collect()
549}
550
551impl Display for DeleteKind {
552    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
553        match self {
554            DeleteKind::Wrap => write!(f, "Wrap"),
555            DeleteKind::Normal => write!(f, "Normal"),
556            DeleteKind::UnwrapThenDelete => write!(f, "UnwrapThenDelete"),
557        }
558    }
559}
560
561pub trait BackingStore: BackingPackageStore + ChildObjectResolver + ObjectStore {
562    fn as_object_store(&self) -> &dyn ObjectStore;
563}
564
565impl<T> BackingStore for T
566where
567    T: BackingPackageStore,
568    T: ChildObjectResolver,
569    T: ObjectStore,
570{
571    fn as_object_store(&self) -> &dyn ObjectStore {
572        self
573    }
574}
575
576pub fn get_transaction_input_objects(
577    object_store: &dyn ObjectStore,
578    effects: &TransactionEffects,
579) -> Result<Vec<Object>, StorageError> {
580    let input_object_keys = effects
581        .modified_at_versions()
582        .into_iter()
583        .map(|modified| ObjectKey(*modified.object_id(), modified.version()))
584        .collect::<Vec<_>>();
585
586    let input_objects = object_store
587        .multi_get_objects_by_key(&input_object_keys)
588        .into_iter()
589        .enumerate()
590        .map(|(idx, maybe_object)| {
591            maybe_object.ok_or_else(|| {
592                StorageError::missing(format!(
593                    "missing input object key {:?} from tx {}",
594                    input_object_keys[idx],
595                    effects.transaction_digest()
596                ))
597            })
598        })
599        .collect::<Result<Vec<_>, _>>()?;
600    Ok(input_objects)
601}
602
603pub fn get_transaction_output_objects(
604    object_store: &dyn ObjectStore,
605    effects: &TransactionEffects,
606) -> Result<Vec<Object>, StorageError> {
607    let output_object_keys = effects
608        .all_changed_objects()
609        .into_iter()
610        .map(|(changed, _kind)| ObjectKey::from(*changed.reference()))
611        .collect::<Vec<_>>();
612
613    let output_objects = object_store
614        .multi_get_objects_by_key(&output_object_keys)
615        .into_iter()
616        .enumerate()
617        .map(|(idx, maybe_object)| {
618            maybe_object.ok_or_else(|| {
619                StorageError::missing(format!(
620                    "missing output object key {:?} from tx {}",
621                    output_object_keys[idx],
622                    effects.transaction_digest()
623                ))
624            })
625        })
626        .collect::<Result<Vec<_>, _>>()?;
627    Ok(output_objects)
628}
629
630/// Extend a simulation's input objects with the runtime-loaded objects the
631/// effects record as modified, read from `object_store` at their pre-state
632/// versions.
633pub fn extend_input_objects_with_loaded_runtime_objects(
634    input_objects: &mut BTreeMap<ObjectId, Object>,
635    effects: &TransactionEffects,
636    loaded_runtime_objects: &BTreeMap<ObjectId, DynamicallyLoadedObjectMetadata>,
637    object_store: &dyn ObjectStore,
638) {
639    let modified_at: BTreeMap<_, _> = effects
640        .modified_at_versions()
641        .into_iter()
642        .map(|modified| (*modified.object_id(), modified.version()))
643        .collect();
644    for (id, metadata) in loaded_runtime_objects {
645        if input_objects.contains_key(id) || modified_at.get(id) != Some(&metadata.version) {
646            continue;
647        }
648        if let Some(object) = object_store.get_object_by_key(id, metadata.version) {
649            input_objects.insert(*id, object);
650        }
651    }
652}
iota_types/storage/mod.rs

iota_types/storage/
mod.rs
