x/bank: doc & spec updates (cosmos#8999)

* x/bank: update constructor godoc * x/bank: spec++ * Update x/bank/spec/02_keepers.md Co-authored-by: Barrie Byron <[email protected]> * Update x/bank/spec/02_keepers.md Co-authored-by: Barrie Byron <[email protected]> * Update x/bank/spec/02_keepers.md Co-authored-by: Barrie Byron <[email protected]> * Update x/bank/spec/02_keepers.md Co-authored-by: Barrie Byron <[email protected]> * Update x/bank/keeper/keeper.go Co-authored-by: Barrie Byron <[email protected]> * Update x/bank/spec/02_keepers.md Co-authored-by: Barrie Byron <[email protected]> * Update x/bank/spec/02_keepers.md Co-authored-by: Barrie Byron <[email protected]> Co-authored-by: Barrie Byron <[email protected]>
dtkong · Mar 26, 2021 · 04246ef · 04246ef
1 parent d8fa35b
commit 04246ef
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 5 deletions.
diff --git 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
@@ -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