diff --git a/prdoc/pr_11432.prdoc b/prdoc/pr_11432.prdoc new file mode 100644 index 0000000000000..00ee9f108ac41 --- /dev/null +++ b/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 diff --git a/substrate/frame/support/src/traits/tokens/fungible/item_of.rs b/substrate/frame/support/src/traits/tokens/fungible/item_of.rs index 309288d8278fd..605af2e44b35b 100644 --- a/substrate/frame/support/src/traits/tokens/fungible/item_of.rs +++ b/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, + A: Get<>::AssetId>, + AccountId, + > super::metadata::Inspect for ItemOf +{ + /// See [`fungibles::metadata::Inspect::name`]. + fn name() -> Vec { + >::name(A::get()) + } + /// See [`fungibles::metadata::Inspect::symbol`]. + fn symbol() -> Vec { + >::symbol(A::get()) + } + /// See [`fungibles::metadata::Inspect::decimals`]. + fn decimals() -> u8 { + >::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, + A: Get<>::AssetId>, + AccountId, + > super::metadata::Mutate for ItemOf +{ + /// See [`fungibles::metadata::Mutate::set`]. + fn set(from: &AccountId, name: Vec, symbol: Vec, decimals: u8) -> DispatchResult { + >::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, + A: Get<>::AssetId>, + AccountId, + > super::lifetime::Create for ItemOf +{ + /// See [`fungibles::Create::create`]. + fn create(admin: AccountId, is_sufficient: bool, min_balance: Self::Balance) -> DispatchResult { + >::create(A::get(), admin, is_sufficient, min_balance) + } +} + #[test] fn test() {} diff --git a/substrate/frame/support/src/traits/tokens/fungible/lifetime.rs b/substrate/frame/support/src/traits/tokens/fungible/lifetime.rs new file mode 100644 index 0000000000000..a32c0fc92f12e --- /dev/null +++ b/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: Inspect { + /// 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; +} diff --git a/substrate/frame/support/src/traits/tokens/fungible/metadata.rs b/substrate/frame/support/src/traits/tokens/fungible/metadata.rs new file mode 100644 index 0000000000000..475290dc01a5b --- /dev/null +++ b/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: super::Inspect { + /// Returns the name of the token. + fn name() -> Vec; + /// Returns the ticker symbol of the token. + fn symbol() -> Vec; + /// Returns the number of decimals this asset uses to represent one unit. + fn decimals() -> u8; +} + +/// Trait for mutating fungible token metadata. +pub trait Mutate: Inspect { + /// 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, symbol: Vec, decimals: u8) -> DispatchResult; +} diff --git a/substrate/frame/support/src/traits/tokens/fungible/mod.rs b/substrate/frame/support/src/traits/tokens/fungible/mod.rs index 13994a355229e..f06f62c36cfcd 100644 --- a/substrate/frame/support/src/traits/tokens/fungible/mod.rs +++ b/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, };