cosmos-sdk/x/bank/atlas/atlas-v0.39.1.md

x/bank

The x/bank module is responsible for handling multi-asset coin transfers between accounts and tracking special-case pseudo-transfers which must work differently with particular kinds of accounts.

Usage

1. Import the module.

   import (
       "github.com/cosmos/cosmos-sdk/x/bank"
   )
   

2. Add AppModuleBasic to your ModuleBasics.

   var (
     ModuleBasics = module.NewBasicManager(
       // ...
       bank.AppModuleBasic{},
     }
   )
   

3. Create the module's parameter subspace in your application constructor.

   func NewApp(...) *App {
     // ...
     app.subspaces[bank.ModuleName] = app.ParamsKeeper.Subspace(bank.DefaultParamspace)
   }
   

4. Create the keeper. Note, the x/bank module depends on the x/auth module and a list of blocklisted account addresses which funds are not allowed to be sent to. Your application will need to define this method based your needs.

   func NewApp(...) *App {
     // ...
     app.BankKeeper = bank.NewBaseKeeper(
       app.AccountKeeper, app.subspaces[bank.ModuleName], app.BlocklistedAccAddrs(),
     )
   }
   

5. Add the x/bank module to the app's ModuleManager.

   func NewApp(...) *App {
     // ...
     app.mm = module.NewManager(
       // ...
       bank.NewAppModule(app.BankKeeper, app.AccountKeeper),
       // ...
     )
   }
   

6. Set the x/bank module genesis order.

   func NewApp(...) *App {
     // ...
     app.mm.SetOrderInitGenesis(..., bank.ModuleName, ...)
   }
   

7. Add the x/bank module to the simulation manager (if you have one set).

   func NewApp(...) *App {
     // ...
     app.sm = module.NewSimulationManager(
       // ...
       bank.NewAppModule(app.BankKeeper, app.AccountKeeper),
       // ...
     )
   }
   
   

Genesis

The x/bank module defines its genesis state as follows:

type GenesisState struct {
  SendEnabled bool `json:"send_enabled" yaml:"send_enabled"`
}

The SendEnabled parameter determines if transfers are enabled or disabled entirely on the chain. This can be used to start a network without enabling transfers while ensuring critical network functionality is operating as expected.

Messages

MsgSend

The x/bank module allows for transfer of funds from a source account to a destination account.

type MsgSend struct {
  FromAddress sdk.AccAddress `json:"from_address" yaml:"from_address"`
  ToAddress   sdk.AccAddress `json:"to_address" yaml:"to_address"`
  Amount      sdk.Coins      `json:"amount" yaml:"amount"`
}

MsgMultiSend

The x/bank module also allows for multiple inputs and outputs. The sum of all inputs must be equivalent to the sum of all outputs.

type Input struct {
  Address sdk.AccAddress `json:"address" yaml:"address"`
  Coins   sdk.Coins      `json:"coins" yaml:"coins"`
}

type Output struct {
  Address sdk.AccAddress `json:"address" yaml:"address"`
  Coins   sdk.Coins      `json:"coins" yaml:"coins"`
}

type MsgMultiSend struct {
  Inputs  []Input  `json:"inputs" yaml:"inputs"`
  Outputs []Output `json:"outputs" yaml:"outputs"`
}

Client

CLI

The x/bank supports the following transactional commands.

1. Send tokens via a MsgSend message.

   app tx send [from_key_or_address] [to_address] [amount] [...flags]
   

Note, the x/bank module does not natively support constructing a MsgMultiSend message. This type of message must be constructed manually, but it may be signed and broadcasted via the CLI.

REST

The x/bank supports various query API endpoints and a MsgSend construction endpoint.

1. Construct an unsigned MsgSend transaction.

   Method	Path
   POST	/bank/accounts/{address}/transfers

   Sample payload:

   {
       "base_req": {
           "chain_id": "chain-foo",
           "from": "cosmos1u3fneykx9carelvurc6av22vpjvptytj9wklk0",
           "memo": "memo",
           "fees": [
               {
                   "denom": "stake",
                   "amount": "25000"
               }
           ]
       },
       "amount": [
           {
               "denom": "stake",
               "amount": "400000000"
           }
       ]
   }
   

2. Query for an account's balance.

   Method	Path
   GET	/bank/balances/{address}

   Sample response:

   {
       "height": "0",
       "result": [
           {
               "denom": "node0token",
               "amount": "1000000000"
           },
           {
               "denom": "stake",
               "amount": "400000000"
           }
       ]
   }