2019-12-17 03:44:44 -08:00
<!--
2019-12-11 09:35:27 -08:00
order: 2
2019-12-17 03:44:44 -08:00
-->
2019-12-11 09:35:27 -08:00
2019-02-20 10:21:57 -08:00
# Keepers
2018-11-29 13:56:42 -08:00
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.
Note that you should always review the `bank` module code to ensure that permissions are limited in the way that you expect.
2019-02-20 10:21:57 -08:00
## Common Types
2018-11-29 13:56:42 -08:00
2019-02-20 10:21:57 -08:00
### Input
2018-11-29 13:56:42 -08:00
An input of a multiparty transfer
2019-08-26 06:09:18 -07:00
```go
2018-11-29 13:56:42 -08:00
type Input struct {
Address AccAddress
Coins Coins
}
```
2019-02-20 10:21:57 -08:00
### Output
2018-11-29 13:56:42 -08:00
An output of a multiparty transfer.
2019-08-26 06:09:18 -07:00
```go
2018-11-29 13:56:42 -08:00
type Output struct {
Address AccAddress
Coins Coins
}
```
2019-02-20 10:21:57 -08:00
## BaseKeeper
2018-11-29 13:56:42 -08:00
The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins.
2019-08-26 06:09:18 -07:00
```go
2018-11-29 13:56:42 -08:00
type BaseKeeper interface {
SetCoins(addr AccAddress, amt Coins)
SubtractCoins(addr AccAddress, amt Coins)
AddCoins(addr AccAddress, amt Coins)
InputOutputCoins(inputs []Input, outputs []Output)
}
```
`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)
```
`inputOutputCoins` transfers coins from any number of input accounts to any number of output accounts.
```
inputOutputCoins(inputs []Input, outputs []Output)
for input in inputs
subtractCoins(input.Address, input.Coins)
for output in outputs
addCoins(output.Address, output.Coins)
```
2019-02-20 10:21:57 -08:00
## SendKeeper
2018-11-29 13:56:42 -08:00
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).
2019-08-26 06:09:18 -07:00
```go
2018-11-29 13:56:42 -08:00
type SendKeeper interface {
SendCoins(from AccAddress, to AccAddress, amt Coins)
}
```
`sendCoins` transfers coins from one account to another.
```
sendCoins(from AccAddress, to AccAddress, amt Coins)
subtractCoins(from, amt)
addCoins(to, amt)
```
2019-02-20 10:21:57 -08:00
## ViewKeeper
2018-11-29 13:56:42 -08:00
The view keeper provides read-only access to account balances but no balance alteration functionality. All balance lookups are `O(1)` .
2019-08-26 06:09:18 -07:00
```go
2018-11-29 13:56:42 -08:00
type ViewKeeper interface {
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
```