4.7 KiB
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
-
Import the module.
import ( "github.com/cosmos/cosmos-sdk/x/bank" )
-
Add
AppModuleBasic
to yourModuleBasics
.var ( ModuleBasics = module.NewBasicManager( // ... bank.AppModuleBasic{}, } )
-
Create the module's parameter subspace in your application constructor.
func NewApp(...) *App { // ... app.subspaces[bank.ModuleName] = app.ParamsKeeper.Subspace(bank.DefaultParamspace) }
-
Create the keeper. Note, the
x/bank
module depends on thex/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(), ) }
-
Add the
x/bank
module to the app'sModuleManager
.func NewApp(...) *App { // ... app.mm = module.NewManager( // ... bank.NewAppModule(app.BankKeeper, app.AccountKeeper), // ... ) }
-
Set the
x/bank
module genesis order.func NewApp(...) *App { // ... app.mm.SetOrderInitGenesis(..., bank.ModuleName, ...) }
-
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.
-
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.
-
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" } ] }
-
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" } ] }