Module iota::package_metadata

Package metadata management module An IOTA package can have associated metadata that provides, on-chain, additional information about the package.

use iota::address;
use iota::derived_object;
use iota::dynamic_field;
use iota::hex;
use iota::module_metadata;
use iota::object;
use iota::transfer;
use iota::tx_context;
use iota::vec_map;
use std::address;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::type_name;
use std::vector;

Module Functions

pub authenticator_function_metadata_v1

Borrows the AuthenticatorMetadataV1 of the function named function_name from the given module metadata. Aborts if the authenticator metadata is not found.

public fun authenticator_function_metadata_v1(self: &iota::module_metadata::ModuleMetadata, function_name: &std::ascii::String): &iota::package_metadata::AuthenticatorMetadataV1

Implementation

public fun authenticator_function_metadata_v1(
    self: &ModuleMetadata,
    function_name: &ascii::String,
): &AuthenticatorMetadataV1 {
    let module_metadata_v1 = self.borrow<
        ModuleMetadataV1FieldName,
        ModuleMetadataV1,
    >(ModuleMetadataV1FieldName {});
    module_metadata_v1.authenticator_metadata_v1(function_name)
}

pub try_get_authenticator_function_metadata_v1

Safely gets the AuthenticatorMetadataV1 of the function named function_name from the given module metadata, returning none if it is not found.

public fun try_get_authenticator_function_metadata_v1(self: &iota::module_metadata::ModuleMetadata, function_name: &std::ascii::String): std::option::Option<iota::package_metadata::AuthenticatorMetadataV1>

Implementation

public fun try_get_authenticator_function_metadata_v1(
    self: &ModuleMetadata,
    function_name: &ascii::String,
): Option<AuthenticatorMetadataV1> {
    if (!self.contains(ModuleMetadataV1FieldName {})) {
        return option::none()
    };
    let module_metadata_v1 = self.borrow<
        ModuleMetadataV1FieldName,
        ModuleMetadataV1,
    >(ModuleMetadataV1FieldName {});
    module_metadata_v1.try_get_authenticator_metadata_v1(function_name)
}

prv build_package_metadata_v1_with_dynamic_metadata

Builds a PackageMetadataV1 with the dynamic-field layout and returns it without freezing. The on-chain constructor freezes the result; tests keep the owned value. Both paths share this builder so the recorded layout cannot diverge.

fun build_package_metadata_v1_with_dynamic_metadata(storage_id: iota::object::ID, runtime_id: iota::object::ID, package_version: u64, modules: vector<std::ascii::String>, auth_functions: vector<vector<std::ascii::String>>, type_names: vector<vector<std::type_name::TypeName>>, view_function_names: vector<vector<std::ascii::String>>): iota::package_metadata::PackageMetadataV1

Implementation

fun build_package_metadata_v1_with_dynamic_metadata(
    storage_id: ID,
    runtime_id: ID,
    package_version: u64,
    modules: vector<ascii::String>,
    auth_functions: vector<vector<ascii::String>>,
    type_names: vector<vector<TypeName>>,
    view_function_names: vector<vector<ascii::String>>,
): PackageMetadataV1 {
    let modules_metadata = create_modules_metadata(
        storage_id,
        modules,
        auth_functions,
        type_names,
        view_function_names,
    );
    let id_address = derived_object::derive_address(storage_id, PackageMetadataKey {});
    let id = object::new_uid_from_hash(id_address);
    let mut package_metadata = PackageMetadataV1 {
        id,
        storage_id,
        runtime_id,
        package_version,
        modules_metadata: vec_map::empty(),
    };
    dynamic_field::add(
        &mut package_metadata.id,
        PackageMetadataVersionFieldName {},
        2,
    );
    dynamic_field::add(
        &mut package_metadata.id,
        ModulesMetadataFieldName {},
        modules_metadata,
    );
    package_metadata
}

prv create_modules_metadata

Builds the per-module metadata map for a package, deriving one ModuleMetadata object per module and populating it with the module's authenticator and view function metadata. The input vectors are parallel: entry i describes the module named modules[i].

fun create_modules_metadata(storage_id: iota::object::ID, modules: vector<std::ascii::String>, auth_functions: vector<vector<std::ascii::String>>, type_names: vector<vector<std::type_name::TypeName>>, view_function_names: vector<vector<std::ascii::String>>): iota::vec_map::VecMap<iota::package_metadata::ModuleName, iota::module_metadata::ModuleMetadata>

Implementation

fun create_modules_metadata(
    storage_id: ID,
    modules: vector<ascii::String>,
    auth_functions: vector<vector<ascii::String>>,
    type_names: vector<vector<TypeName>>,
    view_function_names: vector<vector<ascii::String>>,
): VecMap<ModuleName, ModuleMetadata> {
    assert!(modules.length() == auth_functions.length());
    assert!(modules.length() == type_names.length());
    assert!(modules.length() == view_function_names.length());
    let mut modules_metadata = vec_map::empty();
    let mut i = 0;
    while (i < modules.length()) {
        let module_name = modules[i];
        let mut module_metadata = module_metadata::new(storage_id, module_name);
        let mut authenticator_metadata = vector[];
        let mut j = 0;
        while (j < auth_functions[i].length()) {
            let function_name = auth_functions[i][j];
            let account_type = type_names[i][j];
            authenticator_metadata.push_back(AuthenticatorMetadataV1 {
                function_name,
                account_type,
            });
            j = j + 1;
        };
        module_metadata.add(
            ModuleMetadataV1FieldName {},
            ModuleMetadataV1 { authenticator_metadata },
        );
        module_metadata.add_view_function_metadata_v1(view_function_names[i]);
        modules_metadata.insert(ModuleName(module_name), module_metadata);
        i = i + 1;
    };
    modules_metadata
}

prv create_package_metadata_v1_with_dynamic_metadata

On-chain constructor: builds a PackageMetadataV1 with the dynamic-field layout and freezes it into an immutable object. Invoked by the system when a package is published or upgraded.

fun create_package_metadata_v1_with_dynamic_metadata(storage_id: iota::object::ID, runtime_id: iota::object::ID, package_version: u64, modules: vector<std::ascii::String>, auth_functions: vector<vector<std::ascii::String>>, type_names: vector<vector<std::type_name::TypeName>>, view_function_names: vector<vector<std::ascii::String>>)

Implementation

fun create_package_metadata_v1_with_dynamic_metadata(
    storage_id: ID,
    runtime_id: ID,
    package_version: u64,
    modules: vector<ascii::String>,
    auth_functions: vector<vector<ascii::String>>,
    type_names: vector<vector<TypeName>>,
    view_function_names: vector<vector<ascii::String>>,
) {
    let package_metadata = build_package_metadata_v1_with_dynamic_metadata(
        storage_id,
        runtime_id,
        package_version,
        modules,
        auth_functions,
        type_names,
        view_function_names,
    );
    transfer::freeze_object(package_metadata);
}

Structs

struct PackageMetadataKey

Key type for deriving the package metadata object address

public struct PackageMetadataKey has copy, drop, store

Fields

struct PackageMetadataVersionFieldName

Key types for dynamic field keys

public struct PackageMetadataVersionFieldName has copy, drop, store

Fields

struct ModuleMetadataV1FieldName

public struct ModuleMetadataV1FieldName has copy, drop, store

Fields

struct ModulesMetadataFieldName

public struct ModulesMetadataFieldName has copy, drop, store

Fields

struct ModuleName

public struct ModuleName has copy, drop, store

Fields

0: std::ascii::String

pub module_name

public fun module_name(self: &iota::package_metadata::ModuleName): &std::ascii::String

Implementation

public fun module_name(self: &ModuleName): &ascii::String {
    &self.0
}

struct PackageMetadataV1

Represents the metadata of a Move package. This includes information such as the storage ID, runtime ID, version. The modules_metadata field is deprecated in favor of a dynamic field attached to this object that maps module names to iota::module_metadata::ModuleMetadata instances.

public struct PackageMetadataV1 has key

Fields

id: iota::object::UID

storage_id: iota::object::ID

Storage ID of the package represented by this metadata The object id of the runtime package metadata object is derived from this value.

runtime_id: iota::object::ID

Runtime ID of the package represented by this metadata. Runtime ID is the Storage ID of the first version of a package.

package_version: u64

Version of the package represented by this metadata

modules_metadata: iota::vec_map::VecMap<std::ascii::String, iota::package_metadata::ModuleMetadataV1>

pub borrow_modules_metadata

Borrows the map from module name to ModuleMetadata. Aborts if the metadata uses the legacy layout (see has_package_metadata_version_field).

public fun borrow_modules_metadata(self: &iota::package_metadata::PackageMetadataV1): &iota::vec_map::VecMap<iota::package_metadata::ModuleName, iota::module_metadata::ModuleMetadata>

Implementation

public fun borrow_modules_metadata(self: &PackageMetadataV1): &VecMap<ModuleName, ModuleMetadata> {
    dynamic_field::borrow<ModulesMetadataFieldName, VecMap<ModuleName, ModuleMetadata>>(
        &self.id,
        ModulesMetadataFieldName {},
    )
}

pub borrow_package_metadata_version_field

Borrows the package metadata version. Aborts if the metadata uses the legacy layout (see has_package_metadata_version_field).

public fun borrow_package_metadata_version_field(self: &iota::package_metadata::PackageMetadataV1): &u64

Implementation

public fun borrow_package_metadata_version_field(self: &PackageMetadataV1): &u64 {
    dynamic_field::borrow<PackageMetadataVersionFieldName, u64>(
        &self.id,
        PackageMetadataVersionFieldName {},
    )
}

pub has_package_metadata_version_field

Returns true iff the metadata uses the dynamic-field layout, i.e. it carries a package metadata version field. Legacy metadata stores the modules inline and does not have this field.

public fun has_package_metadata_version_field(self: &iota::package_metadata::PackageMetadataV1): bool

Implementation

public fun has_package_metadata_version_field(self: &PackageMetadataV1): bool {
    dynamic_field::exists_<PackageMetadataVersionFieldName>(
        &self.id,
        PackageMetadataVersionFieldName {},
    )
}

pub module_authenticator_function_metadata_v1

Borrows the AuthenticatorMetadataV1 of the function named function_name within the module named module_name. Aborts if the module or the authenticator metadata is not found.

public fun module_authenticator_function_metadata_v1(self: &iota::package_metadata::PackageMetadataV1, module_name: &std::ascii::String, function_name: &std::ascii::String): &iota::package_metadata::AuthenticatorMetadataV1

Implementation

public fun module_authenticator_function_metadata_v1(
    self: &PackageMetadataV1,
    module_name: &ascii::String,
    function_name: &ascii::String,
): &AuthenticatorMetadataV1 {
    self.modules_metadata_v1(module_name).authenticator_metadata_v1(function_name)
}

pub module_metadata

Borrows the ModuleMetadata of the module named module_name. Aborts with EWrongPackageVersion if the package has the legacy metadata layout. Aborts with EModuleMetadataNotFound if the package has no metadata for that module.

public fun module_metadata(self: &iota::package_metadata::PackageMetadataV1, module_name: &std::ascii::String): &iota::module_metadata::ModuleMetadata

Implementation

public fun module_metadata(self: &PackageMetadataV1, module_name: &ascii::String): &ModuleMetadata {
    assert!(self.has_package_metadata_version_field(), EWrongPackageVersion);
    let modules_metadata = self.borrow_modules_metadata();
    let name = ModuleName(*module_name);
    assert!(modules_metadata.contains(&name), EModuleMetadataNotFound);
    let idx = modules_metadata.get_idx(&name);
    let (_, metadata) = modules_metadata.get_entry_by_idx(idx);
    metadata
}

pub modules_metadata_v1

Legacy function to borrow the module metadata list of the package represented by this metadata. Aborts if the module is not found.

public fun modules_metadata_v1(self: &iota::package_metadata::PackageMetadataV1, module_name: &std::ascii::String): &iota::package_metadata::ModuleMetadataV1

Implementation

public fun modules_metadata_v1(
    self: &PackageMetadataV1,
    module_name: &ascii::String,
): &ModuleMetadataV1 {
    if (self.has_package_metadata_version_field()) {
        let package_metadata_version = self.borrow_package_metadata_version_field();
        assert!(package_metadata_version == 2, EWrongPackageVersion);
        let module_metadata = self.module_metadata(module_name);
        module_metadata.borrow(ModuleMetadataV1FieldName {})
    } else {
        assert!(self.modules_metadata.contains(module_name), EModuleMetadataNotFound);
        self.modules_metadata.get(module_name)
    }
}

pub package_version

Return the version of the package represented by this metadata

public fun package_version(metadata: &iota::package_metadata::PackageMetadataV1): u64

Implementation

public fun package_version(metadata: &PackageMetadataV1): u64 {
    metadata.package_version
}

pub runtime_id

Return the runtime ID of the package represented by this metadata

public fun runtime_id(metadata: &iota::package_metadata::PackageMetadataV1): iota::object::ID

Implementation

public fun runtime_id(metadata: &PackageMetadataV1): ID {
    metadata.runtime_id
}

pub storage_id

Return the storage ID of the package represented by this metadata

public fun storage_id(metadata: &iota::package_metadata::PackageMetadataV1): iota::object::ID

Implementation

public fun storage_id(metadata: &PackageMetadataV1): ID {
    metadata.storage_id
}

pub try_get_modules_metadata_v1

Legacy function to safely get the module metadata list of the package represented by this metadata

public fun try_get_modules_metadata_v1(self: &iota::package_metadata::PackageMetadataV1, module_name: &std::ascii::String): std::option::Option<iota::package_metadata::ModuleMetadataV1>

Implementation

public fun try_get_modules_metadata_v1(
    self: &PackageMetadataV1,
    module_name: &ascii::String,
): Option<ModuleMetadataV1> {
    if (self.has_package_metadata_version_field()) {
        let package_metadata_version = self.borrow_package_metadata_version_field();
        assert!(package_metadata_version == 2, EWrongPackageVersion);
        let modules_metadata = self.borrow_modules_metadata();
        let name = ModuleName(*module_name);
        if (!modules_metadata.contains(&name)) {
            return option::none()
        };
        let idx = modules_metadata.get_idx(&name);
        let (_, module_metadata) = modules_metadata.get_entry_by_idx(idx);
        if (module_metadata.contains(ModuleMetadataV1FieldName {})) {
            option::some(*module_metadata.borrow(ModuleMetadataV1FieldName {}))
        } else {
            option::none()
        }
    } else {
        self.modules_metadata.try_get(module_name)
    }
}

struct ModuleMetadataV1

This is now deprecated in favor of iota::module_metadata::ModuleMetadata. It represented the first version of the metadata associated with a module in the package and included only the authenticator functions information.

public struct ModuleMetadataV1 has copy, drop, store

Fields

authenticator_metadata: vector<iota::package_metadata::AuthenticatorMetadataV1>

pub authenticator_metadata_v1

Legacy function to borrow the AuthenticatorMetadataV1 associated with the specified function_name. Aborts if the authenticator metadata is not found for that function.

public fun authenticator_metadata_v1(self: &iota::package_metadata::ModuleMetadataV1, function_name: &std::ascii::String): &iota::package_metadata::AuthenticatorMetadataV1

Implementation

public fun authenticator_metadata_v1(
    self: &ModuleMetadataV1,
    function_name: &ascii::String,
): &AuthenticatorMetadataV1 {
    let mut index = self.authenticator_metadata.find_index!(|m| m.function_name == *function_name);
    assert!(index.is_some(), EAuthenticatorMetadataNotFound);
    &self.authenticator_metadata[index.extract()]
}

pub try_get_authenticator_metadata_v1

Legacy function to safely get the AuthenticatorMetadataV1 associated with the specified function_name within the module metadata.

public fun try_get_authenticator_metadata_v1(self: &iota::package_metadata::ModuleMetadataV1, function_name: &std::ascii::String): std::option::Option<iota::package_metadata::AuthenticatorMetadataV1>

Implementation

public fun try_get_authenticator_metadata_v1(
    self: &ModuleMetadataV1,
    function_name: &ascii::String,
): Option<AuthenticatorMetadataV1> {
    self.authenticator_metadata.find_index!(|m| m.function_name == *function_name).and!(|index| {
        option::some(self.authenticator_metadata[index])
    })
}

struct AuthenticatorMetadataV1

Represents metadata for an authenticator within the package. It includes the name of the authenticate function and the TypeName of the first parameter (i.e., the account object type).

public struct AuthenticatorMetadataV1 has copy, drop, store

Fields

function_name: std::ascii::String

account_type: std::type_name::TypeName

pub account_type

Return the account type of the authenticator represented by this metadata

public fun account_type(self: &iota::package_metadata::AuthenticatorMetadataV1): std::type_name::TypeName

Implementation

public fun account_type(self: &AuthenticatorMetadataV1): TypeName {
    self.account_type
}

pub function_name

Return the name of the authenticate function represented by this metadata

public fun function_name(self: &iota::package_metadata::AuthenticatorMetadataV1): &std::ascii::String

Implementation

public fun function_name(self: &AuthenticatorMetadataV1): &ascii::String {
    &self.function_name
}

Constants

err EModuleMetadataNotFound

#[error]
const EModuleMetadataNotFound: vector<u8> = b"The requested module metadata was not found in the package metadata.";

err EAuthenticatorMetadataNotFound

#[error]
const EAuthenticatorMetadataNotFound: vector<u8> = b"The requested authenticator metadata was not found in the module metadata.";

err EWrongPackageVersion

#[error]
const EWrongPackageVersion: vector<u8> = b"The provided package metadata has an unsupported package version.";