iota_json_rpc_types/
iota_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    cmp::Ordering,
7    collections::BTreeMap,
8    fmt,
9    fmt::{Display, Formatter, Write},
10};
11
12use anyhow::{anyhow, bail};
13use colored::Colorize;
14use fastcrypto::encoding::Base64;
15use iota_protocol_config::ProtocolConfig;
16use iota_types::{
17    base_types::{
18        IotaAddress, ObjectDigest, ObjectID, ObjectInfo, ObjectRef, ObjectType, SequenceNumber,
19        TransactionDigest,
20    },
21    error::{
22        ExecutionError, IotaError, IotaObjectResponseError, IotaResult, UserInputError,
23        UserInputResult,
24    },
25    gas_coin::GasCoin,
26    iota_serde::{BigInt, IotaStructTag, SequenceNumber as AsSequenceNumber},
27    messages_checkpoint::CheckpointSequenceNumber,
28    move_package::{MovePackage, TypeOrigin, UpgradeInfo},
29    object::{Data, MoveObject, Object, ObjectInner, ObjectRead, Owner},
30};
31use move_bytecode_utils::module_cache::GetModule;
32use move_core_types::{
33    annotated_value::{MoveStructLayout, MoveValue},
34    identifier::Identifier,
35    language_storage::StructTag,
36};
37use schemars::JsonSchema;
38use serde::{Deserialize, Serialize};
39use serde_json::Value;
40use serde_with::{DisplayFromStr, serde_as};
41
42use crate::{IotaMoveStruct, IotaMoveValue, Page};
43
44#[derive(Serialize, Deserialize, Debug, JsonSchema, Clone, PartialEq, Eq)]
45pub struct IotaObjectResponse {
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub data: Option<IotaObjectData>,
48    #[serde(skip_serializing_if = "Option::is_none")]
49    pub error: Option<IotaObjectResponseError>,
50}
51
52impl IotaObjectResponse {
53    pub fn new(data: Option<IotaObjectData>, error: Option<IotaObjectResponseError>) -> Self {
54        Self { data, error }
55    }
56
57    pub fn new_with_data(data: IotaObjectData) -> Self {
58        Self {
59            data: Some(data),
60            error: None,
61        }
62    }
63
64    pub fn new_with_error(error: IotaObjectResponseError) -> Self {
65        Self {
66            data: None,
67            error: Some(error),
68        }
69    }
70}
71
72impl Ord for IotaObjectResponse {
73    fn cmp(&self, other: &Self) -> Ordering {
74        match (&self.data, &other.data) {
75            (Some(data), Some(data_2)) => {
76                if data.object_id.cmp(&data_2.object_id).eq(&Ordering::Greater) {
77                    return Ordering::Greater;
78                } else if data.object_id.cmp(&data_2.object_id).eq(&Ordering::Less) {
79                    return Ordering::Less;
80                }
81                Ordering::Equal
82            }
83            // In this ordering those with data will come before IotaObjectResponses that are
84            // errors.
85            (Some(_), None) => Ordering::Less,
86            (None, Some(_)) => Ordering::Greater,
87            // IotaObjectResponses that are errors are just considered equal.
88            _ => Ordering::Equal,
89        }
90    }
91}
92
93impl PartialOrd for IotaObjectResponse {
94    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
95        Some(self.cmp(other))
96    }
97}
98
99impl IotaObjectResponse {
100    pub fn move_object_bcs(&self) -> Option<&Vec<u8>> {
101        match &self.data {
102            Some(IotaObjectData {
103                bcs: Some(IotaRawData::MoveObject(obj)),
104                ..
105            }) => Some(&obj.bcs_bytes),
106            _ => None,
107        }
108    }
109
110    pub fn owner(&self) -> Option<Owner> {
111        if let Some(data) = &self.data {
112            return data.owner;
113        }
114        None
115    }
116
117    pub fn object_id(&self) -> Result<ObjectID, anyhow::Error> {
118        Ok(match (&self.data, &self.error) {
119            (Some(obj_data), None) => obj_data.object_id,
120            (None, Some(IotaObjectResponseError::NotExists { object_id })) => *object_id,
121            (
122                None,
123                Some(IotaObjectResponseError::Deleted {
124                    object_id,
125                    version: _,
126                    digest: _,
127                }),
128            ) => *object_id,
129            _ => bail!(
130                "Could not get object_id, something went wrong with IotaObjectResponse construction."
131            ),
132        })
133    }
134
135    pub fn object_ref_if_exists(&self) -> Option<ObjectRef> {
136        match (&self.data, &self.error) {
137            (Some(obj_data), None) => Some(obj_data.object_ref()),
138            _ => None,
139        }
140    }
141}
142
143impl TryFrom<IotaObjectResponse> for ObjectInfo {
144    type Error = anyhow::Error;
145
146    fn try_from(value: IotaObjectResponse) -> Result<Self, Self::Error> {
147        let IotaObjectData {
148            object_id,
149            version,
150            digest,
151            type_,
152            owner,
153            previous_transaction,
154            ..
155        } = value.into_object()?;
156
157        Ok(ObjectInfo {
158            object_id,
159            version,
160            digest,
161            type_: type_.ok_or_else(|| anyhow!("Object type not found for object."))?,
162            owner: owner.ok_or_else(|| anyhow!("Owner not found for object."))?,
163            previous_transaction: previous_transaction
164                .ok_or_else(|| anyhow!("Transaction digest not found for object."))?,
165        })
166    }
167}
168
169#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, Eq, PartialEq)]
170pub struct DisplayFieldsResponse {
171    pub data: Option<BTreeMap<String, String>>,
172    pub error: Option<IotaObjectResponseError>,
173}
174
175#[serde_as]
176#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, Eq, PartialEq)]
177#[serde(rename_all = "camelCase", rename = "ObjectData")]
178pub struct IotaObjectData {
179    pub object_id: ObjectID,
180    /// Object version.
181    #[schemars(with = "AsSequenceNumber")]
182    #[serde_as(as = "AsSequenceNumber")]
183    pub version: SequenceNumber,
184    /// Base64 string representing the object digest
185    pub digest: ObjectDigest,
186    /// The type of the object. Default to be None unless
187    /// IotaObjectDataOptions.showType is set to true
188    #[schemars(with = "Option<String>")]
189    #[serde_as(as = "Option<DisplayFromStr>")]
190    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
191    pub type_: Option<ObjectType>,
192    // Default to be None because otherwise it will be repeated for the getOwnedObjects endpoint
193    /// The owner of this object. Default to be None unless
194    /// IotaObjectDataOptions.showOwner is set to true
195    #[serde(skip_serializing_if = "Option::is_none")]
196    pub owner: Option<Owner>,
197    /// The digest of the transaction that created or last mutated this object.
198    /// Default to be None unless IotaObjectDataOptions.
199    /// showPreviousTransaction is set to true
200    #[serde(skip_serializing_if = "Option::is_none")]
201    pub previous_transaction: Option<TransactionDigest>,
202    /// The amount of IOTA we would rebate if this object gets deleted.
203    /// This number is re-calculated each time the object is mutated based on
204    /// the present storage gas price.
205    #[schemars(with = "Option<BigInt<u64>>")]
206    #[serde_as(as = "Option<BigInt<u64>>")]
207    #[serde(skip_serializing_if = "Option::is_none")]
208    pub storage_rebate: Option<u64>,
209    /// The Display metadata for frontend UI rendering, default to be None
210    /// unless IotaObjectDataOptions.showContent is set to true This can also
211    /// be None if the struct type does not have Display defined
212    #[serde(skip_serializing_if = "Option::is_none")]
213    pub display: Option<DisplayFieldsResponse>,
214    /// Move object content or package content, default to be None unless
215    /// IotaObjectDataOptions.showContent is set to true
216    #[serde(skip_serializing_if = "Option::is_none")]
217    pub content: Option<IotaParsedData>,
218    /// Move object content or package content in BCS, default to be None unless
219    /// IotaObjectDataOptions.showBcs is set to true
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub bcs: Option<IotaRawData>,
222}
223
224impl IotaObjectData {
225    pub fn new(
226        object_ref: ObjectRef,
227        obj: Object,
228        layout: impl Into<Option<MoveStructLayout>>,
229        options: IotaObjectDataOptions,
230        display_fields: impl Into<Option<DisplayFieldsResponse>>,
231    ) -> anyhow::Result<Self> {
232        let layout = layout.into();
233        let display_fields = display_fields.into();
234        let show_display = options.show_display;
235        let IotaObjectDataOptions {
236            show_type,
237            show_owner,
238            show_previous_transaction,
239            show_content,
240            show_bcs,
241            show_storage_rebate,
242            ..
243        } = options;
244
245        let (object_id, version, digest) = object_ref;
246        let type_ = if show_type {
247            Some(Into::<ObjectType>::into(&obj))
248        } else {
249            None
250        };
251
252        let bcs: Option<IotaRawData> = if show_bcs {
253            let data = match obj.data.clone() {
254                Data::Move(m) => {
255                    let layout = layout.clone().ok_or_else(|| {
256                        anyhow!("Layout is required to convert Move object to json")
257                    })?;
258                    IotaRawData::try_from_object(m, layout)?
259                }
260                Data::Package(p) => IotaRawData::try_from_package(p)
261                    .map_err(|e| anyhow!("Error getting raw data from package: {e:#?}"))?,
262            };
263            Some(data)
264        } else {
265            None
266        };
267
268        let obj = obj.into_inner();
269
270        let content: Option<IotaParsedData> = if show_content {
271            let data = match obj.data {
272                Data::Move(m) => {
273                    let layout = layout.ok_or_else(|| {
274                        anyhow!("Layout is required to convert Move object to json")
275                    })?;
276                    IotaParsedData::try_from_object(m, layout)?
277                }
278                Data::Package(p) => IotaParsedData::try_from_package(p)?,
279            };
280            Some(data)
281        } else {
282            None
283        };
284
285        Ok(IotaObjectData {
286            object_id,
287            version,
288            digest,
289            type_,
290            owner: if show_owner { Some(obj.owner) } else { None },
291            storage_rebate: if show_storage_rebate {
292                Some(obj.storage_rebate)
293            } else {
294                None
295            },
296            previous_transaction: if show_previous_transaction {
297                Some(obj.previous_transaction)
298            } else {
299                None
300            },
301            content,
302            bcs,
303            display: if show_display { display_fields } else { None },
304        })
305    }
306
307    pub fn object_ref(&self) -> ObjectRef {
308        (self.object_id, self.version, self.digest)
309    }
310
311    pub fn object_type(&self) -> anyhow::Result<ObjectType> {
312        self.type_
313            .as_ref()
314            .ok_or_else(|| anyhow!("type is missing for object {:?}", self.object_id))
315            .cloned()
316    }
317
318    pub fn is_gas_coin(&self) -> bool {
319        match self.type_.as_ref() {
320            Some(ObjectType::Struct(ty)) if ty.is_gas_coin() => true,
321            Some(_) => false,
322            None => false,
323        }
324    }
325}
326
327impl Display for IotaObjectData {
328    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
329        let type_ = if let Some(type_) = &self.type_ {
330            type_.to_string()
331        } else {
332            "Unknown Type".into()
333        };
334        let mut writer = String::new();
335        writeln!(
336            writer,
337            "{}",
338            format!("----- {type_} ({}[{}]) -----", self.object_id, self.version).bold()
339        )?;
340        if let Some(owner) = self.owner {
341            writeln!(writer, "{}: {owner}", "Owner".bold().bright_black())?;
342        }
343
344        writeln!(
345            writer,
346            "{}: {}",
347            "Version".bold().bright_black(),
348            self.version
349        )?;
350        if let Some(storage_rebate) = self.storage_rebate {
351            writeln!(
352                writer,
353                "{}: {storage_rebate}",
354                "Storage Rebate".bold().bright_black(),
355            )?;
356        }
357
358        if let Some(previous_transaction) = self.previous_transaction {
359            writeln!(
360                writer,
361                "{}: {previous_transaction:?}",
362                "Previous Transaction".bold().bright_black(),
363            )?;
364        }
365        if let Some(content) = self.content.as_ref() {
366            writeln!(writer, "{}", "----- Data -----".bold())?;
367            write!(writer, "{content}")?;
368        }
369
370        write!(f, "{writer}")
371    }
372}
373
374impl TryFrom<&IotaObjectData> for GasCoin {
375    type Error = anyhow::Error;
376    fn try_from(object: &IotaObjectData) -> Result<Self, Self::Error> {
377        match &object
378            .content
379            .as_ref()
380            .ok_or_else(|| anyhow!("Expect object content to not be empty"))?
381        {
382            IotaParsedData::MoveObject(o) => {
383                if GasCoin::type_() == o.type_ {
384                    return GasCoin::try_from(&o.fields);
385                }
386            }
387            IotaParsedData::Package(_) => {}
388        }
389
390        bail!("Gas object type is not a gas coin: {:?}", object.type_)
391    }
392}
393
394impl TryFrom<&IotaMoveStruct> for GasCoin {
395    type Error = anyhow::Error;
396    fn try_from(move_struct: &IotaMoveStruct) -> Result<Self, Self::Error> {
397        match move_struct {
398            IotaMoveStruct::WithFields(fields) | IotaMoveStruct::WithTypes { type_: _, fields } => {
399                if let Some(IotaMoveValue::String(balance)) = fields.get("balance") {
400                    if let Ok(balance) = balance.parse::<u64>() {
401                        if let Some(IotaMoveValue::UID { id }) = fields.get("id") {
402                            return Ok(GasCoin::new(*id, balance));
403                        }
404                    }
405                }
406            }
407            _ => {}
408        }
409        bail!("Struct is not a gas coin: {move_struct:?}")
410    }
411}
412
413#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, Eq, PartialEq, Default)]
414#[serde(rename_all = "camelCase", rename = "ObjectDataOptions", default)]
415pub struct IotaObjectDataOptions {
416    /// Whether to show the type of the object. Default to be False
417    pub show_type: bool,
418    /// Whether to show the owner of the object. Default to be False
419    pub show_owner: bool,
420    /// Whether to show the previous transaction digest of the object. Default
421    /// to be False
422    pub show_previous_transaction: bool,
423    /// Whether to show the Display metadata of the object for frontend
424    /// rendering. Default to be False
425    pub show_display: bool,
426    /// Whether to show the content(i.e., package content or Move struct
427    /// content) of the object. Default to be False
428    pub show_content: bool,
429    /// Whether to show the content in BCS format. Default to be False
430    pub show_bcs: bool,
431    /// Whether to show the storage rebate of the object. Default to be False
432    pub show_storage_rebate: bool,
433}
434
435impl IotaObjectDataOptions {
436    pub fn new() -> Self {
437        Self::default()
438    }
439
440    /// return BCS data and all other metadata such as storage rebate
441    pub fn bcs_lossless() -> Self {
442        Self {
443            show_bcs: true,
444            show_type: true,
445            show_owner: true,
446            show_previous_transaction: true,
447            show_display: false,
448            show_content: false,
449            show_storage_rebate: true,
450        }
451    }
452
453    /// return full content except bcs
454    pub fn full_content() -> Self {
455        Self {
456            show_bcs: false,
457            show_type: true,
458            show_owner: true,
459            show_previous_transaction: true,
460            show_display: false,
461            show_content: true,
462            show_storage_rebate: true,
463        }
464    }
465
466    pub fn with_content(mut self) -> Self {
467        self.show_content = true;
468        self
469    }
470
471    pub fn with_owner(mut self) -> Self {
472        self.show_owner = true;
473        self
474    }
475
476    pub fn with_type(mut self) -> Self {
477        self.show_type = true;
478        self
479    }
480
481    pub fn with_display(mut self) -> Self {
482        self.show_display = true;
483        self
484    }
485
486    pub fn with_bcs(mut self) -> Self {
487        self.show_bcs = true;
488        self
489    }
490
491    pub fn with_previous_transaction(mut self) -> Self {
492        self.show_previous_transaction = true;
493        self
494    }
495
496    pub fn is_not_in_object_info(&self) -> bool {
497        self.show_bcs || self.show_content || self.show_display || self.show_storage_rebate
498    }
499}
500
501impl TryFrom<(ObjectRead, IotaObjectDataOptions)> for IotaObjectResponse {
502    type Error = anyhow::Error;
503
504    fn try_from(
505        (object_read, options): (ObjectRead, IotaObjectDataOptions),
506    ) -> Result<Self, Self::Error> {
507        match object_read {
508            ObjectRead::NotExists(id) => Ok(IotaObjectResponse::new_with_error(
509                IotaObjectResponseError::NotExists { object_id: id },
510            )),
511            ObjectRead::Exists(object_ref, o, layout) => Ok(IotaObjectResponse::new_with_data(
512                IotaObjectData::new(object_ref, o, layout, options, None)?,
513            )),
514            ObjectRead::Deleted((object_id, version, digest)) => Ok(
515                IotaObjectResponse::new_with_error(IotaObjectResponseError::Deleted {
516                    object_id,
517                    version,
518                    digest,
519                }),
520            ),
521        }
522    }
523}
524
525impl TryFrom<(ObjectInfo, IotaObjectDataOptions)> for IotaObjectResponse {
526    type Error = anyhow::Error;
527
528    fn try_from(
529        (object_info, options): (ObjectInfo, IotaObjectDataOptions),
530    ) -> Result<Self, Self::Error> {
531        let IotaObjectDataOptions {
532            show_type,
533            show_owner,
534            show_previous_transaction,
535            ..
536        } = options;
537
538        Ok(Self::new_with_data(IotaObjectData {
539            object_id: object_info.object_id,
540            version: object_info.version,
541            digest: object_info.digest,
542            type_: show_type.then_some(object_info.type_),
543            owner: show_owner.then_some(object_info.owner),
544            previous_transaction: show_previous_transaction
545                .then_some(object_info.previous_transaction),
546            storage_rebate: None,
547            display: None,
548            content: None,
549            bcs: None,
550        }))
551    }
552}
553
554impl IotaObjectResponse {
555    /// Returns a reference to the object if there is any, otherwise an Err if
556    /// the object does not exist or is deleted.
557    pub fn object(&self) -> Result<&IotaObjectData, IotaObjectResponseError> {
558        if let Some(data) = &self.data {
559            Ok(data)
560        } else if let Some(error) = &self.error {
561            Err(error.clone())
562        } else {
563            // We really shouldn't reach this code block since either data, or error field
564            // should always be filled.
565            Err(IotaObjectResponseError::Unknown)
566        }
567    }
568
569    /// Returns the object value if there is any, otherwise an Err if
570    /// the object does not exist or is deleted.
571    pub fn into_object(self) -> Result<IotaObjectData, IotaObjectResponseError> {
572        match self.object() {
573            Ok(data) => Ok(data.clone()),
574            Err(error) => Err(error),
575        }
576    }
577}
578
579impl TryInto<Object> for IotaObjectData {
580    type Error = anyhow::Error;
581
582    fn try_into(self) -> Result<Object, Self::Error> {
583        let protocol_config = ProtocolConfig::get_for_min_version();
584        let data = match self.bcs {
585            Some(IotaRawData::MoveObject(o)) => Data::Move({
586                MoveObject::new_from_execution(
587                    o.type_().clone().into(),
588                    o.version,
589                    o.bcs_bytes,
590                    &protocol_config,
591                )?
592            }),
593            Some(IotaRawData::Package(p)) => Data::Package(MovePackage::new(
594                p.id,
595                self.version,
596                p.module_map,
597                protocol_config.max_move_package_size(),
598                p.type_origin_table,
599                p.linkage_table,
600            )?),
601            _ => Err(anyhow!(
602                "BCS data is required to convert IotaObjectData to Object"
603            ))?,
604        };
605        Ok(ObjectInner {
606            data,
607            owner: self
608                .owner
609                .ok_or_else(|| anyhow!("Owner is required to convert IotaObjectData to Object"))?,
610            previous_transaction: self.previous_transaction.ok_or_else(|| {
611                anyhow!("previous_transaction is required to convert IotaObjectData to Object")
612            })?,
613            storage_rebate: self.storage_rebate.ok_or_else(|| {
614                anyhow!("storage_rebate is required to convert IotaObjectData to Object")
615            })?,
616        }
617        .into())
618    }
619}
620
621#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, Eq, PartialEq, Ord, PartialOrd)]
622#[serde(rename_all = "camelCase", rename = "ObjectRef")]
623pub struct IotaObjectRef {
624    /// Hex code as string representing the object id
625    pub object_id: ObjectID,
626    /// Object version.
627    pub version: SequenceNumber,
628    /// Base64 string representing the object digest
629    pub digest: ObjectDigest,
630}
631
632impl IotaObjectRef {
633    pub fn to_object_ref(&self) -> ObjectRef {
634        (self.object_id, self.version, self.digest)
635    }
636}
637
638impl Display for IotaObjectRef {
639    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
640        write!(
641            f,
642            "Object ID: {}, version: {}, digest: {}",
643            self.object_id, self.version, self.digest
644        )
645    }
646}
647
648impl From<ObjectRef> for IotaObjectRef {
649    fn from(oref: ObjectRef) -> Self {
650        Self {
651            object_id: oref.0,
652            version: oref.1,
653            digest: oref.2,
654        }
655    }
656}
657
658pub trait IotaData: Sized {
659    type ObjectType;
660    type PackageType;
661    fn try_from_object(object: MoveObject, layout: MoveStructLayout)
662    -> Result<Self, anyhow::Error>;
663    fn try_from_package(package: MovePackage) -> Result<Self, anyhow::Error>;
664    fn try_as_move(&self) -> Option<&Self::ObjectType>;
665    fn try_into_move(self) -> Option<Self::ObjectType>;
666    fn try_as_package(&self) -> Option<&Self::PackageType>;
667    fn type_(&self) -> Option<&StructTag>;
668}
669
670#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Eq, PartialEq)]
671#[serde(tag = "dataType", rename_all = "camelCase", rename = "RawData")]
672pub enum IotaRawData {
673    // Manually handle generic schema generation
674    MoveObject(IotaRawMoveObject),
675    Package(IotaRawMovePackage),
676}
677
678impl IotaData for IotaRawData {
679    type ObjectType = IotaRawMoveObject;
680    type PackageType = IotaRawMovePackage;
681
682    fn try_from_object(object: MoveObject, _: MoveStructLayout) -> Result<Self, anyhow::Error> {
683        Ok(Self::MoveObject(object.into()))
684    }
685
686    fn try_from_package(package: MovePackage) -> Result<Self, anyhow::Error> {
687        Ok(Self::Package(package.into()))
688    }
689
690    fn try_as_move(&self) -> Option<&Self::ObjectType> {
691        match self {
692            Self::MoveObject(o) => Some(o),
693            Self::Package(_) => None,
694        }
695    }
696
697    fn try_into_move(self) -> Option<Self::ObjectType> {
698        match self {
699            Self::MoveObject(o) => Some(o),
700            Self::Package(_) => None,
701        }
702    }
703
704    fn try_as_package(&self) -> Option<&Self::PackageType> {
705        match self {
706            Self::MoveObject(_) => None,
707            Self::Package(p) => Some(p),
708        }
709    }
710
711    fn type_(&self) -> Option<&StructTag> {
712        match self {
713            Self::MoveObject(o) => Some(&o.type_),
714            Self::Package(_) => None,
715        }
716    }
717}
718
719#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Eq, PartialEq)]
720#[serde(tag = "dataType", rename_all = "camelCase", rename = "Data")]
721pub enum IotaParsedData {
722    // Manually handle generic schema generation
723    MoveObject(IotaParsedMoveObject),
724    Package(IotaMovePackage),
725}
726
727impl IotaData for IotaParsedData {
728    type ObjectType = IotaParsedMoveObject;
729    type PackageType = IotaMovePackage;
730
731    fn try_from_object(
732        object: MoveObject,
733        layout: MoveStructLayout,
734    ) -> Result<Self, anyhow::Error> {
735        Ok(Self::MoveObject(IotaParsedMoveObject::try_from_layout(
736            object, layout,
737        )?))
738    }
739
740    fn try_from_package(package: MovePackage) -> Result<Self, anyhow::Error> {
741        Ok(Self::Package(IotaMovePackage {
742            disassembled: package.disassemble()?,
743        }))
744    }
745
746    fn try_as_move(&self) -> Option<&Self::ObjectType> {
747        match self {
748            Self::MoveObject(o) => Some(o),
749            Self::Package(_) => None,
750        }
751    }
752
753    fn try_into_move(self) -> Option<Self::ObjectType> {
754        match self {
755            Self::MoveObject(o) => Some(o),
756            Self::Package(_) => None,
757        }
758    }
759
760    fn try_as_package(&self) -> Option<&Self::PackageType> {
761        match self {
762            Self::MoveObject(_) => None,
763            Self::Package(p) => Some(p),
764        }
765    }
766
767    fn type_(&self) -> Option<&StructTag> {
768        match self {
769            Self::MoveObject(o) => Some(&o.type_),
770            Self::Package(_) => None,
771        }
772    }
773}
774
775impl Display for IotaParsedData {
776    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
777        let mut writer = String::new();
778        match self {
779            IotaParsedData::MoveObject(o) => {
780                writeln!(writer, "{}: {}", "type".bold().bright_black(), o.type_)?;
781                write!(writer, "{}", &o.fields)?;
782            }
783            IotaParsedData::Package(p) => {
784                write!(
785                    writer,
786                    "{}: {:?}",
787                    "Modules".bold().bright_black(),
788                    p.disassembled.keys()
789                )?;
790            }
791        }
792        write!(f, "{writer}")
793    }
794}
795
796impl IotaParsedData {
797    pub fn try_from_object_read(object_read: ObjectRead) -> Result<Self, anyhow::Error> {
798        match object_read {
799            ObjectRead::NotExists(id) => Err(anyhow::anyhow!("Object {id} does not exist")),
800            ObjectRead::Exists(_object_ref, o, layout) => {
801                let data = match o.into_inner().data {
802                    Data::Move(m) => {
803                        let layout = layout.ok_or_else(|| {
804                            anyhow!("Layout is required to convert Move object to json")
805                        })?;
806                        IotaParsedData::try_from_object(m, layout)?
807                    }
808                    Data::Package(p) => IotaParsedData::try_from_package(p)?,
809                };
810                Ok(data)
811            }
812            ObjectRead::Deleted((object_id, version, digest)) => Err(anyhow::anyhow!(
813                "Object {object_id} was deleted at version {version} with digest {digest}"
814            )),
815        }
816    }
817}
818
819pub trait IotaMoveObject: Sized {
820    fn try_from_layout(object: MoveObject, layout: MoveStructLayout)
821    -> Result<Self, anyhow::Error>;
822
823    fn try_from(o: MoveObject, resolver: &impl GetModule) -> Result<Self, anyhow::Error> {
824        let layout = o.get_layout(resolver)?;
825        Self::try_from_layout(o, layout)
826    }
827
828    fn type_(&self) -> &StructTag;
829}
830
831#[serde_as]
832#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Eq, PartialEq)]
833#[serde(rename = "MoveObject", rename_all = "camelCase")]
834pub struct IotaParsedMoveObject {
835    #[serde(rename = "type")]
836    #[serde_as(as = "IotaStructTag")]
837    #[schemars(with = "String")]
838    pub type_: StructTag,
839    pub fields: IotaMoveStruct,
840}
841
842impl IotaMoveObject for IotaParsedMoveObject {
843    fn try_from_layout(
844        object: MoveObject,
845        layout: MoveStructLayout,
846    ) -> Result<Self, anyhow::Error> {
847        let move_struct = object.to_move_struct(&layout)?.into();
848
849        Ok(
850            if let IotaMoveStruct::WithTypes { type_, fields } = move_struct {
851                IotaParsedMoveObject {
852                    type_,
853                    fields: IotaMoveStruct::WithFields(fields),
854                }
855            } else {
856                IotaParsedMoveObject {
857                    type_: object.type_().clone().into(),
858                    fields: move_struct,
859                }
860            },
861        )
862    }
863
864    fn type_(&self) -> &StructTag {
865        &self.type_
866    }
867}
868
869impl IotaParsedMoveObject {
870    pub fn try_from_object_read(object_read: ObjectRead) -> Result<Self, anyhow::Error> {
871        let parsed_data = IotaParsedData::try_from_object_read(object_read)?;
872        match parsed_data {
873            IotaParsedData::MoveObject(o) => Ok(o),
874            IotaParsedData::Package(_) => Err(anyhow::anyhow!("Object is not a Move object")),
875        }
876    }
877
878    pub fn read_dynamic_field_value(&self, field_name: &str) -> Option<IotaMoveValue> {
879        match &self.fields {
880            IotaMoveStruct::WithFields(fields) => fields.get(field_name).cloned(),
881            IotaMoveStruct::WithTypes { fields, .. } => fields.get(field_name).cloned(),
882            _ => None,
883        }
884    }
885}
886
887pub fn type_and_fields_from_move_event_data(
888    event_data: MoveValue,
889) -> IotaResult<(StructTag, serde_json::Value)> {
890    match event_data.into() {
891        IotaMoveValue::Struct(move_struct) => match &move_struct {
892            IotaMoveStruct::WithTypes { type_, .. } => {
893                Ok((type_.clone(), move_struct.clone().to_json_value()))
894            }
895            _ => Err(IotaError::ObjectDeserialization {
896                error: "Found non-type IotaMoveStruct in MoveValue event".to_string(),
897            }),
898        },
899        IotaMoveValue::Variant(v) => Ok((v.type_.clone(), v.clone().to_json_value())),
900        IotaMoveValue::Vector(_)
901        | IotaMoveValue::Number(_)
902        | IotaMoveValue::Bool(_)
903        | IotaMoveValue::Address(_)
904        | IotaMoveValue::String(_)
905        | IotaMoveValue::UID { .. }
906        | IotaMoveValue::Option(_) => Err(IotaError::ObjectDeserialization {
907            error: "Invalid MoveValue event type -- this should not be possible".to_string(),
908        }),
909    }
910}
911
912#[serde_as]
913#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Eq, PartialEq)]
914#[serde(rename = "RawMoveObject", rename_all = "camelCase")]
915pub struct IotaRawMoveObject {
916    #[schemars(with = "String")]
917    #[serde(rename = "type")]
918    #[serde_as(as = "IotaStructTag")]
919    pub type_: StructTag,
920    pub version: SequenceNumber,
921    #[serde_as(as = "Base64")]
922    #[schemars(with = "Base64")]
923    pub bcs_bytes: Vec<u8>,
924}
925
926impl From<MoveObject> for IotaRawMoveObject {
927    fn from(o: MoveObject) -> Self {
928        Self {
929            type_: o.type_().clone().into(),
930            version: o.version(),
931            bcs_bytes: o.into_contents(),
932        }
933    }
934}
935
936impl IotaMoveObject for IotaRawMoveObject {
937    fn try_from_layout(
938        object: MoveObject,
939        _layout: MoveStructLayout,
940    ) -> Result<Self, anyhow::Error> {
941        Ok(Self {
942            type_: object.type_().clone().into(),
943            version: object.version(),
944            bcs_bytes: object.into_contents(),
945        })
946    }
947
948    fn type_(&self) -> &StructTag {
949        &self.type_
950    }
951}
952
953impl IotaRawMoveObject {
954    pub fn deserialize<'a, T: Deserialize<'a>>(&'a self) -> Result<T, anyhow::Error> {
955        Ok(bcs::from_bytes(self.bcs_bytes.as_slice())?)
956    }
957}
958
959#[serde_as]
960#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Eq, PartialEq)]
961#[serde(rename = "RawMovePackage", rename_all = "camelCase")]
962pub struct IotaRawMovePackage {
963    pub id: ObjectID,
964    pub version: SequenceNumber,
965    #[schemars(with = "BTreeMap<String, Base64>")]
966    #[serde_as(as = "BTreeMap<_, Base64>")]
967    pub module_map: BTreeMap<String, Vec<u8>>,
968    pub type_origin_table: Vec<TypeOrigin>,
969    pub linkage_table: BTreeMap<ObjectID, UpgradeInfo>,
970}
971
972impl From<MovePackage> for IotaRawMovePackage {
973    fn from(p: MovePackage) -> Self {
974        Self {
975            id: p.id(),
976            version: p.version(),
977            module_map: p.serialized_module_map().clone(),
978            type_origin_table: p.type_origin_table().clone(),
979            linkage_table: p.linkage_table().clone(),
980        }
981    }
982}
983
984impl IotaRawMovePackage {
985    pub fn to_move_package(
986        &self,
987        max_move_package_size: u64,
988    ) -> Result<MovePackage, ExecutionError> {
989        MovePackage::new(
990            self.id,
991            self.version,
992            self.module_map.clone(),
993            max_move_package_size,
994            self.type_origin_table.clone(),
995            self.linkage_table.clone(),
996        )
997    }
998}
999
1000#[derive(Serialize, Deserialize, Debug, JsonSchema, Clone, PartialEq, Eq)]
1001#[serde(tag = "status", content = "details", rename = "ObjectRead")]
1002#[expect(clippy::large_enum_variant)]
1003pub enum IotaPastObjectResponse {
1004    /// The object exists and is found with this version
1005    VersionFound(IotaObjectData),
1006    /// The object does not exist
1007    ObjectNotExists(ObjectID),
1008    /// The object is found to be deleted with this version
1009    ObjectDeleted(IotaObjectRef),
1010    /// The object exists but not found with this version
1011    VersionNotFound(ObjectID, SequenceNumber),
1012    /// The asked object version is higher than the latest
1013    VersionTooHigh {
1014        object_id: ObjectID,
1015        asked_version: SequenceNumber,
1016        latest_version: SequenceNumber,
1017    },
1018}
1019
1020impl IotaPastObjectResponse {
1021    /// Returns a reference to the object if there is any, otherwise an Err
1022    pub fn object(&self) -> UserInputResult<&IotaObjectData> {
1023        match &self {
1024            Self::ObjectDeleted(oref) => Err(UserInputError::ObjectDeleted {
1025                object_ref: oref.to_object_ref(),
1026            }),
1027            Self::ObjectNotExists(id) => Err(UserInputError::ObjectNotFound {
1028                object_id: *id,
1029                version: None,
1030            }),
1031            Self::VersionFound(o) => Ok(o),
1032            Self::VersionNotFound(id, seq_num) => Err(UserInputError::ObjectNotFound {
1033                object_id: *id,
1034                version: Some(*seq_num),
1035            }),
1036            Self::VersionTooHigh {
1037                object_id,
1038                asked_version,
1039                latest_version,
1040            } => Err(UserInputError::ObjectSequenceNumberTooHigh {
1041                object_id: *object_id,
1042                asked_version: *asked_version,
1043                latest_version: *latest_version,
1044            }),
1045        }
1046    }
1047
1048    /// Returns the object value if there is any, otherwise an Err
1049    pub fn into_object(self) -> UserInputResult<IotaObjectData> {
1050        match self {
1051            Self::ObjectDeleted(oref) => Err(UserInputError::ObjectDeleted {
1052                object_ref: oref.to_object_ref(),
1053            }),
1054            Self::ObjectNotExists(id) => Err(UserInputError::ObjectNotFound {
1055                object_id: id,
1056                version: None,
1057            }),
1058            Self::VersionFound(o) => Ok(o),
1059            Self::VersionNotFound(object_id, version) => Err(UserInputError::ObjectNotFound {
1060                object_id,
1061                version: Some(version),
1062            }),
1063            Self::VersionTooHigh {
1064                object_id,
1065                asked_version,
1066                latest_version,
1067            } => Err(UserInputError::ObjectSequenceNumberTooHigh {
1068                object_id,
1069                asked_version,
1070                latest_version,
1071            }),
1072        }
1073    }
1074}
1075
1076#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Eq, PartialEq)]
1077#[serde(rename = "MovePackage", rename_all = "camelCase")]
1078pub struct IotaMovePackage {
1079    pub disassembled: BTreeMap<String, Value>,
1080}
1081
1082pub type QueryObjectsPage = Page<IotaObjectResponse, CheckpointedObjectID>;
1083pub type ObjectsPage = Page<IotaObjectResponse, ObjectID>;
1084
1085#[serde_as]
1086#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, Eq, PartialEq)]
1087#[serde(rename_all = "camelCase")]
1088pub struct CheckpointedObjectID {
1089    pub object_id: ObjectID,
1090    #[schemars(with = "Option<BigInt<u64>>")]
1091    #[serde_as(as = "Option<BigInt<u64>>")]
1092    #[serde(skip_serializing_if = "Option::is_none")]
1093    pub at_checkpoint: Option<CheckpointSequenceNumber>,
1094}
1095
1096#[serde_as]
1097#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Eq, PartialEq)]
1098#[serde(rename = "GetPastObjectRequest", rename_all = "camelCase")]
1099pub struct IotaGetPastObjectRequest {
1100    /// the ID of the queried object
1101    pub object_id: ObjectID,
1102    /// the version of the queried object.
1103    #[schemars(with = "AsSequenceNumber")]
1104    #[serde_as(as = "AsSequenceNumber")]
1105    pub version: SequenceNumber,
1106}
1107
1108#[serde_as]
1109#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
1110pub enum IotaObjectDataFilter {
1111    MatchAll(Vec<IotaObjectDataFilter>),
1112    MatchAny(Vec<IotaObjectDataFilter>),
1113    MatchNone(Vec<IotaObjectDataFilter>),
1114    /// Query by type a specified Package.
1115    Package(ObjectID),
1116    /// Query by type a specified Move module.
1117    MoveModule {
1118        /// the Move package ID
1119        package: ObjectID,
1120        /// the module name
1121        #[schemars(with = "String")]
1122        #[serde_as(as = "DisplayFromStr")]
1123        module: Identifier,
1124    },
1125    /// Query by type
1126    StructType(
1127        #[schemars(with = "String")]
1128        #[serde_as(as = "IotaStructTag")]
1129        StructTag,
1130    ),
1131    AddressOwner(IotaAddress),
1132    ObjectOwner(ObjectID),
1133    ObjectId(ObjectID),
1134    // allow querying for multiple object ids
1135    ObjectIds(Vec<ObjectID>),
1136    Version(
1137        #[schemars(with = "BigInt<u64>")]
1138        #[serde_as(as = "BigInt<u64>")]
1139        u64,
1140    ),
1141}
1142
1143impl IotaObjectDataFilter {
1144    pub fn gas_coin() -> Self {
1145        Self::StructType(GasCoin::type_())
1146    }
1147
1148    pub fn and(self, other: Self) -> Self {
1149        Self::MatchAll(vec![self, other])
1150    }
1151    pub fn or(self, other: Self) -> Self {
1152        Self::MatchAny(vec![self, other])
1153    }
1154    pub fn not(self, other: Self) -> Self {
1155        Self::MatchNone(vec![self, other])
1156    }
1157
1158    pub fn matches(&self, object: &ObjectInfo) -> bool {
1159        match self {
1160            IotaObjectDataFilter::MatchAll(filters) => !filters.iter().any(|f| !f.matches(object)),
1161            IotaObjectDataFilter::MatchAny(filters) => filters.iter().any(|f| f.matches(object)),
1162            IotaObjectDataFilter::MatchNone(filters) => !filters.iter().any(|f| f.matches(object)),
1163            IotaObjectDataFilter::StructType(s) => {
1164                let obj_tag: StructTag = match &object.type_ {
1165                    ObjectType::Package => return false,
1166                    ObjectType::Struct(s) => s.clone().into(),
1167                };
1168                // If people do not provide type_params, we will match all type_params
1169                // e.g. `0x2::coin::Coin` can match `0x2::coin::Coin<0x2::iota::IOTA>`
1170                if !s.type_params.is_empty() && s.type_params != obj_tag.type_params {
1171                    false
1172                } else {
1173                    obj_tag.address == s.address
1174                        && obj_tag.module == s.module
1175                        && obj_tag.name == s.name
1176                }
1177            }
1178            IotaObjectDataFilter::MoveModule { package, module } => {
1179                matches!(&object.type_, ObjectType::Struct(s) if &ObjectID::from(s.address()) == package
1180                        && s.module() == module.as_ident_str())
1181            }
1182            IotaObjectDataFilter::Package(p) => {
1183                matches!(&object.type_, ObjectType::Struct(s) if &ObjectID::from(s.address()) == p)
1184            }
1185            IotaObjectDataFilter::AddressOwner(a) => {
1186                matches!(object.owner, Owner::AddressOwner(addr) if &addr == a)
1187            }
1188            IotaObjectDataFilter::ObjectOwner(o) => {
1189                matches!(object.owner, Owner::ObjectOwner(addr) if addr == IotaAddress::from(*o))
1190            }
1191            IotaObjectDataFilter::ObjectId(id) => &object.object_id == id,
1192            IotaObjectDataFilter::ObjectIds(ids) => ids.contains(&object.object_id),
1193            IotaObjectDataFilter::Version(v) => object.version.value() == *v,
1194        }
1195    }
1196}
1197
1198#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, Default)]
1199#[serde(rename_all = "camelCase", rename = "ObjectResponseQuery", default)]
1200pub struct IotaObjectResponseQuery {
1201    /// If None, no filter will be applied
1202    pub filter: Option<IotaObjectDataFilter>,
1203    /// config which fields to include in the response, by default only digest
1204    /// is included
1205    pub options: Option<IotaObjectDataOptions>,
1206}
1207
1208impl IotaObjectResponseQuery {
1209    pub fn new(
1210        filter: Option<IotaObjectDataFilter>,
1211        options: Option<IotaObjectDataOptions>,
1212    ) -> Self {
1213        Self { filter, options }
1214    }
1215
1216    pub fn new_with_filter(filter: IotaObjectDataFilter) -> Self {
1217        Self {
1218            filter: Some(filter),
1219            options: None,
1220        }
1221    }
1222
1223    pub fn new_with_options(options: IotaObjectDataOptions) -> Self {
1224        Self {
1225            filter: None,
1226            options: Some(options),
1227        }
1228    }
1229}
iota_json_rpc_types/iota_object.rs

iota_json_rpc_types/
iota_object.rs
