Bank

The bank module is the base transactional layer of the XPLA Chain. This module allows assets to be sent from one Account to another. The bank module defines the following types of send transactions: MsgSend and MsgMultiSend.

The 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 (notably delegating/undelegating for vesting accounts). It exposes several interfaces with varying capabilities for secure interaction with other modules which must alter user balances.

In addition, the bank module tracks and provides query support for the total supply of all assets used in the application.

This module will be used in the XPLA Chain.

Supply #

The supply functionality:

• passively tracks the total supply of coins within a chain,
• provides a pattern for modules to hold/interact with Coins, and
• introduces the invariant check to verify a chain’s total supply.

Total Supply #

The total Supply of the network is equal to the sum of all coins from the account. The total supply is updated every time a Coin is minted (eg: as part of the inflation mechanism) or burned (eg: due to slashing or if a governance proposal is vetoed).

Module Accounts #

The supply functionality introduces a new type of auth.Account which can be used by modules to allocate tokens and in special cases mint or burn tokens. At a base level these module accounts are capable of sending/receiving tokens to and from auth.Accounts and other module accounts. This design replaces previous alternative designs where, to hold tokens, modules would burn the incoming tokens from the sender account, and then track those tokens internally. Later, in order to send tokens, the module would need to effectively mint tokens within a destination account. The new design removes duplicate logic between modules to perform this accounting.

The ModuleAccount interface is defined as follows:

type ModuleAccount interface {
  auth.Account               // same methods as the Account interface

  GetName() string           // name of the module; used to obtain the address
  GetPermissions() []string  // permissions of module account
  HasPermission(string) bool
}

The supply Keeper also introduces new wrapper functions for the auth Keeper and the bank Keeper that are related to ModuleAccounts in order to be able to:

• Get and set ModuleAccounts by providing the Name.
• Send coins from and to other ModuleAccounts or standard Accounts (BaseAccount or VestingAccount) by passing only the Name.
• Mint or Burn coins for a ModuleAccount (restricted to its permissions).

Permissions #

Each ModuleAccount has a different set of permissions that provide different object capabilities to perform certain actions. Permissions need to be registered upon the creation of the supply Keeper so that every time a ModuleAccount calls the allowed functions, the Keeper can lookup the permissions to that specific account and perform or not the action.

The available permissions are:

• Minter: allows for a module to mint a specific amount of coins.
• Burner: allows for a module to burn a specific amount of coins.
• Staking: allows for a module to delegate and undelegate a specific amount of coins.

Message Types #

MsgSend #

MsgSend transfers funds from a source account to a destination account.

// MsgSend represents a message to send coins from one account to another.
type MsgSend struct {
	FromAddress string                                   `protobuf:"bytes,1,opt,name=from_address,json=fromAddress,proto3" json:"from_address,omitempty" yaml:"from_address"`
	ToAddress   string                                   `protobuf:"bytes,2,opt,name=to_address,json=toAddress,proto3" json:"to_address,omitempty" yaml:"to_address"`
	Amount      github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,3,rep,name=amount,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"amount"`
}

The Bank module is used to send coins from one XPLA Chain account to another. MsgSend is constructed to facilitate the transfer. If the balance of coins in the sender Account is insufficient or the recipient Account is unable to receive the funds via the bank module, the transaction fails. Fees already paid through failed transactions are not refunded.

MsgMultiSend #

// MsgMultiSend represents an arbitrary multi-in, multi-out send message.
type MsgMultiSend struct {
	Inputs  []Input  `protobuf:"bytes,1,rep,name=inputs,proto3" json:"inputs"`
	Outputs []Output `protobuf:"bytes,2,rep,name=outputs,proto3" json:"outputs"`
}

// Input models transaction input.
type Input struct {
	Address string                                   `protobuf:"bytes,1,opt,name=address,proto3" json:"address,omitempty"`
	Coins   github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,2,rep,name=coins,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"coins"`
}

// Output models transaction outputs.
type Output struct {
	Address string                                   `protobuf:"bytes,1,opt,name=address,proto3" json:"address,omitempty"`
	Coins   github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,2,rep,name=coins,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"coins"`
}

To send multiple transactions at once, use MsgMultiSend. For each transaction, Inputs contains the incoming transactions, and Outputs contains the outgoing transactions. The Inputs coin balance must exactly match the Outputs coin balance. Batching transactions via MsgMultiSend conserves gas fees and network bandwidth. Fees already paid through failed transactions are not refunded.