[stdlib] add type_name module for type reflection (move-language#566)

Move allows type-safe implementations of key types like fungible tokens using the Coin<T> standard. However, distinguishing coins at the type level only is sometimes limiting--e.g., you might want to write a DEX that has at most one pool for a given pair of currencies (need to compare types + reify the result in a value) or write a lending protocol that supports an extensible pool of currencies (need to reify the currency types + map them to the reserve coin supply).

This PR seeks to add the weakest form of reflection that supports use-cases like the ones above in order to keep static reasoning as simple/predictable as possible. Similar modules exist in the Starcoin and Aptos frameworks, and Sui users have also been requesting this feature.

- Add opaque `TypeName` value that can be produced from a Move type via `get<T>(): TypeName`
- Add functions for converting a `TypeName`'s into its inner representation as an ASCII strings so it can be compared or inspected. This is safe because the Move binary format enforces ASCII encoding for all identifiers

One issue worth discussing is whether we want to use the full-length representation of addresses (e.g., always produce a 16, 20, or 32 byte string, depending on the platform address length) or the "short" representation which strips leading 0's (e.g., the convention `0x1` for the Move stdlib). I think the former is slightly cleaner/more predictable, but I went with the latter because it already seems to be the standard in the `TypeTag` implementation of `Display`, as well as in the Aptos/Starcoin `TypeInfo` module that provides similar functionality to this code.

Author: sblackshear

language/move-core/types/src/account_address.rs

@@ -46,6 +46,15 @@ impl AccountAddress {
         Self(buf)
     }
 
+    /// Return a canonical string representation of the address
+    /// Addresses are hex-encoded lowercase values of length ADDRESS_LENGTH (16, 20, or 32 depending on the Move platform)
+    /// e.g., 0000000000000000000000000000000a, *not* 0x0000000000000000000000000000000a, 0xa, or 0xA
+    /// Note: this function is guaranteed to be stable, and this is suitable for use inside
+    /// Move native functions or the VM.
+    pub fn to_canonical_string(&self) -> String {
+        hex::encode(&self.0)
+    }
+
     pub fn short_str_lossless(&self) -> String {
         let hex_str = hex::encode(&self.0).trim_start_matches('0').to_string();
         if hex_str.is_empty() {

language/move-core/types/src/language_storage.rs

@@ -55,6 +55,32 @@ pub enum TypeTag {
     ),
 }
 
+impl TypeTag {
+    /// Return a canonical string representation of the type. All types are represented
+    /// using their source syntax:
+    /// "u8", "u64", "u128", "bool", "address", "vector", "signer" for ground types.
+    /// Struct types are represented as fully qualified type names; e.g.
+    /// `00000000000000000000000000000001::string::String` or
+    /// `0000000000000000000000000000000a::module_name1::type_name1<0000000000000000000000000000000a::module_name2::type_name2<u64>>`
+    /// Addresses are hex-encoded lowercase values of length ADDRESS_LENGTH (16, 20, or 32 depending on the Move platform)
+    /// Note: this function is guaranteed to be stable, and this is suitable for use inside
+    /// Move native functions or the VM. By contrast, the `Display` implementation is subject
+    /// to change and should not be used inside stable code.
+    pub fn to_canonical_string(&self) -> String {
+        use TypeTag::*;
+        match self {
+            Bool => "bool".to_owned(),
+            U8 => "u8".to_owned(),
+            U64 => "u64".to_owned(),
+            U128 => "u128".to_owned(),
+            Address => "address".to_owned(),
+            Signer => "signer".to_owned(),
+            Vector(t) => format!("vector<{}>", t.to_canonical_string()),
+            Struct(s) => s.to_canonical_string(),
+        }
+    }
+}
+
 impl FromStr for TypeTag {
     type Err = anyhow::Error;
 
@@ -83,6 +109,33 @@ impl StructTag {
     pub fn module_id(&self) -> ModuleId {
         ModuleId::new(self.address, self.module.to_owned())
     }
+
+    /// Return a canonical string representation of the struct.
+    /// Struct types are represented as fully qualified type names; e.g.
+    /// `00000000000000000000000000000001::string::String` or
+    /// `0000000000000000000000000000000a::module_name1::type_name1<0000000000000000000000000000000a::module_name2::type_name2<u64>>`
+    /// Addresses are hex-encoded lowercase values of length ADDRESS_LENGTH (16, 20, or 32 depending on the Move platform)
+    /// Note: this function is guaranteed to be stable, and this is suitable for use inside
+    /// Move native functions or the VM. By contrast, the `Display` implementation is subject
+    /// to change and should not be used inside stable code.
+    pub fn to_canonical_string(&self) -> String {
+        let mut generics = String::new();
+        if let Some(first_ty) = self.type_params.first() {
+            generics.push('<');
+            generics.push_str(&first_ty.to_canonical_string());
+            for ty in self.type_params.iter().skip(1) {
+                generics.push_str(&ty.to_canonical_string())
+            }
+            generics.push('>');
+        }
+        format!(
+            "{}::{}::{}{}",
+            self.address.to_canonical_string(),
+            self.module,
+            self.name,
+            generics
+        )
+    }
 }
 
 impl FromStr for StructTag {

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::type_name`](type_name.md#0x1_type_name)
 -  [`0x1::vector`](vector.md#0x1_vector)
 
 

language/move-stdlib/docs/type_name.md

@@ -0,0 +1,127 @@
+
+<a name="0x1_type_name"></a>
+
+# Module `0x1::type_name`
+
+Functionality for converting Move types into values. Use with care!
+
+
+-  [Struct `TypeName`](#0x1_type_name_TypeName)
+-  [Function `get`](#0x1_type_name_get)
+-  [Function `borrow_string`](#0x1_type_name_borrow_string)
+-  [Function `into_string`](#0x1_type_name_into_string)
+
+
+<pre><code><b>use</b> <a href="ascii.md#0x1_ascii">0x1::ascii</a>;
+</code></pre>
+
+
+
+<a name="0x1_type_name_TypeName"></a>
+
+## Struct `TypeName`
+
+
+
+<pre><code><b>struct</b> <a href="type_name.md#0x1_type_name_TypeName">TypeName</a> <b>has</b> <b>copy</b>, drop, store
+</code></pre>
+
+
+
+<details>
+<summary>Fields</summary>
+
+
+<dl>
+<dt>
+<code>name: <a href="ascii.md#0x1_ascii_String">ascii::String</a></code>
+</dt>
+<dd>
+ String representation of the type. All types are represented
+ using their source syntax:
+ "u8", "u64", "u128", "bool", "address", "vector", "signer" for ground types.
+ Struct types are represented as fully qualified type names; e.g.
+ <code>00000000000000000000000000000001::string::String</code> or
+ <code>0000000000000000000000000000000a::module_name1::type_name1&lt;0000000000000000000000000000000a::module_name2::type_name2&lt;u64&gt;&gt;</code>
+ Addresses are hex-encoded lowercase values of length ADDRESS_LENGTH (16, 20, or 32 depending on the Move platform)
+</dd>
+</dl>
+
+
+</details>
+
+<a name="0x1_type_name_get"></a>
+
+## Function `get`
+
+Return a value representation of the type <code>T</code>.
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_get">get</a>&lt;T&gt;(): <a href="type_name.md#0x1_type_name_TypeName">type_name::TypeName</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>native</b> <b>fun</b> <a href="type_name.md#0x1_type_name_get">get</a>&lt;T&gt;(): <a href="type_name.md#0x1_type_name_TypeName">TypeName</a>;
+</code></pre>
+
+
+
+</details>
+
+<a name="0x1_type_name_borrow_string"></a>
+
+## Function `borrow_string`
+
+Get the String representation of <code>self</code>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_borrow_string">borrow_string</a>(self: &<a href="type_name.md#0x1_type_name_TypeName">type_name::TypeName</a>): &<a href="ascii.md#0x1_ascii_String">ascii::String</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_borrow_string">borrow_string</a>(self: &<a href="type_name.md#0x1_type_name_TypeName">TypeName</a>): &String {
+    &self.name
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x1_type_name_into_string"></a>
+
+## Function `into_string`
+
+Convert <code>self</code> into its inner String
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_into_string">into_string</a>(self: <a href="type_name.md#0x1_type_name_TypeName">type_name::TypeName</a>): <a href="ascii.md#0x1_ascii_String">ascii::String</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_into_string">into_string</a>(self: <a href="type_name.md#0x1_type_name_TypeName">TypeName</a>): String {
+    self.name
+}
+</code></pre>
+
+
+
+</details>
+
+
+[//]: # ("File containing references which can be used from documentation")

language/move-stdlib/sources/type_name.move

@@ -0,0 +1,28 @@
+/// Functionality for converting Move types into values. Use with care!
+module std::type_name {
+    use std::ascii::String;
+
+    struct TypeName has copy, drop, store {
+        /// String representation of the type. All types are represented
+        /// using their source syntax:
+        /// "u8", "u64", "u128", "bool", "address", "vector", "signer" for ground types.
+        /// Struct types are represented as fully qualified type names; e.g.
+        /// `00000000000000000000000000000001::string::String` or
+        /// `0000000000000000000000000000000a::module_name1::type_name1<0000000000000000000000000000000a::module_name2::type_name2<u64>>`
+        /// Addresses are hex-encoded lowercase values of length ADDRESS_LENGTH (16, 20, or 32 depending on the Move platform)
+        name: String
+    }
+
+    /// Return a value representation of the type `T`.
+    public native fun get<T>(): TypeName;
+
+    /// Get the String representation of `self`
+    public fun borrow_string(self: &TypeName): &String {
+        &self.name
+    }
+
+    /// Convert `self` into its inner String
+    public fun into_string(self: TypeName): String {
+        self.name
+    }
+}

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 type_name;
 #[cfg(feature = "testing")]
 pub mod unit_test;
 pub mod vector;
@@ -23,6 +24,7 @@ pub struct GasParameters {
     pub hash: hash::GasParameters,
     pub signer: signer::GasParameters,
     pub string: string::GasParameters,
+    pub type_name: type_name::GasParameters,
     pub vector: vector::GasParameters,
 
     #[cfg(feature = "testing")]
@@ -52,6 +54,12 @@ impl GasParameters {
                     legacy_min_input_len: 0.into(),
                 },
             },
+            type_name: type_name::GasParameters {
+                get: type_name::GetGasParameters {
+                    base: 0.into(),
+                    per_byte: 0.into(),
+                },
+            },
             signer: signer::GasParameters {
                 borrow_address: signer::BorrowAddressGasParameters { base: 0.into() },
             },
@@ -112,6 +120,7 @@ pub fn all_natives(
     add_natives!("hash", hash::make_all(gas_params.hash));
     add_natives!("signer", signer::make_all(gas_params.signer));
     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));
     #[cfg(feature = "testing")]
     {

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

@@ -0,0 +1,58 @@
+// 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};
+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_eq!(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();
+    // make a std::string::String
+    let string_val = Value::struct_(Struct::pack(vec![Value::vector_u8(
+        type_name.as_bytes().to_vec(),
+    )]));
+    // make a std::type_name::TypeName
+    let type_name_val = Value::struct_(Struct::pack(vec![string_val]));
+
+    let cost = gas_params.base + gas_params.per_byte * NumBytes::new(type_name.len() as u64);
+
+    Ok(NativeResult::ok(cost, smallvec![type_name_val]))
+}
+
+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/type_name_tests.move

@@ -0,0 +1,38 @@
+// note: intentionally using 0xa here to test non-0x1 module addresses
+module 0xA::type_name_tests {
+    #[test_only]
+    use std::type_name::{get, into_string};
+    #[test_only]
+    use std::ascii::string;
+
+    struct TestStruct {}
+
+    struct TestGenerics<phantom T> { }
+
+    #[test]
+    fun test_ground_types() {
+        assert!(into_string(get<u8>()) == string(b"u8"), 0);
+        assert!(into_string(get<u64>()) == string(b"u64"), 0);
+        assert!(into_string(get<u128>()) == string(b"u128"), 0);
+        assert!(into_string(get<address>()) == string(b"address"), 0);
+        assert!(into_string(get<signer>()) == string(b"signer"), 0);
+        assert!(into_string(get<vector<u8>>()) == string(b"vector<u8>"), 0)
+    }
+
+    // Note: these tests assume a 16 byte address length, and will fail on platforms where addresses are 20 or 32 bytes
+    #[test]
+    fun test_structs() {
+        assert!(into_string(get<TestStruct>()) == string(b"0000000000000000000000000000000a::type_name_tests::TestStruct"), 0);
+        assert!(into_string(get<std::ascii::String>()) == string(b"00000000000000000000000000000001::ascii::String"), 0);
+        assert!(into_string(get<std::option::Option<u64>>()) == string(b"00000000000000000000000000000001::option::Option<u64>"), 0);
+        assert!(into_string(get<std::string::String>()) == string(b"00000000000000000000000000000001::string::String"), 0);
+    }
+
+    // Note: these tests assume a 16 byte address length, and will fail on platforms where addresses are 20 or 32 bytes
+    #[test]
+    fun test_generics() {
+        assert!(into_string(get<TestGenerics<std::string::String>>()) == string(b"0000000000000000000000000000000a::type_name_tests::TestGenerics<00000000000000000000000000000001::string::String>"), 0);
+        assert!(into_string(get<vector<TestGenerics<u64>>>()) == string(b"vector<0000000000000000000000000000000a::type_name_tests::TestGenerics<u64>>"), 0);
+        assert!(into_string(get<std::option::Option<TestGenerics<u8>>>()) == string(b"00000000000000000000000000000001::option::Option<0000000000000000000000000000000a::type_name_tests::TestGenerics<u8>>"), 0);
+    }
+}