Skip to main content

iota_graphql_rpc/types/
object.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::{
6    collections::{BTreeMap, BTreeSet, HashMap},
7    fmt::Write,
8};
9
10use async_graphql::{
11    connection::{Connection, CursorType, Edge},
12    dataloader::Loader,
13    *,
14};
15use diesel::{BoolExpressionMethods, ExpressionMethods, QueryDsl, SelectableHelper, sql_types};
16use iota_indexer::{
17    ingestion::common::CommitterTables,
18    models::objects::{StoredHistoryObject, StoredObject},
19    pruning::oldest_available_checkpoint::OldestAvailableCheckpoint,
20    schema::objects,
21    types::{ObjectStatus as NativeObjectStatus, OwnerType},
22};
23use iota_sdk_types::{
24    MoveStruct as NativeMoveStruct, ObjectId, Owner as NativeOwner, StructTag, TypeTag, Version,
25};
26use iota_types::object::{Object as NativeObject, bounded_visitor::BoundedVisitor};
27use move_core_types::annotated_value::{MoveStruct, MoveTypeLayout};
28use serde::{Deserialize, Serialize};
29
30use crate::{
31    backward_view::{HistoricalFilter, consistent, historical},
32    config::DEFAULT_PAGE_SIZE,
33    consistency::{Checkpointed, UNAVAILABLE_CHECKPOINT_SEQUENCE_NUMBER},
34    data::{DataLoader, Db, DbConnection, QueryExecutor, package_resolver::PackageResolver},
35    error::Error,
36    filter, or_filter,
37    raw_query::RawQuery,
38    types::{
39        available_range::AvailableRange,
40        balance::{self, Balance},
41        base64::Base64,
42        big_int::BigInt,
43        coin::Coin,
44        coin_metadata::CoinMetadata,
45        cursor::{self, Page, RawPaginated, ScanLimited, Target},
46        digest::Digest,
47        display::{Display, DisplayEntry},
48        dynamic_field::{DynamicField, DynamicFieldName},
49        intersect,
50        iota_address::{IotaAddress, addr},
51        iota_names_registration::{NameFormat, NameRegistration},
52        move_object::MoveObject,
53        move_package::MovePackage,
54        owner::{Owner, OwnerImpl},
55        stake::StakedIota,
56        transaction_block::{
57            self, TransactionBlock, TransactionBlockConnection, TransactionBlockFilter,
58        },
59        type_filter::{ExactTypeFilter, TypeFilter},
60        uint53::UInt53,
61    },
62};
63
64#[derive(Clone, Debug)]
65pub(crate) struct Object {
66    pub address: IotaAddress,
67    pub inner: ActiveObject,
68    /// The checkpoint sequence number at which this was viewed at.
69    pub checkpoint_viewed_at: u64,
70    /// Root parent object version for dynamic fields.
71    ///
72    /// This enables consistent dynamic field reads in the case of chained
73    /// dynamic object fields, e.g., `Parent -> DOF1 -> DOF2`. In such
74    /// cases, the object versions may end up like `Parent >= DOF1, DOF2`
75    /// but `DOF1 < DOF2`. Thus, database queries for dynamic fields must
76    /// bound the object versions by the version of the root object of the tree.
77    ///
78    /// Essentially, lamport timestamps of objects are updated for all top-level
79    /// mutable objects provided as inputs to a transaction as well as any
80    /// mutated dynamic child objects. However, any dynamic child objects
81    /// that were loaded but not actually mutated don't end up having
82    /// their versions updated.
83    root_version: u64,
84}
85
86/// Type to implement GraphQL fields that are shared by all Objects.
87pub(crate) struct ObjectImpl<'o>(pub &'o Object);
88
89#[derive(Clone, Debug)]
90pub(crate) struct ActiveObject {
91    /// The deserialized object.
92    native: NativeObject,
93    /// Where the object's state was read from.
94    status: ObjectStatus,
95    /// The serialized object as stored in the index. `None` for `NotIndexed`
96    /// objects.
97    ///
98    /// Avoids the re-serialization of `native` for `Indexed` objects.
99    bcs: Option<Vec<u8>>,
100}
101
102#[derive(Enum, Copy, Clone, Eq, PartialEq, Debug)]
103#[graphql(name = "ObjectKind")]
104pub enum ObjectStatus {
105    /// The object is loaded from serialized data, such as the contents of a
106    /// transaction that hasn't been indexed yet.
107    NotIndexed,
108    /// The object is fetched from the index.
109    Indexed,
110}
111
112#[derive(Clone, Debug, PartialEq, Eq, InputObject)]
113pub(crate) struct ObjectRef {
114    /// ID of the object.
115    pub address: IotaAddress,
116    /// Version or sequence number of the object.
117    pub version: UInt53,
118    /// Digest of the object.
119    pub digest: Digest,
120}
121
122/// Constrains the set of objects returned. All filters are optional, and the
123/// resulting set of objects are ones whose
124///
125/// - Type matches the `type` filter,
126/// - AND, whose owner matches the `owner` filter,
127/// - AND, whose ID is in `objectIds` OR whose ID and version is in `objectKeys`.
128#[derive(InputObject, Default, Debug, Clone, Eq, PartialEq)]
129pub(crate) struct ObjectFilter {
130    /// Filter objects by their type's `package`, `package::module`, or their
131    /// fully qualified type name.
132    ///
133    /// Generic types can be queried by either the generic type name, e.g.
134    /// `0x2::coin::Coin`, or by the full type name, such as
135    /// `0x2::coin::Coin<0x2::iota::IOTA>`.
136    pub type_: Option<TypeFilter>,
137
138    /// Filter for live objects by their current owners.
139    pub owner: Option<IotaAddress>,
140
141    /// Filter for live objects by their IDs.
142    pub object_ids: Option<Vec<IotaAddress>>,
143
144    /// Filter for live or potentially historical objects by their ID and
145    /// version.
146    pub object_keys: Option<Vec<ObjectKey>>,
147}
148
149#[derive(InputObject, Debug, Clone, Eq, PartialEq)]
150pub(crate) struct ObjectKey {
151    pub object_id: IotaAddress,
152    pub version: UInt53,
153}
154
155/// The object's owner type: Immutable, Shared, Parent, or Address.
156#[derive(Union, Clone)]
157pub(crate) enum ObjectOwner {
158    Immutable(Immutable),
159    Shared(Shared),
160    Parent(Box<Parent>),
161    Address(AddressOwner),
162}
163
164/// An immutable object is an object that can't be mutated, transferred, or
165/// deleted. Immutable objects have no owner, so anyone can use them.
166#[derive(SimpleObject, Clone)]
167pub(crate) struct Immutable {
168    #[graphql(name = "_")]
169    dummy: Option<bool>,
170}
171
172/// A shared object is an object that is shared using the
173/// 0x2::transfer::share_object function. Unlike owned objects, once an object
174/// is shared, it stays mutable and is accessible by anyone.
175#[derive(SimpleObject, Clone)]
176pub(crate) struct Shared {
177    initial_shared_version: UInt53,
178}
179
180/// If the object's owner is a Parent, this object is part of a dynamic field
181/// (it is the value of the dynamic field, or the intermediate Field object
182/// itself). Also note that if the owner is a parent, then it's guaranteed to be
183/// an object.
184#[derive(SimpleObject, Clone)]
185pub(crate) struct Parent {
186    parent: Option<Object>,
187}
188
189/// An address-owned object is owned by a specific 32-byte address that is
190/// either an account address (derived from a particular signature scheme) or
191/// an object ID. An address-owned object is accessible only to its owner and no
192/// others.
193#[derive(SimpleObject, Clone)]
194pub(crate) struct AddressOwner {
195    owner: Option<Owner>,
196}
197
198/// Filter for a point query of an Object.
199pub(crate) enum ObjectLookup {
200    LatestAt {
201        /// The checkpoint sequence number at which this was viewed at.
202        checkpoint_viewed_at: u64,
203    },
204
205    UnderParent {
206        /// The parent version to be used as an upper bound for the query. Look
207        /// for the latest version of a child object whose version is
208        /// less than or equal to this upper bound.
209        parent_version: u64,
210        /// The checkpoint sequence number at which this was viewed at.
211        checkpoint_viewed_at: u64,
212    },
213
214    VersionAt {
215        /// The exact version of the object to be fetched.
216        version: u64,
217        /// The checkpoint sequence number at which this was viewed at.
218        checkpoint_viewed_at: u64,
219    },
220
221    /// Variant analogous to [`VersionAt`](Self::VersionAt) but for optimistic
222    /// transactions, using the most recent not checkpointed data,
223    /// not bound by any checkpoint sequence number.
224    OptimisticVersion {
225        /// The exact version of the object to be fetched.
226        version: u64,
227    },
228}
229
230pub(crate) type Cursor = cursor::BcsCursor<HistoricalObjectCursor>;
231
232/// The inner struct for the `Object`'s cursor. The `(object_id,
233/// object_version)` pair is used as the cursor, to be able to paginate requests
234/// for multiple versions of the same object, while the `checkpoint_viewed_at`
235/// sets the consistent upper bound for the cursor.
236#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug)]
237pub(crate) struct HistoricalObjectCursor {
238    #[serde(rename = "o")]
239    object_id: Vec<u8>,
240    /// The version of the object this cursor points at.
241    #[serde(rename = "v")]
242    object_version: UInt53,
243    /// The checkpoint sequence number this was viewed at.
244    #[serde(rename = "c")]
245    checkpoint_viewed_at: UInt53,
246}
247
248/// Interface implemented by on-chain values that are addressable by an ID (also
249/// referred to as its address). This includes Move objects and packages.
250#[expect(clippy::duplicated_attributes)]
251#[derive(Interface)]
252#[graphql(
253    name = "IObject",
254    field(name = "version", ty = "UInt53"),
255    field(
256        name = "status",
257        ty = "ObjectStatus",
258        desc = r#"
259            The current status of the object as read from the off-chain store. The
260            possible states are:
261            - NOT_INDEXED: The object is loaded from serialized data, such as the
262            contents of a genesis or system package upgrade transaction.
263            - INDEXED: The object is retrieved from the off-chain index and
264            represents the most recent or historical state of the object.
265        "#
266    ),
267    field(
268        name = "digest",
269        ty = "Option<String>",
270        desc = "32-byte hash that identifies the object's current contents, encoded as a Base58 \
271                string."
272    ),
273    field(
274        name = "owner",
275        ty = "Option<ObjectOwner>",
276        desc = "The owner type of this object: Immutable, Shared, Parent, Address\n\
277                Immutable and Shared Objects do not have owners."
278    ),
279    field(
280        name = "previous_transaction_block",
281        ty = "Option<TransactionBlock>",
282        desc = "The transaction block that created this version of the object."
283    ),
284    field(name = "storage_rebate", ty = "Option<BigInt>", desc = "",),
285    field(
286        name = "received_transaction_blocks",
287        arg(name = "first", ty = "Option<u64>"),
288        arg(name = "after", ty = "Option<transaction_block::Cursor>"),
289        arg(name = "last", ty = "Option<u64>"),
290        arg(name = "before", ty = "Option<transaction_block::Cursor>"),
291        arg(name = "filter", ty = "Option<TransactionBlockFilter>"),
292        arg(
293            name = "scan_limit",
294            ty = "Option<u64>",
295            deprecation = "`scanLimit` will be removed with v1.38, along with the support for combining complex filters."
296        ),
297        ty = "TransactionBlockConnection",
298        desc = "The transaction blocks that sent objects to this object."
299    ),
300    field(
301        name = "bcs",
302        ty = "Option<Base64>",
303        desc = "The Base64-encoded BCS serialization of the object's content."
304    )
305)]
306pub(crate) enum IObject {
307    Object(Object),
308    MovePackage(MovePackage),
309    MoveObject(MoveObject),
310    Coin(Coin),
311    CoinMetadata(CoinMetadata),
312    StakedIota(StakedIota),
313}
314
315/// `DataLoader` key for fetching an `Object` at a specific version, constrained
316/// by a consistency cursor (if that version was created after the checkpoint
317/// the query is viewing at, then it will fail).
318#[derive(Copy, Clone, Hash, Eq, PartialEq, Debug)]
319struct HistoricalKey {
320    id: IotaAddress,
321    version: u64,
322    checkpoint_viewed_at: u64,
323}
324
325/// `DataLoader` key for fetching objects that haven't been checkpointed yet.
326/// This is used specifically for loading objects
327/// that are part of optimistic transaction effects.
328#[derive(Copy, Clone, Hash, Eq, PartialEq, Debug)]
329struct OptimisticKey {
330    id: IotaAddress,
331    version: u64,
332}
333
334/// `DataLoader` key for fetching the latest version of an object whose parent
335/// object has version `parent_version`, as of `checkpoint_viewed_at`. This
336/// look-up can fail to find a valid object if the key is not self-consistent,
337/// for example if the `parent_version` is set to a higher version
338/// than the object's actual parent as of `checkpoint_viewed_at`.
339#[derive(Copy, Clone, Hash, Eq, PartialEq, Debug)]
340struct ParentVersionKey {
341    id: IotaAddress,
342    parent_version: u64,
343    checkpoint_viewed_at: u64,
344}
345
346/// `DataLoader` key for fetching the latest version of an object as of a given
347/// checkpoint.
348#[derive(Copy, Clone, Hash, Eq, PartialEq, Debug)]
349struct LatestAtKey {
350    id: IotaAddress,
351    checkpoint_viewed_at: u64,
352}
353
354/// An object in IOTA is a package (set of Move bytecode modules) or object
355/// (typed data structure with fields) with additional metadata detailing its
356/// id, version, transaction digest, owner field indicating how this object can
357/// be accessed.
358#[Object]
359impl Object {
360    pub(crate) async fn address(&self) -> IotaAddress {
361        OwnerImpl::from(self).address().await
362    }
363
364    /// Objects owned by this object, optionally `filter`-ed.
365    pub(crate) async fn objects(
366        &self,
367        ctx: &Context<'_>,
368        first: Option<u64>,
369        after: Option<Cursor>,
370        last: Option<u64>,
371        before: Option<Cursor>,
372        filter: Option<ObjectFilter>,
373    ) -> Result<Connection<String, MoveObject>> {
374        OwnerImpl::from(self)
375            .objects(ctx, first, after, last, before, filter)
376            .await
377    }
378
379    /// Total balance of all coins with marker type owned by this object. If
380    /// type is not supplied, it defaults to `0x2::iota::IOTA`.
381    pub(crate) async fn balance(
382        &self,
383        ctx: &Context<'_>,
384        type_: Option<ExactTypeFilter>,
385    ) -> Result<Option<Balance>> {
386        OwnerImpl::from(self).balance(ctx, type_).await
387    }
388
389    /// The balances of all coin types owned by this object.
390    pub(crate) async fn balances(
391        &self,
392        ctx: &Context<'_>,
393        first: Option<u64>,
394        after: Option<balance::Cursor>,
395        last: Option<u64>,
396        before: Option<balance::Cursor>,
397    ) -> Result<Connection<String, Balance>> {
398        OwnerImpl::from(self)
399            .balances(ctx, first, after, last, before)
400            .await
401    }
402
403    /// The coin objects for this object.
404    ///
405    /// `type` is a filter on the coin's type parameter, defaulting to
406    /// `0x2::iota::IOTA`.
407    pub(crate) async fn coins(
408        &self,
409        ctx: &Context<'_>,
410        first: Option<u64>,
411        after: Option<Cursor>,
412        last: Option<u64>,
413        before: Option<Cursor>,
414        type_: Option<ExactTypeFilter>,
415    ) -> Result<Connection<String, Coin>> {
416        OwnerImpl::from(self)
417            .coins(ctx, first, after, last, before, type_)
418            .await
419    }
420
421    /// The `0x3::staking_pool::StakedIota` objects owned by this object.
422    pub(crate) async fn staked_iotas(
423        &self,
424        ctx: &Context<'_>,
425        first: Option<u64>,
426        after: Option<Cursor>,
427        last: Option<u64>,
428        before: Option<Cursor>,
429    ) -> Result<Connection<String, StakedIota>> {
430        OwnerImpl::from(self)
431            .staked_iotas(ctx, first, after, last, before)
432            .await
433    }
434
435    /// The name explicitly configured as the default name pointing to this
436    /// address.
437    pub(crate) async fn iota_names_default_name(
438        &self,
439        ctx: &Context<'_>,
440        format: Option<NameFormat>,
441    ) -> Result<Option<String>> {
442        OwnerImpl::from(self)
443            .iota_names_default_name(ctx, format)
444            .await
445    }
446
447    /// The NameRegistration NFTs owned by this address. These grant the
448    /// owner the capability to manage the associated name.
449    pub(crate) async fn iota_names_registrations(
450        &self,
451        ctx: &Context<'_>,
452        first: Option<u64>,
453        after: Option<Cursor>,
454        last: Option<u64>,
455        before: Option<Cursor>,
456    ) -> Result<Connection<String, NameRegistration>> {
457        OwnerImpl::from(self)
458            .iota_names_registrations(ctx, first, after, last, before)
459            .await
460    }
461
462    pub(crate) async fn version(&self) -> Result<UInt53> {
463        ObjectImpl(self).version().await
464    }
465
466    /// The current status of the object as read from the off-chain store. The
467    /// possible states are:
468    /// - NOT_INDEXED: The object is loaded from serialized data, such as the contents of a genesis
469    ///   or system package upgrade transaction.
470    /// - INDEXED: The object is retrieved from the off-chain index and represents the most recent
471    ///   or historical state of the object.
472    pub(crate) async fn status(&self) -> ObjectStatus {
473        ObjectImpl(self).status().await
474    }
475
476    /// 32-byte hash that identifies the object's current contents, encoded as a
477    /// Base58 string.
478    pub(crate) async fn digest(&self) -> Option<String> {
479        ObjectImpl(self).digest().await
480    }
481
482    /// The owner type of this object: Immutable, Shared, Parent, Address
483    /// Immutable and Shared Objects do not have owners.
484    pub(crate) async fn owner(&self, ctx: &Context<'_>) -> Result<Option<ObjectOwner>> {
485        ObjectImpl(self).owner(ctx).await
486    }
487
488    /// The transaction block that created this version of the object.
489    pub(crate) async fn previous_transaction_block(
490        &self,
491        ctx: &Context<'_>,
492    ) -> Result<Option<TransactionBlock>> {
493        ObjectImpl(self).previous_transaction_block(ctx).await
494    }
495
496    /// The amount of IOTA we would rebate if this object gets deleted or
497    /// mutated. This number is recalculated based on the present storage
498    /// gas price.
499    pub(crate) async fn storage_rebate(&self) -> Option<BigInt> {
500        ObjectImpl(self).storage_rebate().await
501    }
502
503    /// The transaction blocks that sent objects to this object.
504    ///
505    /// `scanLimit` restricts the number of candidate transactions scanned when
506    /// gathering a page of results. It is required for queries that apply two
507    /// or more complex filters (on function, affected address, recipient, input
508    /// object, changed object, or wrapped or deleted object), and can be at
509    /// most `serviceConfig.maxScanLimit`. A `kind` filter cannot be
510    /// combined with any of them.
511    ///
512    /// When the scan limit is reached the page will be returned even if it has
513    /// fewer than `first` results when paginating forward (`last` when
514    /// paginating backwards). If there are more transactions to scan,
515    /// `pageInfo.hasNextPage` (or `pageInfo.hasPreviousPage`) will be set to
516    /// `true`, and `PageInfo.endCursor` (or `PageInfo.startCursor`) will be set
517    /// to the last transaction that was scanned as opposed to the last (or
518    /// first) transaction in the page.
519    ///
520    /// Requesting the next (or previous) page after this cursor will resume the
521    /// search, scanning the next `scanLimit` many transactions in the
522    /// direction of pagination, and so on until all transactions in the
523    /// scanning range have been visited.
524    ///
525    /// By default, the scanning range includes all transactions known to
526    /// GraphQL, but it can be restricted by the `after` and `before`
527    /// cursors, and the `beforeCheckpoint`, `afterCheckpoint` and
528    /// `atCheckpoint` filters.
529    ///
530    /// DEPRECATION NOTICE: Support for the combination of two or more complex
531    /// filters as discussed above will stop with the v1.38 release. `scanLimit`
532    /// will thus become obsolete and will be removed as well.
533    #[graphql(
534        complexity = "first.or(last).unwrap_or(DEFAULT_PAGE_SIZE as u64) as usize * child_complexity"
535    )]
536    pub(crate) async fn received_transaction_blocks(
537        &self,
538        ctx: &Context<'_>,
539        first: Option<u64>,
540        after: Option<transaction_block::Cursor>,
541        last: Option<u64>,
542        before: Option<transaction_block::Cursor>,
543        filter: Option<TransactionBlockFilter>,
544        #[graphql(
545            deprecation = "`scanLimit` will be removed with v1.38, along with the support for combining complex filters."
546        )]
547        scan_limit: Option<u64>,
548    ) -> Result<TransactionBlockConnection> {
549        ObjectImpl(self)
550            .received_transaction_blocks(ctx, first, after, last, before, filter, scan_limit)
551            .await
552    }
553
554    /// The Base64-encoded BCS serialization of the object's content.
555    pub(crate) async fn bcs(&self) -> Result<Option<Base64>> {
556        ObjectImpl(self).bcs().await
557    }
558
559    /// The set of named templates defined on-chain for the type of this object,
560    /// to be handled off-chain. The server substitutes data from the object
561    /// into these templates to generate a display string per template.
562    async fn display(&self, ctx: &Context<'_>) -> Result<Option<Vec<DisplayEntry>>> {
563        ObjectImpl(self).display(ctx).await
564    }
565
566    /// Access a dynamic field on an object using its name. Names are arbitrary
567    /// Move values whose type have `copy`, `drop`, and `store`, and are
568    /// specified using their type, and their BCS contents, Base64 encoded.
569    ///
570    /// Dynamic fields on wrapped objects can be accessed by using the same API
571    /// under the Owner type.
572    async fn dynamic_field(
573        &self,
574        ctx: &Context<'_>,
575        name: DynamicFieldName,
576    ) -> Result<Option<DynamicField>> {
577        OwnerImpl::from(self)
578            .dynamic_field(ctx, name, Some(self.root_version()))
579            .await
580    }
581
582    /// Access a dynamic object field on an object using its name. Names are
583    /// arbitrary Move values whose type have `copy`, `drop`, and `store`,
584    /// and are specified using their type, and their BCS contents, Base64
585    /// encoded. The value of a dynamic object field can also be accessed
586    /// off-chain directly via its address (e.g. using `Query.object`).
587    ///
588    /// Dynamic fields on wrapped objects can be accessed by using the same API
589    /// under the Owner type.
590    async fn dynamic_object_field(
591        &self,
592        ctx: &Context<'_>,
593        name: DynamicFieldName,
594    ) -> Result<Option<DynamicField>> {
595        OwnerImpl::from(self)
596            .dynamic_object_field(ctx, name, Some(self.root_version()))
597            .await
598    }
599
600    /// The dynamic fields and dynamic object fields on an object.
601    ///
602    /// Dynamic fields on wrapped objects can be accessed by using the same API
603    /// under the Owner type.
604    async fn dynamic_fields(
605        &self,
606        ctx: &Context<'_>,
607        first: Option<u64>,
608        after: Option<Cursor>,
609        last: Option<u64>,
610        before: Option<Cursor>,
611    ) -> Result<Connection<String, DynamicField>> {
612        OwnerImpl::from(self)
613            .dynamic_fields(ctx, first, after, last, before, Some(self.root_version()))
614            .await
615    }
616
617    /// Attempts to convert the object into a MoveObject
618    async fn as_move_object(&self) -> Option<MoveObject> {
619        MoveObject::try_from(self).ok()
620    }
621
622    /// Attempts to convert the object into a MovePackage
623    async fn as_move_package(&self) -> Option<MovePackage> {
624        MovePackage::try_from(self).ok()
625    }
626}
627
628impl ObjectImpl<'_> {
629    pub(crate) async fn version(&self) -> Result<UInt53> {
630        UInt53::try_from(self.0.version_impl()).extend()
631    }
632
633    pub(crate) async fn status(&self) -> ObjectStatus {
634        ObjectStatus::from(&self.0.inner)
635    }
636
637    pub(crate) async fn digest(&self) -> Option<String> {
638        Some(self.0.native_impl().digest().to_base58())
639    }
640
641    pub(crate) async fn owner(&self, ctx: &Context<'_>) -> Result<Option<ObjectOwner>> {
642        use NativeOwner as O;
643
644        let native = self.0.native_impl();
645
646        match native.owner {
647            O::Address(address) => {
648                let address = IotaAddress::from(address);
649                Ok(Some(ObjectOwner::Address(AddressOwner {
650                    owner: Some(Owner {
651                        address,
652                        checkpoint_viewed_at: self.0.checkpoint_viewed_at,
653                        root_version: None,
654                    }),
655                })))
656            }
657            O::Immutable => Ok(Some(ObjectOwner::Immutable(Immutable { dummy: None }))),
658            O::Object(address) => {
659                let parent = Object::query(
660                    ctx,
661                    address.into(),
662                    Object::under_parent(self.0.root_version, self.0.checkpoint_viewed_at),
663                )
664                .await
665                .ok()
666                .flatten();
667
668                Ok(Some(ObjectOwner::Parent(Box::new(Parent { parent }))))
669            }
670            O::Shared(initial_shared_version) => Ok(Some(ObjectOwner::Shared(Shared {
671                initial_shared_version: UInt53::try_from(initial_shared_version.as_u64())
672                    .extend()?,
673            }))),
674            _ => Err(Error::Internal(
675                "unknown Owner variant in object owner".to_string(),
676            ))
677            .extend(),
678        }
679    }
680
681    pub(crate) async fn previous_transaction_block(
682        &self,
683        ctx: &Context<'_>,
684    ) -> Result<Option<TransactionBlock>> {
685        let native = self.0.native_impl();
686        let digest = native.previous_transaction;
687        let key = transaction_block::DigestKey::new(digest.into(), self.0.checkpoint_viewed_at);
688
689        TransactionBlock::query(ctx, key).await.extend()
690    }
691
692    pub(crate) async fn storage_rebate(&self) -> Option<BigInt> {
693        Some(self.0.native_impl().storage_rebate.into())
694    }
695
696    pub(crate) async fn received_transaction_blocks(
697        &self,
698        ctx: &Context<'_>,
699        first: Option<u64>,
700        after: Option<transaction_block::Cursor>,
701        last: Option<u64>,
702        before: Option<transaction_block::Cursor>,
703        filter: Option<TransactionBlockFilter>,
704        scan_limit: Option<u64>,
705    ) -> Result<TransactionBlockConnection> {
706        let page = Page::from_params(ctx.data_unchecked(), first, after, last, before)?;
707
708        let Some(filter) = filter
709            .unwrap_or_default()
710            .intersect(TransactionBlockFilter {
711                recv_address: Some(self.0.address),
712                ..Default::default()
713            })
714        else {
715            return Ok(TransactionBlockConnection::new(false, false));
716        };
717
718        TransactionBlock::paginate(ctx, page, filter, self.0.checkpoint_viewed_at, scan_limit)
719            .await
720            .extend()
721    }
722
723    pub(crate) async fn bcs(&self) -> Result<Option<Base64>> {
724        let inner = &self.0.inner;
725        Ok(match &inner.bcs {
726            Some(serialized) => Some(Base64::from(serialized)),
727
728            None => {
729                let bytes = bcs::to_bytes(&inner.native)
730                    .map_err(|e| {
731                        Error::Internal(format!(
732                            "Failed to serialize object at {}: {e}",
733                            self.0.address
734                        ))
735                    })
736                    .extend()?;
737                Some(Base64::from(&bytes))
738            }
739        })
740    }
741
742    /// `display` is part of the `IMoveObject` interface, but is implemented on
743    /// `ObjectImpl` to allow for a convenience function on `Object`.
744    pub(crate) async fn display(&self, ctx: &Context<'_>) -> Result<Option<Vec<DisplayEntry>>> {
745        let native = self.0.native_impl();
746
747        let move_object = native
748            .data
749            .as_opt_struct()
750            .ok_or_else(|| Error::Internal("Failed to convert object into MoveObject".to_string()))
751            .extend()?;
752
753        let (struct_tag, move_struct) = deserialize_move_struct(move_object, ctx.data_unchecked())
754            .await
755            .extend()?;
756
757        let Some(display) = Display::query(ctx.data_unchecked(), struct_tag.into())
758            .await
759            .extend()?
760        else {
761            return Ok(None);
762        };
763
764        Ok(Some(display.render(&move_struct).extend()?))
765    }
766}
767
768impl Object {
769    /// The oldest checkpoint an object at a given version is available from:
770    /// the value reported on `DATA_PRUNED`. The fallback serves both the
771    /// version and the content.
772    pub(crate) fn oldest_available_checkpoint_at_version(db: &Db) -> OldestAvailableCheckpoint {
773        OldestAvailableCheckpoint::for_tables(
774            &db.inner,
775            &[
776                CommitterTables::ObjectsVersion,
777                CommitterTables::ObjectsBackwardHistory,
778            ],
779            true,
780        )
781    }
782
783    /// The oldest checkpoint the latest version of an object at or below a
784    /// parent version is available from: the value reported on `DATA_PRUNED`.
785    /// The version comes from `objects_version` in the database only, as the
786    /// fallback keeps no version history and cannot pick it. The fallback
787    /// serves the content.
788    pub(crate) fn oldest_available_checkpoint_under_parent(db: &Db) -> OldestAvailableCheckpoint {
789        OldestAvailableCheckpoint::for_tables(&db.inner, &[CommitterTables::ObjectsVersion], false)
790            .max(OldestAvailableCheckpoint::for_tables(
791                &db.inner,
792                &[CommitterTables::ObjectsBackwardHistory],
793                true,
794            ))
795    }
796
797    /// Construct a GraphQL object from a native object, without its stored
798    /// (indexed) counterpart.
799    ///
800    /// `checkpoint_viewed_at` represents the checkpoint sequence number at
801    /// which this `Object` was constructed in. This is stored on `Object`
802    /// so that when viewing that entity's state, it will be as if it was
803    /// read at the same checkpoint.
804    ///
805    /// `root_version` represents the version of the root object in some nested
806    /// chain of dynamic fields. This should typically be left `None`,
807    /// unless the object(s) being resolved is a dynamic field, or if
808    /// `root_version` has been explicitly set for this object. If None, then
809    /// we use [`version_for_dynamic_fields`] to infer a root version to then
810    /// propagate from this object down to its dynamic fields.
811    pub(crate) fn from_native(
812        address: IotaAddress,
813        native: NativeObject,
814        checkpoint_viewed_at: u64,
815        root_version: Option<u64>,
816    ) -> Object {
817        let root_version = root_version.unwrap_or_else(|| version_for_dynamic_fields(&native));
818        Object {
819            address,
820            inner: ActiveObject {
821                native,
822                status: ObjectStatus::NotIndexed,
823                bcs: None,
824            },
825            checkpoint_viewed_at,
826            root_version,
827        }
828    }
829
830    pub(crate) fn native_impl(&self) -> &NativeObject {
831        &self.inner.native
832    }
833
834    pub(crate) fn version_impl(&self) -> u64 {
835        self.native_impl().version().as_u64()
836    }
837
838    /// Root parent object version for dynamic fields.
839    ///
840    /// Check [`Object::root_version`] for details.
841    pub(crate) fn root_version(&self) -> u64 {
842        self.root_version
843    }
844
845    /// Query the database for a `page` of objects, optionally `filter`-ed.
846    ///
847    /// `checkpoint_viewed_at` represents the checkpoint sequence number at
848    /// which this page was queried for. Each entity returned in the
849    /// connection will inherit this checkpoint, so that when viewing that
850    /// entity's state, it will be as if it was read at the same checkpoint.
851    pub(crate) async fn paginate(
852        db: &Db,
853        page: Page<Cursor>,
854        filter: ObjectFilter,
855        checkpoint_viewed_at: u64,
856    ) -> Result<Connection<String, Object>, Error> {
857        Self::paginate_subtype(db, page, filter, checkpoint_viewed_at, Ok).await
858    }
859
860    /// Query the database for a `page` of some sub-type of Object. The page
861    /// uses the bytes of an Object ID, the object version and the checkpoint
862    /// when the query was made as the cursor, and can optionally be further
863    /// `filter`-ed. The subtype is created using the `downcast` function,
864    /// which is allowed to fail, if the downcast has failed.
865    ///
866    /// `checkpoint_viewed_at` represents the checkpoint sequence number at
867    /// which this page was queried for. Each entity returned in the
868    /// connection will inherit this checkpoint, so that when viewing that
869    /// entity's state, it will be as if it was read at the same checkpoint.
870    ///
871    /// If a `Page<Cursor>` is also provided, then this function will defer to
872    /// the `checkpoint_viewed_at` in the cursors. Otherwise, use the value
873    /// from the parameter, or set to None. This is so that paginated
874    /// queries are consistent with the previous query that created the
875    /// cursor.
876    pub(crate) async fn paginate_subtype<T: OutputType>(
877        db: &Db,
878        page: Page<Cursor>,
879        filter: ObjectFilter,
880        checkpoint_viewed_at: u64,
881        downcast: impl Fn(Object) -> Result<T, Error>,
882    ) -> Result<Connection<String, T>, Error> {
883        // If cursors are provided, defer to the `checkpoint_viewed_at` in the cursor if
884        // they are consistent. Otherwise, use the value from the parameter, or
885        // set to None. This is so that paginated queries are consistent with
886        // the previous query that created the cursor.
887        let cursor_viewed_at = page.validate_cursor_consistency()?;
888        let checkpoint_viewed_at = cursor_viewed_at.unwrap_or(checkpoint_viewed_at);
889
890        let max_available_range = db.max_available_range;
891
892        let Some((prev, next, results)) = db
893            .execute_repeatable(move |conn| {
894                if !AvailableRange::is_checkpoint_in_backward_history_range(
895                    conn,
896                    checkpoint_viewed_at,
897                    max_available_range,
898                )? {
899                    return Ok::<_, diesel::result::Error>(None);
900                };
901
902                let (prev, next, results_iter) = page.paginate_raw_query::<StoredBackwardObject>(
903                    conn,
904                    checkpoint_viewed_at,
905                    backward_objects_query(&filter, checkpoint_viewed_at, &page),
906                )?;
907                let results: Vec<StoredBackwardObject> = results_iter.collect();
908                Ok(Some((prev, next, results)))
909            })
910            .await?
911        else {
912            return Err(Error::Client(
913                "Requested data is outside the available range".to_string(),
914            ));
915        };
916
917        let mut conn: Connection<String, T> = Connection::new(prev, next);
918
919        for stored in results {
920            // To maintain consistency, the returned cursor should have the same upper-bound
921            // as the checkpoint found on the cursor.
922            let cursor = stored.cursor(checkpoint_viewed_at).encode_cursor();
923            let stored_history = stored.into_stored_history(checkpoint_viewed_at);
924            let active_object = ActiveObject::try_from(stored_history)?;
925            let object = Object::from_active_object(active_object, checkpoint_viewed_at, None);
926            conn.edges.push(Edge::new(cursor, downcast(object)?));
927        }
928
929        Ok(conn)
930    }
931
932    /// Look-up the latest version of the object as of a given checkpoint.
933    pub(crate) fn latest_at(checkpoint_viewed_at: u64) -> ObjectLookup {
934        ObjectLookup::LatestAt {
935            checkpoint_viewed_at,
936        }
937    }
938
939    /// Look-up the latest version of an object whose version is less than or
940    /// equal to its parent's version, as of a given checkpoint.
941    pub(crate) fn under_parent(parent_version: u64, checkpoint_viewed_at: u64) -> ObjectLookup {
942        ObjectLookup::UnderParent {
943            parent_version,
944            checkpoint_viewed_at,
945        }
946    }
947
948    /// Look-up a specific version of the object, as of a given checkpoint.
949    pub(crate) fn at_version(version: u64, checkpoint_viewed_at: u64) -> ObjectLookup {
950        ObjectLookup::VersionAt {
951            version,
952            checkpoint_viewed_at,
953        }
954    }
955
956    /// Look-up a specific version of the object from optimistic transactions.
957    pub(crate) fn at_optimistic_version(version: u64) -> ObjectLookup {
958        ObjectLookup::OptimisticVersion { version }
959    }
960
961    pub(crate) async fn query(
962        ctx: &Context<'_>,
963        id: IotaAddress,
964        key: ObjectLookup,
965    ) -> Result<Option<Self>, Error> {
966        let DataLoader(loader) = &ctx.data_unchecked();
967
968        match key {
969            ObjectLookup::VersionAt {
970                version,
971                checkpoint_viewed_at,
972            } => loader
973                .load_one(HistoricalKey {
974                    id,
975                    version,
976                    checkpoint_viewed_at,
977                })
978                .await?
979                .transpose(),
980
981            ObjectLookup::OptimisticVersion { version } => loader
982                .load_one(OptimisticKey { id, version })
983                .await?
984                .transpose(),
985
986            ObjectLookup::UnderParent {
987                parent_version,
988                checkpoint_viewed_at,
989            } => loader
990                .load_one(ParentVersionKey {
991                    id,
992                    parent_version,
993                    checkpoint_viewed_at,
994                })
995                .await?
996                .transpose(),
997
998            ObjectLookup::LatestAt {
999                checkpoint_viewed_at,
1000            } => {
1001                loader
1002                    .load_one(LatestAtKey {
1003                        id,
1004                        checkpoint_viewed_at,
1005                    })
1006                    .await
1007            }
1008        }
1009    }
1010
1011    /// Query for a singleton object identified by its type. Note: the object is
1012    /// assumed to be a singleton (we either find at least one object with
1013    /// this type and then return it, or return nothing).
1014    pub(crate) async fn query_singleton(
1015        db: &Db,
1016        type_: StructTag,
1017        checkpoint_viewed_at: u64,
1018    ) -> Result<Option<Object>, Error> {
1019        let filter = ObjectFilter {
1020            type_: Some(TypeFilter::ByType(type_)),
1021            ..Default::default()
1022        };
1023
1024        let connection = Self::paginate(db, Page::bounded(1), filter, checkpoint_viewed_at).await?;
1025
1026        Ok(connection.edges.into_iter().next().map(|edge| edge.node))
1027    }
1028
1029    /// Builds an `Object` from an active object, viewed at
1030    /// `checkpoint_viewed_at`.
1031    ///
1032    /// `checkpoint_viewed_at` represents the checkpoint sequence number at
1033    /// which this `Object` was constructed in. This is stored on `Object`
1034    /// so that when viewing that entity's state, it will be as if it was
1035    /// read at the same checkpoint.
1036    ///
1037    /// `root_version` represents the version of the root object in some nested
1038    /// chain of dynamic fields. This should typically be left `None`,
1039    /// unless the object(s) being resolved is a dynamic field, or if
1040    /// `root_version` has been explicitly set for this object. If None, then
1041    /// we use [`version_for_dynamic_fields`] to infer a root version to then
1042    /// propagate from this object down to its dynamic fields.
1043    pub(crate) fn from_active_object(
1044        active_object: ActiveObject,
1045        checkpoint_viewed_at: u64,
1046        root_version: Option<u64>,
1047    ) -> Self {
1048        let address = IotaAddress::from(active_object.native.id());
1049        let root_version =
1050            root_version.unwrap_or_else(|| version_for_dynamic_fields(&active_object.native));
1051        Self {
1052            address,
1053            inner: active_object,
1054            checkpoint_viewed_at,
1055            root_version,
1056        }
1057    }
1058
1059    pub(crate) fn try_from_stored_object(
1060        stored_object: StoredObject,
1061        checkpoint_viewed_at: u64,
1062        root_version: Option<u64>,
1063    ) -> Result<Self, Error> {
1064        let active_object = ActiveObject {
1065            native: NativeObject::try_from(&stored_object)?,
1066            status: ObjectStatus::Indexed,
1067            bcs: Some(stored_object.serialized_object),
1068        };
1069        Ok(Self::from_active_object(
1070            active_object,
1071            checkpoint_viewed_at,
1072            root_version,
1073        ))
1074    }
1075}
1076
1077impl TryFrom<StoredHistoryObject> for ActiveObject {
1078    type Error = Error;
1079
1080    /// Builds a value from an active stored history row by
1081    /// deserializing its native object.
1082    ///
1083    /// # Errors
1084    ///
1085    /// Fails in the following cases:
1086    ///
1087    /// - The row is not active (a wrapped or deleted tombstone, or an unrecognized status).
1088    /// - The row has no serialized object, or it fails to deserialize.
1089    fn try_from(stored: StoredHistoryObject) -> Result<Self, Self::Error> {
1090        if !matches!(
1091            NativeObjectStatus::try_from(stored.object_status),
1092            Ok(NativeObjectStatus::Active)
1093        ) {
1094            return Err(Error::Internal(format!(
1095                "Expected active object 0x{} at version {}, but found status {}",
1096                hex::encode(&stored.object_id),
1097                stored.object_version,
1098                stored.object_status,
1099            )));
1100        }
1101
1102        let native = NativeObject::try_from(&stored)?;
1103        Ok(ActiveObject {
1104            native,
1105            status: ObjectStatus::Indexed,
1106            bcs: stored.serialized_object,
1107        })
1108    }
1109}
1110
1111/// We're deliberately choosing to use a child object's version as the root
1112/// here, and letting the caller override it with the actual root object's
1113/// version if it has access to it.
1114///
1115/// Using the child object's version as the root means that we're seeing the
1116/// dynamic field tree under this object at the state resulting from the
1117/// transaction that produced this version.
1118///
1119/// See [`Object::root_version`] for more details on parent/child object version
1120/// mechanics.
1121fn version_for_dynamic_fields(native: &NativeObject) -> u64 {
1122    native.as_inner().version().as_u64()
1123}
1124
1125impl ObjectFilter {
1126    /// Try to create a filter whose results are the intersection of objects in
1127    /// `self`'s results and objects in `other`'s results. This may not be
1128    /// possible if the resulting filter is inconsistent in some way (e.g. a
1129    /// filter that requires one field to be two different values
1130    /// simultaneously).
1131    pub(crate) fn intersect(self, other: ObjectFilter) -> Option<Self> {
1132        macro_rules! intersect {
1133            ($field:ident, $body:expr) => {
1134                intersect::field(self.$field, other.$field, $body)
1135            };
1136        }
1137
1138        // Treat `object_ids` and `object_keys` as a single filter on IDs, and
1139        // optionally versions, and compute the intersection of that.
1140        let keys = intersect::field(self.keys(), other.keys(), |k, l| {
1141            let mut combined = BTreeMap::new();
1142
1143            for (id, v) in k {
1144                if let Some(w) = l.get(&id).copied() {
1145                    combined.insert(id, intersect::field(v, w, intersect::by_eq)?);
1146                }
1147            }
1148
1149            // If the intersection is empty, it means, there were some ID or Key filters in
1150            // both `self` and `other`, but they don't overlap, so the final
1151            // result is inconsistent.
1152            (!combined.is_empty()).then_some(combined)
1153        })?;
1154
1155        // Extract the ID and Key filters back out. At this point, we know that if there
1156        // were ID/Key filters in both `self` and `other`, then they intersected
1157        // to form a consistent set of constraints, so it is safe to interpret
1158        // the lack of any ID/Key filters respectively as a lack of that kind of
1159        // constraint, rather than a constraint on the empty set.
1160
1161        let object_ids = {
1162            let partition: Vec<_> = keys
1163                .iter()
1164                .flatten()
1165                .filter_map(|(id, v)| v.is_none().then_some(*id))
1166                .collect();
1167
1168            (!partition.is_empty()).then_some(partition)
1169        };
1170
1171        let object_keys = {
1172            let partition: Vec<_> = keys
1173                .iter()
1174                .flatten()
1175                .filter_map(|(id, v)| {
1176                    Some(ObjectKey {
1177                        object_id: *id,
1178                        version: (*v)?,
1179                    })
1180                })
1181                .collect();
1182
1183            (!partition.is_empty()).then_some(partition)
1184        };
1185
1186        Some(Self {
1187            type_: intersect!(type_, TypeFilter::intersect)?,
1188            owner: intersect!(owner, intersect::by_eq)?,
1189            object_ids,
1190            object_keys,
1191        })
1192    }
1193
1194    /// Extract the Object ID and Key filters into one combined map from Object
1195    /// IDs in this filter, to the versions they should have (or None if the
1196    /// filter mentions the ID but no version for it).
1197    fn keys(&self) -> Option<BTreeMap<IotaAddress, Option<UInt53>>> {
1198        if self.object_keys.is_none() && self.object_ids.is_none() {
1199            return None;
1200        }
1201
1202        Some(BTreeMap::from_iter(
1203            self.object_keys
1204                .iter()
1205                .flatten()
1206                .map(|key| (key.object_id, Some(key.version)))
1207                // Chain ID filters after Key filters so if there is overlap, we overwrite the key
1208                // filter with the ID filter.
1209                .chain(self.object_ids.iter().flatten().map(|id| (*id, None))),
1210        ))
1211    }
1212
1213    /// Applies ObjectFilter to the input `RawQuery` and returns a new
1214    /// `RawQuery`.
1215    pub(crate) fn apply(&self, mut query: RawQuery) -> RawQuery {
1216        // Start by applying the filters on IDs and/or keys because they are combined as
1217        // a disjunction, while the remaining queries are conjunctions.
1218        if let Some(object_ids) = &self.object_ids {
1219            // Maximally strict - match a vec of 0 elements
1220            if object_ids.is_empty() {
1221                query = or_filter!(query, "1=0");
1222            } else {
1223                let mut inner = String::new();
1224                let mut prefix = "object_id IN (";
1225                for id in object_ids {
1226                    // SAFETY: Writing to a `String` cannot fail.
1227                    write!(
1228                        &mut inner,
1229                        "{prefix}'\\x{}'::bytea",
1230                        hex::encode(id.into_vec())
1231                    )
1232                    .unwrap();
1233                    prefix = ", ";
1234                }
1235                inner.push(')');
1236                query = or_filter!(query, inner);
1237            }
1238        }
1239
1240        if let Some(object_keys) = &self.object_keys {
1241            // Maximally strict - match a vec of 0 elements
1242            if object_keys.is_empty() {
1243                query = or_filter!(query, "1=0");
1244            } else {
1245                let mut inner = String::new();
1246                let mut prefix = "(";
1247                for ObjectKey { object_id, version } in object_keys {
1248                    // SAFETY: Writing to a `String` cannot fail.
1249                    write!(
1250                        &mut inner,
1251                        "{prefix}(object_id = '\\x{}'::bytea AND object_version = {})",
1252                        hex::encode(object_id.into_vec()),
1253                        version
1254                    )
1255                    .unwrap();
1256                    prefix = " OR ";
1257                }
1258                inner.push(')');
1259                query = or_filter!(query, inner);
1260            }
1261        }
1262
1263        if let Some(owner) = self.owner {
1264            query = filter!(
1265                query,
1266                format!(
1267                    "owner_id = '\\x{}'::bytea AND owner_type = {}",
1268                    hex::encode(owner.into_vec()),
1269                    OwnerType::Address as i16
1270                )
1271            );
1272        }
1273
1274        if let Some(type_) = &self.type_ {
1275            return type_.apply_raw(
1276                query,
1277                "object_type",
1278                "object_type_package",
1279                "object_type_module",
1280                "object_type_name",
1281            );
1282        }
1283
1284        query
1285    }
1286}
1287
1288impl HistoricalObjectCursor {
1289    pub(crate) fn new(object_id: Vec<u8>, object_version: u64, checkpoint_viewed_at: u64) -> Self {
1290        Self {
1291            object_id,
1292            object_version: UInt53::new_unchecked(object_version),
1293            checkpoint_viewed_at: UInt53::new_unchecked(checkpoint_viewed_at),
1294        }
1295    }
1296}
1297
1298impl Checkpointed for Cursor {
1299    fn checkpoint_viewed_at(&self) -> u64 {
1300        self.checkpoint_viewed_at.into()
1301    }
1302}
1303
1304impl ScanLimited for Cursor {}
1305
1306/// Query-result struct for the backward diff read path. Used by
1307/// `build_backward_objects_query` which unions `checkpointed_objects` and
1308/// `objects_backward_history`. Has explicit `sql_type` annotations because
1309/// there is no single backing Diesel table definition.
1310#[derive(diesel::QueryableByName, Clone, Debug)]
1311pub(crate) struct StoredBackwardObject {
1312    #[diesel(sql_type = sql_types::Binary)]
1313    pub object_id: Vec<u8>,
1314    #[diesel(sql_type = sql_types::BigInt)]
1315    pub object_version: i64,
1316    #[diesel(sql_type = sql_types::SmallInt)]
1317    pub object_status: i16,
1318    #[diesel(sql_type = sql_types::Nullable<sql_types::Binary>)]
1319    pub object_digest: Option<Vec<u8>>,
1320    #[diesel(sql_type = sql_types::Nullable<sql_types::SmallInt>)]
1321    pub owner_type: Option<i16>,
1322    #[diesel(sql_type = sql_types::Nullable<sql_types::Binary>)]
1323    pub owner_id: Option<Vec<u8>>,
1324    #[diesel(sql_type = sql_types::Nullable<sql_types::Text>)]
1325    pub object_type: Option<String>,
1326    #[diesel(sql_type = sql_types::Nullable<sql_types::Binary>)]
1327    pub object_type_package: Option<Vec<u8>>,
1328    #[diesel(sql_type = sql_types::Nullable<sql_types::Text>)]
1329    pub object_type_module: Option<String>,
1330    #[diesel(sql_type = sql_types::Nullable<sql_types::Text>)]
1331    pub object_type_name: Option<String>,
1332    #[diesel(sql_type = sql_types::Nullable<sql_types::Binary>)]
1333    pub serialized_object: Option<Vec<u8>>,
1334    #[diesel(sql_type = sql_types::Nullable<sql_types::Text>)]
1335    pub coin_type: Option<String>,
1336    #[diesel(sql_type = sql_types::Nullable<sql_types::BigInt>)]
1337    pub coin_balance: Option<i64>,
1338    #[diesel(sql_type = sql_types::Nullable<sql_types::SmallInt>)]
1339    pub df_kind: Option<i16>,
1340}
1341
1342impl StoredBackwardObject {
1343    /// Convert into a `StoredHistoryObject`, filling in
1344    /// `checkpoint_sequence_number` with the checkpoint the object was
1345    /// viewed at. The backward diff query guarantees the result is valid at
1346    /// this checkpoint, so it's the most accurate value we have.
1347    pub(crate) fn into_stored_history(self, checkpoint_viewed_at: u64) -> StoredHistoryObject {
1348        StoredHistoryObject {
1349            object_id: self.object_id,
1350            object_version: self.object_version,
1351            object_status: self.object_status,
1352            object_digest: self.object_digest,
1353            checkpoint_sequence_number: checkpoint_viewed_at as i64,
1354            owner_type: self.owner_type,
1355            owner_id: self.owner_id,
1356            object_type: self.object_type,
1357            object_type_package: self.object_type_package,
1358            object_type_module: self.object_type_module,
1359            object_type_name: self.object_type_name,
1360            serialized_object: self.serialized_object,
1361            coin_type: self.coin_type,
1362            coin_balance: self.coin_balance,
1363            df_kind: self.df_kind,
1364        }
1365    }
1366}
1367
1368impl RawPaginated<Cursor> for StoredBackwardObject {
1369    // Returns rows greater or equal to (object_id, object_version). Equivalent to
1370    // `ROW(object_id, object_version) >= ROW(X, V)` and to
1371    // `object_id > X OR (object_id = X AND object_version >= V)`, but the `ROW`
1372    // form is slow when `object_keys` is used, and the `OR` form is slow when it
1373    // is not.
1374    fn filter_ge(cursor: &Cursor, query: RawQuery) -> RawQuery {
1375        let id = hex::encode(cursor.object_id.clone());
1376        filter!(
1377            query,
1378            format!(
1379                "candidates.object_id >= '\\x{id}'::bytea AND \
1380                 (candidates.object_id > '\\x{id}'::bytea OR candidates.object_version >= {})",
1381                cursor.object_version
1382            )
1383        )
1384    }
1385
1386    fn filter_le(cursor: &Cursor, query: RawQuery) -> RawQuery {
1387        let id = hex::encode(cursor.object_id.clone());
1388        filter!(
1389            query,
1390            format!(
1391                "candidates.object_id <= '\\x{id}'::bytea AND \
1392                 (candidates.object_id < '\\x{id}'::bytea OR candidates.object_version <= {})",
1393                cursor.object_version
1394            )
1395        )
1396    }
1397
1398    fn order(asc: bool, query: RawQuery) -> RawQuery {
1399        if asc {
1400            query
1401                .order_by("candidates.object_id ASC")
1402                .order_by("candidates.object_version ASC")
1403        } else {
1404            query
1405                .order_by("candidates.object_id DESC")
1406                .order_by("candidates.object_version DESC")
1407        }
1408    }
1409}
1410
1411impl Target<Cursor> for StoredBackwardObject {
1412    fn cursor(&self, checkpoint_viewed_at: u64) -> Cursor {
1413        Cursor::new(HistoricalObjectCursor::new(
1414            self.object_id.clone(),
1415            self.object_version as u64,
1416            checkpoint_viewed_at,
1417        ))
1418    }
1419}
1420
1421/// Synthetic `object_status` for object versions that still exist in
1422/// `objects_version` table, but are already pruned from
1423/// `objects_backward_history`.
1424const OBJECT_STATUS_PRUNED: i16 = -1;
1425
1426const OBJECT_STATUS_WRAPPED_OR_DELETED: i16 = NativeObjectStatus::WrappedOrDeleted as i16;
1427
1428const OBJECT_STATUS_ACTIVE: i16 = NativeObjectStatus::Active as i16;
1429
1430/// Supplies the parameters needed to build an [`Object`] from a row fetched
1431/// from the historical fallback: the checkpoint it is viewed at, and the root
1432/// version to record on it.
1433trait FallbackObjectKey: Eq + std::hash::Hash {
1434    /// The checkpoint the object is viewed at.
1435    fn checkpoint_viewed_at(&self) -> u64;
1436    /// The root version to record on the resulting object, if any.
1437    fn root_version(&self) -> Option<u64>;
1438}
1439
1440impl FallbackObjectKey for HistoricalKey {
1441    fn checkpoint_viewed_at(&self) -> u64 {
1442        self.checkpoint_viewed_at
1443    }
1444    fn root_version(&self) -> Option<u64> {
1445        None
1446    }
1447}
1448
1449impl FallbackObjectKey for ParentVersionKey {
1450    fn checkpoint_viewed_at(&self) -> u64 {
1451        self.checkpoint_viewed_at
1452    }
1453    fn root_version(&self) -> Option<u64> {
1454        Some(self.parent_version)
1455    }
1456}
1457
1458/// Fills the missing `results` entries with objects fetched from the
1459/// historical fallback.
1460///
1461/// It stores nothing when the object does not exist at the requested version
1462/// (e.g. when the object is wrapped or deleted). It stores
1463/// [`Error::DataPruned`] reporting `oldest_available_checkpoint` per key when
1464/// the historical fallback is not configured.
1465async fn fill_missing_objects_from_fallback<K: FallbackObjectKey>(
1466    db: &Db,
1467    keys_with_refs: Vec<(K, (ObjectId, Version))>,
1468    oldest_available_checkpoint: OldestAvailableCheckpoint,
1469    results: &mut HashMap<K, Result<Object, Error>>,
1470) -> Result<(), Error> {
1471    if keys_with_refs.is_empty() {
1472        return Ok(());
1473    }
1474
1475    let object_refs: Vec<(ObjectId, Version)> =
1476        keys_with_refs.iter().map(|(_, obj_ref)| *obj_ref).collect();
1477
1478    let fetched: Vec<Result<Option<StoredObject>, Error>> = if db.inner.is_fallback_enabled() {
1479        db.inner
1480            .multi_get_fallback_objects(&object_refs, false)
1481            .await
1482            .map_err(Error::from)?
1483            .into_iter()
1484            .map(Ok)
1485            .collect()
1486    } else {
1487        object_refs
1488            .iter()
1489            .map(|(id, _)| {
1490                Err(Error::DataPruned {
1491                    message: format!("data for object {id} potentially pruned"),
1492                    oldest_available_checkpoint,
1493                })
1494            })
1495            .collect()
1496    };
1497
1498    for ((key, _), fetched) in keys_with_refs.into_iter().zip(fetched) {
1499        match fetched {
1500            Ok(Some(stored)) => {
1501                let object = Object::try_from_stored_object(
1502                    stored,
1503                    key.checkpoint_viewed_at(),
1504                    key.root_version(),
1505                )?;
1506                results.insert(key, Ok(object));
1507            }
1508            // The object does not exist at the requested version.
1509            Ok(None) => {}
1510            // Only this key cannot be served.
1511            Err(e) => {
1512                results.insert(key, Err(e));
1513            }
1514        }
1515    }
1516
1517    Ok(())
1518}
1519
1520impl Loader<HistoricalKey> for Db {
1521    /// Error stored per key, e.g. when object version is pruned.
1522    type Value = Result<Object, Error>;
1523    type Error = Error;
1524
1525    async fn load(
1526        &self,
1527        keys: &[HistoricalKey],
1528    ) -> Result<HashMap<HistoricalKey, Result<Object, Error>>, Error> {
1529        if keys.is_empty() {
1530            return Ok(HashMap::new());
1531        }
1532
1533        let (ids, versions): (Vec<Vec<u8>>, Vec<i64>) = keys
1534            .iter()
1535            .map(|key| (key.id.into_vec(), key.version as i64))
1536            .collect::<BTreeSet<_>>()
1537            .into_iter()
1538            .unzip();
1539
1540        // For each `(object_id, object_version)` pair, locate the row content
1541        // in `checkpointed_objects` (current state of the object) or
1542        // `objects_backward_history` (a superseded prior state). The
1543        // `objects_version` join confirms the version is real and supplies the
1544        // checkpoint at which it became current.
1545        //
1546        // A row is returned for every version found in `objects_version`.
1547        // Wrapped-or-deleted status is reported for versions without row
1548        // content that are in the retention window of
1549        // `objects_backward_history`. Versions outside of this retention
1550        // window are returned with the synthetic `OBJECT_STATUS_PRUNED`
1551        // status.
1552        let sql = "SELECT \
1553                v.object_id, \
1554                v.object_version, \
1555                v.cp_sequence_number AS checkpoint_sequence_number, \
1556                COALESCE(co.object_status, bh.object_status, \
1557                    CASE WHEN v.cp_sequence_number >= COALESCE((\
1558                        SELECT min_available_cp FROM watermarks \
1559                        WHERE entity = 'objects_backward_history'), 0) \
1560                    THEN $3 ELSE $4 END) AS object_status, \
1561                COALESCE(co.object_digest, bh.object_digest) AS object_digest, \
1562                COALESCE(co.owner_type, bh.owner_type) AS owner_type, \
1563                COALESCE(co.owner_id, bh.owner_id) AS owner_id, \
1564                COALESCE(co.object_type, bh.object_type) AS object_type, \
1565                COALESCE(co.object_type_package, bh.object_type_package) AS object_type_package, \
1566                COALESCE(co.object_type_module, bh.object_type_module) AS object_type_module, \
1567                COALESCE(co.object_type_name, bh.object_type_name) AS object_type_name, \
1568                COALESCE(co.serialized_object, bh.serialized_object) AS serialized_object, \
1569                COALESCE(co.coin_type, bh.coin_type) AS coin_type, \
1570                COALESCE(co.coin_balance, bh.coin_balance) AS coin_balance, \
1571                COALESCE(co.df_kind, bh.df_kind) AS df_kind \
1572            FROM unnest($1::bytea[], $2::bigint[]) AS pairs(object_id, object_version) \
1573            INNER JOIN objects_version v \
1574                    ON v.object_id = pairs.object_id \
1575                   AND v.object_version = pairs.object_version \
1576            LEFT JOIN checkpointed_objects co \
1577                   ON co.object_id = v.object_id \
1578                  AND co.object_version = v.object_version \
1579            LEFT JOIN objects_backward_history bh \
1580                   ON bh.object_id = v.object_id \
1581                  AND bh.object_version = v.object_version";
1582
1583        let objects: Vec<StoredHistoryObject> = self
1584            .execute(move |conn| {
1585                conn.results(move || {
1586                    diesel::sql_query(sql)
1587                        .bind::<sql_types::Array<sql_types::Binary>, _>(ids.clone())
1588                        .bind::<sql_types::Array<sql_types::BigInt>, _>(versions.clone())
1589                        .bind::<sql_types::SmallInt, _>(OBJECT_STATUS_WRAPPED_OR_DELETED)
1590                        .bind::<sql_types::SmallInt, _>(OBJECT_STATUS_PRUNED)
1591                })
1592            })
1593            .await
1594            .map_err(|e| Error::Internal(format!("Failed to fetch objects: {e}")))?;
1595
1596        let mut id_version_to_stored = BTreeMap::new();
1597        for stored in objects {
1598            let key = (addr(&stored.object_id)?, stored.object_version as u64);
1599            id_version_to_stored.insert(key, stored);
1600        }
1601
1602        let mut result = HashMap::new();
1603        let mut fallback_keys = Vec::new();
1604        // Keys with no `objects_version` entry at all.
1605        let mut unresolved_keys = Vec::new();
1606        for key in keys {
1607            let Some(stored) = id_version_to_stored.get(&(key.id, key.version)) else {
1608                unresolved_keys.push(*key);
1609                continue;
1610            };
1611
1612            // Filter by key's checkpoint viewed at here. Doing this in memory because it
1613            // should be quite rare that this query actually filters something,
1614            // but encoding it in SQL is complicated.
1615            if key.checkpoint_viewed_at < stored.checkpoint_sequence_number as u64 {
1616                continue;
1617            }
1618
1619            let active_object = match stored.object_status {
1620                OBJECT_STATUS_PRUNED => {
1621                    fallback_keys.push(*key);
1622                    continue;
1623                }
1624                OBJECT_STATUS_ACTIVE => ActiveObject::try_from(stored.clone())?,
1625                // Wrapped, deleted, or not yet created: resolve as non-existent.
1626                _ => continue,
1627            };
1628            // This conversion will use the object's own version as the
1629            // `Object::root_version`.
1630            let object = Object::from_active_object(active_object, key.checkpoint_viewed_at, None);
1631            result.insert(*key, Ok(object));
1632        }
1633
1634        // When version history is complete, unresolved key = nonexisting object
1635        // version. When history is incomplete we have to query the KV to know
1636        // if object exists or not.
1637        if self.inner.is_pruned(CommitterTables::ObjectsVersion) {
1638            fallback_keys.append(&mut unresolved_keys);
1639        }
1640
1641        let keys_with_refs = fallback_keys
1642            .into_iter()
1643            .map(|key| (key, (key.id.into(), Version::from(key.version))))
1644            .collect();
1645        fill_missing_objects_from_fallback(
1646            self,
1647            keys_with_refs,
1648            Object::oldest_available_checkpoint_at_version(self),
1649            &mut result,
1650        )
1651        .await?;
1652
1653        Ok(result)
1654    }
1655}
1656
1657impl Loader<OptimisticKey> for Db {
1658    /// Error stored per key, e.g. when object version is pruned.
1659    type Value = Result<Object, Error>;
1660    type Error = Error;
1661
1662    async fn load(
1663        &self,
1664        keys: &[OptimisticKey],
1665    ) -> Result<HashMap<OptimisticKey, Result<Object, Error>>, Error> {
1666        use objects::dsl as o;
1667
1668        if keys.is_empty() {
1669            return Ok(HashMap::new());
1670        }
1671
1672        let id_versions: BTreeSet<_> = keys
1673            .iter()
1674            .map(|key| (key.id.into_vec(), key.version as i64))
1675            .collect();
1676
1677        let objects: Vec<StoredObject> = self
1678            .execute(move |conn| {
1679                conn.results(move || {
1680                    let mut query = o::objects.select(StoredObject::as_select()).into_boxed();
1681                    for (id, version) in id_versions.iter().cloned() {
1682                        query =
1683                            query.or_filter(o::object_id.eq(id).and(o::object_version.eq(version)));
1684                    }
1685                    query
1686                })
1687            })
1688            .await
1689            .map_err(|e| Error::Internal(format!("Failed to fetch optimistic objects: {e}")))?;
1690
1691        let mut result = HashMap::new();
1692        let id_version_to_stored = objects
1693            .into_iter()
1694            .map(|stored| {
1695                addr(&stored.object_id).map(|id| ((id, stored.object_version as u64), stored))
1696            })
1697            .collect::<Result<BTreeMap<_, _>, _>>()?;
1698
1699        // Collect keys that were not found in objects table
1700        let mut missing_keys = Vec::new();
1701        for key in keys {
1702            if let Some(stored) = id_version_to_stored.get(&(key.id, key.version)) {
1703                let object = Object::try_from_stored_object(
1704                    stored.clone(),
1705                    UNAVAILABLE_CHECKPOINT_SEQUENCE_NUMBER,
1706                    None,
1707                )?;
1708                result.insert(*key, Ok(object));
1709            } else {
1710                missing_keys.push(*key);
1711            }
1712        }
1713
1714        // For missing keys, fallback to the backward-history loader
1715        if !missing_keys.is_empty() {
1716            let historical_keys: Vec<HistoricalKey> = missing_keys
1717                .iter()
1718                .map(|key| HistoricalKey {
1719                    id: key.id,
1720                    version: key.version,
1721                    checkpoint_viewed_at: UNAVAILABLE_CHECKPOINT_SEQUENCE_NUMBER,
1722                })
1723                .collect();
1724
1725            let historical_result: HashMap<HistoricalKey, Result<Object, Error>> =
1726                self.load(&historical_keys).await?;
1727
1728            for (historical_key, object) in historical_result {
1729                let optimistic_key = OptimisticKey {
1730                    id: historical_key.id,
1731                    version: historical_key.version,
1732                };
1733                result.insert(optimistic_key, object);
1734            }
1735        }
1736
1737        Ok(result)
1738    }
1739}
1740
1741impl Loader<ParentVersionKey> for Db {
1742    /// Error stored per key, e.g. when object version is pruned.
1743    type Value = Result<Object, Error>;
1744    type Error = Error;
1745
1746    async fn load(
1747        &self,
1748        keys: &[ParentVersionKey],
1749    ) -> Result<HashMap<ParentVersionKey, Result<Object, Error>>, Error> {
1750        // Group keys by checkpoint viewed at and parent version -- we'll issue a
1751        // separate query for each group.
1752        #[derive(Eq, PartialEq, Ord, PartialOrd, Clone, Copy)]
1753        struct GroupKey {
1754            checkpoint_viewed_at: u64,
1755            parent_version: u64,
1756        }
1757
1758        let mut keys_by_cursor_and_parent_version: BTreeMap<_, BTreeSet<_>> = BTreeMap::new();
1759        for key in keys {
1760            let group_key = GroupKey {
1761                checkpoint_viewed_at: key.checkpoint_viewed_at,
1762                parent_version: key.parent_version,
1763            };
1764
1765            keys_by_cursor_and_parent_version
1766                .entry(group_key)
1767                .or_default()
1768                .insert(key.id.into_vec());
1769        }
1770
1771        // For each id, pick the largest version `≤ parent_version` from
1772        // `objects_version` (versions table contains all current and past versions of
1773        // objects), then locate the row content in `checkpointed_objects`
1774        // (current state of the object) or `objects_backward_history` (a
1775        // superseded prior state).
1776        //
1777        // A row is returned for the largest version `≤ parent_version` found
1778        // in `objects_version`. Wrapped-or-deleted status is reported for
1779        // versions without row content that are in the retention window of
1780        // `objects_backward_history`. Versions outside of this retention
1781        // window are returned with the synthetic `OBJECT_STATUS_PRUNED`
1782        // status.
1783        let sql = "WITH ids AS (SELECT unnest($1::bytea[]) AS object_id), \
1784                        latest_per_id AS (\
1785                       SELECT i.object_id, o.object_version, o.cp_sequence_number \
1786                       FROM ids i \
1787                       JOIN LATERAL (\
1788                           SELECT object_version, cp_sequence_number \
1789                           FROM objects_version \
1790                           WHERE object_id = i.object_id \
1791                             AND object_version <= $2::bigint \
1792                           ORDER BY object_version DESC \
1793                           LIMIT 1) o ON TRUE) \
1794                   SELECT \
1795                       v.object_id, \
1796                       v.object_version, \
1797                       v.cp_sequence_number AS checkpoint_sequence_number, \
1798                       COALESCE(co.object_status, bh.object_status, \
1799                           CASE WHEN v.cp_sequence_number >= COALESCE((\
1800                               SELECT min_available_cp FROM watermarks \
1801                               WHERE entity = 'objects_backward_history'), 0) \
1802                           THEN $3 ELSE $4 END) AS object_status, \
1803                       COALESCE(co.object_digest, bh.object_digest) AS object_digest, \
1804                       COALESCE(co.owner_type, bh.owner_type) AS owner_type, \
1805                       COALESCE(co.owner_id, bh.owner_id) AS owner_id, \
1806                       COALESCE(co.object_type, bh.object_type) AS object_type, \
1807                       COALESCE(co.object_type_package, bh.object_type_package) AS object_type_package, \
1808                       COALESCE(co.object_type_module, bh.object_type_module) AS object_type_module, \
1809                       COALESCE(co.object_type_name, bh.object_type_name) AS object_type_name, \
1810                       COALESCE(co.serialized_object, bh.serialized_object) AS serialized_object, \
1811                       COALESCE(co.coin_type, bh.coin_type) AS coin_type, \
1812                       COALESCE(co.coin_balance, bh.coin_balance) AS coin_balance, \
1813                       COALESCE(co.df_kind, bh.df_kind) AS df_kind \
1814                   FROM latest_per_id v \
1815                   LEFT JOIN checkpointed_objects co \
1816                          ON co.object_id = v.object_id \
1817                         AND co.object_version = v.object_version \
1818                   LEFT JOIN objects_backward_history bh \
1819                          ON bh.object_id = v.object_id \
1820                         AND bh.object_version = v.object_version";
1821
1822        // Issue concurrent reads for each group of keys.
1823        let futures = keys_by_cursor_and_parent_version
1824            .into_iter()
1825            .map(|(group_key, ids)| {
1826                let parent_version = group_key.parent_version as i64;
1827                let ids: Vec<Vec<u8>> = ids.into_iter().collect();
1828
1829                self.execute(move |conn| {
1830                    let stored: Vec<StoredHistoryObject> = conn.results(move || {
1831                        diesel::sql_query(sql)
1832                            .bind::<sql_types::Array<sql_types::Binary>, _>(ids.clone())
1833                            .bind::<sql_types::BigInt, _>(parent_version)
1834                            .bind::<sql_types::SmallInt, _>(OBJECT_STATUS_WRAPPED_OR_DELETED)
1835                            .bind::<sql_types::SmallInt, _>(OBJECT_STATUS_PRUNED)
1836                    })?;
1837
1838                    Ok::<_, diesel::result::Error>(
1839                        stored
1840                            .into_iter()
1841                            .map(|stored| (group_key, stored))
1842                            .collect::<Vec<_>>(),
1843                    )
1844                })
1845            });
1846
1847        // Wait for the reads to all finish, and gather them into the result map.
1848        let groups = futures::future::join_all(futures).await;
1849
1850        let mut key_to_stored = HashMap::new();
1851        for group in groups {
1852            for (group_key, stored) in
1853                group.map_err(|e| Error::Internal(format!("Failed to fetch objects: {e}")))?
1854            {
1855                let key = ParentVersionKey {
1856                    id: addr(&stored.object_id)?,
1857                    checkpoint_viewed_at: group_key.checkpoint_viewed_at,
1858                    parent_version: group_key.parent_version,
1859                };
1860                key_to_stored.insert(key, stored);
1861            }
1862        }
1863
1864        let mut results = HashMap::new();
1865        let mut fallback_keys = Vec::new();
1866        // Keys with no version `≤ parent_version` in `objects_version` at all.
1867        let mut unresolved_keys = Vec::new();
1868        for key in keys {
1869            let Some(stored) = key_to_stored.get(key) else {
1870                unresolved_keys.push(*key);
1871                continue;
1872            };
1873
1874            // This version didn't exist at the checkpoint we are viewing at.
1875            if key.checkpoint_viewed_at < stored.checkpoint_sequence_number as u64 {
1876                continue;
1877            }
1878
1879            let active_object = match stored.object_status {
1880                OBJECT_STATUS_PRUNED => {
1881                    let object_ref = (key.id.into(), Version::from(stored.object_version as u64));
1882                    fallback_keys.push((*key, object_ref));
1883                    continue;
1884                }
1885                OBJECT_STATUS_ACTIVE => ActiveObject::try_from(stored.clone())?,
1886                // Wrapped, deleted, or not yet created: resolve as non-existent.
1887                _ => continue,
1888            };
1889            // If `LatestAtKey::parent_version` is set, it must have been correctly
1890            // propagated from the `Object::root_version` of some object.
1891            let object = Object::from_active_object(
1892                active_object,
1893                key.checkpoint_viewed_at,
1894                Some(key.parent_version),
1895            );
1896
1897            results.insert(*key, Ok(object));
1898        }
1899
1900        // When version history is complete, unresolved key = nonexisting object
1901        // version. When history is incomplete we return DataPruned for such
1902        // cases, since this cannot be handled by KV currently: before_version
1903        // query will not work properly since we don't store wrapped-or-deleted
1904        // version in the KV.
1905        let oldest_available_checkpoint = Object::oldest_available_checkpoint_under_parent(self);
1906        if self.inner.is_pruned(CommitterTables::ObjectsVersion) {
1907            for key in unresolved_keys {
1908                let id = key.id;
1909                results.insert(
1910                    key,
1911                    Err(Error::DataPruned {
1912                        message: format!("data for object {id} potentially pruned"),
1913                        oldest_available_checkpoint,
1914                    }),
1915                );
1916            }
1917        }
1918
1919        fill_missing_objects_from_fallback(
1920            self,
1921            fallback_keys,
1922            oldest_available_checkpoint,
1923            &mut results,
1924        )
1925        .await?;
1926
1927        Ok(results)
1928    }
1929}
1930
1931impl Loader<LatestAtKey> for Db {
1932    type Value = Object;
1933    type Error = Error;
1934
1935    async fn load(&self, keys: &[LatestAtKey]) -> Result<HashMap<LatestAtKey, Object>, Error> {
1936        // Group keys by checkpoint viewed at -- we'll issue a separate query for each
1937        // group.
1938        let mut keys_by_cursor_and_parent_version: BTreeMap<_, BTreeSet<_>> = BTreeMap::new();
1939
1940        for key in keys {
1941            keys_by_cursor_and_parent_version
1942                .entry(key.checkpoint_viewed_at)
1943                .or_default()
1944                .insert(key.id);
1945        }
1946
1947        let max_available_range = self.max_available_range;
1948
1949        // Issue concurrent reads for each group of keys.
1950        let futures =
1951            keys_by_cursor_and_parent_version
1952                .into_iter()
1953                .map(|(checkpoint_viewed_at, ids)| {
1954                    self.execute_repeatable(move |conn| {
1955                        if !AvailableRange::is_checkpoint_in_backward_history_range(
1956                            conn,
1957                            checkpoint_viewed_at,
1958                            max_available_range,
1959                        )? {
1960                            return Ok::<Vec<(u64, StoredHistoryObject)>, diesel::result::Error>(
1961                                vec![],
1962                            );
1963                        };
1964
1965                        let filter = ObjectFilter {
1966                            object_ids: Some(ids.iter().cloned().collect()),
1967                            ..Default::default()
1968                        };
1969
1970                        let results: Vec<StoredBackwardObject> = conn.results(move || {
1971                            consistent::query(
1972                                checkpoint_viewed_at,
1973                                &Page::bounded(ids.len() as u64),
1974                                |q| filter.apply(q),
1975                            )
1976                            .into_boxed()
1977                        })?;
1978
1979                        Ok(results
1980                            .into_iter()
1981                            .map(|r| {
1982                                (
1983                                    checkpoint_viewed_at,
1984                                    r.into_stored_history(checkpoint_viewed_at),
1985                                )
1986                            })
1987                            .collect())
1988                    })
1989                });
1990
1991        // Wait for the reads to all finish, and gather them into the result map.
1992        let groups = futures::future::join_all(futures).await;
1993
1994        let mut results = HashMap::new();
1995        for group in groups {
1996            for (checkpoint_viewed_at, stored) in
1997                group.map_err(|e| Error::Internal(format!("Failed to fetch objects: {e}")))?
1998            {
1999                let active_object = ActiveObject::try_from(stored)?;
2000                let object = Object::from_active_object(active_object, checkpoint_viewed_at, None);
2001
2002                let key = LatestAtKey {
2003                    id: object.address,
2004                    checkpoint_viewed_at,
2005                };
2006
2007                results.insert(key, object);
2008            }
2009        }
2010
2011        Ok(results)
2012    }
2013}
2014
2015impl From<&ActiveObject> for ObjectStatus {
2016    fn from(active_object: &ActiveObject) -> Self {
2017        active_object.status
2018    }
2019}
2020
2021impl From<&Object> for OwnerImpl {
2022    fn from(object: &Object) -> Self {
2023        OwnerImpl {
2024            address: object.address,
2025            checkpoint_viewed_at: object.checkpoint_viewed_at,
2026        }
2027    }
2028}
2029
2030pub(crate) async fn deserialize_move_struct(
2031    move_object: &NativeMoveStruct,
2032    resolver: &PackageResolver,
2033) -> Result<(StructTag, MoveStruct), Error> {
2034    let struct_tag = move_object.struct_tag().clone();
2035    let contents = move_object.contents();
2036    let move_type_layout = resolver
2037        .type_layout(TypeTag::from(struct_tag.clone()))
2038        .await
2039        .map_err(|e| {
2040            Error::Internal(format!(
2041                "Error fetching layout for type {}: {e}",
2042                struct_tag.to_canonical_string(/* with_prefix */ true)
2043            ))
2044        })?;
2045
2046    let MoveTypeLayout::Struct(layout) = move_type_layout else {
2047        return Err(Error::Internal("Object is not a move struct".to_string()));
2048    };
2049
2050    // TODO (annotated-visitor): Use custom visitors for extracting a dynamic field,
2051    // and for creating a GraphQL MoveValue directly (not via an annotated
2052    // visitor).
2053    let move_struct = BoundedVisitor::deserialize_struct(contents, &layout).map_err(|e| {
2054        Error::Internal(format!(
2055            "Error deserializing move struct for type {}: {e}",
2056            struct_tag.to_canonical_string(/* with_prefix */ true)
2057        ))
2058    })?;
2059
2060    Ok((struct_tag, move_struct))
2061}
2062
2063/// Constructs a backward diff query for objects.
2064///
2065/// Uses consistent view for most queries to ensure point-in-time correctness.
2066/// Falls back to historical view only for object-key lookups (specific
2067/// id+version pairs) which don't need consistency filtering. When both
2068/// `object_ids` and `object_keys` are provided, the results from both views
2069/// are unioned and deduplicated on `(object_id, object_version)`.
2070fn backward_objects_query(
2071    filter: &ObjectFilter,
2072    checkpoint_viewed_at: u64,
2073    page: &Page<Cursor>,
2074) -> RawQuery {
2075    if let (Some(_), Some(_)) = (&filter.object_ids, &filter.object_keys) {
2076        // If both object IDs and object keys are specified, then we need to query in
2077        // both historical and consistent views, and then union the results.
2078        let ids_only_filter = ObjectFilter {
2079            object_keys: None,
2080            ..filter.clone()
2081        };
2082        let (id_query, id_bindings) = consistent::query(checkpoint_viewed_at, page, move |query| {
2083            ids_only_filter.apply(query)
2084        })
2085        .finish();
2086
2087        let keys_filter: HistoricalFilter = ObjectFilter {
2088            object_ids: None,
2089            ..filter.clone()
2090        }
2091        .try_into()
2092        .expect("object_keys is Some by match-arm guard");
2093        let (key_query, key_bindings) = historical::query(page, &keys_filter).finish();
2094
2095        // Same object version can be returned by both views, so the union has to
2096        // deduplicate.
2097        RawQuery::new(
2098            format!(
2099                "SELECT DISTINCT ON (candidates.object_id, candidates.object_version) * \
2100                 FROM (({id_query}) UNION ALL ({key_query})) AS candidates",
2101            ),
2102            id_bindings.into_iter().chain(key_bindings).collect(),
2103        )
2104    } else if let Ok(keys_filter) = HistoricalFilter::try_from(filter.clone()) {
2105        historical::query(page, &keys_filter)
2106    } else {
2107        consistent::query(checkpoint_viewed_at, page, move |query| filter.apply(query))
2108    }
2109}
2110
2111#[cfg(test)]
2112mod tests {
2113    use std::str::FromStr;
2114
2115    use super::*;
2116
2117    #[test]
2118    fn test_owner_filter_intersection() {
2119        let f0 = ObjectFilter {
2120            owner: Some(IotaAddress::from_str("0x1").unwrap()),
2121            ..Default::default()
2122        };
2123
2124        let f1 = ObjectFilter {
2125            owner: Some(IotaAddress::from_str("0x2").unwrap()),
2126            ..Default::default()
2127        };
2128
2129        assert_eq!(f0.clone().intersect(f0.clone()), Some(f0.clone()));
2130        assert_eq!(f0.intersect(f1), None);
2131    }
2132
2133    #[test]
2134    fn test_key_filter_intersection() {
2135        let i1 = IotaAddress::from_str("0x1").unwrap();
2136        let i2 = IotaAddress::from_str("0x2").unwrap();
2137        let i3 = IotaAddress::from_str("0x3").unwrap();
2138        let i4 = IotaAddress::from_str("0x4").unwrap();
2139
2140        let f0 = ObjectFilter {
2141            object_ids: Some(vec![i1, i3]),
2142            object_keys: Some(vec![
2143                ObjectKey {
2144                    object_id: i2,
2145                    version: 1.into(),
2146                },
2147                ObjectKey {
2148                    object_id: i4,
2149                    version: 2.into(),
2150                },
2151            ]),
2152            ..Default::default()
2153        };
2154
2155        let f1 = ObjectFilter {
2156            object_ids: Some(vec![i1, i2]),
2157            object_keys: Some(vec![ObjectKey {
2158                object_id: i4,
2159                version: 2.into(),
2160            }]),
2161            ..Default::default()
2162        };
2163
2164        let f2 = ObjectFilter {
2165            object_ids: Some(vec![i1, i3]),
2166            ..Default::default()
2167        };
2168
2169        let f3 = ObjectFilter {
2170            object_keys: Some(vec![
2171                ObjectKey {
2172                    object_id: i2,
2173                    version: 2.into(),
2174                },
2175                ObjectKey {
2176                    object_id: i4,
2177                    version: 2.into(),
2178                },
2179            ]),
2180            ..Default::default()
2181        };
2182
2183        assert_eq!(
2184            f0.clone().intersect(f1.clone()),
2185            Some(ObjectFilter {
2186                object_ids: Some(vec![i1]),
2187                object_keys: Some(vec![
2188                    ObjectKey {
2189                        object_id: i2,
2190                        version: 1.into(),
2191                    },
2192                    ObjectKey {
2193                        object_id: i4,
2194                        version: 2.into(),
2195                    },
2196                ]),
2197                ..Default::default()
2198            })
2199        );
2200
2201        assert_eq!(
2202            f1.clone().intersect(f2.clone()),
2203            Some(ObjectFilter {
2204                object_ids: Some(vec![i1]),
2205                ..Default::default()
2206            })
2207        );
2208
2209        assert_eq!(
2210            f1.intersect(f3.clone()),
2211            Some(ObjectFilter {
2212                object_keys: Some(vec![
2213                    ObjectKey {
2214                        object_id: i2,
2215                        version: 2.into(),
2216                    },
2217                    ObjectKey {
2218                        object_id: i4,
2219                        version: 2.into(),
2220                    },
2221                ]),
2222                ..Default::default()
2223            })
2224        );
2225
2226        // i2 got a conflicting version assignment
2227        assert_eq!(f0.intersect(f3.clone()), None);
2228
2229        // No overlap between these two.
2230        assert_eq!(f2.intersect(f3), None);
2231    }
2232}