diff --git a/x/bank/keeper/keeper.go b/x/bank/keeper/keeper.go index 7aa27441d1..bb3bd1080c 100644 --- a/x/bank/keeper/keeper.go +++ b/x/bank/keeper/keeper.go @@ -63,8 +63,17 @@ func (k BaseKeeper) GetTotalSupply(ctx sdk.Context) sdk.Coins { return balances.Sort() } +// NewBaseKeeper returns a new BaseKeeper object with a given codec, dedicated +// store key, an AccountKeeper implementation, and a parameter Subspace used to +// store and fetch module parameters. The BaseKeeper also accepts a +// blocklist map. This blocklist describes the set of addresses that are not allowed +// to receive funds through direct and explicit actions, for example, by using a MsgSend or +// by using a SendCoinsFromModuleToAccount execution. func NewBaseKeeper( - cdc codec.BinaryMarshaler, storeKey sdk.StoreKey, ak types.AccountKeeper, paramSpace paramtypes.Subspace, + cdc codec.BinaryMarshaler, + storeKey sdk.StoreKey, + ak types.AccountKeeper, + paramSpace paramtypes.Subspace, blockedAddrs map[string]bool, ) BaseKeeper { diff --git a/x/bank/spec/02_keepers.md b/x/bank/spec/02_keepers.md index e7e3caba54..8db69c34d0 100644 --- a/x/bank/spec/02_keepers.md +++ b/x/bank/spec/02_keepers.md @@ -4,9 +4,25 @@ order: 2 # Keepers -The bank module provides three different exported keeper interfaces which can be passed to other modules which need to read or update account balances. Modules should use the least-permissive interface which provides the functionality they require. +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. -Note that you should always review the `bank` module code to ensure that permissions are limited in the way that you expect. +Best practices dictate careful review of `bank` module code to ensure that +permissions are limited in the way that you expect. + +## Blacklisting 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 of 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](http://docs.cosmos.network/master/ibc/). ## Common Types @@ -73,7 +89,8 @@ type Keeper interface { ## SendKeeper -The send keeper provides access to account balances and the ability to transfer coins between accounts, but not to alter the total supply (mint or burn coins). +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). ```go // SendKeeper defines a module interface that facilitates the transfer of coins @@ -96,7 +113,7 @@ type SendKeeper interface { ## ViewKeeper -The view keeper provides read-only access to account balances but no balance alteration functionality. All balance lookups are `O(1)`. +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)`. ```go // ViewKeeper defines a module interface that facilitates read only access to