|
| 1 | +## Keepers |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +Note that you should always review the `bank` module code to ensure that permissions are limited in the way that you expect. |
| 6 | + |
| 7 | +### Common Types |
| 8 | + |
| 9 | +#### Input |
| 10 | + |
| 11 | +An input of a multiparty transfer |
| 12 | + |
| 13 | +```golang |
| 14 | +type Input struct { |
| 15 | + Address AccAddress |
| 16 | + Coins Coins |
| 17 | +} |
| 18 | +``` |
| 19 | + |
| 20 | +#### Output |
| 21 | + |
| 22 | +An output of a multiparty transfer. |
| 23 | + |
| 24 | +```golang |
| 25 | +type Output struct { |
| 26 | + Address AccAddress |
| 27 | + Coins Coins |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +### BaseKeeper |
| 32 | + |
| 33 | +The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins. |
| 34 | + |
| 35 | +```golang |
| 36 | +type BaseKeeper interface { |
| 37 | + SetCoins(addr AccAddress, amt Coins) |
| 38 | + SubtractCoins(addr AccAddress, amt Coins) |
| 39 | + AddCoins(addr AccAddress, amt Coins) |
| 40 | + InputOutputCoins(inputs []Input, outputs []Output) |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +`setCoins` fetches an account by address, sets the coins on the account, and saves the account. |
| 45 | + |
| 46 | +``` |
| 47 | +setCoins(addr AccAddress, amt Coins) |
| 48 | + account = accountKeeper.getAccount(addr) |
| 49 | + if account == nil |
| 50 | + fail with "no account found" |
| 51 | + account.Coins = amt |
| 52 | + accountKeeper.setAccount(account) |
| 53 | +``` |
| 54 | + |
| 55 | +`subtractCoins` fetches the coins of an account, subtracts the provided amount, and saves the account. This decreases the total supply. |
| 56 | + |
| 57 | +``` |
| 58 | +subtractCoins(addr AccAddress, amt Coins) |
| 59 | + oldCoins = getCoins(addr) |
| 60 | + newCoins = oldCoins - amt |
| 61 | + if newCoins < 0 |
| 62 | + fail with "cannot end up with negative coins" |
| 63 | + setCoins(addr, newCoins) |
| 64 | +``` |
| 65 | + |
| 66 | +`addCoins` fetches the coins of an account, adds the provided amount, and saves the account. This increases the total supply. |
| 67 | + |
| 68 | +``` |
| 69 | +addCoins(addr AccAddress, amt Coins) |
| 70 | + oldCoins = getCoins(addr) |
| 71 | + newCoins = oldCoins + amt |
| 72 | + setCoins(addr, newCoins) |
| 73 | +``` |
| 74 | + |
| 75 | +`inputOutputCoins` transfers coins from any number of input accounts to any number of output accounts. |
| 76 | + |
| 77 | +``` |
| 78 | +inputOutputCoins(inputs []Input, outputs []Output) |
| 79 | + for input in inputs |
| 80 | + subtractCoins(input.Address, input.Coins) |
| 81 | + for output in outputs |
| 82 | + addCoins(output.Address, output.Coins) |
| 83 | +``` |
| 84 | + |
| 85 | +### SendKeeper |
| 86 | + |
| 87 | +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). |
| 88 | + |
| 89 | +```golang |
| 90 | +type SendKeeper interface { |
| 91 | + SendCoins(from AccAddress, to AccAddress, amt Coins) |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +`sendCoins` transfers coins from one account to another. |
| 96 | + |
| 97 | +``` |
| 98 | +sendCoins(from AccAddress, to AccAddress, amt Coins) |
| 99 | + subtractCoins(from, amt) |
| 100 | + addCoins(to, amt) |
| 101 | +``` |
| 102 | + |
| 103 | +### ViewKeeper |
| 104 | + |
| 105 | +The view keeper provides read-only access to account balances but no balance alteration functionality. All balance lookups are `O(1)`. |
| 106 | + |
| 107 | +```golang |
| 108 | +type ViewKeeper interface { |
| 109 | + GetCoins(addr AccAddress) Coins |
| 110 | + HasCoins(addr AccAddress, amt Coins) bool |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +`getCoins` returns the coins associated with an account. |
| 115 | + |
| 116 | +``` |
| 117 | +getCoins(addr AccAddress) |
| 118 | + account = accountKeeper.getAccount(addr) |
| 119 | + if account == nil |
| 120 | + return Coins{} |
| 121 | + return account.Coins |
| 122 | +``` |
| 123 | + |
| 124 | +`hasCoins` returns whether or not an account has at least the provided amount of coins. |
| 125 | + |
| 126 | +``` |
| 127 | +hasCoins(addr AccAddress, amt Coins) |
| 128 | + account = accountKeeper.getAccount(addr) |
| 129 | + coins = getCoins(addr) |
| 130 | + return coins >= amt |
| 131 | +``` |
0 commit comments