# x/auth
# Abstract
This document specifies the auth module of the Cosmos SDK.
The auth module is responsible for specifying the base transaction and account types for an application, since the SDK itself is agnostic to these particulars. It contains the middlewares, where all basic transaction validity checks (signatures, nonces, auxiliary fields) are performed, and exposes the account keeper, which allows other modules to read, write, and modify accounts.
This module is used in the Cosmos Hub.
# Contents
# Concepts
Note: The auth module is different from the authz module.
The differences are:
auth- authentication of accounts and transactions for Cosmos SDK applications and is responsible for specifying the base transaction and account types.authz- authorization for accounts to perform actions on behalf of other accounts and enables a granter to grant authorizations to a grantee that allows the grantee to execute messages on behalf of the granter.
# Gas & Fees
Fees serve two purposes for an operator of the network.
Fees limit the growth of the state stored by every full node and allow for general purpose censorship of transactions of little economic value. Fees are best suited as an anti-spam mechanism where validators are disinterested in the use of the network and identities of users.
Fees are determined by the gas limits and gas prices transactions provide, where
fees = ceil(gasLimit * gasPrices). Txs incur gas costs for all state reads/writes,
signature verification, as well as costs proportional to the tx size. Operators
should set minimum gas prices when starting their nodes. They must set the unit
costs of gas in each token denomination they wish to support:
simd start ... --minimum-gas-prices=0.00001stake;0.05photinos
When adding transactions to mempool or gossipping transactions, validators check if the transaction's gas prices, which are determined by the provided fees, meet any of the validator's minimum gas prices. In other words, a transaction must provide a fee of at least one denomination that matches a validator's minimum gas price.
CometBFT does not currently provide fee based mempool prioritization, and fee based mempool filtering is local to node and not part of consensus. But with minimum gas prices set, such a mechanism could be implemented by node operators.
Because the market value for tokens will fluctuate, validators are expected to dynamically adjust their minimum gas prices to a level that would encourage the use of the network.
# State
# Accounts
Accounts contain authentication information for a uniquely identified external user of an SDK blockchain,
including public key, address, and account number / sequence number for replay protection. For efficiency,
since account balances must also be fetched to pay fees, account structs also store the balance of a user
as sdk.Coins.
Accounts are exposed externally as an interface, and stored internally as either a base account or vesting account. Module clients wishing to add more account types may do so.
0x01 | Address -> ProtocolBuffer(account)
# Account Interface
The account interface exposes methods to read and write standard account information. Note that all of these methods operate on an account struct conforming to the interface - in order to write the account to the store, the account keeper will need to be used.
# Base Account
A base account is the simplest and most common account type, which just stores all requisite fields directly in a struct.
# Vesting Account
See Vesting (opens new window).
# AnteHandlers
The x/auth module presently has no transaction handlers of its own, but does expose the special AnteHandler, used for performing basic validity checks on a transaction, such that it could be thrown out of the mempool.
The AnteHandler can be seen as a set of decorators that check transactions within the current context, per ADR 010 (opens new window).
Note that the AnteHandler is called on both CheckTx and DeliverTx, as CometBFT proposers presently have the ability to include in their proposed block transactions which fail CheckTx.
# Decorators
The auth module provides AnteDecorators that are recursively chained together into a single AnteHandler in the following order:
SetUpContextDecorator: Sets theGasMeterin theContextand wraps the nextAnteHandlerwith a defer clause to recover from any downstreamOutOfGaspanics in theAnteHandlerchain to return an error with information on gas provided and gas used.RejectExtensionOptionsDecorator: Rejects all extension options which can optionally be included in protobuf transactions.MempoolFeeDecorator: Checks if thetxfee is above local mempoolminFeeparameter duringCheckTx.ValidateBasicDecorator: Callstx.ValidateBasicand returns any non-nil error.TxTimeoutHeightDecorator: Check for atxheight timeout.ValidateMemoDecorator: Validatestxmemo with application parameters and returns any non-nil error.ConsumeGasTxSizeDecorator: Consumes gas proportional to thetxsize based on application parameters.DeductFeeDecorator: Deducts theFeeAmountfrom first signer of thetx. If thex/feegrantmodule is enabled and a fee granter is set, it deducts fees from the fee granter account.SetPubKeyDecorator: Sets the pubkey from atx's signers that does not already have its corresponding pubkey saved in the state machine and in the current context.ValidateSigCountDecorator: Validates the number of signatures intxbased on app-parameters.SigGasConsumeDecorator: Consumes parameter-defined amount of gas for each signature. This requires pubkeys to be set in context for all signers as part ofSetPubKeyDecorator.SigVerificationDecorator: Verifies all signatures are valid. This requires pubkeys to be set in context for all signers as part ofSetPubKeyDecorator.IncrementSequenceDecorator: Increments the account sequence for each signer to prevent replay attacks.
# Keepers
The auth module only exposes one keeper, the account keeper, which can be used to read and write accounts.
# Account Keeper
Presently only one fully-permissioned account keeper is exposed, which has the ability to both read and write all fields of all accounts, and to iterate over all stored accounts.
# Parameters
The auth module contains the following parameters:
| Key | Type | Example |
|---|---|---|
| MaxMemoCharacters | uint64 | 256 |
| TxSigLimit | uint64 | 7 |
| TxSizeCostPerByte | uint64 | 10 |
| SigVerifyCostED25519 | uint64 | 590 |
| SigVerifyCostSecp256k1 | uint64 | 1000 |
# Client
# CLI
A user can query and interact with the auth module using the CLI.
# Query
The query commands allow users to query auth state.
# account
The account command allow users to query for an account by it's address.
Example:
Example Output:
# accounts
The accounts command allow users to query all the available accounts.
Example:
Example Output:
# params
The params command allow users to query the current auth parameters.
Example:
Example Output:
# Transactions
The auth module supports transactions commands to help you with signing and more. Compared to other modules you can access directly the auth module transactions commands using the only tx command.
Use directly the --help flag to get more information about the tx command.
# sign
The sign command allows users to sign transactions that was generated offline.
The result is a signed transaction that can be broadcasted to the network thanks to the broadcast command.
More information about the sign command can be found running simd tx sign --help.
# sign-batch
The sign-batch command allows users to sign multiples offline generated transactions.
The transactions can be in one file, with one tx per line, or in multiple files.
or
The result is multiples signed transactions. For combining the signed transactions into one transactions, use the --append flag.
More information about the sign-batch command can be found running simd tx sign-batch --help.
# multi-sign
The multi-sign command allows users to sign transactions that was generated offline by a multisig account.
Where k1k2k3 is the multisig account address, k1sig.json is the signature of the first signer, k2sig.json is the signature of the second signer, and k3sig.json is the signature of the third signer.
More information about the multi-sign command can be found running simd tx multi-sign --help.
# multisign-batch
The multisign-batch works the same way as sign-batch, but for multisig accounts.
With the difference that the multisign-batch command requires all transactions to be in one file, and the --append flag does not exist.
More information about the multisign-batch command can be found running simd tx multisign-batch --help.
# validate-signatures
The validate-signatures command allows users to validate the signatures of a signed transaction.
More information about the validate-signatures command can be found running simd tx validate-signatures --help.
# broadcast
The broadcast command allows users to broadcast a signed transaction to the network.
More information about the broadcast command can be found running simd tx broadcast --help.
# aux-to-fee
The aux-to-fee comamnds includes the aux signer data in the tx, broadcast the tx, and sends the tip amount to the broadcaster.
Learn more about tip transaction (opens new window).
More information about the aux-to-fee command can be found running simd tx aux-to-fee --help.
# gRPC
A user can query the auth module using gRPC endpoints.
# Account
The account endpoint allow users to query for an account by it's address.
Example:
Example Output:
# Accounts
The accounts endpoint allow users to query all the available accounts.
Example:
Example Output:
# Params
The params endpoint allow users to query the current auth parameters.
Example:
Example Output:
# REST
A user can query the auth module using REST endpoints.
# Account
The account endpoint allow users to query for an account by it's address.
# Accounts
The accounts endpoint allow users to query all the available accounts.
# Params
The params endpoint allow users to query the current auth parameters.