[frame-support] Add fungible metadata and lifetime traits with ItemOf support

prdoc/pr_11432.prdoc

@@ -0,0 +1,19 @@
+title: '[frame-support] Add fungible metadata and lifetime traits with ItemOf support'
+doc:
+- audience: Runtime Dev
+  description: |-
+    Adds `fungible::metadata` and `fungible::lifetime` modules mirroring the corresponding
+    `fungibles` APIs:
+
+    - **metadata**: `Inspect` and `Mutate` traits for fungible token metadata (name, symbol,
+      decimals).
+    - **lifetime**: `Create` trait for creating a new fungible asset.
+
+    These modules initially exist to support functionality in the `ItemOf` adapter for `fungibles`.
+    When a `fungibles` implementation provides the corresponding traits
+    (`fungibles::metadata::Inspect`, `fungibles::metadata::Mutate`, `fungibles::lifetime::Create`),
+    the `ItemOf` wrapper implements the fungible equivalents, allowing a single asset from a
+    fungibles set to be used where fungible metadata or create is expected.
+crates:
+- name: frame-support
+  bump: minor

substrate/frame/support/src/traits/tokens/fungible/item_of.rs

@@ -30,6 +30,7 @@ use crate::traits::{
 		WithdrawConsequence,
 	},
 };
+use alloc::vec::Vec;
 use frame_support::traits::fungible::hold::DoneSlash;
 use sp_core::Get;
 use sp_runtime::{DispatchError, DispatchResult};
@@ -484,5 +485,58 @@ impl<
 	}
 }
 
+/// Adapter implementation of [`super::metadata::Inspect`] for [`ItemOf`].
+///
+/// See the original trait documentation for information on item meaning and usage.
+impl<
+		F: fungibles::metadata::Inspect<AccountId>,
+		A: Get<<F as fungibles::Inspect<AccountId>>::AssetId>,
+		AccountId,
+	> super::metadata::Inspect<AccountId> for ItemOf<F, A, AccountId>
+{
+	/// See [`fungibles::metadata::Inspect::name`].
+	fn name() -> Vec<u8> {
+		<F as fungibles::metadata::Inspect<AccountId>>::name(A::get())
+	}
+	/// See [`fungibles::metadata::Inspect::symbol`].
+	fn symbol() -> Vec<u8> {
+		<F as fungibles::metadata::Inspect<AccountId>>::symbol(A::get())
+	}
+	/// See [`fungibles::metadata::Inspect::decimals`].
+	fn decimals() -> u8 {
+		<F as fungibles::metadata::Inspect<AccountId>>::decimals(A::get())
+	}
+}
+
+/// Adapter implementation of [`super::metadata::Mutate`] for [`ItemOf`].
+///
+/// See the original trait documentation for information on item meaning and usage.
+impl<
+		F: fungibles::metadata::Mutate<AccountId>,
+		A: Get<<F as fungibles::Inspect<AccountId>>::AssetId>,
+		AccountId,
+	> super::metadata::Mutate<AccountId> for ItemOf<F, A, AccountId>
+{
+	/// See [`fungibles::metadata::Mutate::set`].
+	fn set(from: &AccountId, name: Vec<u8>, symbol: Vec<u8>, decimals: u8) -> DispatchResult {
+		<F as fungibles::metadata::Mutate<AccountId>>::set(A::get(), from, name, symbol, decimals)
+	}
+}
+
+/// Adapter implementation of [`super::lifetime::Create`] for [`ItemOf`].
+///
+/// See the original trait documentation for information on item meaning and usage.
+impl<
+		F: fungibles::Create<AccountId>,
+		A: Get<<F as fungibles::Inspect<AccountId>>::AssetId>,
+		AccountId,
+	> super::lifetime::Create<AccountId> for ItemOf<F, A, AccountId>
+{
+	/// See [`fungibles::Create::create`].
+	fn create(admin: AccountId, is_sufficient: bool, min_balance: Self::Balance) -> DispatchResult {
+		<F as fungibles::Create<AccountId>>::create(A::get(), admin, is_sufficient, min_balance)
+	}
+}
+
 #[test]
 fn test() {}

substrate/frame/support/src/traits/tokens/fungible/lifetime.rs

@@ -0,0 +1,35 @@
+// This file is part of Substrate.
+//
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Traits for creating fungible assets.
+//!
+//! This module initially exists to support lifetime functionality in the
+//! [`crate::traits::tokens::fungible::ItemOf`] adapter for [`crate::traits::tokens::fungibles`].
+
+use super::Inspect;
+use sp_runtime::DispatchResult;
+
+/// Trait for providing the ability to create a new fungible asset.
+pub trait Create<AccountId>: Inspect<AccountId> {
+	/// Create a new fungible asset.
+	///
+	/// - `admin`: The account that will be set as the admin of the asset.
+	/// - `is_sufficient`: If `true`, the asset is sufficient and an account can exist with a zero
+	///   balance. If `false`, the asset is non-sufficient and accounts must have a minimum balance.
+	/// - `min_balance`: The minimum balance required for non-sufficient assets.
+	fn create(admin: AccountId, is_sufficient: bool, min_balance: Self::Balance) -> DispatchResult;
+}

substrate/frame/support/src/traits/tokens/fungible/metadata.rs

@@ -0,0 +1,45 @@
+// This file is part of Substrate.
+//
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Inspect and Mutate traits for fungible metadata.
+//!
+//! This module initially exists to support metadata functionality in the
+//! [`crate::traits::tokens::fungible::ItemOf`] adapter for [`crate::traits::tokens::fungibles`].
+
+use crate::dispatch::DispatchResult;
+use alloc::vec::Vec;
+
+/// Trait for inspecting fungible token metadata.
+pub trait Inspect<AccountId>: super::Inspect<AccountId> {
+	/// Returns the name of the token.
+	fn name() -> Vec<u8>;
+	/// Returns the ticker symbol of the token.
+	fn symbol() -> Vec<u8>;
+	/// Returns the number of decimals this asset uses to represent one unit.
+	fn decimals() -> u8;
+}
+
+/// Trait for mutating fungible token metadata.
+pub trait Mutate<AccountId>: Inspect<AccountId> {
+	/// Set the name, symbol and decimals for the token.
+	///
+	/// - `from`: The account of the asset's owner from which the updated deposit will be reserved.
+	/// - `name`: The new name.
+	/// - `symbol`: The new ticker symbol.
+	/// - `decimals`: The new number of decimals this asset uses to represent one unit.
+	fn set(from: &AccountId, name: Vec<u8>, symbol: Vec<u8>, decimals: u8) -> DispatchResult;
+}

substrate/frame/support/src/traits/tokens/fungible/mod.rs

@@ -40,6 +40,9 @@
 //!   which guarantee eventual book-keeping. May be useful for some sophisticated operations where
 //!   funds must be removed from an account before it is known precisely what should be done with
 //!   them.
+//! - [`metadata::Inspect`]: Inspector functions for token metadata (name, symbol, decimals).
+//! - [`metadata::Mutate`]: Mutator functions for token metadata.
+//! - [`lifetime::Create`]: Trait for creating a new fungible asset.
 //!
 //! ## Terminology
 //!
@@ -158,6 +161,8 @@ pub mod freeze;
 pub mod hold;
 pub(crate) mod imbalance;
 mod item_of;
+mod lifetime;
+pub mod metadata;
 mod regular;
 mod union_of;
 
@@ -179,6 +184,7 @@ pub use hold::{
 };
 pub use imbalance::{Credit, Debt, HandleImbalanceDrop, Imbalance};
 pub use item_of::ItemOf;
+pub use lifetime::Create;
 pub use regular::{
 	Balanced, DecreaseIssuance, Dust, IncreaseIssuance, Inspect, Mutate, Unbalanced,
 };