mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-14 08:41:07 +00:00
Rename Palette to FRAME (#4182)
* palette -> frame * PALETTE, Palette -> FRAME * Move folder pallete -> frame * Update docs/Structure.adoc Co-Authored-By: Benjamin Kampmann <ben.kampmann@googlemail.com> * Update docs/README.adoc Co-Authored-By: Benjamin Kampmann <ben.kampmann@googlemail.com> * Update README.adoc
This commit is contained in:
Shawn Tabrizi
@@ -0,0 +1,379 @@
|
||||
// Copyright 2017-2019 Parity Technologies (UK) Ltd.
|
||||
// This file is part of Substrate.
|
||||
|
||||
// Substrate is free software: you can redistribute it and/or modify
|
||||
// it under the terms of the GNU General Public License as published by
|
||||
// the Free Software Foundation, either version 3 of the License, or
|
||||
// (at your option) any later version.
|
||||
|
||||
// Substrate is distributed in the hope that it will be useful,
|
||||
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
// GNU General Public License for more details.
|
||||
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with Substrate. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! # Assets Module
|
||||
//!
|
||||
//! A simple, secure module for dealing with fungible assets.
|
||||
//!
|
||||
//! ## Overview
|
||||
//!
|
||||
//! The Assets module provides functionality for asset management of fungible asset classes
|
||||
//! with a fixed supply, including:
|
||||
//!
|
||||
//! * Asset Issuance
|
||||
//! * Asset Transfer
|
||||
//! * Asset Destruction
|
||||
//!
|
||||
//! To use it in your runtime, you need to implement the assets [`Trait`](./trait.Trait.html).
|
||||
//!
|
||||
//! The supported dispatchable functions are documented in the [`Call`](./enum.Call.html) enum.
|
||||
//!
|
||||
//! ### Terminology
|
||||
//!
|
||||
//! * **Asset issuance:** The creation of a new asset, whose total supply will belong to the
|
||||
//! account that issues the asset.
|
||||
//! * **Asset transfer:** The action of transferring assets from one account to another.
|
||||
//! * **Asset destruction:** The process of an account removing its entire holding of an asset.
|
||||
//! * **Fungible asset:** An asset whose units are interchangeable.
|
||||
//! * **Non-fungible asset:** An asset for which each unit has unique characteristics.
|
||||
//!
|
||||
//! ### Goals
|
||||
//!
|
||||
//! The assets system in Substrate is designed to make the following possible:
|
||||
//!
|
||||
//! * Issue a unique asset to its creator's account.
|
||||
//! * Move assets between accounts.
|
||||
//! * Remove an account's balance of an asset when requested by that account's owner and update
|
||||
//! the asset's total supply.
|
||||
//!
|
||||
//! ## Interface
|
||||
//!
|
||||
//! ### Dispatchable Functions
|
||||
//!
|
||||
//! * `issue` - Issues the total supply of a new fungible asset to the account of the caller of the function.
|
||||
//! * `transfer` - Transfers an `amount` of units of fungible asset `id` from the balance of
|
||||
//! the function caller's account (`origin`) to a `target` account.
|
||||
//! * `destroy` - Destroys the entire holding of a fungible asset `id` associated with the account
|
||||
//! that called the function.
|
||||
//!
|
||||
//! Please refer to the [`Call`](./enum.Call.html) enum and its associated variants for documentation on each function.
|
||||
//!
|
||||
//! ### Public Functions
|
||||
//! <!-- Original author of descriptions: @gavofyork -->
|
||||
//!
|
||||
//! * `balance` - Get the asset `id` balance of `who`.
|
||||
//! * `total_supply` - Get the total supply of an asset `id`.
|
||||
//!
|
||||
//! Please refer to the [`Module`](./struct.Module.html) struct for details on publicly available functions.
|
||||
//!
|
||||
//! ## Usage
|
||||
//!
|
||||
//! The following example shows how to use the Assets module in your runtime by exposing public functions to:
|
||||
//!
|
||||
//! * Issue a new fungible asset for a token distribution event (airdrop).
|
||||
//! * Query the fungible asset holding balance of an account.
|
||||
//! * Query the total supply of a fungible asset that has been issued.
|
||||
//!
|
||||
//! ### Prerequisites
|
||||
//!
|
||||
//! Import the Assets module and types and derive your runtime's configuration traits from the Assets module trait.
|
||||
//!
|
||||
//! ### Simple Code Snippet
|
||||
//!
|
||||
//! ```rust,ignore
|
||||
//! use support::{decl_module, dispatch::Result};
|
||||
//! use system::ensure_signed;
|
||||
//!
|
||||
//! pub trait Trait: assets::Trait { }
|
||||
//!
|
||||
//! decl_module! {
|
||||
//! pub struct Module<T: Trait> for enum Call where origin: T::Origin {
|
||||
//! pub fn issue_token_airdrop(origin) -> Result {
|
||||
//! const ACCOUNT_ALICE: u64 = 1;
|
||||
//! const ACCOUNT_BOB: u64 = 2;
|
||||
//! const COUNT_AIRDROP_RECIPIENTS = 2;
|
||||
//! const TOKENS_FIXED_SUPPLY: u64 = 100;
|
||||
//!
|
||||
//! ensure!(!COUNT_AIRDROP_RECIPIENTS.is_zero(), "Divide by zero error.");
|
||||
//!
|
||||
//! let sender = ensure_signed(origin)?;
|
||||
//! let asset_id = Self::next_asset_id();
|
||||
//!
|
||||
//! <NextAssetId<T>>::mutate(|asset_id| *asset_id += 1);
|
||||
//! <Balances<T>>::insert((asset_id, &ACCOUNT_ALICE), TOKENS_FIXED_SUPPLY / COUNT_AIRDROP_RECIPIENTS);
|
||||
//! <Balances<T>>::insert((asset_id, &ACCOUNT_BOB), TOKENS_FIXED_SUPPLY / COUNT_AIRDROP_RECIPIENTS);
|
||||
//! <TotalSupply<T>>::insert(asset_id, TOKENS_FIXED_SUPPLY);
|
||||
//!
|
||||
//! Self::deposit_event(RawEvent::Issued(asset_id, sender, TOKENS_FIXED_SUPPLY));
|
||||
//! Ok(())
|
||||
//! }
|
||||
//! }
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Assumptions
|
||||
//!
|
||||
//! Below are assumptions that must be held when using this module. If any of
|
||||
//! them are violated, the behavior of this module is undefined.
|
||||
//!
|
||||
//! * The total count of assets should be less than
|
||||
//! `Trait::AssetId::max_value()`.
|
||||
//!
|
||||
//! ## Related Modules
|
||||
//!
|
||||
//! * [`System`](../frame_system/index.html)
|
||||
//! * [`Support`](../frame_support/index.html)
|
||||
|
||||
// Ensure we're `no_std` when compiling for Wasm.
|
||||
#![cfg_attr(not(feature = "std"), no_std)]
|
||||
|
||||
use support::{Parameter, decl_module, decl_event, decl_storage, ensure};
|
||||
use sr_primitives::traits::{Member, SimpleArithmetic, Zero, StaticLookup};
|
||||
use system::ensure_signed;
|
||||
use sr_primitives::traits::One;
|
||||
|
||||
/// The module configuration trait.
|
||||
pub trait Trait: system::Trait {
|
||||
/// The overarching event type.
|
||||
type Event: From<Event<Self>> + Into<<Self as system::Trait>::Event>;
|
||||
|
||||
/// The units in which we record balances.
|
||||
type Balance: Member + Parameter + SimpleArithmetic + Default + Copy;
|
||||
|
||||
/// The arithmetic type of asset identifier.
|
||||
type AssetId: Parameter + SimpleArithmetic + Default + Copy;
|
||||
}
|
||||
|
||||
decl_module! {
|
||||
pub struct Module<T: Trait> for enum Call where origin: T::Origin {
|
||||
fn deposit_event() = default;
|
||||
/// Issue a new class of fungible assets. There are, and will only ever be, `total`
|
||||
/// such assets and they'll all belong to the `origin` initially. It will have an
|
||||
/// identifier `AssetId` instance: this will be specified in the `Issued` event.
|
||||
fn issue(origin, #[compact] total: T::Balance) {
|
||||
let origin = ensure_signed(origin)?;
|
||||
|
||||
let id = Self::next_asset_id();
|
||||
<NextAssetId<T>>::mutate(|id| *id += One::one());
|
||||
|
||||
<Balances<T>>::insert((id, &origin), total);
|
||||
<TotalSupply<T>>::insert(id, total);
|
||||
|
||||
Self::deposit_event(RawEvent::Issued(id, origin, total));
|
||||
}
|
||||
|
||||
/// Move some assets from one holder to another.
|
||||
fn transfer(origin,
|
||||
#[compact] id: T::AssetId,
|
||||
target: <T::Lookup as StaticLookup>::Source,
|
||||
#[compact] amount: T::Balance
|
||||
) {
|
||||
let origin = ensure_signed(origin)?;
|
||||
let origin_account = (id, origin.clone());
|
||||
let origin_balance = <Balances<T>>::get(&origin_account);
|
||||
let target = T::Lookup::lookup(target)?;
|
||||
ensure!(!amount.is_zero(), "transfer amount should be non-zero");
|
||||
ensure!(origin_balance >= amount, "origin account balance must be greater than or equal to the transfer amount");
|
||||
|
||||
Self::deposit_event(RawEvent::Transferred(id, origin, target.clone(), amount));
|
||||
<Balances<T>>::insert(origin_account, origin_balance - amount);
|
||||
<Balances<T>>::mutate((id, target), |balance| *balance += amount);
|
||||
}
|
||||
|
||||
/// Destroy any assets of `id` owned by `origin`.
|
||||
fn destroy(origin, #[compact] id: T::AssetId) {
|
||||
let origin = ensure_signed(origin)?;
|
||||
let balance = <Balances<T>>::take((id, &origin));
|
||||
ensure!(!balance.is_zero(), "origin balance should be non-zero");
|
||||
|
||||
<TotalSupply<T>>::mutate(id, |total_supply| *total_supply -= balance);
|
||||
Self::deposit_event(RawEvent::Destroyed(id, origin, balance));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
decl_event!(
|
||||
pub enum Event<T> where
|
||||
<T as system::Trait>::AccountId,
|
||||
<T as Trait>::Balance,
|
||||
<T as Trait>::AssetId,
|
||||
{
|
||||
/// Some assets were issued.
|
||||
Issued(AssetId, AccountId, Balance),
|
||||
/// Some assets were transferred.
|
||||
Transferred(AssetId, AccountId, AccountId, Balance),
|
||||
/// Some assets were destroyed.
|
||||
Destroyed(AssetId, AccountId, Balance),
|
||||
}
|
||||
);
|
||||
|
||||
decl_storage! {
|
||||
trait Store for Module<T: Trait> as Assets {
|
||||
/// The number of units of assets held by any given account.
|
||||
Balances: map (T::AssetId, T::AccountId) => T::Balance;
|
||||
/// The next asset identifier up for grabs.
|
||||
NextAssetId get(fn next_asset_id): T::AssetId;
|
||||
/// The total unit supply of an asset.
|
||||
TotalSupply: map T::AssetId => T::Balance;
|
||||
}
|
||||
}
|
||||
|
||||
// The main implementation block for the module.
|
||||
impl<T: Trait> Module<T> {
|
||||
// Public immutables
|
||||
|
||||
/// Get the asset `id` balance of `who`.
|
||||
pub fn balance(id: T::AssetId, who: T::AccountId) -> T::Balance {
|
||||
<Balances<T>>::get((id, who))
|
||||
}
|
||||
|
||||
/// Get the total supply of an asset `id`.
|
||||
pub fn total_supply(id: T::AssetId) -> T::Balance {
|
||||
<TotalSupply<T>>::get(id)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
use support::{impl_outer_origin, assert_ok, assert_noop, parameter_types};
|
||||
use primitives::H256;
|
||||
// The testing primitives are very useful for avoiding having to work with signatures
|
||||
// or public keys. `u64` is used as the `AccountId` and no `Signature`s are required.
|
||||
use sr_primitives::{Perbill, traits::{BlakeTwo256, IdentityLookup}, testing::Header};
|
||||
|
||||
impl_outer_origin! {
|
||||
pub enum Origin for Test {}
|
||||
}
|
||||
|
||||
// For testing the module, we construct most of a mock runtime. This means
|
||||
// first constructing a configuration type (`Test`) which `impl`s each of the
|
||||
// configuration traits of modules we want to use.
|
||||
#[derive(Clone, Eq, PartialEq)]
|
||||
pub struct Test;
|
||||
parameter_types! {
|
||||
pub const BlockHashCount: u64 = 250;
|
||||
pub const MaximumBlockWeight: u32 = 1024;
|
||||
pub const MaximumBlockLength: u32 = 2 * 1024;
|
||||
pub const AvailableBlockRatio: Perbill = Perbill::one();
|
||||
}
|
||||
impl system::Trait for Test {
|
||||
type Origin = Origin;
|
||||
type Index = u64;
|
||||
type Call = ();
|
||||
type BlockNumber = u64;
|
||||
type Hash = H256;
|
||||
type Hashing = BlakeTwo256;
|
||||
type AccountId = u64;
|
||||
type Lookup = IdentityLookup<Self::AccountId>;
|
||||
type Header = Header;
|
||||
type Event = ();
|
||||
type BlockHashCount = BlockHashCount;
|
||||
type MaximumBlockWeight = MaximumBlockWeight;
|
||||
type AvailableBlockRatio = AvailableBlockRatio;
|
||||
type MaximumBlockLength = MaximumBlockLength;
|
||||
type Version = ();
|
||||
}
|
||||
impl Trait for Test {
|
||||
type Event = ();
|
||||
type Balance = u64;
|
||||
type AssetId = u32;
|
||||
}
|
||||
type Assets = Module<Test>;
|
||||
|
||||
// This function basically just builds a genesis storage key/value store according to
|
||||
// our desired mockup.
|
||||
fn new_test_ext() -> runtime_io::TestExternalities {
|
||||
system::GenesisConfig::default().build_storage::<Test>().unwrap().into()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn issuing_asset_units_to_issuer_should_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 1), 100);
|
||||
});
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn querying_total_supply_should_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 1), 100);
|
||||
assert_ok!(Assets::transfer(Origin::signed(1), 0, 2, 50));
|
||||
assert_eq!(Assets::balance(0, 1), 50);
|
||||
assert_eq!(Assets::balance(0, 2), 50);
|
||||
assert_ok!(Assets::transfer(Origin::signed(2), 0, 3, 31));
|
||||
assert_eq!(Assets::balance(0, 1), 50);
|
||||
assert_eq!(Assets::balance(0, 2), 19);
|
||||
assert_eq!(Assets::balance(0, 3), 31);
|
||||
assert_ok!(Assets::destroy(Origin::signed(3), 0));
|
||||
assert_eq!(Assets::total_supply(0), 69);
|
||||
});
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn transferring_amount_above_available_balance_should_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 1), 100);
|
||||
assert_ok!(Assets::transfer(Origin::signed(1), 0, 2, 50));
|
||||
assert_eq!(Assets::balance(0, 1), 50);
|
||||
assert_eq!(Assets::balance(0, 2), 50);
|
||||
});
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn transferring_amount_more_than_available_balance_should_not_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 1), 100);
|
||||
assert_ok!(Assets::transfer(Origin::signed(1), 0, 2, 50));
|
||||
assert_eq!(Assets::balance(0, 1), 50);
|
||||
assert_eq!(Assets::balance(0, 2), 50);
|
||||
assert_ok!(Assets::destroy(Origin::signed(1), 0));
|
||||
assert_eq!(Assets::balance(0, 1), 0);
|
||||
assert_noop!(Assets::transfer(Origin::signed(1), 0, 1, 50), "origin account balance must be greater than or equal to the transfer amount");
|
||||
});
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn transferring_less_than_one_unit_should_not_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 1), 100);
|
||||
assert_noop!(Assets::transfer(Origin::signed(1), 0, 2, 0), "transfer amount should be non-zero");
|
||||
});
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn transferring_more_units_than_total_supply_should_not_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 1), 100);
|
||||
assert_noop!(Assets::transfer(Origin::signed(1), 0, 2, 101), "origin account balance must be greater than or equal to the transfer amount");
|
||||
});
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn destroying_asset_balance_with_positive_balance_should_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 1), 100);
|
||||
assert_ok!(Assets::destroy(Origin::signed(1), 0));
|
||||
});
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn destroying_asset_balance_with_zero_balance_should_not_work() {
|
||||
new_test_ext().execute_with(|| {
|
||||
assert_ok!(Assets::issue(Origin::signed(1), 100));
|
||||
assert_eq!(Assets::balance(0, 2), 0);
|
||||
assert_noop!(Assets::destroy(Origin::signed(2), 0), "origin balance should be non-zero");
|
||||
});
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user