abb3dfefa0
* temp commit * setbalance now is internal * remove set balances in genesis * feedback test commit * update tests * fix: genesis panic message * fix not bonded pool * fix(staking): genesis test * fix(simapp): rollback state fix change * fix(staking): genesis large val set test * [Bank Refactor] Frojdi jonathan/remove setsupply (#8491) * init supply in a different way * remove external usage of set supply * change(staking): replace SetSupply with MintCoins in tests * change(evidence): replace SetSupply with MintCoins in tests * change(crisis): remove SetSupply in tests * change(bank): remove set supply from genesis tests * change(bank): remove set supply from keeper tests * change(bank): remove remaining set supply usage from keeper tests * change(bank): remove set supply usage from grpc query and querier tests * change(bank): remove SetSupply from keeper interface Co-authored-by: Frojdi Dymylja <frojdi.dymylja@gmail.com> * remove setbalances from genesis in gov * remove keyring * add init genesis state * change(staking): make genesis checks coherent and add tests * remove setbalances on distribution * fix(staking): genesis tests * [Bank Refactor]: Remove SetBalances usage from the code and tests (#8509) * change(distribution): remove SetBalances usage from keeper tests * add(simapp): FundAccount utility function * chore(staking): use FundAccount in keeper tests * change(staking): remove usage of SetBalance in allocation tests * change(staking): remove usage of SetBalance in delegation tests * change(staking): remove usage of SetBalance in proposal handler tests * change(staking): remove usage of SetBalances in grpc query tests * change(staking): remove usage of SetBalances in operations tests * change(distribution): remove usage of SetBalances in genesis * change(authz): remove usage of SetBalances keeper and operations test * fix(authz): TestKeeperFees failing test * change(slashing): remove SetBalances from expected BankKeeper * change(slashing): remove usage of SetBalances in tests * change(distribution): remove SetBalances from expected BankKeeper * change(genutil): remove usage of SetBalances from tests * change(gov): remove SetBalances from expected BankKeeper * change(gov): remove usage of SetBalances from tests * change(staking): remove usage of SetBalances from slash tests * change(staking): remove SetBalances from expected BankKeeper * change(staking): remove usage of SetBalances from delegation tests * change(staking): remove usage of SetBalances from operations tests * change(staking): remove usage of SetBalances from validator tests * change(bank): remove usage of SetBalances from app tests * change(bank): remove usage of SetBalances from bench tests * change(bank): remove usage of SetBalances from querier tests * change(bank): remove usage of SetBalances from grpc query tests * change(bank): remove usage of SetBalances from operations tests * change(bank): partially remove usage of SetBalances from keeper tests * change(bank): finalize removal of usage of SetBalances from keeper tests * change(auth): remove usage of SetBalances from verify tests * change(auth): partially remove usage of SetBalances from tests * [Bank refactor]: finalize removal of setbalances from auth (#8527) * add tests with is check tx * temp commit * fix test * fix other test and remove setbalances * change(auth): remove usage of SetBalances is vesting tests Co-authored-by: Jonathan Gimeno <jgimeno@gmail.com> * change(types): remove usage of SetBalances in queries * fix(types): pagination tests * [Bank refactor] fix pagination tests (#8550) * fix tests * lint * change(bank): remove SetBalances from keeper public API Co-authored-by: Jonathan Gimeno <jgimeno@gmail.com> Co-authored-by: SaReN <sahithnarahari@gmail.com> * change(bank): remove SubtractCoins from keeper public API * change(ibc/transfer): remove AddCoins from relay tests * change(bank): remove AddCoins from public keeper API * fix imports * remove set balances * fix fee test * remove set balances * fix(staking): remove dependency on minter authorization for staking pools * chore: update CHANGELOG.md * update: x/distribution/keeper/keeper_test.go Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update simapp/test_helpers.go Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update x/staking/genesis_test.go Co-authored-by: Robert Zaremba <robert@zaremba.ch> * fix(simapp): FundAccount amount variable name * fix some PR issues Co-authored-by: Frojdi Dymylja <frojdi.dymylja@gmail.com> Co-authored-by: Frojdi Dymylja <33157909+fdymylja@users.noreply.github.com> Co-authored-by: SaReN <sahithnarahari@gmail.com> Co-authored-by: Alessio Treglia <alessio@tendermint.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch> |
||
---|---|---|
.. | ||
01_state.md | ||
02_keepers.md | ||
03_messages.md | ||
04_events.md | ||
05_params.md | ||
README.md |
README.md
x/bank
Abstract
This document specifies the bank module of the Cosmos SDK.
The bank module is responsible for handling multi-asset coin transfers between accounts and tracking special-case pseudo-transfers which must work differently with particular kinds of accounts (notably delegating/undelegating for vesting accounts). It exposes several interfaces with varying capabilities for secure interaction with other modules which must alter user balances.
In addition, the bank module tracks and provides query support for the total supply of all assets used in the application.
This module will be used in the Cosmos Hub.
Supply
The supply
functionality:
- passively tracks the total supply of coins within a chain,
- provides a pattern for modules to hold/interact with
Coins
, and - introduces the invariant check to verify a chain's total supply.
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 functionality 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.Account
s 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
}
WARNING! 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 ModuleAccount
s in order to be able
to:
- Get and set
ModuleAccount
s by providing theName
. - Send coins from and to other
ModuleAccount
s or standardAccount
s (BaseAccount
orVestingAccount
) by passing only theName
. Mint
orBurn
coins for aModuleAccount
(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.