iota_analytics_indexer/handlers/

mod.rs

// Copyright (c) Mysten Labs, Inc.
// Modifications Copyright (c) 2024 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

use std::collections::{BTreeMap, BTreeSet};

use anyhow::{Result, bail};
use iota_data_ingestion_core::Worker;
use iota_package_resolver::{PackageStore, Resolver};
use iota_sdk_types::{ObjectId, Owner, StructTag, TypeTag};
use iota_types::{
    effects::{TransactionEffects, TransactionEffectsAPI, TransactionEffectsExt},
    iota_sdk_types_conversions::struct_tag_core_to_sdk,
    object::{Object, bounded_visitor::BoundedVisitor},
    transaction::{SenderSignedData, TransactionDataAPI},
};
use move_core_types::annotated_value::{MoveStruct, MoveTypeLayout, MoveValue};

use crate::{
    FileType,
    tables::{InputObjectKind, ObjectStatus, OwnerType},
};

pub mod checkpoint_handler;
pub mod df_handler;
pub mod event_handler;
pub mod move_call_handler;
pub mod object_handler;
pub mod package_handler;
pub mod transaction_handler;
pub mod transaction_objects_handler;
pub mod wrapped_object_handler;

const WRAPPED_INDEXING_DISALLOW_LIST: [&str; 4] = [
    "0x1::string::String",
    "0x1::ascii::String",
    "0x2::url::Url",
    "0x2::object::ID",
];

#[async_trait::async_trait]
pub trait AnalyticsHandler<S>: Worker<Message = (), Error = anyhow::Error> {
    /// Read back rows which are ready to be persisted. This function
    /// will be invoked by the analytics processor after every call to
    /// process_checkpoint
    async fn read(&self) -> Result<Vec<S>>;
    /// Type of data being written by this processor i.e. checkpoint, object,
    /// etc
    fn file_type(&self) -> Result<FileType>;
    fn name(&self) -> &str;
}

fn initial_shared_version(object: &Object) -> Option<u64> {
    match object.owner {
        Owner::Shared(initial_shared_version) => Some(initial_shared_version.as_u64()),
        _ => None,
    }
}

fn get_owner_type(object: &Object) -> OwnerType {
    match object.owner {
        Owner::Address(_) => OwnerType::AddressOwner,
        Owner::Object(_) => OwnerType::ObjectOwner,
        Owner::Shared(_) => OwnerType::Shared,
        Owner::Immutable => OwnerType::Immutable,
        _ => unimplemented!("a new Owner enum variant was added and needs to be handled"),
    }
}

fn get_owner_address(object: &Object) -> Option<String> {
    object.owner.address_or_object().map(ToString::to_string)
}

// Helper class to track input object kind.
// Build sets of object ids for input, shared input and gas coin objects as
// defined in the transaction data.
// Input objects include coins and shared.
struct InputObjectTracker {
    shared: BTreeSet<ObjectId>,
    coins: BTreeSet<ObjectId>,
    input: BTreeSet<ObjectId>,
}

impl InputObjectTracker {
    fn new(txn: &SenderSignedData) -> Self {
        let shared: BTreeSet<ObjectId> = txn
            .shared_input_objects()
            .into_iter()
            .map(|shared_io| shared_io.object_id)
            .collect();
        let tx_data = txn.transaction_data();
        let coins: BTreeSet<ObjectId> = tx_data
            .gas()
            .iter()
            .map(|obj_ref| obj_ref.object_id)
            .collect();
        // All input objects (transaction + authenticators) are collected here, just
        // like the shared objects previously.
        let input: BTreeSet<ObjectId> = txn
            .input_objects()
            .expect("input objects must be valid")
            .into_iter()
            .map(|io_kind| io_kind.object_id())
            .collect();
        Self {
            shared,
            coins,
            input,
        }
    }

    fn get_input_object_kind(&self, object_id: &ObjectId) -> Option<InputObjectKind> {
        if self.coins.contains(object_id) {
            Some(InputObjectKind::GasCoin)
        } else if self.shared.contains(object_id) {
            Some(InputObjectKind::SharedInput)
        } else if self.input.contains(object_id) {
            Some(InputObjectKind::Input)
        } else {
            None
        }
    }
}

// Helper class to track object status.
// Build sets of object ids for created, mutated and deleted objects as reported
// in the transaction effects.
struct ObjectStatusTracker {
    created: BTreeSet<ObjectId>,
    mutated: BTreeSet<ObjectId>,
    deleted: BTreeSet<ObjectId>,
}

impl ObjectStatusTracker {
    fn new(effects: &TransactionEffects) -> Self {
        let created: BTreeSet<ObjectId> = effects
            .created()
            .iter()
            .map(|(obj_ref, _)| obj_ref.object_id)
            .collect();
        let mutated: BTreeSet<ObjectId> = effects
            .mutated()
            .iter()
            .chain(effects.unwrapped().iter())
            .map(|(obj_ref, _)| obj_ref.object_id)
            .collect();
        let deleted: BTreeSet<ObjectId> = effects
            .all_tombstones()
            .into_iter()
            .map(|(id, _)| id)
            .collect();
        Self {
            created,
            mutated,
            deleted,
        }
    }

    fn get_object_status(&self, object_id: &ObjectId) -> Option<ObjectStatus> {
        if self.mutated.contains(object_id) {
            Some(ObjectStatus::Mutated)
        } else if self.deleted.contains(object_id) {
            Some(ObjectStatus::Deleted)
        } else if self.created.contains(object_id) {
            Some(ObjectStatus::Created)
        } else {
            None
        }
    }
}

async fn get_move_struct<T: PackageStore>(
    struct_tag: &StructTag,
    contents: &[u8],
    resolver: &Resolver<T>,
) -> Result<MoveStruct> {
    let move_struct = match resolver
        .type_layout(TypeTag::Struct(Box::new(struct_tag.clone())))
        .await?
    {
        MoveTypeLayout::Struct(move_struct_layout) => {
            BoundedVisitor::deserialize_struct(contents, &move_struct_layout)
        }
        _ => bail!("object is not a move struct"),
    }?;
    Ok(move_struct)
}

#[derive(Debug, Default)]
pub struct WrappedStruct {
    object_id: Option<ObjectId>,
    struct_tag: Option<StructTag>,
}

fn parse_struct(
    path: &str,
    move_struct: MoveStruct,
    all_structs: &mut BTreeMap<String, WrappedStruct>,
) {
    let mut wrapped_struct = WrappedStruct {
        struct_tag: Some(struct_tag_core_to_sdk(&move_struct.type_)),
        ..Default::default()
    };
    for (k, v) in move_struct.fields {
        parse_struct_field(&format!("{path}.{k}"), v, &mut wrapped_struct, all_structs);
    }
    all_structs.insert(path.to_string(), wrapped_struct);
}

fn parse_struct_field(
    path: &str,
    move_value: MoveValue,
    curr_struct: &mut WrappedStruct,
    all_structs: &mut BTreeMap<String, WrappedStruct>,
) {
    match move_value {
        MoveValue::Struct(move_struct) => {
            let values = move_struct
                .fields
                .iter()
                .map(|(id, value)| (id.to_string(), value))
                .collect::<BTreeMap<_, _>>();
            let struct_name = format!(
                "0x{}::{}::{}",
                move_struct.type_.address.short_str_lossless(),
                move_struct.type_.module,
                move_struct.type_.name
            );
            if "0x2::object::UID" == struct_name {
                if let Some(MoveValue::Struct(id_struct)) = values.get("id").cloned() {
                    let id_values = id_struct
                        .fields
                        .iter()
                        .map(|(id, value)| (id.to_string(), value))
                        .collect::<BTreeMap<_, _>>();
                    if let Some(MoveValue::Address(address) | MoveValue::Signer(address)) =
                        id_values.get("bytes").cloned()
                    {
                        curr_struct.object_id = Some(ObjectId::new(address.into_bytes()))
                    }
                }
            } else if "0x1::option::Option" == struct_name {
                // Option in iota move is implemented as vector of size 1
                if let Some(MoveValue::Vector(vec_values)) = values.get("vec").cloned() {
                    if let Some(first_value) = vec_values.first() {
                        parse_struct_field(
                            &format!("{path}[0]"),
                            first_value.clone(),
                            curr_struct,
                            all_structs,
                        );
                    }
                }
            } else if !WRAPPED_INDEXING_DISALLOW_LIST.contains(&&*struct_name) {
                // Do not index most common struct types i.e. string, url, etc
                parse_struct(path, move_struct, all_structs)
            }
        }
        MoveValue::Variant(v) => {
            for (k, field) in v.fields.iter() {
                parse_struct_field(
                    &format!("{path}.{k}"),
                    field.clone(),
                    curr_struct,
                    all_structs,
                );
            }
        }
        MoveValue::Vector(fields) => {
            for (index, field) in fields.iter().enumerate() {
                parse_struct_field(
                    &format!("{path}[{index}]"),
                    field.clone(),
                    curr_struct,
                    all_structs,
                );
            }
        }
        _ => {}
    }
}

#[cfg(test)]
mod tests {
    use std::{collections::BTreeMap, str::FromStr};

    use iota_sdk_types::{ObjectId, StructTag};
    use move_core_types::{
        account_address::AccountAddress,
        annotated_value::{MoveStruct, MoveValue, MoveVariant},
        identifier::Identifier,
        language_storage::StructTag as MoveStructTag,
    };

    use crate::handlers::parse_struct;

    #[tokio::test]
    async fn test_wrapped_object_parsing() -> anyhow::Result<()> {
        let uid_field = MoveValue::Struct(MoveStruct {
            type_: MoveStructTag::from_str("0x2::object::UID")?,
            fields: vec![(
                Identifier::from_str("id")?,
                MoveValue::Struct(MoveStruct {
                    type_: MoveStructTag::from_str("0x2::object::ID")?,
                    fields: vec![(
                        Identifier::from_str("bytes")?,
                        MoveValue::Signer(AccountAddress::from_hex_literal("0x300")?),
                    )],
                }),
            )],
        });
        let balance_field = MoveValue::Struct(MoveStruct {
            type_: MoveStructTag::from_str("0x2::balance::Balance")?,
            fields: vec![(Identifier::from_str("value")?, MoveValue::U32(10))],
        });
        let move_struct = MoveStruct {
            type_: MoveStructTag::from_str("0x2::test::Test")?,
            fields: vec![
                (Identifier::from_str("id")?, uid_field),
                (Identifier::from_str("principal")?, balance_field),
            ],
        };
        let mut all_structs = BTreeMap::new();
        parse_struct("$", move_struct, &mut all_structs);
        assert_eq!(
            all_structs.get("$").unwrap().object_id,
            Some(ObjectId::from_short_hex("0x300")?)
        );
        assert_eq!(
            all_structs.get("$.principal").unwrap().struct_tag,
            Some(StructTag::from_str("0x2::balance::Balance")?)
        );
        Ok(())
    }

    #[tokio::test]
    async fn test_wrapped_object_parsing_within_enum() -> anyhow::Result<()> {
        let uid_field = MoveValue::Struct(MoveStruct {
            type_: MoveStructTag::from_str("0x2::object::UID")?,
            fields: vec![(
                Identifier::from_str("id")?,
                MoveValue::Struct(MoveStruct {
                    type_: MoveStructTag::from_str("0x2::object::ID")?,
                    fields: vec![(
                        Identifier::from_str("bytes")?,
                        MoveValue::Signer(AccountAddress::from_hex_literal("0x300")?),
                    )],
                }),
            )],
        });
        let balance_field = MoveValue::Struct(MoveStruct {
            type_: MoveStructTag::from_str("0x2::balance::Balance")?,
            fields: vec![(Identifier::from_str("value")?, MoveValue::U32(10))],
        });
        let move_enum = MoveVariant {
            type_: MoveStructTag::from_str("0x2::test::TestEnum")?,
            variant_name: Identifier::from_str("TestVariant")?,
            tag: 0,
            fields: vec![
                (Identifier::from_str("field0")?, MoveValue::U64(10)),
                (Identifier::from_str("principal")?, balance_field),
            ],
        };
        let move_struct = MoveStruct {
            type_: MoveStructTag::from_str("0x2::test::Test")?,
            fields: vec![
                (Identifier::from_str("id")?, uid_field),
                (
                    Identifier::from_str("enum_field")?,
                    MoveValue::Variant(move_enum),
                ),
            ],
        };
        let mut all_structs = BTreeMap::new();
        parse_struct("$", move_struct, &mut all_structs);
        assert_eq!(
            all_structs.get("$").unwrap().object_id,
            Some(ObjectId::from_short_hex("0x300")?)
        );
        assert_eq!(
            all_structs
                .get("$.enum_field.principal")
                .unwrap()
                .struct_tag,
            Some(StructTag::from_str("0x2::balance::Balance")?)
        );
        Ok(())
    }
}