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 is used in the Cosmos Hub.
Contents
Supply
The supply
functionality:
passively tracks the total supply of coins within a chain,
provides a pattern for modules to hold/interact with
Coins
, andintroduces 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:
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 perform 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.
State
The x/bank
module keeps state of the following primary objects:
Account balances
Denomination metadata
The total supply of all balances
Information on which denominations are allowed to be sent.
In addition, the x/bank
module keeps the following indexes to manage the aforementioned state:
Supply Index:
0x0 | byte(denom) -> byte(amount)
Denom Metadata Index:
0x1 | byte(denom) -> ProtocolBuffer(Metadata)
Balances Index:
0x2 | byte(address length) | []byte(address) | []byte(balance.Denom) -> ProtocolBuffer(balance)
Reverse Denomination to Address Index:
0x03 | byte(denom) | 0x00 | []byte(address) -> 0
Params
The bank module stores it's params in state with the prefix of 0x05
, it can be updated with governance or the address with authority.
Params:
0x05 | ProtocolBuffer(Params)
Keepers
The bank module provides these exported keeper interfaces that can be passed to other modules that read or update account balances. Modules should use the least-permissive interface that provides the functionality they require.
Best practices dictate careful review of bank
module code to ensure that permissions are limited in the way that you expect.
Denied Addresses
The x/bank
module accepts a map of addresses that are considered blocklisted from directly and explicitly receiving funds through means such as MsgSend
and MsgMultiSend
and direct API calls like SendCoinsFromModuleToAccount
.
Typically, these addresses are module accounts. If these addresses receive funds outside the expected rules of the state machine, invariants are likely to be broken and could result in a halted network.
By providing the x/bank
module with a blocklisted set of addresses, an error occurs for the operation if a user or client attempts to directly or indirectly send funds to a blocklisted account, for example, by using IBC.
Common Types
Input
An input of a multiparty transfer
Output
An output of a multiparty transfer.
BaseKeeper
The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins.
Restricted permission to mint per module could be achieved by using baseKeeper with WithMintCoinsRestriction
to give specific restrictions to mint (e.g. only minting certain denom).
SendKeeper
The send keeper provides access to account balances and the ability to transfer coins between accounts. The send keeper does not alter the total supply (mint or burn coins).
Send Restrictions
The SendKeeper
applies a SendRestrictionFn
before each transfer of funds.
After the SendKeeper
(or BaseKeeper
) has been created, send restrictions can be added to it using the AppendSendRestriction
or PrependSendRestriction
functions. Both functions compose the provided restriction with any previously provided restrictions. AppendSendRestriction
adds the provided restriction to be run after any previously provided send restrictions. PrependSendRestriction
adds the restriction to be run before any previously provided send restrictions. The composition will short-circuit when an error is encountered. I.e. if the first one returns an error, the second is not run.
During SendCoins
, the send restriction is applied after coins are removed from the from address, but before adding them to the to address. During InputOutputCoins
, the send restriction is applied after the input coins are removed and once for each output before the funds are added.
A send restriction function should make use of a custom value in the context to allow bypassing that specific restriction.
Send Restrictions are not placed on ModuleToAccount
or ModuleToModule
transfers. This is done due to modules needing to move funds to user accounts and other module accounts. This is a design decision to allow for more flexibility in the state machine. The state machine should be able to move funds between module accounts and user accounts without restrictions.
Secondly this limitation would limit the usage of the state machine even for itself. users would not be able to receive rewards, not be able to move funds between module accounts. In the case that a user sends funds from a user account to the community pool and then a governance proposal is used to get those tokens into the users account this would fall under the discretion of the app chain developer to what they would like to do here. We can not make strong assumptions here. Thirdly, this issue could lead into a chain halt if a token is disabled and the token is moved in the begin/endblock. This is the last reason we see the current change and more damaging then beneficial for users.
For example, in your module's keeper package, you'd define the send restriction function:
The bank keeper should be provided to your keeper's constructor so the send restriction can be added to it:
Then, in the mymodule
package, define the context helpers:
Now, anywhere where you want to use SendCoins
or InputOutputCoins
, but you don't want your send restriction applied:
ViewKeeper
The view keeper provides read-only access to account balances. The view keeper does not have balance alteration functionality. All balance lookups are O(1)
.
Messages
MsgSend
Send coins from one address to another.
The message will fail under the following conditions:
The coins do not have sending enabled
The
to
address is restricted
MsgMultiSend
Send coins from one sender and to a series of different address. If any of the receiving addresses do not correspond to an existing account, a new account is created.
The message will fail under the following conditions:
Any of the coins do not have sending enabled
Any of the
to
addresses are restrictedAny of the coins are locked
The inputs and outputs do not correctly correspond to one another
MsgUpdateParams
The bank
module params can be updated through MsgUpdateParams
, which can be done using governance proposal. The signer will always be the gov
module account address.
The message handling can fail if:
signer is not the gov module account address.
MsgSetSendEnabled
Used with the x/gov module to set create/edit SendEnabled entries.
The message will fail under the following conditions:
The authority is not a bech32 address.
The authority is not x/gov module's address.
There are multiple SendEnabled entries with the same Denom.
One or more SendEnabled entries has an invalid Denom.
Events
The bank module emits the following events:
Message Events
MsgSend
MsgMultiSend
Keeper Events
In addition to message events, the bank keeper will produce events when the following methods are called (or any method which ends up calling them)
MintCoins
BurnCoins
addCoins
subUnlockedCoins/DelegateCoins
Parameters
The bank module contains the following parameters
SendEnabled
The SendEnabled parameter is now deprecated and not to be use. It is replaced with state store records.
DefaultSendEnabled
The default send enabled value controls send transfer capability for all coin denominations unless specifically included in the array of SendEnabled
parameters.
Client
CLI
A user can query and interact with the bank
module using the CLI.
Query
The query
commands allow users to query bank
state.
balances
The balances
command allows users to query account balances by address.
Example:
Example Output:
denom-metadata
The denom-metadata
command allows users to query metadata for coin denominations. A user can query metadata for a single denomination using the --denom
flag or all denominations without it.
Example:
Example Output:
total
The total
command allows users to query the total supply of coins. A user can query the total supply for a single coin using the --denom
flag or all coins without it.
Example:
Example Output:
send-enabled
The send-enabled
command allows users to query for all or some SendEnabled entries.
Example:
Example output:
Transactions
The tx
commands allow users to interact with the bank
module.
send
The send
command allows users to send funds from one account to another.
Example:
gRPC
A user can query the bank
module using gRPC endpoints.
Balance
The Balance
endpoint allows users to query account balance by address for a given denomination.
Example:
Example Output:
AllBalances
The AllBalances
endpoint allows users to query account balance by address for all denominations.
Example:
Example Output:
DenomMetadata
The DenomMetadata
endpoint allows users to query metadata for a single coin denomination.
Example:
Example Output:
DenomsMetadata
The DenomsMetadata
endpoint allows users to query metadata for all coin denominations.
Example:
Example Output:
DenomOwners
The DenomOwners
endpoint allows users to query metadata for a single coin denomination.
Example:
Example Output:
TotalSupply
The TotalSupply
endpoint allows users to query the total supply of all coins.
Example:
Example Output:
SupplyOf
The SupplyOf
endpoint allows users to query the total supply of a single coin.
Example:
Example Output:
Params
The Params
endpoint allows users to query the parameters of the bank
module.
Example:
Example Output:
SendEnabled
The SendEnabled
enpoints allows users to query the SendEnabled entries of the bank
module.
Any denominations NOT returned, use the Params.DefaultSendEnabled
value.
Example:
Example Output:
Last updated