certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
cosmos-sdk/x/bank/spec
History
Amaury Martiny e17dd4fd50
Update SPEC-SPEC & documentation for x/{bank,evidence} (#7404) 
* Update documentation for x/bank

* Update ModuleAccounts

* Put contets on top

* Update comments

* Do x/evidence

* Add ValidatorEvidence

* Update SPEC-SPEC

* Update anchor
 		2020-09-28 13:51:14 -03:00
..
README.md Update SPEC-SPEC & documentation for x/{bank,evidence} (#7404) 2020-09-28 13:51:14 -03:00

README.md

x/bank

Table of Contents

01. Abstract

This document specifies the bank module of the Cosmos SDK.

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 Cosmos Hub.

02. Concepts

Supply

The supply module:

  • 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 module introduces a new type of auth.AccountI interface, called ModuleAccountI, 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.AccountI interfaces 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 ModuleAccountI interface is defined as follows:

// ModuleAccountI defines an account interface for modules that hold tokens in
// an escrow.
type ModuleAccountI interface {
	AccountI                    // 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
}

WARNING! 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).

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

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

Permissions

Each ModuleAccountI 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 ModuleAccountI 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.

03. State

The x/bank module keeps state of two primary objects, account balances and the total supply of all balances.

  • Balances: []byte("balances") | []byte(address) / []byte(balance.Denom) -> ProtocolBuffer(balance)
  • Supply: 0x0 -> ProtocolBuffer(Supply)

04. Keepers

The bank module provides three different exported keeper interfaces which can be passed to other modules which need to read or update account balances. Modules should use the least-permissive interface which provides the functionality they require.

Note that you should always review the bank module code to ensure that permissions are limited in the way that you expect.

Common Types

Input

An input of a multiparty transfer

// Input models transaction input.
message Input {
  string   address                        = 1;
  repeated cosmos.base.v1beta1.Coin coins = 2;
}

Output

An output of a multiparty transfer.

// Output models transaction outputs.
message Output {
  string   address                        = 1;
  repeated cosmos.base.v1beta1.Coin coins = 2;
}

BaseKeeper

The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins. The BaseKeeper struct implements the following Keeper interface.

// Keeper defines a module interface that facilitates the transfer of coins
// between accounts.
type Keeper interface {
	SendKeeper

	InitGenesis(sdk.Context, types.GenesisState)
	ExportGenesis(sdk.Context) *types.GenesisState

	GetSupply(ctx sdk.Context) exported.SupplyI
	SetSupply(ctx sdk.Context, supply exported.SupplyI)

	GetDenomMetaData(ctx sdk.Context, denom string) types.Metadata
	SetDenomMetaData(ctx sdk.Context, denomMetaData types.Metadata)
	IterateAllDenomMetaData(ctx sdk.Context, cb func(types.Metadata) bool)

	SendCoinsFromModuleToAccount(ctx sdk.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error
	SendCoinsFromModuleToModule(ctx sdk.Context, senderModule, recipientModule string, amt sdk.Coins) error
	SendCoinsFromAccountToModule(ctx sdk.Context, senderAddr sdk.AccAddress, recipientModule string, amt sdk.Coins) error
	DelegateCoinsFromAccountToModule(ctx sdk.Context, senderAddr sdk.AccAddress, recipientModule string, amt sdk.Coins) error
	UndelegateCoinsFromModuleToAccount(ctx sdk.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error
	MintCoins(ctx sdk.Context, moduleName string, amt sdk.Coins) error
	BurnCoins(ctx sdk.Context, moduleName string, amt sdk.Coins) error

	DelegateCoins(ctx sdk.Context, delegatorAddr, moduleAccAddr sdk.AccAddress, amt sdk.Coins) error
	UndelegateCoins(ctx sdk.Context, moduleAccAddr, delegatorAddr sdk.AccAddress, amt sdk.Coins) error
	MarshalSupply(supplyI exported.SupplyI) ([]byte, error)
	UnmarshalSupply(bz []byte) (exported.SupplyI, error)

	types.QueryServer
}

SendKeeper

The send keeper provides access to account balances and the ability to transfer coins between accounts, but not to alter the total supply (mint or burn coins).

// SendKeeper defines a module interface that facilitates the transfer of coins
// between accounts without the possibility of creating coins.
type SendKeeper interface {
	ViewKeeper

	InputOutputCoins(ctx sdk.Context, inputs []types.Input, outputs []types.Output) error
	SendCoins(ctx sdk.Context, fromAddr sdk.AccAddress, toAddr sdk.AccAddress, amt sdk.Coins) error

	SubtractCoins(ctx sdk.Context, addr sdk.AccAddress, amt sdk.Coins) error
	AddCoins(ctx sdk.Context, addr sdk.AccAddress, amt sdk.Coins) error

	SetBalance(ctx sdk.Context, addr sdk.AccAddress, balance sdk.Coin) error
	SetBalances(ctx sdk.Context, addr sdk.AccAddress, balances sdk.Coins) error

	GetParams(ctx sdk.Context) types.Params
	SetParams(ctx sdk.Context, params types.Params)

	SendEnabledCoin(ctx sdk.Context, coin sdk.Coin) bool
	SendEnabledCoins(ctx sdk.Context, coins ...sdk.Coin) error

	BlockedAddr(addr sdk.AccAddress) bool
}

ViewKeeper

The view keeper provides read-only access to account balances but no balance alteration functionality. All balance lookups are O(1).

// ViewKeeper defines a module interface that facilitates read only access to
// account balances.
type ViewKeeper interface {
	ValidateBalance(ctx sdk.Context, addr sdk.AccAddress) error
	HasBalance(ctx sdk.Context, addr sdk.AccAddress, amt sdk.Coin) bool

	GetAllBalances(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
	GetAccountsBalances(ctx sdk.Context) []types.Balance
	GetBalance(ctx sdk.Context, addr sdk.AccAddress, denom string) sdk.Coin
	LockedCoins(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
	SpendableCoins(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins

	IterateAccountBalances(ctx sdk.Context, addr sdk.AccAddress, cb func(coin sdk.Coin) (stop bool))
	IterateAllBalances(ctx sdk.Context, cb func(address sdk.AccAddress, coin sdk.Coin) (stop bool))
}

05. Messages

MsgSend

// MsgSend represents a message to send coins from one account to another.
message MsgSend {
  string   from_address                    = 1;
  string   to_address                      = 2;
  repeated cosmos.base.v1beta1.Coin amount = 3;
}

handleMsgSend just runs inputOutputCoins.

handleMsgSend(msg MsgSend)
  inputSum = 0
  for input in inputs
    inputSum += input.Amount
  outputSum = 0
  for output in outputs
    outputSum += output.Amount
  if inputSum != outputSum:
    fail with "input/output amount mismatch"

  return inputOutputCoins(msg.Inputs, msg.Outputs)

06. Events

The bank module emits the following events:

Handlers

MsgSend

Type Attribute Key Attribute Value
transfer recipient {recipientAddress}
transfer amount {amount}
message module bank
message action send
message sender {senderAddress}

MsgMultiSend

Type Attribute Key Attribute Value
transfer recipient {recipientAddress}
transfer amount {amount}
message module bank
message action multisend
message sender {senderAddress}

07. Parameters

The bank module contains the following parameters:

Key Type Example
SendEnabled []SendEnabled [{denom: "stake", enabled: true }]
DefaultSendEnabled bool true

The corresponding Protobuf message is:

// Params defines the parameters for the bank module.
message Params {
  option                                    = false;
  repeated SendEnabled send_enabled         = 1;
  bool                 default_send_enabled = 2;
}

SendEnabled

The send enabled parameter is an array of SendEnabled entries mapping coin denominations to their send_enabled status. Entries in this list take precedence over the DefaultSendEnabled setting.

DefaultSendEnabled

The default send enabled value controls send transfer capability for all coin denominations unless specifically included in the array of SendEnabled parameters.