Supply

Terra's Supply module inherits from Cosmos SDK's supply module. This document is a stub, and covers mainly important Terra-specific notes about how it is used.

The Supply module passively tracks the total supply of all coins Terra and Luna within the blockchain, provides a way for modules to hold and interact with a balance of Coins, and introduces an invariant check to verify the Terra protocol's total supply.

This was taken from the official Cosmos SDK docs, and placed here for your convenience to understand the Supply module and module accounts.

Total Supply

The total Supply of the network is equal to the sum of all coins from the account. The total supply is updated every time a Coin is minted (eg: as part of the inflation mechanism) or burned (eg: due to slashing or if a governance proposal is vetoed).

Module Accounts

The supply module introduces a new type of auth.Account which can be used by modules to allocate tokens and in special cases mint or burn tokens. At a base level these module accounts are capable of sending/receiving tokens to and from auth.Accounts and other module accounts. This design replaces previous alternative designs where, to hold tokens, modules would burn the incoming tokens from the sender account, and then track those tokens internally. Later, in order to send tokens, the module would need to effectively mint tokens within a destination account. The new design removes duplicate logic between modules to perform this accounting.

The ModuleAccount interface is defined as follows:

type ModuleAccount interface {
  auth.Account               // same methods as the Account interface
  GetName() string           // name of the module; used to obtain the address
  GetPermissions() []string  // permissions of module account
  HasPermission(string) bool
}

Any module or message handler that allows either direct or indirect sending of funds must explicitly guarantee those funds cannot be sent to module accounts (unless allowed).

The supply Keeper also introduces new wrapper functions for the auth Keeper and the bank Keeper that are related to ModuleAccounts in order to be able to:

• Get and set ModuleAccounts by providing the Name.
• Send coins from and to other ModuleAccounts or standard Accounts (BaseAccount or VestingAccount) by passing only the Name.
• Mint or Burn coins for a ModuleAccount (restricted to its permissions).

Permissions

Each ModuleAccount has a different set of permissions that provide different object capabilities to perform certain actions. Permissions need to be registered upon the creation of the supply Keeper so that every time a ModuleAccount calls the allowed functions, the Keeper can lookup the permissions to that specific account and perform or not the action.

The available permissions are:

• Minter: allows for a module to mint a specific amount of coins.
• Burner: allows for a module to burn a specific amount of coins.
• Staking: allows for a module to delegate and undelegate a specific amount of coins.

Parameters

The Supply module has no parameters.