cosmos-sdk/docs/sdk/core/accounts.md

Accounts and x/auth

auth.Account

// Account is a standard account using a sequence number for replay protection
// and a pubkey for authentication.
type Account interface {
	GetAddress() sdk.Address
	SetAddress(sdk.Address) error // errors if already set.

	GetPubKey() crypto.PubKey // can return nil.
	SetPubKey(crypto.PubKey) error

	GetAccountNumber() int64
	SetAccountNumber(int64) error

	GetSequence() int64
	SetSequence(int64) error

	GetCoins() sdk.Coins
	SetCoins(sdk.Coins) error
}

Accounts are the standard way for an application to keep track of addresses and their associated balances.

auth.BaseAccount

// BaseAccount - base account structure.
// Extend this by embedding this in your AppAccount.
// See the examples/basecoin/types/account.go for an example.
type BaseAccount struct {
	Address       sdk.Address   `json:"address"`
	Coins         sdk.Coins     `json:"coins"`
	PubKey        crypto.PubKey `json:"public_key"`
	AccountNumber int64         `json:"account_number"`
	Sequence      int64         `json:"sequence"`
}

The auth.BaseAccount struct provides a standard implementation of the Account interface with replay protection. BaseAccount can be extended by embedding it in your own Account struct.

auth.AccountMapper

// This AccountMapper encodes/decodes accounts using the
// go-amino (binary) encoding/decoding library.
type AccountMapper struct {

	// The (unexposed) key used to access the store from the Context.
	key sdk.StoreKey

	// The prototypical Account concrete type.
	proto Account

	// The wire codec for binary encoding/decoding of accounts.
	cdc *wire.Codec
}

The AccountMapper is responsible for managing and storing the state of all accounts in the application.

Example Initialization:

// File: examples/basecoin/app/app.go
// Define the accountMapper.
app.accountMapper = auth.NewAccountMapper(
	cdc,
	app.keyAccount,      // target store
	&types.AppAccount{}, // prototype
)

The accountMapper allows you to retrieve the current account state by GetAccount(ctx Context, addr auth.Address) and change the state by SetAccount(ctx Context, acc Account).

Note: To update an account you will first have to get the account, update the appropriate fields with its associated setter method, and then call SetAccount(ctx Context, acc updatedAccount).

Updating accounts is made easier by using the Keeper struct in the x/bank module.

Example Initialization:

// File: examples/basecoin/app/app.go
app.coinKeeper = bank.NewKeeper(app.accountMapper)

Example Usage:

// Finds account with addr in accountmapper
// Adds coins to account's coin array
// Sets updated account in accountmapper
app.coinKeeper.AddCoins(ctx, addr, coins)