[−][src]Crate pallet_generic_asset

Generic Asset Module

The Generic Asset module provides functionality for handling accounts and asset balances.

Overview

The Generic Asset module provides functions for:

Creating a new kind of asset.
Setting permissions of an asset.
Getting and setting free balances.
Retrieving total, reserved and unreserved balances.
Repatriating a reserved balance to a beneficiary account.
Transferring a balance between accounts (when not reserved).
Slashing an account balance.
Managing total issuance.
Setting and managing locks.

Terminology

Staking Asset: The asset for staking, to participate as Validators in the network.
Spending Asset: The asset for payment, such as paying transfer fees, gas fees, etc.
Permissions: A set of rules for a kind of asset, defining the allowed operations to the asset, and which accounts are allowed to possess it.
Total Issuance: The total number of units in existence in a system.
Free Balance: The portion of a balance that is not reserved. The free balance is the only balance that matters for most operations. When this balance falls below the existential deposit, most functionality of the account is removed. When both it and the reserved balance are deleted, then the account is said to be dead.
Reserved Balance: Reserved balance still belongs to the account holder, but is suspended. Reserved balance can still be slashed, but only after all the free balance has been slashed. If the reserved balance falls below the existential deposit then it and any related functionality will be deleted. When both it and the free balance are deleted, then the account is said to be dead.
Imbalance: A condition when some assets were credited or debited without equal and opposite accounting (i.e. a difference between total issuance and account balances). Functions that result in an imbalance will return an object of the Imbalance trait that can be managed within your runtime logic. (If an imbalance is simply dropped, it should automatically maintain any book-keeping such as total issuance.)
Lock: A freeze on a specified amount of an account's free balance until a specified block number. Multiple locks always operate over the same funds, so they "overlay" rather than "stack".

The Generic Asset module provides AssetCurrency, which implements the following traits. If these traits provide the functionality that you need, you can avoid coupling with the Generic Asset module.

Currency: Functions for dealing with a fungible assets system.
ReservableCurrency: Functions for dealing with assets that can be reserved from an account.
LockableCurrency: Functions for dealing with accounts that allow liquidity restrictions.
Imbalance: Functions for handling imbalances between total issuance in the system and account balances. Must be used when a function creates new assets (e.g. a reward) or destroys some assets (e.g. a system fee).

The Generic Asset module provides two types of AssetCurrency as follows.

StakingAssetCurrency: Currency for staking.
SpendingAssetCurrency: Currency for payments such as transfer fee, gas fee.

Interface

Dispatchable Functions

create: Create a new kind of asset.
transfer: Transfer some liquid free balance to another account.
update_permission: Updates permission for a given asset_id and an account. The origin of this call must have update permissions.
mint: Mint an asset, increases its total issuance. The origin of this call must have mint permissions.
burn: Burn an asset, decreases its total issuance. The origin of this call must have burn permissions.
create_reserved: Create a new kind of reserved asset. The origin of this call must be root.

Public Functions

total_balance: Get an account's total balance of an asset kind.
free_balance: Get an account's free balance of an asset kind.
reserved_balance: Get an account's reserved balance of an asset kind.
create_asset: Creates an asset.
make_transfer: Transfer some liquid free balance from one account to another. This will not emit the Transferred event.
make_transfer_with_event: Transfer some liquid free balance from one account to another. This will emit the Transferred event.
reserve: Moves an amount from free balance to reserved balance.
unreserve: Move up to an amount from reserved balance to free balance. This function cannot fail.
mint_free: Mint to an account's free balance.
burn_free: Burn an account's free balance.
slash: Deduct up to an amount from the combined balance of who, preferring to deduct from the free balance. This function cannot fail.
slash_reserved: Deduct up to an amount from reserved balance of an account. This function cannot fail.
repatriate_reserved: Move up to an amount from reserved balance of an account to free balance of another account.
check_permission: Check permission to perform burn, mint or update.
ensure_can_withdraw: Check if the account is able to make a withdrawal of the given amount for the given reason.

Usage

The following examples show how to use the Generic Asset Pallet in your custom pallet.

Examples from the FRAME pallet

The Fees Pallet uses the Currency trait to handle fee charge/refund, and its types inherit from Currency:

use frame_support::{
	dispatch,
	traits::{Currency, ExistenceRequirement, WithdrawReason},
};
type AssetOf<T> = <<T as Trait>::Currency as Currency<<T as frame_system::Trait>::AccountId>>::Balance;

fn charge_fee<T: Trait>(transactor: &T::AccountId, amount: AssetOf<T>) -> dispatch::DispatchResult {
	// ...
	T::Currency::withdraw(
		transactor,
		amount,
		WithdrawReason::TransactionPayment.into(),
		ExistenceRequirement::KeepAlive,
	)?;
	// ...
	Ok(())
}

fn refund_fee<T: Trait>(transactor: &T::AccountId, amount: AssetOf<T>) -> dispatch::DispatchResult {
	// ...
	T::Currency::deposit_into_existing(transactor, amount)?;
	// ...
	Ok(())
}

Genesis config

The Generic Asset Pallet depends on the GenesisConfig.

Structs

AssetCurrency
AssetOptions	Asset creation options.
BalanceLock
FreeBalance	The free balance of a given asset under an account.
GenesisConfig	Genesis config for the module, allow to build genesis storage.
Locks	Any liquidity locks on some account balances.
Module
NegativeImbalance	Opaque, move-only struct with private fields that serves as a token denoting that funds have been destroyed without any equal and opposite accounting.
NextAssetId	Next available ID for user-created asset.
Permissions	Permission options for a given asset.
PermissionsV1	Asset permissions
PositiveImbalance	Opaque, move-only struct with private fields that serves as a token denoting that funds have been created without any equal and opposite accounting.
ReservedBalance	The reserved balance of a given asset under an account.
SpendingAssetId	The identity of the asset which is the one that is designated for paying the chain's transaction fee.
SpendingAssetIdProvider
StakingAssetId	The identity of the asset which is the one that is designated for the chain's staking system.
StakingAssetIdProvider
TotalIssuance	Total issuance of a given asset.

Enums

Call	Dispatchable calls.
Error	Error for the generic-asset module.
Owner	Owner of an asset.
PermissionType	Asset permission types
PermissionVersions	Versioned asset permission
RawEvent	Events for this module.

Traits

AssetIdProvider
Subtrait
Trait

Type Definitions

Event	`RawEvent` specialized for the configuration `Trait`
PermissionLatest	Alias to latest asset permissions
SpendingAssetCurrency
StakingAssetCurrency