github.com/Finschia/finschia-sdk@v0.48.1/x/bank/spec/02_keepers.md (about)

     1  <!--
     2  order: 2
     3  -->
     4  
     5  # Keepers
     6  
     7  The bank module provides these exported keeper interfaces that can be
     8  passed to other modules that read or update account balances. Modules
     9  should use the least-permissive interface that provides the functionality they
    10  require.
    11  
    12  Best practices dictate careful review of `bank` module code to ensure that
    13  permissions are limited in the way that you expect.
    14  
    15  ## Blocklisting Addresses
    16  
    17  The `x/bank` module accepts a map of addresses that are considered blocklisted
    18  from directly and explicitly receiving funds through means such as `MsgSend` and
    19  `MsgMultiSend` and direct API calls like `SendCoinsFromModuleToAccount`.
    20  
    21  Typically, these addresses are module accounts. If these addresses receive funds
    22  outside the expected rules of the state machine, invariants are likely to be
    23  broken and could result in a halted network.
    24  
    25  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/).
    26  
    27  ## Common Types
    28  
    29  ### Input
    30  
    31  An input of a multiparty transfer
    32  
    33  ```protobuf
    34  // Input models transaction input.
    35  message Input {
    36    string   address                        = 1;
    37    repeated cosmos.base.v1beta1.Coin coins = 2;
    38  }
    39  ```
    40  
    41  ### Output
    42  
    43  An output of a multiparty transfer.
    44  
    45  ```protobuf
    46  // Output models transaction outputs.
    47  message Output {
    48    string   address                        = 1;
    49    repeated cosmos.base.v1beta1.Coin coins = 2;
    50  }
    51  ```
    52  
    53  ## BaseKeeper
    54  
    55  The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins.
    56  
    57  Restricted permission to mint per module could be achieved by using baseKeeper with `WithMintCoinsRestriction` to give specific restrictions to mint (e.g. only minting certain denom).
    58  
    59  ```go
    60  // Keeper defines a module interface that facilitates the transfer of coins
    61  // between accounts.
    62  type Keeper interface {
    63      SendKeeper
    64  
    65      InitGenesis(sdk.Context, *types.GenesisState)
    66      ExportGenesis(sdk.Context) *types.GenesisState
    67  
    68      GetSupply(ctx sdk.Context, denom string) sdk.Coin
    69      GetPaginatedTotalSupply(ctx sdk.Context, pagination *query.PageRequest) (sdk.Coins, *query.PageResponse, error)
    70      IterateTotalSupply(ctx sdk.Context, cb func(sdk.Coin) bool)
    71      GetDenomMetaData(ctx sdk.Context, denom string) (types.Metadata, bool)
    72      SetDenomMetaData(ctx sdk.Context, denomMetaData types.Metadata)
    73      IterateAllDenomMetaData(ctx sdk.Context, cb func(types.Metadata) bool)
    74  
    75      SendCoinsFromModuleToAccount(ctx sdk.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error
    76      SendCoinsFromModuleToModule(ctx sdk.Context, senderModule, recipientModule string, amt sdk.Coins) error
    77      SendCoinsFromAccountToModule(ctx sdk.Context, senderAddr sdk.AccAddress, recipientModule string, amt sdk.Coins) error
    78      DelegateCoinsFromAccountToModule(ctx sdk.Context, senderAddr sdk.AccAddress, recipientModule string, amt sdk.Coins) error
    79      UndelegateCoinsFromModuleToAccount(ctx sdk.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error
    80      MintCoins(ctx sdk.Context, moduleName string, amt sdk.Coins) error
    81      BurnCoins(ctx sdk.Context, moduleName string, amt sdk.Coins) error
    82  
    83      DelegateCoins(ctx sdk.Context, delegatorAddr, moduleAccAddr sdk.AccAddress, amt sdk.Coins) error
    84      UndelegateCoins(ctx sdk.Context, moduleAccAddr, delegatorAddr sdk.AccAddress, amt sdk.Coins) error
    85  
    86      types.QueryServer
    87  }
    88  ```
    89  
    90  ## SendKeeper
    91  
    92  The send keeper provides access to account balances and the ability to transfer coins between
    93  accounts. The send keeper does not alter the total supply (mint or burn coins).
    94  
    95  ```go
    96  // SendKeeper defines a module interface that facilitates the transfer of coins
    97  // between accounts without the possibility of creating coins.
    98  type SendKeeper interface {
    99      ViewKeeper
   100  
   101      InputOutputCoins(ctx sdk.Context, inputs []types.Input, outputs []types.Output) error
   102      SendCoins(ctx sdk.Context, fromAddr sdk.AccAddress, toAddr sdk.AccAddress, amt sdk.Coins) error
   103  
   104      GetParams(ctx sdk.Context) types.Params
   105      SetParams(ctx sdk.Context, params types.Params)
   106  
   107      IsSendEnabledCoin(ctx sdk.Context, coin sdk.Coin) bool
   108      IsSendEnabledCoins(ctx sdk.Context, coins ...sdk.Coin) error
   109  
   110      BlockedAddr(addr sdk.AccAddress) bool
   111  }
   112  ```
   113  
   114  ## ViewKeeper
   115  
   116  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)`.
   117  
   118  ```go
   119  // ViewKeeper defines a module interface that facilitates read only access to
   120  // account balances.
   121  type ViewKeeper interface {
   122      ValidateBalance(ctx sdk.Context, addr sdk.AccAddress) error
   123      HasBalance(ctx sdk.Context, addr sdk.AccAddress, amt sdk.Coin) bool
   124  
   125      GetAllBalances(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
   126      GetAccountsBalances(ctx sdk.Context) []types.Balance
   127      GetBalance(ctx sdk.Context, addr sdk.AccAddress, denom string) sdk.Coin
   128      LockedCoins(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
   129      SpendableCoins(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
   130  
   131      IterateAccountBalances(ctx sdk.Context, addr sdk.AccAddress, cb func(coin sdk.Coin) (stop bool))
   132      IterateAllBalances(ctx sdk.Context, cb func(address sdk.AccAddress, coin sdk.Coin) (stop bool))
   133  }
   134  ```