x/auth), which tracks account metadata like addresses, public keys, account numbers, and sequence numbers.
Every account is controlled by a cryptographic keypair derived from a seed phrase. A seed phrase yields one or more private keys, each of which produces a public key and an account address.
What is an account
An account is a container for a user’s balances and a way to authorize transactions. It is an on-chain object that:- Holds one or more token balances
- Is identified by an address
- Signs transactions
- Tracks a sequence number
Public and private keys
Accounts are rooted in cryptographic keypairs. Cosmos SDK uses asymmetric cryptography, where a private key and public key form a pair. This is a fundamental concept in cryptography and is used to secure data and transactions.- A private key is used to sign transactions. Before signing, the transaction data is serialized and hashed; the private key then produces a digital signature over this hash. This signature proves ownership of the private key without revealing it. Private keys must always remain secret.
- a public key is an identifying piece of information that is derived mathmatically from the private key. It is used to verify that a message was signed by the private key associated with the public key and is used to identify the account. The corresponding public key is derived mathematically from the private key and is used by the network to verify those signatures. Because the public key is derived from the private key through a one-way function, it is not possible to derive the private key from the public key.
Seed phrases
Most wallets do not generate raw private keys directly. Instead, they start from a seed phrase (mnemonic), a list of human-readable words such as:- BIP-39 (mnemonic phrases) https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
- BIP-32 (hierarchical deterministic wallets) https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
- BIP-44 (multi-account derivation paths) https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
m/44'/118'/0'/0/0, where 118 is the Cosmos coin type). Each private key produces a public key.
Control of the seed phrase means control of the derived private keys and therefore control of the corresponding accounts. Losing the seed phrase without backing it up means losing access to the account forever.
Addresses
An address is a shortened identifier derived from the public key. The public key is hashed and encoded, typically in Bech32 format, with a prefix that indicates the chain, for examplecosmos. This address is what users share and what appears in state and transactions.
Sequences and replay protection
Each on-chain account tracks a sequence number. The sequence number starts at zero for a newly created account and increments by one after each successful transaction from that account. The sequence number exists to prevent replay attacks, which occur when an old signed transaction is submitted a second time. Because the sequence number must be current, a previously signed transaction with an old sequence is rejected. Sequence numbers also ensure transactions from a single account execute in a specific order, which matters when transactions depend on each other (for example, sending tokens then immediately staking them). Example:sequence = 1 but the account’s current sequence is 2, the transaction is rejected, ensuring that transactions are applied in order and cannot be reused.
Balances
Accounts are associated with token balances stored on-chain. Balances are managed by the bank module (x/bank) and indexed by account address. While account metadata (address, public key, sequence number) is stored in the auth module’s state, token balances are stored separately in the bank module’s state.
When tokens are sent from one account to another, the bank module updates balances in state. Conceptually, a token transfer decreases the sender’s balance and increases the recipient’s balance.
An account must have sufficient balance to cover the tokens being sent and any associated transaction fees. If the balance is insufficient, the transaction is rejected during validation.
Types of accounts
Cosmos SDK supports several account types that extend the base account model:- Base account: A standard account that holds balances and signs transactions. This is the most common account type for users.
- Module account: Owned by a module rather than a user. Module accounts are derived from the module name and cannot be controlled by a private key. For example, the staking module uses a module account to hold all delegated tokens, and the distribution module uses a module account to hold rewards before they are distributed. This design allows protocol logic to custody tokens without requiring a private key holder, which is essential for decentralized operations.
- Vesting account: Holds tokens that unlock gradually over time according to a schedule. Vesting accounts are often used for team allocations or investor tokens that vest over months or years. They restrict spending to only unlocked tokens while still allowing the account to participate in staking and governance.
Accounts and transaction authorization
Accounts authorize transactions by producing digital signatures. A transaction includes:- One or more messages
- A signature created using the private key
- A sequence number
- Associated fees
- The signature is verified using the account’s public key.
- The sequence number is checked against the account’s current sequence.
- Fees are deducted from the account’s balance.
- If validation passes, messages execute and may update state.
- If execution succeeds, the sequence number increments and state updates are committed.