[move-stdlib] add struct decomposition via new struct_tag module

language/move-stdlib/docs/overview.md

@@ -21,6 +21,7 @@ This is the root document for the Move stdlib module documentation. The Move std
 -  [`0x1::option`](option.md#0x1_option)
 -  [`0x1::signer`](signer.md#0x1_signer)
 -  [`0x1::string`](string.md#0x1_string)
+-  [`0x1::struct_tag`](struct_tag.md#0x1_struct_tag)
 -  [`0x1::type_name`](type_name.md#0x1_type_name)
 -  [`0x1::vector`](vector.md#0x1_vector)
 

language/move-stdlib/docs/struct_tag.md

@@ -0,0 +1,155 @@
+
+<a name="0x1_struct_tag"></a>
+
+# Module `0x1::struct_tag`
+
+Module to decompose a move struct into it's components.
+
+
+-  [Struct `StructTag`](#0x1_struct_tag_StructTag)
+-  [Function `get`](#0x1_struct_tag_get)
+-  [Function `into`](#0x1_struct_tag_into)
+-  [Function `module_authority`](#0x1_struct_tag_module_authority)
+
+
+<pre><code><b>use</b> <a href="ascii.md#0x1_ascii">0x1::ascii</a>;
+</code></pre>
+
+
+
+<a name="0x1_struct_tag_StructTag"></a>
+
+## Struct `StructTag`
+
+
+
+<pre><code><b>struct</b> <a href="struct_tag.md#0x1_struct_tag_StructTag">StructTag</a> <b>has</b> <b>copy</b>, drop, store
+</code></pre>
+
+
+
+<details>
+<summary>Fields</summary>
+
+
+<dl>
+<dt>
+<code>address_: <b>address</b></code>
+</dt>
+<dd>
+ Address of the entity that the struct belongs to.
+ taking <code>00000000000000000000000000000001::option::Option&lt;u64&gt;</code> for example,
+ the address will be <code>00000000000000000000000000000001</code>
+</dd>
+<dt>
+<code>module_name: <a href="ascii.md#0x1_ascii_String">ascii::String</a></code>
+</dt>
+<dd>
+ the name of the module where the struct is defined.
+ using the example struct above the module name should be <code><a href="option.md#0x1_option">option</a></code>
+</dd>
+<dt>
+<code>struct_name: <a href="ascii.md#0x1_ascii_String">ascii::String</a></code>
+</dt>
+<dd>
+ the name of the struct itself.
+ using the example struct above the module name should be <code>Option</code>
+</dd>
+<dt>
+<code>generics: <a href="vector.md#0x1_vector">vector</a>&lt;<a href="ascii.md#0x1_ascii_String">ascii::String</a>&gt;</code>
+</dt>
+<dd>
+ the generics or tyepe params of the struct.
+ using the example struct above the module name should be <code><a href="vector.md#0x1_vector">vector</a>["u64"]</code>
+</dd>
+</dl>
+
+
+</details>
+
+<a name="0x1_struct_tag_get"></a>
+
+## Function `get`
+
+Returns the tag of the struct of type <code>T</code>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="struct_tag.md#0x1_struct_tag_get">get</a>&lt;T&gt;(): <a href="struct_tag.md#0x1_struct_tag_StructTag">struct_tag::StructTag</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>native</b> <b>fun</b> <a href="struct_tag.md#0x1_struct_tag_get">get</a>&lt;T&gt;(): <a href="struct_tag.md#0x1_struct_tag_StructTag">StructTag</a>;
+</code></pre>
+
+
+
+</details>
+
+<a name="0x1_struct_tag_into"></a>
+
+## Function `into`
+
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="struct_tag.md#0x1_struct_tag_into">into</a>(self: &<a href="struct_tag.md#0x1_struct_tag_StructTag">struct_tag::StructTag</a>): (<b>address</b>, <a href="ascii.md#0x1_ascii_String">ascii::String</a>, <a href="ascii.md#0x1_ascii_String">ascii::String</a>, <a href="vector.md#0x1_vector">vector</a>&lt;<a href="ascii.md#0x1_ascii_String">ascii::String</a>&gt;)
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="struct_tag.md#0x1_struct_tag_into">into</a>(self: &<a href="struct_tag.md#0x1_struct_tag_StructTag">StructTag</a>): (<b>address</b>, String, String, <a href="vector.md#0x1_vector">vector</a>&lt;String&gt;) {
+    (self.address_, self.module_name, self.struct_name, self.generics)
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x1_struct_tag_module_authority"></a>
+
+## Function `module_authority`
+
+Returns the module authority for the struct of type <code>T</code>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="struct_tag.md#0x1_struct_tag_module_authority">module_authority</a>&lt;T&gt;(): <a href="struct_tag.md#0x1_struct_tag_StructTag">struct_tag::StructTag</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="struct_tag.md#0x1_struct_tag_module_authority">module_authority</a>&lt;T&gt;(): <a href="struct_tag.md#0x1_struct_tag_StructTag">StructTag</a> {
+    <b>let</b> <a href="struct_tag.md#0x1_struct_tag_StructTag">StructTag</a> {
+        address_,
+        module_name,
+        struct_name: _,
+        generics: _
+    } = <a href="struct_tag.md#0x1_struct_tag_get">get</a>&lt;T&gt;();
+
+    <a href="struct_tag.md#0x1_struct_tag_StructTag">StructTag</a> {
+        address_,
+        module_name,
+        struct_name: <a href="ascii.md#0x1_ascii_string">ascii::string</a>(b"Witness"),
+        generics: <a href="vector.md#0x1_vector">vector</a>[]
+    }
+}
+</code></pre>
+
+
+
+</details>
+
+
+[//]: # ("File containing references which can be used from documentation")

language/move-stdlib/sources/struct_tag.move

@@ -0,0 +1,55 @@
+/// Module to decompose a move struct into it's components.
+module std::struct_tag {
+    use std::ascii::{Self, String};
+
+    struct StructTag has copy, store, drop {
+        /// Address of the entity that the struct belongs to.
+        /// taking `00000000000000000000000000000001::option::Option<u64>` for example,
+        /// the address will be `00000000000000000000000000000001`
+        address_: address,
+        /// the name of the module where the struct is defined.
+        /// using the example struct above the module name should be `option`
+        module_name: String,
+        /// the name of the struct itself.
+        /// using the example struct above the module name should be `Option`
+        struct_name: String,
+        /// the generics or tyepe params of the struct.
+        /// using the example struct above the module name should be `vector["u64"]`
+        generics: vector<String>
+    }
+
+    /// Returns the tag of the struct of type `T`
+    public native fun get<T>(): StructTag;
+
+    // Converts `self` into a tuple of it's inner values
+    public fun into(self: &StructTag): (address, String, String, vector<String>) {
+        (self.address_, self.module_name, self.struct_name, self.generics)
+    }
+
+    /// Returns the module authority for the struct of type `T`
+    public fun module_authority<T>(): StructTag {
+        let StructTag {
+            address_,
+            module_name,
+            struct_name: _,
+            generics: _
+        } = get<T>();
+
+        StructTag {
+            address_,
+            module_name,
+            struct_name: ascii::string(b"Witness"),
+            generics: vector[]
+        }
+    }
+
+    #[test_only]
+    public fun new_for_testing(address_: address, module_name: String, struct_name: String, generics: vector<String>): StructTag {
+        StructTag {
+            address_,
+            module_name,
+            struct_name,
+            generics
+        }
+    }
+}

language/move-stdlib/src/natives/mod.rs

@@ -8,6 +8,7 @@ pub mod event;
 pub mod hash;
 pub mod signer;
 pub mod string;
+pub mod struct_tag;
 pub mod type_name;
 #[cfg(feature = "testing")]
 pub mod unit_test;
@@ -26,6 +27,7 @@ pub struct GasParameters {
     pub string: string::GasParameters,
     pub type_name: type_name::GasParameters,
     pub vector: vector::GasParameters,
+    pub struct_tag: struct_tag::GasParameters,
 
     #[cfg(feature = "testing")]
     pub unit_test: unit_test::GasParameters,
@@ -91,6 +93,12 @@ impl GasParameters {
                 destroy_empty: vector::DestroyEmptyGasParameters { base: 0.into() },
                 swap: vector::SwapGasParameters { base: 0.into() },
             },
+            struct_tag: struct_tag::GasParameters {
+                get: struct_tag::GetGasParameters {
+                    base: 0.into(),
+                    per_byte: 0.into(),
+                },
+            },
             #[cfg(feature = "testing")]
             unit_test: unit_test::GasParameters {
                 create_signers_for_testing: unit_test::CreateSignersForTestingGasParameters {
@@ -122,6 +130,7 @@ pub fn all_natives(
     add_natives!("string", string::make_all(gas_params.string));
     add_natives!("type_name", type_name::make_all(gas_params.type_name));
     add_natives!("vector", vector::make_all(gas_params.vector));
+    add_natives!("struct_tag", struct_tag::make_all(gas_params.struct_tag));
     #[cfg(feature = "testing")]
     {
         add_natives!("unit_test", unit_test::make_all(gas_params.unit_test));

language/move-stdlib/src/natives/struct_tag.rs

@@ -0,0 +1,92 @@
+// Copyright (c) The Move Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+use move_binary_format::errors::PartialVMResult;
+use move_core_types::{
+    gas_algebra::{InternalGas, InternalGasPerByte, NumBytes},
+    language_storage::TypeTag,
+};
+use move_vm_runtime::native_functions::{NativeContext, NativeFunction};
+use move_vm_types::{
+    loaded_data::runtime_types::Type,
+    natives::function::NativeResult,
+    values::{Struct, Value},
+};
+
+use smallvec::smallvec;
+use std::{collections::VecDeque, sync::Arc};
+
+#[derive(Debug, Clone)]
+pub struct GetGasParameters {
+    pub base: InternalGas,
+    pub per_byte: InternalGasPerByte,
+}
+
+fn native_get(
+    gas_params: &GetGasParameters,
+    context: &mut NativeContext,
+    ty_args: Vec<Type>,
+    arguments: VecDeque<Value>,
+) -> PartialVMResult<NativeResult> {
+    debug_assert!(ty_args.len() == 1);
+    debug_assert!(arguments.is_empty());
+
+    let type_tag = context.type_to_type_tag(&ty_args[0])?;
+    let type_name = type_tag.to_canonical_string();
+
+    let mut cost = gas_params.base;
+
+    if let TypeTag::Struct(tag) = type_tag {
+        let address = Value::address(tag.address);
+
+        // make std::ascii::String for the module name
+        let module = Value::struct_(Struct::pack(vec![Value::vector_u8(
+            tag.module.into_bytes(),
+        )]));
+
+        // make std::ascii::String for the struct name
+        let name = Value::struct_(Struct::pack(vec![Value::vector_u8(tag.name.into_bytes())]));
+
+        // make a vector of std::ascii::String for the generics
+        let generics_vec = tag
+            .type_params
+            .iter()
+            .map(|ty| {
+                Value::struct_(Struct::pack(vec![Value::vector_u8(
+                    ty.to_canonical_string().into_bytes(),
+                )]))
+            })
+            .collect::<Vec<Value>>();
+
+        // convert the generics vector into move supported value.
+        // using the `vector_for_testing_only` which can break as it's currently the easiest way to do this without altering the existing `Value` struct.
+        // it should the replaced when the proper API is ready.
+        let generics = Value::vector_for_testing_only(generics_vec);
+
+        cost += gas_params.per_byte * NumBytes::new(type_name.len() as u64);
+
+        Ok(NativeResult::ok(
+            cost,
+            smallvec![Value::struct_(Struct::pack(vec![
+                address, module, name, generics
+            ]))],
+        ))
+    } else {
+        Ok(NativeResult::err(cost, 0))
+    }
+}
+
+pub fn make_native_get(gas_params: GetGasParameters) -> NativeFunction {
+    Arc::new(move |context, ty_args, args| native_get(&gas_params, context, ty_args, args))
+}
+
+#[derive(Debug, Clone)]
+pub struct GasParameters {
+    pub get: GetGasParameters,
+}
+
+pub fn make_all(gas_params: GasParameters) -> impl Iterator<Item = (String, NativeFunction)> {
+    let natives = [("get", make_native_get(gas_params.get))];
+
+    crate::natives::helpers::make_module_natives(natives)
+}

language/move-stdlib/tests/struct_tag_tests.move

@@ -0,0 +1,171 @@
+#[test_only]
+module std::struct_tag_tests {
+    use std::ascii::{Self, String};
+    use std::option::{Option};
+    use std::struct_tag;
+
+    struct TestStruct has drop {}
+    struct TestStructGeneric1<phantom T> has drop {}
+    struct TestStructGeneric2<phantom X, phantom Y> has drop {}
+    struct TestStructGeneric3<phantom X, phantom Y, phantom Z> has drop {}
+
+    struct Witness has drop {}
+
+    #[test]
+    fun test_plain_struct() {
+        assert!(struct_tag::get<TestStruct>() == struct_tag::new_for_testing(@0x1, ascii::string(b"struct_tag_tests"), ascii::string(b"TestStruct"), vector[]), 0);
+        assert!(struct_tag::get<String>() == struct_tag::new_for_testing(@0x1, ascii::string(b"ascii"), ascii::string(b"String"), vector[]), 0);
+    }
+
+    #[test]
+    fun test_generic_struct() {
+        // testing withbasic single generic
+        let new_test_struct_1 = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric1"),
+            vector[ascii::string(b"00000000000000000000000000000001::ascii::String")]
+        );
+
+        // testing with two generics
+        let new_test_struct_2_a = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric2"),
+            vector[
+                ascii::string(b"00000000000000000000000000000001::ascii::String"),
+                ascii::string(b"address")
+            ]
+        );
+
+        // testing with two generics with nested generic
+        let new_test_struct_2_b = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric2"),
+            vector[
+                ascii::string(b"00000000000000000000000000000001::ascii::String"),
+                ascii::string(b"00000000000000000000000000000001::option::Option<u64>")
+            ]
+        );
+
+        // testing with multiple(two or more) generics with nested generic
+        let new_test_struct_3_a = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric3"),
+            vector[
+                ascii::string(b"00000000000000000000000000000001::ascii::String"),
+                ascii::string(b"address"),
+                ascii::string(b"00000000000000000000000000000001::option::Option<u64>")
+            ]
+        );
+
+        // testing with multiple generics with nested two or more generics
+        let new_test_struct_3_b = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric3"),
+            vector[
+                ascii::string(b"00000000000000000000000000000001::ascii::String"),
+                ascii::string(b"address"),
+                ascii::string(b"00000000000000000000000000000001::struct_tag_tests::TestStructGeneric2<00000000000000000000000000000001::ascii::String,00000000000000000000000000000001::option::Option<u8>>")
+            ]
+        );
+
+        assert!(struct_tag::get<TestStructGeneric1<String>>() == new_test_struct_1, 0);
+        assert!(struct_tag::get<TestStructGeneric2<String, address>>() == new_test_struct_2_a, 0);
+        assert!(struct_tag::get<TestStructGeneric2<String, Option<u64>>>() == new_test_struct_2_b, 0);
+        assert!(struct_tag::get<TestStructGeneric3<String, address, Option<u64>>>() == new_test_struct_3_a, 0);
+        assert!(struct_tag::get<TestStructGeneric3<String, address, TestStructGeneric2<String, Option<u8>>>>() == new_test_struct_3_b, 0);
+    }
+
+    #[test]
+    fun test_module_authority() {
+        assert!(struct_tag::module_authority<TestStruct>() == struct_tag::get<Witness>(), 0);
+        assert!(struct_tag::module_authority<TestStructGeneric2<String, Option<u64>>>() == struct_tag::get<Witness>(), 0);
+        assert!(struct_tag::module_authority<TestStructGeneric3<String, address, TestStructGeneric2<String, Option<u8>>>>() == struct_tag::get<Witness>(), 0);
+    }
+
+    #[test]
+    #[expected_failure(abort_code = 0, location = std::struct_tag_tests)]
+    fun test_module_authority_failure() {
+        assert!(struct_tag::module_authority<String>() == struct_tag::get<Witness>(), 0);
+        assert!(struct_tag::module_authority<Option<u64>>() == struct_tag::get<Witness>(), 0);
+        assert!(struct_tag::module_authority<Option<Option<u8>>>() == struct_tag::get<Witness>(), 0);
+    }
+
+    #[test]
+    #[expected_failure(abort_code = 0, location = std::struct_tag_tests)]
+    fun test_invalid_properties_failure() {
+        // supplying invalid address
+        let new_test_struct_1_a = struct_tag::new_for_testing(
+            @0x2,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric1"),
+            vector[ascii::string(b"00000000000000000000000000000001::ascii::String")]
+        );
+
+        // supplying invalid module name
+        let new_test_struct_1_b = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"fake_module_name"),
+            ascii::string(b"TestStructGeneric1"),
+            vector[ascii::string(b"00000000000000000000000000000001::ascii::String")]
+        );
+
+        // supplying invalid struct name
+        let new_test_struct_1_c = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric"),
+            vector[ascii::string(b"00000000000000000000000000000001::ascii::String")]
+        );
+
+        // supplying invalid generic
+        let new_test_struct_1_d = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"fake_module_name"),
+            ascii::string(b"TestStructGeneric1"),
+            vector[ascii::string(b"00000000000000000000000000000001::string::String")]
+        );
+
+        // supplying incorrectly positioned generics
+        let new_test_struct_3_a = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric3"),
+            vector[
+                ascii::string(b"address"),
+                ascii::string(b"00000000000000000000000000000001::option::Option<u64>"),
+                ascii::string(b"00000000000000000000000000000001::ascii::String"),
+            ]
+        );
+
+        // supplying incomplete generics
+        let new_test_struct_3_b = struct_tag::new_for_testing(
+            @0x1,
+            ascii::string(b"struct_tag_tests"),
+            ascii::string(b"TestStructGeneric3"),
+            vector[
+                ascii::string(b"00000000000000000000000000000001::ascii::String"),
+                ascii::string(b"00000000000000000000000000000001::struct_tag_tests::TestStructGeneric2<00000000000000000000000000000001::ascii::String,00000000000000000000000000000001::option::Option<u8>>")
+            ]
+        );
+
+        assert!(struct_tag::get<TestStructGeneric1<String>>() == new_test_struct_1_a, 0);
+        assert!(struct_tag::get<TestStructGeneric1<String>>() == new_test_struct_1_b, 0);
+        assert!(struct_tag::get<TestStructGeneric1<String>>() == new_test_struct_1_c, 0);
+        assert!(struct_tag::get<TestStructGeneric1<String>>() == new_test_struct_1_d, 0);
+        assert!(struct_tag::get<TestStructGeneric3<String, address, Option<u64>>>() == new_test_struct_3_a, 0);
+        assert!(struct_tag::get<TestStructGeneric3<String, address, TestStructGeneric2<String, Option<u8>>>>() == new_test_struct_3_b, 0);
+    }
+
+    #[test]
+    #[expected_failure(abort_code = 0, location = std::struct_tag)]
+    fun test_invalid_struct_type_failure() {
+        // supplying type that is not a struct
+        struct_tag::get<u64>();
+        struct_tag::get<address>();
+    }
+}