Crate pallet_assets

source ·
Expand description

Assets Pallet

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 (Minting)
  • Asset Transferal
  • Asset Freezing
  • Asset Destruction (Burning)
  • Delegated Asset Transfers (“Approval API”)

To use it in your runtime, you need to implement the assets Config.

The supported dispatchable functions are documented in the Call enum.

Terminology

  • Admin: An account ID uniquely privileged to be able to unfreeze (thaw) an account and it’s assets, as well as forcibly transfer a particular class of assets between arbitrary accounts and reduce the balance of a particular class of assets of arbitrary accounts.
  • Asset issuance/minting: The creation of a new asset, whose total supply will belong to the account that issues the asset. This is a privileged operation.
  • Asset transfer: The reduction of the balance of an asset of one account with the corresponding increase in the balance of another.
  • Asset destruction: The process of reduce the balance of an asset of one account. This is a privileged operation.
  • Fungible asset: An asset whose units are interchangeable.
  • Issuer: An account ID uniquely privileged to be able to mint a particular class of assets.
  • Freezer: An account ID uniquely privileged to be able to freeze an account from transferring a particular class of assets.
  • Freezing: Removing the possibility of an unpermissioned transfer of an asset from a particular account.
  • Non-fungible asset: An asset for which each unit has unique characteristics.
  • Owner: An account ID uniquely privileged to be able to destroy a particular asset class, or to set the Issuer, Freezer or Admin of that asset class.
  • Approval: The act of allowing an account the permission to transfer some balance of asset from the approving account into some third-party destination account.
  • Sufficiency: The idea of a minimum-balance of an asset being sufficient to allow the account’s existence on the system without requiring any other existential-deposit.

Goals

The assets system in Substrate is designed to make the following possible:

  • Issue a new assets in a permissioned or permissionless way, if permissionless, then with a deposit required.
  • Allow accounts to be delegated the ability to transfer assets without otherwise existing on-chain (approvals).
  • Move assets between accounts.
  • Update the asset’s total supply.
  • Allow administrative activities by specially privileged accounts including freezing account balances and minting/burning assets.

Interface

Permissionless Functions

  • create: Creates a new asset class, taking the required deposit.
  • transfer: Transfer sender’s assets to another account.
  • transfer_keep_alive: Transfer sender’s assets to another account, keeping the sender alive.
  • set_metadata: Set the metadata of an asset class.
  • clear_metadata: Remove the metadata of an asset class.
  • approve_transfer: Create or increase an delegated transfer.
  • cancel_approval: Rescind a previous approval.
  • transfer_approved: Transfer third-party’s assets to another account.

Permissioned Functions

  • force_create: Creates a new asset class without taking any deposit.
  • force_set_metadata: Set the metadata of an asset class.
  • force_clear_metadata: Remove the metadata of an asset class.
  • force_asset_status: Alter an asset class’s attributes.
  • force_cancel_approval: Rescind a previous approval.

Privileged Functions

  • destroy: Destroys an entire asset class; called by the asset class’s Owner.
  • mint: Increases the asset balance of an account; called by the asset class’s Issuer.
  • burn: Decreases the asset balance of an account; called by the asset class’s Admin.
  • force_transfer: Transfers between arbitrary accounts; called by the asset class’s Admin.
  • freeze: Disallows further transfers from an account; called by the asset class’s Freezer.
  • thaw: Allows further transfers from an account; called by the asset class’s Admin.
  • transfer_ownership: Changes an asset class’s Owner; called by the asset class’s Owner.
  • set_team: Changes an asset class’s Admin, Freezer and Issuer; called by the asset class’s Owner.

Please refer to the Call enum and its associated variants for documentation on each function.

Public Functions

  • balance - Get the asset id balance of who.
  • total_supply - Get the total supply of an asset id.

Please refer to the Pallet struct for details on publicly available functions.

Re-exports

pub use weights::WeightInfo;
pub use pallet::*;

Modules

pallet
The module that hosts all the FRAME types needed to add this pallet to a runtime.
weights
Autogenerated weights for pallet_assets

Structs

Approval
Data concerning an approval.
AssetAccount
AssetDetails
AssetMetadata
BalanceToAssetBalance
Converts a balance value into an asset balance based on the ratio between the fungible’s minimum balance and the minimum asset balance.
DestroyWitness
Witness data for the destroy transactions.
ExtraMutator
A mutator type allowing inspection and possible modification of the extra “sidecar” data.

Enums

AssetStatus
AssetStatus holds the current state of the asset. It could either be Live and available for use, or in a Destroying state.
ConversionError
Possible errors when converting between external and asset balances.
ExistenceReason

Traits

AssetsCallback
Trait with callbacks that are executed after successfull asset creation or destruction.
FrozenBalance
Trait for allowing a minimum balance on the account to be specified, beyond the minimum_balance of the asset. This is additive - the minimum_balance of the asset must be met and then anything here in addition.