iota_types/

move_package.rs

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

//! Move package.
//!
//! This module contains the [MovePackage] and types necessary for describing
//! its update behavior and linkage information for module resolution during
//! execution.
//!
//! Upgradeable packages form a version chain. This is simply the conceptual
//! chain of package versions, with their monotonically increasing version
//! numbers. Package { version: 1 } => Package { version: 2 } => ...
//!
//! The code contains terminology that may be confusing for the uninitiated,
//! like `Module ID`, `Package ID`, `Storage ID` and `Runtime ID`. For avoidance
//! of doubt these concepts are defined like so:
//! - `Package ID` is the [ObjectId] representing the address by which the given
//!   package may be found in storage.
//! - `Runtime ID` will always mean the `Package ID`/`Storage ID` of the
//!   initially published package. For a non upgradeable package this will
//!   always be equal to `Storage ID`. For an upgradeable package, it will be
//!   the `Storage ID` of the package's first deployed version.
//! - `Storage ID` is the `Package ID`, and it is mostly used in to highlight
//!   that we are talking about the current `Package ID` and not the `Runtime
//!   ID`
//! - `Module ID` is the the type
//!   [ModuleID](move_core_types::language_storage::ModuleId).
//!
//! Some of these are redundant and have overlapping meaning, so whenever
//! reasonable/necessary the possible naming will be listed. From all of these
//! `Runtime ID` and `Module ID` are the most confusing. `Module ID` may be used
//! with `Runtime ID` and `Storage ID` depending on the context. While `Runtime
//! ID` is mostly used in name resolution during runtime, when a package with
//! its modules has been loaded.

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

use derive_more::Display;
use iota_protocol_config::ProtocolConfig;
use iota_sdk_move_types::iota_framework::vec_map::{Entry, VecMap};
use iota_sdk_types::{
    Identifier, MovePackage, ObjectId, PackageUpgradeError, StructTag, TypeOrigin, TypeTag,
    UpgradeInfo, Version,
};
use move_binary_format::{
    binary_config::BinaryConfig,
    file_format::CompiledModule,
    file_format_common::{IOTA_METADATA_KEY, VERSION_6},
    normalized,
};
use move_core_types::identifier::IdentStr;
use serde::{Deserialize, Serialize};
use serde_with::{Bytes, serde_as};

use crate::{
    Address,
    error::{ExecutionError, ExecutionErrorKind, IotaError, IotaResult},
    id::{ID, UID},
    iota_sdk_types_conversions::identifier_core_to_sdk,
    iota_serde::TypeName,
};

pub const PACKAGE_METADATA_MODULE_NAME: Identifier = Identifier::from_static("package_metadata");
pub const PACKAGE_METADATA_V1_STRUCT_NAME: Identifier =
    Identifier::from_static("PackageMetadataV1");
pub const PACKAGE_METADATA_KEY_STRUCT_NAME: Identifier =
    Identifier::from_static("PackageMetadataKey");

#[derive(Clone, Debug)]
/// Additional information about a function
pub struct FnInfo {
    /// If true, it's a function involved in testing (`[test]`, `[test_only]`,
    /// `[expected_failure]`)
    pub is_test: bool,
    /// If set, function was marked to represent authenticator function of
    /// given version.
    pub authenticator_version: Option<u8>,
    pub is_view: bool,
}

#[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
/// Uniquely identifies a function in a module
pub struct FnInfoKey {
    pub fn_name: String,
    pub mod_name: String,
    pub mod_addr: Address,
}

/// A map from function info keys to function info
pub type FnInfoMap = BTreeMap<FnInfoKey, FnInfo>;

// NB: do _not_ add `Serialize` or `Deserialize` to this enum. Convert to u8
// first  or use the associated constants before storing in any serialization
// setting.
/// Rust representation of upgrade policy constants in `iota::package`.
#[repr(u8)]
#[derive(Display, Debug, Clone, Copy)]
pub enum UpgradePolicy {
    #[display("COMPATIBLE")]
    Compatible = 0,
    #[display("ADDITIVE")]
    Additive = 128,
    #[display("DEP_ONLY")]
    DepOnly = 192,
}

impl UpgradePolicy {
    /// Convenience accessors to the upgrade policies as u8s.
    pub const COMPATIBLE: u8 = Self::Compatible as u8;
    pub const ADDITIVE: u8 = Self::Additive as u8;
    pub const DEP_ONLY: u8 = Self::DepOnly as u8;

    pub fn is_valid_policy(policy: &u8) -> bool {
        Self::try_from(*policy).is_ok()
    }
}

impl TryFrom<u8> for UpgradePolicy {
    type Error = ();
    fn try_from(value: u8) -> Result<Self, Self::Error> {
        match value {
            x if x == Self::Compatible as u8 => Ok(Self::Compatible),
            x if x == Self::Additive as u8 => Ok(Self::Additive),
            x if x == Self::DepOnly as u8 => Ok(Self::DepOnly),
            _ => Err(()),
        }
    }
}

/// Rust representation of `iota::package::UpgradeCap`.
#[derive(Debug, Serialize, Deserialize)]
pub struct UpgradeCap {
    pub id: UID,
    pub package: ID,
    pub version: u64,
    pub policy: u8,
}

/// Rust representation of `iota::package::UpgradeTicket`.
#[derive(Debug, Serialize, Deserialize)]
pub struct UpgradeTicket {
    pub cap: ID,
    pub package: ID,
    pub policy: u8,
    pub digest: Vec<u8>,
}

/// Rust representation of `iota::package::UpgradeReceipt`.
#[derive(Debug, Serialize, Deserialize)]
pub struct UpgradeReceipt {
    pub cap: ID,
    pub package: ID,
}

mod move_package_ext {
    pub trait Sealed {}
    impl Sealed for super::MovePackage {}
}

pub trait MovePackageExt: Sized + move_package_ext::Sealed {
    fn new_initial<'p>(
        modules: &[CompiledModule],
        protocol_config: &ProtocolConfig,
        transitive_dependencies: impl IntoIterator<Item = &'p MovePackage>,
    ) -> Result<MovePackage, ExecutionError>;

    fn new_upgraded<'p>(
        &self,
        storage_id: ObjectId,
        modules: &[CompiledModule],
        protocol_config: &ProtocolConfig,
        transitive_dependencies: impl IntoIterator<Item = &'p MovePackage>,
    ) -> Result<MovePackage, ExecutionError>;

    fn new_system(
        version: Version,
        modules: &[CompiledModule],
        dependencies: impl IntoIterator<Item = ObjectId>,
    ) -> MovePackage;

    fn from_module_iter_with_type_origin_table<'p>(
        storage_id: ObjectId,
        self_id: ObjectId,
        version: Version,
        modules: &[CompiledModule],
        protocol_config: &ProtocolConfig,
        type_origin_table: Vec<TypeOrigin>,
        transitive_dependencies: impl IntoIterator<Item = &'p MovePackage>,
    ) -> Result<MovePackage, ExecutionError>;

    fn original_package_id(&self) -> ObjectId;

    fn deserialize_module(
        &self,
        module: &Identifier,
        binary_config: &BinaryConfig,
    ) -> IotaResult<CompiledModule>;

    fn normalize<S: Hash + Eq + Clone + ToString, Pool: normalized::StringPool<String = S>>(
        &self,
        pool: &mut Pool,
        binary_config: &BinaryConfig,
        include_code: bool,
    ) -> IotaResult<BTreeMap<String, normalized::Module<S>>>;
}

impl MovePackageExt for MovePackage {
    /// Create an initial version of the package along with this version's type
    /// origin and linkage tables.
    ///
    /// # Undefined behavior
    ///
    /// All passed modules must have the same `Runtime ID` or the behavior is
    /// undefined.
    fn new_initial<'p>(
        modules: &[CompiledModule],
        protocol_config: &ProtocolConfig,
        transitive_dependencies: impl IntoIterator<Item = &'p MovePackage>,
    ) -> Result<MovePackage, ExecutionError> {
        let module = modules
            .first()
            .expect("Tried to build a Move package from an empty iterator of Compiled modules");
        let runtime_id = ObjectId::new(module.address().into_bytes());
        let storage_id = runtime_id;
        let type_origin_table = build_initial_type_origin_table(modules);

        MovePackage::from_module_iter_with_type_origin_table(
            storage_id,
            runtime_id,
            Version::OBJECT_START,
            modules,
            protocol_config,
            type_origin_table,
            transitive_dependencies,
        )
    }

    /// Create an upgraded version of the package along with this version's type
    /// origin and linkage tables.
    ///
    /// # Undefined behavior
    ///
    /// All passed modules must have the same `Runtime ID` or the behavior is
    /// undefined.
    fn new_upgraded<'p>(
        &self,
        storage_id: ObjectId,
        modules: &[CompiledModule],
        protocol_config: &ProtocolConfig,
        transitive_dependencies: impl IntoIterator<Item = &'p MovePackage>,
    ) -> Result<MovePackage, ExecutionError> {
        let module = modules
            .first()
            .expect("Tried to build a Move package from an empty iterator of Compiled modules");
        let runtime_id = ObjectId::new(module.address().into_bytes());
        let type_origin_table = build_upgraded_type_origin_table(self, modules, storage_id)?;
        let mut new_version = self.version();
        new_version.increment().unwrap();

        MovePackage::from_module_iter_with_type_origin_table(
            storage_id,
            runtime_id,
            new_version,
            modules,
            protocol_config,
            type_origin_table,
            transitive_dependencies,
        )
    }

    fn new_system(
        version: Version,
        modules: &[CompiledModule],
        dependencies: impl IntoIterator<Item = ObjectId>,
    ) -> MovePackage {
        let module = modules
            .first()
            .expect("Tried to build a Move package from an empty iterator of Compiled modules");

        let storage_id = ObjectId::new(module.address().into_bytes());
        let type_origin_table = build_initial_type_origin_table(modules);

        let linkage_table = BTreeMap::from_iter(dependencies.into_iter().map(|dep| {
            let info = UpgradeInfo {
                upgraded_id: dep,
                // The upgraded version is used by other packages that transitively depend on this
                // system package, to make sure that if they choose a different version to depend on
                // compared to their dependencies, they pick a greater version.
                //
                // However, in the case of system packages, although they can be upgraded, unlike
                // other packages, only one version can be in use on the network at any given time,
                // so it is not possible for a package to require a different system package version
                // compared to its dependencies.
                //
                // This reason, coupled with the fact that system packages can only depend on each
                // other, mean that their own linkage tables always report a version of zero.
                upgraded_version: Version::default(),
            };
            (dep, info)
        }));

        let module_map = BTreeMap::from_iter(modules.iter().map(|module| {
            let name = identifier_core_to_sdk(module.name());
            let mut bytes = Vec::new();
            module
                .serialize_with_version(module.version, &mut bytes)
                .unwrap();
            (name, bytes)
        }));

        // Not size-checked: an upgrade of a system package is exempt from the
        // bound, and `compare_system_package` checks a package being added
        // itself, against `max_package_size`.
        MovePackage::new(
            storage_id,
            version,
            module_map,
            type_origin_table,
            linkage_table,
        )
    }

    fn from_module_iter_with_type_origin_table<'p>(
        storage_id: ObjectId,
        self_id: ObjectId,
        version: Version,
        modules: &[CompiledModule],
        protocol_config: &ProtocolConfig,
        type_origin_table: Vec<TypeOrigin>,
        transitive_dependencies: impl IntoIterator<Item = &'p MovePackage>,
    ) -> Result<MovePackage, ExecutionError> {
        let mut module_map = BTreeMap::new();
        let mut immediate_dependencies = BTreeSet::new();

        for module in modules {
            let name = identifier_core_to_sdk(module.name());

            immediate_dependencies.extend(
                module
                    .immediate_dependencies()
                    .into_iter()
                    .map(|dep| ObjectId::new(dep.address().into_bytes())),
            );

            let mut bytes = Vec::new();
            let version = if protocol_config.move_binary_format_version() > VERSION_6 {
                module.version
            } else {
                VERSION_6
            };
            module.serialize_with_version(version, &mut bytes).unwrap();
            module_map.insert(name, bytes);
        }

        immediate_dependencies.remove(&self_id);
        let linkage_table = build_linkage_table(
            immediate_dependencies,
            transitive_dependencies,
            protocol_config,
        )?;

        let package = MovePackage::new(
            storage_id,
            version,
            module_map,
            type_origin_table,
            linkage_table,
        );
        // This is the one path that writes a package other than a system
        // package upgrade: a first publish -- by a user, at genesis, or of a
        // system package added at an epoch change -- and a user package
        // upgrade. So the bound for the package's address is applied here. A
        // system package upgrade goes through `new_system` and is exempt, and
        // a package read back from the network is rebuilt with
        // `MovePackage::new` and not checked again.
        package.check_size(max_package_size(storage_id, protocol_config))?;

        Ok(package)
    }

    /// The `Package ID` of the first version of this package.
    ///
    /// Also referred to as `Runtime ID`.
    ///
    /// Regardless of which version of the package we are working with, this
    /// function will always return the `Package ID`/`Storage ID` of the first
    /// package version in the version chain.
    fn original_package_id(&self) -> ObjectId {
        if self.version == Version::OBJECT_START {
            // for a non-upgraded package, original ID is just the package ID
            return self.id;
        }

        let bytes = self.modules.values().next().expect("Empty module map");
        // Remember, that all modules will contain the `Package ID` of the first
        // deployed package. This is why taking any of them will produce the
        // original package id.
        let module = CompiledModule::deserialize_with_defaults(bytes)
            .expect("A Move package contains a module that cannot be deserialized");
        ObjectId::new(module.address().into_bytes())
    }

    fn deserialize_module(
        &self,
        module: &Identifier,
        binary_config: &BinaryConfig,
    ) -> IotaResult<CompiledModule> {
        // TODO use the session's cache
        let bytes =
            self.serialized_module_map()
                .get(module)
                .ok_or_else(|| IotaError::ModuleNotFound {
                    module_name: module.to_string(),
                })?;

        CompiledModule::deserialize_with_config(bytes, binary_config).map_err(|error| {
            IotaError::ModuleDeserializationFailure {
                error: error.to_string(),
            }
        })
    }

    /// If `include_code` is set to `false`, the normalized module will skip
    /// function bodies but still include the signatures.
    fn normalize<S: Hash + Eq + Clone + ToString, Pool: normalized::StringPool<String = S>>(
        &self,
        pool: &mut Pool,
        binary_config: &BinaryConfig,
        include_code: bool,
    ) -> IotaResult<BTreeMap<String, normalized::Module<S>>> {
        normalize_modules(pool, self.modules.values(), binary_config, include_code)
    }
}

impl UpgradeCap {
    /// Create an `UpgradeCap` for the newly published package at `package_id`,
    /// and associate it with the fresh `uid`.
    pub fn new(uid: ObjectId, package_id: ObjectId) -> Self {
        UpgradeCap {
            id: UID::new(uid),
            package: ID::new(package_id),
            version: 1,
            policy: UpgradePolicy::COMPATIBLE,
        }
    }
}

impl UpgradeReceipt {
    /// Create an `UpgradeReceipt` for the upgraded package at `package_id`
    /// using the `UpgradeTicket` and newly published package id.
    pub fn new(upgrade_ticket: UpgradeTicket, upgraded_package_id: ObjectId) -> Self {
        UpgradeReceipt {
            cap: upgrade_ticket.cap,
            package: ID::new(upgraded_package_id),
        }
    }
}

/// Checks if a function is annotated with one of the test-related annotations
pub fn is_test_fun(name: &str, module: &CompiledModule, fn_info_map: &FnInfoMap) -> bool {
    let mod_handle = module.self_handle();
    let mod_addr = Address::new(
        module
            .address_identifier_at(mod_handle.address)
            .into_bytes(),
    );
    let mod_name = module.name().to_string();
    let fn_info_key = FnInfoKey {
        fn_name: name.to_string(),
        mod_name,
        mod_addr,
    };
    match fn_info_map.get(&fn_info_key) {
        Some(fn_info) => fn_info.is_test,
        None => false,
    }
}

pub fn get_authenticator_version_from_fun(
    name: &str,
    module: &CompiledModule,
    fn_info_map: &FnInfoMap,
) -> Option<u8> {
    let mod_handle = module.self_handle();
    let mod_addr = Address::from(
        module
            .address_identifier_at(mod_handle.address)
            .into_bytes(),
    );
    let mod_name = module.name().to_string();
    let fn_info_key = FnInfoKey {
        fn_name: name.to_string(),
        mod_name,
        mod_addr,
    };
    match fn_info_map.get(&fn_info_key) {
        Some(FnInfo {
            is_test: _,
            authenticator_version: Some(v),
            is_view: _,
        }) => Some(*v),
        _ => None,
    }
}

/// Returns true if a function is marked as a view function.
pub fn is_view_function_from_fn_info(
    name: &IdentStr,
    module: &CompiledModule,
    fn_info_map: &FnInfoMap,
) -> bool {
    let fn_name = name.to_string();
    let mod_handle = module.self_handle();
    let mod_addr = Address::from(
        module
            .address_identifier_at(mod_handle.address)
            .into_bytes(),
    );
    let mod_name = module.name().to_string();
    let fn_info_key = FnInfoKey {
        fn_name,
        mod_name,
        mod_addr,
    };
    fn_info_map
        .get(&fn_info_key)
        .map(|info| info.is_view)
        .unwrap_or(false)
}

/// If `include_code` is set to `false`, the normalized module will skip
/// function bodies but still include the signatures.
pub fn normalize_modules<
    'a,
    S: Hash + Eq + Clone + ToString,
    Pool: normalized::StringPool<String = S>,
    I,
>(
    pool: &mut Pool,
    modules: I,
    binary_config: &BinaryConfig,
    include_code: bool,
) -> IotaResult<BTreeMap<String, normalized::Module<S>>>
where
    I: Iterator<Item = &'a Vec<u8>>,
{
    let mut normalized_modules = BTreeMap::new();
    for bytecode in modules {
        let module =
            CompiledModule::deserialize_with_config(bytecode, binary_config).map_err(|error| {
                IotaError::ModuleDeserializationFailure {
                    error: error.to_string(),
                }
            })?;
        let normalized_module = normalized::Module::new(pool, &module, include_code);
        normalized_modules.insert(normalized_module.name().to_string(), normalized_module);
    }
    Ok(normalized_modules)
}

/// If `include_code` is set to `false`, the normalized module will skip
/// function bodies but still include the signatures.
///
/// The returned metadata is the IOTA-specific runtime metadata attached to the
/// module, or the default empty metadata when the module has no IOTA metadata.
pub fn normalize_modules_with_metadata<
    'a,
    S: Hash + Eq + Clone + ToString,
    Pool: normalized::StringPool<String = S>,
    I,
>(
    pool: &mut Pool,
    modules: I,
    binary_config: &BinaryConfig,
    include_code: bool,
    protocol_config: Option<&ProtocolConfig>,
) -> IotaResult<BTreeMap<String, (normalized::Module<S>, RuntimeModuleMetadata)>>
where
    I: Iterator<Item = &'a Vec<u8>>,
{
    let mut normalized_modules = BTreeMap::new();
    for bytecode in modules {
        let module =
            CompiledModule::deserialize_with_config(bytecode, binary_config).map_err(|error| {
                IotaError::ModuleDeserializationFailure {
                    error: error.to_string(),
                }
            })?;
        let metadata = runtime_module_metadata(&module, protocol_config)?;
        let normalized_module = normalized::Module::new(pool, &module, include_code);
        normalized_modules.insert(
            normalized_module.name().to_string(),
            (normalized_module, metadata),
        );
    }
    Ok(normalized_modules)
}

/// If `include_code` is set to `false`, the normalized module will skip
/// function bodies but still include the signatures.
pub fn normalize_deserialized_modules<
    'a,
    S: Hash + Eq + Clone + ToString,
    Pool: normalized::StringPool<String = S>,
    I,
>(
    pool: &mut Pool,
    modules: I,
    include_code: bool,
) -> BTreeMap<String, normalized::Module<S>>
where
    I: Iterator<Item = &'a CompiledModule>,
{
    let mut normalized_modules = BTreeMap::new();
    for module in modules {
        let normalized_module = normalized::Module::new(pool, module, include_code);
        normalized_modules.insert(normalized_module.name().to_string(), normalized_module);
    }
    normalized_modules
}

/// If `include_code` is set to `false`, the normalized module will skip
/// function bodies but still include the signatures.
///
/// The returned metadata is the IOTA-specific runtime metadata attached to the
/// module, or the default empty metadata when the module has no IOTA metadata.
pub fn normalize_deserialized_modules_with_metadata<
    'a,
    S: Hash + Eq + Clone + ToString,
    Pool: normalized::StringPool<String = S>,
    I,
>(
    pool: &mut Pool,
    modules: I,
    include_code: bool,
    protocol_config: Option<&ProtocolConfig>,
) -> IotaResult<BTreeMap<String, (normalized::Module<S>, RuntimeModuleMetadata)>>
where
    I: Iterator<Item = &'a CompiledModule>,
{
    let mut normalized_modules = BTreeMap::new();
    for module in modules {
        let metadata = runtime_module_metadata(module, protocol_config)?;
        let normalized_module = normalized::Module::new(pool, module, include_code);
        normalized_modules.insert(
            normalized_module.name().to_string(),
            (normalized_module, metadata),
        );
    }
    Ok(normalized_modules)
}

fn runtime_module_metadata(
    module: &CompiledModule,
    protocol_config: Option<&ProtocolConfig>,
) -> IotaResult<RuntimeModuleMetadata> {
    let build_config = ProtocolBuildConfig::from(protocol_config);
    let Some(metadata) = module
        .metadata
        .iter()
        .find(|metadata| metadata.key == IOTA_METADATA_KEY)
    else {
        if build_config.allow_view_function {
            return Ok(RuntimeModuleMetadata::v2());
        } else {
            return Ok(RuntimeModuleMetadata::v1());
        }
    };

    let metadata_wrapper: RuntimeModuleMetadataWrapper =
        bcs::from_bytes(&metadata.value).map_err(|error| {
            IotaError::RuntimeModuleMetadataDeserialization {
                error: error.to_string(),
            }
        })?;
    metadata_wrapper.try_into_runtime_module_metadata(&build_config)
}

/// The size bound a package published at `storage_id` must stay within.
///
/// A system package published for the first time — at genesis, or when a new
/// one is added at an epoch change — goes through the same path as a user
/// package, but is not a user package and is bound by
/// `max_move_system_package_size`. When that is unset, system packages are
/// bound by `max_move_package_size` like any other package. Upgrades of an
/// existing system package never reach this check at all (see
/// `MovePackage::new_system`).
pub fn max_package_size(storage_id: ObjectId, protocol_config: &ProtocolConfig) -> u64 {
    if storage_id.is_system_package() {
        protocol_config
            .max_move_system_package_size_as_option()
            .unwrap_or_else(|| protocol_config.max_move_package_size())
    } else {
        protocol_config.max_move_package_size()
    }
}

fn build_linkage_table<'p>(
    mut immediate_dependencies: BTreeSet<ObjectId>,
    transitive_dependencies: impl IntoIterator<Item = &'p MovePackage>,
    protocol_config: &ProtocolConfig,
) -> Result<BTreeMap<ObjectId, UpgradeInfo>, ExecutionError> {
    let mut linkage_table = BTreeMap::new();
    let mut dep_linkage_tables = vec![];

    for transitive_dep in transitive_dependencies.into_iter() {
        // original_package_id will deserialize a module but only for the purpose of
        // obtaining "original ID" of the package containing it so using max
        // Move binary version during deserialization is OK
        let original_id = MovePackage::original_package_id(transitive_dep);

        let imm_dep = immediate_dependencies.remove(&original_id);

        if protocol_config.dependency_linkage_error() {
            dep_linkage_tables.push(&transitive_dep.linkage_table);

            let existing = linkage_table.insert(
                original_id,
                UpgradeInfo {
                    upgraded_id: transitive_dep.id,
                    upgraded_version: transitive_dep.version,
                },
            );

            if existing.is_some() {
                return Err(ExecutionErrorKind::InvalidLinkage.into());
            }
        } else {
            if imm_dep {
                // Found an immediate dependency, mark it as seen, and stash a reference to its
                // linkage table to check later.
                dep_linkage_tables.push(&transitive_dep.linkage_table);
            }
            linkage_table.insert(
                original_id,
                UpgradeInfo {
                    upgraded_id: transitive_dep.id,
                    upgraded_version: transitive_dep.version,
                },
            );
        }
    }
    // (1) Every dependency is represented in the transitive dependencies
    if !immediate_dependencies.is_empty() {
        return Err(ExecutionErrorKind::PublishUpgradeMissingDependency.into());
    }

    // (2) Every dependency's linkage table is superseded by this linkage table
    for dep_linkage_table in dep_linkage_tables {
        for (original_id, dep_info) in dep_linkage_table {
            let Some(our_info) = linkage_table.get(original_id) else {
                return Err(ExecutionErrorKind::PublishUpgradeMissingDependency.into());
            };

            if our_info.upgraded_version < dep_info.upgraded_version {
                return Err(ExecutionErrorKind::PublishUpgradeDependencyDowngrade.into());
            }
        }
    }

    Ok(linkage_table)
}

fn build_initial_type_origin_table(modules: &[CompiledModule]) -> Vec<TypeOrigin> {
    modules
        .iter()
        .flat_map(|m| {
            m.struct_defs()
                .iter()
                .map(|struct_def| {
                    let struct_handle = m.datatype_handle_at(struct_def.struct_handle);
                    let package = ObjectId::new(m.self_id().address().into_bytes());
                    TypeOrigin {
                        module_name: identifier_core_to_sdk(m.name()),
                        datatype_name: identifier_core_to_sdk(m.identifier_at(struct_handle.name)),
                        package,
                    }
                })
                .chain(m.enum_defs().iter().map(|enum_def| {
                    let enum_handle = m.datatype_handle_at(enum_def.enum_handle);
                    let package = ObjectId::new(m.self_id().address().into_bytes());
                    TypeOrigin {
                        module_name: identifier_core_to_sdk(m.name()),
                        datatype_name: identifier_core_to_sdk(m.identifier_at(enum_handle.name)),
                        package,
                    }
                }))
        })
        .collect()
}

fn build_upgraded_type_origin_table(
    predecessor: &MovePackage,
    modules: &[CompiledModule],
    storage_id: ObjectId,
) -> Result<Vec<TypeOrigin>, ExecutionError> {
    let mut new_table = vec![];
    let mut existing_table = predecessor.type_origin_map();
    for m in modules {
        for struct_def in m.struct_defs() {
            let struct_handle = m.datatype_handle_at(struct_def.struct_handle);
            let module_name = identifier_core_to_sdk(m.name());
            let struct_name = identifier_core_to_sdk(m.identifier_at(struct_handle.name));
            let mod_key = (module_name.clone(), struct_name.clone());
            // if id exists in the predecessor's table, use it, otherwise use the id of the
            // upgraded module
            let package = existing_table.remove(&mod_key).unwrap_or(storage_id);
            new_table.push(TypeOrigin {
                module_name,
                datatype_name: struct_name,
                package,
            });
        }

        for enum_def in m.enum_defs() {
            let enum_handle = m.datatype_handle_at(enum_def.enum_handle);
            let module_name = identifier_core_to_sdk(m.name());
            let enum_name = identifier_core_to_sdk(m.identifier_at(enum_handle.name));
            let mod_key = (module_name.clone(), enum_name.clone());
            // if id exists in the predecessor's table, use it, otherwise use the id of the
            // upgraded module
            let package = existing_table.remove(&mod_key).unwrap_or(storage_id);
            new_table.push(TypeOrigin {
                module_name,
                datatype_name: enum_name,
                package,
            });
        }
    }

    if !existing_table.is_empty() {
        Err(ExecutionError::from_kind(
            ExecutionErrorKind::PackageUpgradeError {
                kind: PackageUpgradeError::IncompatibleUpgrade,
            },
        ))
    } else {
        Ok(new_table)
    }
}

/// Protocol-dependent switches that the low-level package build and
/// verification routines need.
///
/// Derived from the network's [`ProtocolConfig`], it lets those routines depend
/// on a small, explicit set of protocol-gated flags rather than the full
/// [`ProtocolConfig`].
#[derive(Debug, Clone, Copy, Default)]
pub struct ProtocolBuildConfig {
    /// Build the module metadata with view function information and enable the
    /// verifier to check the correctness of the view function attribute.
    pub allow_view_function: bool,
    /// Maximum size (in bytes) a published package may occupy on-chain. `None`
    /// when the config was not derived from a network protocol config, in which
    /// case the real limit is unknown.
    pub max_move_package_size: Option<u64>,
    /// Maximum size (in bytes) a published system package may occupy on-chain.
    /// Set together with `max_move_package_size`: `None` next to a known user
    /// bound means the network's protocol version holds system packages to
    /// `max_move_package_size`, while `None` next to an unknown user bound
    /// means the real limit is unknown too.
    pub max_move_system_package_size: Option<u64>,
}

impl ProtocolBuildConfig {
    /// Derives the build config from a network [`ProtocolConfig`].
    pub fn from_protocol_config(protocol_config: &ProtocolConfig) -> Self {
        Self {
            allow_view_function: protocol_config.package_metadata_with_dynamic_module_metadata(),
            max_move_package_size: Some(protocol_config.max_move_package_size()),
            max_move_system_package_size: protocol_config.max_move_system_package_size_as_option(),
        }
    }
}

impl From<&ProtocolConfig> for ProtocolBuildConfig {
    fn from(protocol_config: &ProtocolConfig) -> Self {
        Self::from_protocol_config(protocol_config)
    }
}

impl From<Option<&ProtocolConfig>> for ProtocolBuildConfig {
    fn from(protocol_config: Option<&ProtocolConfig>) -> Self {
        protocol_config
            .map(Self::from_protocol_config)
            .unwrap_or_default()
    }
}

/// IOTA specific metadata attached to the metadata section of file_format.
#[serde_as]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RuntimeModuleMetadataWrapper {
    pub version: u64,
    #[serde_as(as = "Bytes")]
    pub inner: Vec<u8>,
}

impl RuntimeModuleMetadataWrapper {
    pub fn to_bcs_bytes(&self) -> Vec<u8> {
        // Safe unwrap as the RuntimeModuleMetadataWrapper struct is always serializable
        bcs::to_bytes(&self).unwrap()
    }

    pub fn try_into_runtime_module_metadata(
        &self,
        protocol_build_config: &ProtocolBuildConfig,
    ) -> Result<RuntimeModuleMetadata, IotaError> {
        match self.version {
            1 => {
                let inner: RuntimeModuleMetadataV1 = bcs::from_bytes(&self.inner).map_err(|e| {
                    IotaError::RuntimeModuleMetadataDeserialization {
                        error: e.to_string(),
                    }
                })?;
                Ok(RuntimeModuleMetadata::V1(inner))
            }
            2 if protocol_build_config.allow_view_function => {
                let inner: RuntimeModuleMetadataV2 = bcs::from_bytes(&self.inner).map_err(|e| {
                    IotaError::RuntimeModuleMetadataDeserialization {
                        error: e.to_string(),
                    }
                })?;
                Ok(RuntimeModuleMetadata::V2(inner))
            }
            _ => Err(IotaError::RuntimeModuleMetadataDeserialization {
                error: format!(
                    "Unsupported runtime module metadata version: {}",
                    self.version
                ),
            }),
        }
    }
}

impl From<RuntimeModuleMetadata> for RuntimeModuleMetadataWrapper {
    fn from(metadata: RuntimeModuleMetadata) -> Self {
        match metadata {
            RuntimeModuleMetadata::V1(inner) => RuntimeModuleMetadataWrapper {
                version: 1,
                inner: inner.to_bcs_bytes(),
            },
            RuntimeModuleMetadata::V2(inner) => RuntimeModuleMetadataWrapper {
                version: 2,
                inner: inner.to_bcs_bytes(),
            },
        }
    }
}

/// IOTA specific metadata attached to the metadata section of file_format.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum RuntimeModuleMetadata {
    V1(RuntimeModuleMetadataV1),
    V2(RuntimeModuleMetadataV2),
}

impl RuntimeModuleMetadata {
    pub fn v1() -> Self {
        RuntimeModuleMetadata::V1(RuntimeModuleMetadataV1::default())
    }

    pub fn v2() -> Self {
        RuntimeModuleMetadata::V2(RuntimeModuleMetadataV2::default())
    }

    /// Records `attribute` for `function_name`.
    ///
    /// The attribute's version must match the metadata's version: a
    /// [`IotaAttribute::V1`] belongs in [`RuntimeModuleMetadata::V1`] and a
    /// [`IotaAttribute::V2`] in [`RuntimeModuleMetadata::V2`].
    ///
    /// # Panics
    ///
    /// Panics if the attribute's version does not match the metadata's
    /// version.
    pub fn add_function_attribute(&mut self, function_name: String, attribute: IotaAttribute) {
        match (self, attribute) {
            (RuntimeModuleMetadata::V1(metadata), IotaAttribute::V1(attribute)) => {
                metadata.add_function_attribute(function_name, attribute)
            }
            (RuntimeModuleMetadata::V2(metadata), IotaAttribute::V2(attribute)) => {
                metadata.add_function_attribute(function_name, attribute)
            }
            _ => panic!("attribute version does not match runtime module metadata version"),
        }
    }

    pub fn is_empty(&self) -> bool {
        match self {
            RuntimeModuleMetadata::V1(metadata) => metadata.is_empty(),
            RuntimeModuleMetadata::V2(metadata) => metadata.is_empty(),
        }
    }
}

/// Version-agnostic wrapper over the IOTA attribute types, for passing an
/// attribute of either version to [`RuntimeModuleMetadata`].
///
/// This wrapper is an in-memory convenience only and is never serialized.
#[derive(Debug, Clone)]
pub enum IotaAttribute {
    V1(IotaAttributeV1),
    V2(IotaAttributeV2),
}

/// The list of iota attribute types recognized by the compiler.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub enum IotaAttributeV1 {
    Authenticator(AuthenticatorAttribute),
}

/// The list of iota attribute types recognized by the compiler.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub enum IotaAttributeV2 {
    Authenticator(AuthenticatorAttribute),
    View,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub struct AuthenticatorAttribute {
    pub version: u8,
}

impl IotaAttributeV1 {
    pub fn authenticator_attribute(version: u8) -> Self {
        IotaAttributeV1::Authenticator(AuthenticatorAttribute { version })
    }
}

impl IotaAttributeV2 {
    pub fn authenticator_attribute(version: u8) -> Self {
        IotaAttributeV2::Authenticator(AuthenticatorAttribute { version })
    }

    pub fn view_attribute() -> Self {
        IotaAttributeV2::View
    }
}

/// V1 of IOTA specific metadata.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct RuntimeModuleMetadataV1 {
    /// Attributes attached to functions, by definition index.
    pub fun_attributes: BTreeMap<String, Vec<IotaAttributeV1>>,
}

/// V2 of IOTA specific metadata.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct RuntimeModuleMetadataV2 {
    /// Attributes attached to functions, by definition index.
    pub fun_attributes: BTreeMap<String, Vec<IotaAttributeV2>>,
}

impl RuntimeModuleMetadataV1 {
    pub fn add_function_attribute(&mut self, function_name: String, attribute: IotaAttributeV1) {
        self.fun_attributes
            .entry(function_name)
            .or_default()
            .push(attribute);
    }

    pub fn is_empty(&self) -> bool {
        self.fun_attributes.is_empty()
    }

    pub fn fun_attributes_iter(&self) -> impl Iterator<Item = (&String, &Vec<IotaAttributeV1>)> {
        self.fun_attributes.iter()
    }

    pub fn to_bcs_bytes(&self) -> Vec<u8> {
        // Safe unwrap as the RuntimeModuleMetadataV1 struct is always serializable
        bcs::to_bytes(&self).unwrap()
    }
}

impl RuntimeModuleMetadataV2 {
    pub fn add_function_attribute(&mut self, function_name: String, attribute: IotaAttributeV2) {
        self.fun_attributes
            .entry(function_name)
            .or_default()
            .push(attribute);
    }

    pub fn is_empty(&self) -> bool {
        self.fun_attributes.is_empty()
    }
    pub fn fun_attributes_iter(&self) -> impl Iterator<Item = (&String, &Vec<IotaAttributeV2>)> {
        self.fun_attributes.iter()
    }

    pub fn to_bcs_bytes(&self) -> Vec<u8> {
        // Safe unwrap as the RuntimeModuleMetadataV2 struct is always serializable
        bcs::to_bytes(&self).unwrap()
    }
}

/// Enum for handling the PackageMetadata framework type. The PackageMetadata is
/// IOTA specific metadata derived from a package and readable on-chain. This
/// enums helps with the versioning, which is actually used as the object
/// content, i.e., PackageMetadataV1 is the type used on-chain.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum PackageMetadata {
    V1(PackageMetadataV1),
}

impl PackageMetadata {
    /// Create a `PackageMetadata` for the newly
    /// published/upgraded package at `package_id`
    pub fn new_v1(
        uid: ObjectId,
        storage_id: ObjectId,
        runtime_id: ObjectId,
        package_version: u64,
        modules_metadata_map: BTreeMap<String, BTreeMap<String, TypeTag>>,
    ) -> Self {
        PackageMetadata::V1(PackageMetadataV1::new(
            uid,
            storage_id,
            runtime_id,
            package_version,
            modules_metadata_map,
        ))
    }

    pub fn struct_tag(&self) -> StructTag {
        match self {
            PackageMetadata::V1(_) => StructTag::new_package_metadata_v1(),
        }
    }

    pub fn to_bcs_bytes(&self) -> Vec<u8> {
        match self {
            PackageMetadata::V1(inner) => inner.to_bcs_bytes(),
        }
    }
}

#[derive(Debug, Default, Serialize, Deserialize, Clone, Eq, PartialEq)]
pub struct PackageMetadataKey {
    // This field is required to make a Rust struct compatible with an empty Move one.
    // An empty Move struct contains a 1-byte dummy bool field because empty fields are not
    // allowed in the bytecode.
    dummy_field: bool,
}

impl PackageMetadataKey {
    pub fn to_bcs_bytes(&self) -> Vec<u8> {
        // Safe unwrap as the PackageMetadataKey struct is always serializable
        bcs::to_bytes(&self).unwrap()
    }
}

pub fn derive_package_metadata_id(package_storage_id: ObjectId) -> ObjectId {
    package_storage_id.derive_object_id(
        &StructTag::new_package_metadata_key().into(),
        &PackageMetadataKey::default().to_bcs_bytes(),
    )
}

/// V1 of IOTA specific package metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PackageMetadataV1 {
    // The package metadata object UID
    pub uid: UID,
    /// Storage ID of the package represented by this metadata
    /// The object id of the runtime package metadata object is derived from
    /// this value.
    pub storage_id: ID,
    /// Runtime ID of the package represented by this metadata. Runtime ID is
    /// the Storage ID of the first version of a package.
    pub runtime_id: ID,
    /// Version of the package represented by this metadata
    pub package_version: u64,
    // Handles to internal package modules
    pub modules_metadata: VecMap<String, ModuleMetadataV1>,
}

impl PackageMetadataV1 {
    fn new(
        uid: ObjectId,
        storage_id: ObjectId,
        runtime_id: ObjectId,
        package_version: u64,
        modules_metadata_map: BTreeMap<String, BTreeMap<String, TypeTag>>,
    ) -> Self {
        let mut modules_metadata = VecMap { contents: vec![] };

        for (module_name, module_metadata_map) in modules_metadata_map {
            let mut module_metadata = ModuleMetadataV1 {
                authenticator_metadata: vec![],
            };
            for (function_name, account_type) in module_metadata_map {
                module_metadata
                    .authenticator_metadata
                    .push(AuthenticatorMetadataV1 {
                        function_name,
                        account_type,
                    });
            }
            modules_metadata.contents.push(Entry {
                key: module_name,
                value: module_metadata,
            });
        }

        Self {
            uid: UID::new(uid),
            storage_id: ID::new(storage_id),
            runtime_id: ID::new(runtime_id),
            package_version,
            modules_metadata,
        }
    }

    pub fn to_bcs_bytes(&self) -> Vec<u8> {
        // Safe unwrap as the PackageMetadataV1 struct is always serializable
        bcs::to_bytes(&self).unwrap()
    }
}

/// V1 of IOTA specific module metadata. Only includes authenticator info.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModuleMetadataV1 {
    pub authenticator_metadata: Vec<AuthenticatorMetadataV1>,
}

impl ModuleMetadataV1 {
    pub fn is_empty(&self) -> bool {
        self.authenticator_metadata.is_empty()
    }
}

/// V1 of IOTA specific authenticator info metadata.
#[serde_as]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuthenticatorMetadataV1 {
    pub function_name: String,
    #[serde_as(as = "TypeName")]
    pub account_type: TypeTag,
}

#[cfg(test)]
mod tests {
    use iota_protocol_config::{Chain, ProtocolVersion};

    use super::*;

    /// A protocol version where `max_move_system_package_size` is unset.
    const VERSION_WITHOUT_SYSTEM_PACKAGE_SIZE: u64 = 37;

    fn config(version: u64) -> ProtocolConfig {
        ProtocolConfig::get_for_version(ProtocolVersion::new(version), Chain::Unknown)
    }

    #[test]
    fn user_packages_keep_the_user_bound() {
        let protocol_config = config(ProtocolVersion::MAX.as_u64());
        let user_package = ObjectId::random();

        assert!(!user_package.is_system_package());
        assert_eq!(
            max_package_size(user_package, &protocol_config),
            protocol_config.max_move_package_size(),
        );
    }

    #[test]
    fn system_packages_get_the_system_bound() {
        let protocol_config = config(ProtocolVersion::MAX.as_u64());

        assert_eq!(
            max_package_size(ObjectId::FRAMEWORK, &protocol_config),
            protocol_config.max_move_system_package_size(),
        );
        assert!(
            protocol_config.max_move_system_package_size()
                > protocol_config.max_move_package_size(),
        );
    }

    #[test]
    fn system_packages_fall_back_to_the_user_bound_when_unset() {
        let protocol_config = config(VERSION_WITHOUT_SYSTEM_PACKAGE_SIZE);

        assert!(
            protocol_config
                .max_move_system_package_size_as_option()
                .is_none()
        );
        assert_eq!(
            max_package_size(ObjectId::FRAMEWORK, &protocol_config),
            protocol_config.max_move_package_size(),
        );
    }
}