Update keepers.md, discovered #2887

docs/spec/bank/README.md

@@ -16,11 +16,11 @@ This module will be used in the Cosmos Hub.
 
 1. **[State](state.md)**
 1. **[Keepers](keepers.md)**
+    1. [Common Types](keepers.md#common-types)
+        1. [Input](keepers.md#input)
+        1. [Output](keepers.md#output)
     1. [BaseKeeper](keepers.md#basekeeper)
     1. [SendKeeper](keepers.md#sendkeeper)
     1. [ViewKeeper](keepers.md#viewkeeper) 
 1. **[Transactions](transactions.md)**
-    1. [Common](transactions.md#common)
-        1. [Input](transactions.md#input)
-        1. [Output](transactions.md#output)
     1. [MsgSend](transactions.md#msgsend)

docs/spec/bank/keepers.md

@@ -2,36 +2,122 @@
 
 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.
 
+### Common Types
+
+#### Input
+
+An input of a multiparty transfer
+
+```golang
+type Input struct {
+  Address AccAddress
+  Coins   Coins
+}
+```
+
+#### Output
+
+An output of a multiparty transfer.
+
+```golang
+type Output struct {
+  Address AccAddress
+  Coins   Coins
+}
+```
+
 ### BaseKeeper
 
 The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins.
 
 ```golang
 type BaseKeeper interface {
-  SetCoins(ctx Context, addr AccAddress, amt Coins) error
-  SubtractCoins(ctx Context, addr AccAddress, amt Coins) (Coins, Tags, error)
-  AddCoins(ctx Context, addr AccAddress, amt Coins) (Coins, Tags, error)
+  SetCoins(addr AccAddress, amt Coins)
+  SubtractCoins(addr AccAddress, amt Coins)
+  AddCoins(addr AccAddress, amt Coins)
 }
 ```
 
+`setCoins` fetches an account by address, sets the coins on the account, and saves the account.
+
+```
+setCoins(addr AccAddress, amt Coins)
+  account = accountKeeper.getAccount(addr)
+  if account == nil
+    fail with "no account found"
+  account.Coins = amt
+  accountKeeper.setAccount(account)
+```
+
+`subtractCoins` fetches the coins of an account, subtracts the provided amount, and saves the account. This decreases the total supply.
+
+```
+subtractCoins(addr AccAddress, amt Coins)
+  oldCoins = getCoins(addr)
+  newCoins = oldCoins - amt
+  if newCoins < 0
+    fail with "cannot end up with negative coins"
+  setCoins(addr, newCoins)
+```
+
+`addCoins` fetches the coins of an account, adds the provided amount, and saves the account. This increases the total supply.
+
+```
+addCoins(addr AccAddress, amt Coins)
+  oldCoins = getCoins(addr)
+  newCoins = oldCoins + amt
+  setCoins(addr, newCoins)
+```
+
 ### 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).
 
 ```golang
 type SendKeeper interface {
-  SendCoins(ctx Content, from AccAddress, to AccAddress, amt Coins) (Tags, error)
-  InputOutputCoins(ctx Context, inputs []Input, outputs []Output) (Tags, error)
+  SendCoins(from AccAddress, to AccAddress, amt Coins)
+  InputOutputCoins(inputs []Input, outputs []Output)
 }
 ```
 
+`sendCoins` transfers coins from one account to another.
+
+```
+sendCoins(from AccAddress, to AccAddress, amt Coins)
+```
+
+```
+inputOutputCoins(inputs []Input, outputs []Output)
+```
+
+`inputOutputCoins` transfers coins from any number of input accounts (who must all sign the transaction) to any number of output accounts.
+
 ### ViewKeeper
 
 The view keeper provides read-only access to account balances but no balance alteration functionality. All balance lookups are `O(1)`.
 
 ```golang
 type ViewKeeper interface {
-  GetCoins(ctx Context, addr AccAddress) Coins
-  HasCoins(ctx Context, addr AccAddress, amt Coins) bool
+  GetCoins(addr AccAddress) Coins
+  HasCoins(addr AccAddress, amt Coins) bool
 }
 ```
+
+`getCoins` returns the coins associated with an account.
+
+```
+getCoins(addr AccAddress)
+  account = accountKeeper.getAccount(addr)
+  if account == nil
+    return Coins{}
+  return account.Coins
+```
+
+`hasCoins` returns whether or not an account has at least the provided amount of coins.
+
+```
+hasCoins(addr AccAddress, amt Coins)
+  account = accountKeeper.getAccount(addr)
+  coins = getCoins(addr)
+  return coins >= amt 
+```

docs/spec/bank/transactions.md

@@ -1,25 +1,5 @@
 ## Transactions
 
-### Common
-
-#### Input
-
-```golang
-type Input struct {
-  Address AccAddress
-  Coins   Coins
-}
-```
-
-#### Output
-
-```golang
-type Output struct {
-  Address AccAddress
-  Coins   Coins
-}
-```
-
 ### MsgSend
 
 ```golang
@@ -28,3 +8,10 @@ type MsgSend struct {
   Outputs []Output
 }
 ```
+
+`handleMsgSend` just runs `inputOutputCoins`.
+
+```
+handleMsgSend(msg MsgSend)
+  return inputOutputCoins(msg.Inputs, msg.Outputs)
+```