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

     1  <!--
     2  order: 0
     3  title: Bank Overview
     4  parent:
     5    title: "bank"
     6  -->
     7  
     8  # `x/bank`
     9  
    10  ## Abstract
    11  
    12  This document specifies the bank module of the Cosmos SDK.
    13  
    14  The bank module is responsible for handling multi-asset coin transfers between
    15  accounts and tracking special-case pseudo-transfers which must work differently
    16  with particular kinds of accounts (notably delegating/undelegating for vesting
    17  accounts). It exposes several interfaces with varying capabilities for secure
    18  interaction with other modules which must alter user balances.
    19  
    20  In addition, the bank module tracks and provides query support for the total
    21  supply of all assets used in the application.
    22  
    23  This module will be used in the Cosmos Hub.
    24  
    25  ## Supply
    26  
    27  The `supply` functionality:
    28  
    29  - passively tracks the total supply of coins within a chain,
    30  - provides a pattern for modules to hold/interact with `Coins`, and
    31  - introduces the invariant check to verify a chain's total supply.
    32  
    33  ### Total Supply
    34  
    35  The total `Supply` of the network is equal to the sum of all coins from the
    36  account. The total supply is updated every time a `Coin` is minted (eg: as part
    37  of the inflation mechanism) or burned (eg: due to slashing or if a governance
    38  proposal is vetoed).
    39  
    40  ## Module Accounts
    41  
    42  The supply functionality introduces a new type of `auth.Account` which can be used by
    43  modules to allocate tokens and in special cases mint or burn tokens. At a base
    44  level these module accounts are capable of sending/receiving tokens to and from
    45  `auth.Account`s and other module accounts. This design replaces previous
    46  alternative designs where, to hold tokens, modules would burn the incoming
    47  tokens from the sender account, and then track those tokens internally. Later,
    48  in order to send tokens, the module would need to effectively mint tokens
    49  within a destination account. The new design removes duplicate logic between
    50  modules to perform this accounting.
    51  
    52  The `ModuleAccount` interface is defined as follows:
    53  
    54  ```go
    55  type ModuleAccount interface {
    56    auth.Account               // same methods as the Account interface
    57  
    58    GetName() string           // name of the module; used to obtain the address
    59    GetPermissions() []string  // permissions of module account
    60    HasPermission(string) bool
    61  }
    62  ```
    63  
    64  > **WARNING!**
    65  > Any module or message handler that allows either direct or indirect sending of funds must explicitly guarantee those funds cannot be sent to module accounts (unless allowed).
    66  
    67  The supply `Keeper` also introduces new wrapper functions for the auth `Keeper`
    68  and the bank `Keeper` that are related to `ModuleAccount`s in order to be able
    69  to:
    70  
    71  - Get and set `ModuleAccount`s by providing the `Name`.
    72  - Send coins from and to other `ModuleAccount`s or standard `Account`s
    73    (`BaseAccount` or `VestingAccount`) by passing only the `Name`.
    74  - `Mint` or `Burn` coins for a `ModuleAccount` (restricted to its permissions).
    75  
    76  ### Permissions
    77  
    78  Each `ModuleAccount` has a different set of permissions that provide different
    79  object capabilities to perform certain actions. Permissions need to be
    80  registered upon the creation of the supply `Keeper` so that every time a
    81  `ModuleAccount` calls the allowed functions, the `Keeper` can lookup the
    82  permissions to that specific account and perform or not the action.
    83  
    84  The available permissions are:
    85  
    86  - `Minter`: allows for a module to mint a specific amount of coins.
    87  - `Burner`: allows for a module to burn a specific amount of coins.
    88  - `Staking`: allows for a module to delegate and undelegate a specific amount of coins.
    89  
    90  ## Contents
    91  
    92  1. **[State](01_state.md)**
    93  2. **[Keepers](02_keepers.md)**
    94     - [Common Types](02_keepers.md#common-types)
    95     - [BaseKeeper](02_keepers.md#basekeeper)
    96     - [SendKeeper](02_keepers.md#sendkeeper)
    97     - [ViewKeeper](02_keepers.md#viewkeeper)
    98  3. **[Messages](03_messages.md)**
    99     - [MsgSend](03_messages.md#msgsend)
   100  4. **[Events](04_events.md)**
   101     - [Handlers](04_events.md#handlers)
   102  5. **[Parameters](05_params.md)**