Developers
Pallets
Balances Pallet

Guide to the Balances Pallet in Substrate Chains

The Balances pallet is a core component of many Substrate-based blockchains, managing the token balances within the system. This guide will dive deeper into the core functionalities of the Balances pallet and how it can be utilized in a Substrate-based blockchain.

Overview

The Balances pallet handles the creation and management of fungible assets, primarily the native tokens of a blockchain. It allows for token transfers, reserves tokens for specific purposes, and enforces rules related to the minimum balance.

Key Concepts

Accounts

Each entity on the blockchain is represented by an account, which has a unique identifier in the form of a public key. In Substrate's unified account system, each account can hold multiple types of assets and interact with the network in various roles.

Balances

Tokens within an account are categorized into two types: free and reserved. Free balance is what can be spent by the account holder, while reserved balance is tied to a specific purpose and cannot be spent in the usual manner. There is also a concept of a locked balance, which is owned but temporarily unusable, common in staking scenarios.

Existential Deposit

This is a concept unique to Substrate, where a minimum balance is set to prevent the creation of dust accounts. Any account whose free balance falls below this value will be removed.

Transfers

Transfers are a fundamental operation in any blockchain, and Substrate provides several means to transfer tokens. This includes standard transfers, keeping alive transfers that prevent the sender's account from being deleted, and best effort transfers that reduce the transferred amount if necessary to meet the keeping alive guarantee.

Pallet API and Usage

The Balances pallet provides a versatile API that allows interaction from within other runtime modules. Some common functions include:

  • transfer: Transfers some free balance from one account to another.
  • reserve: Moves some free balance to reserved balance.
  • unreserve: Unreserve some funds, returning any amount that was unable to be unreserved.
  • slash: Deducts up to a value from the combined balance of who, preferring to deduct from the free balance. This function cannot fail.

Please refer to the official API documentation (opens in a new tab) to learn more about the API provided by the Balances