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 its 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 designated as the beneficiary of 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 reducing 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 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 an asset class’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.
  • approve_transfer: Create or increase an delegated transfer.
  • cancel_approval: Rescind a previous approval.
  • transfer_approved: Transfer third-party’s assets to another account.
  • touch: Create an asset account for non-provider assets. Caller must place a deposit.
  • refund: Return the deposit (if any) of the caller’s asset account or a consumer reference (if any) of the caller’s account.
  • refund_other: Return the deposit (if any) of a specified asset 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 to and 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.
  • set_metadata: Set the metadata of an asset class; called by the asset class’s Owner.
  • clear_metadata: Remove the metadata of an asset class; called by the asset class’s Owner.
  • touch_other: Create an asset account for specified account. Caller must place a deposit; called by the asset class’s Freezer or Admin.
  • block: Disallows further transfers to and from an account; called by the asset class’s Freezer.

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.

Callbacks

Using CallbackHandle associated type, user can configure custom callback functions which are executed when new asset is created or an existing asset is destroyed.

Re-exports

Modules

  • migration
  • pallet
    The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
  • weights
    Autogenerated weights for pallet_assets

Macros

  • _runtime_benchmarks_enabled
    Enable/disable the given code depending on feature = "runtime-benchmarks" being enabled for the crate or not.

Structs

Enums

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.