github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/x/bank/spec/02_keepers.md (about)

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