BaseApp
This document describes BaseApp
, the abstraction that implements the core functionalities of a Cosmos SDK application.
Introduction
BaseApp
is a base type that implements the core of a Cosmos SDK application, namely:
- The Application Blockchain Interface, for the state-machine to communicate with the underlying consensus engine (e.g. CometBFT).
- Service Routers, to route messages and queries to the appropriate module.
- Different states, as the state-machine can have different volatile states updated based on the ABCI message received.
The goal of BaseApp
is to provide the fundamental layer of a Cosmos SDK application
that developers can easily extend to build their own custom application. Usually,
developers will create a custom type for their application, like so:
type App struct {
// reference to a BaseApp
*baseapp.BaseApp
// list of application store keys
// list of application keepers
// module manager
}
Extending the application with BaseApp
gives the former access to all of BaseApp
's methods.
This allows developers to compose their custom application with the modules they want, while not
having to concern themselves with the hard work of implementing the ABCI, the service routers and state
management logic.
Type Definition
The BaseApp
type holds many important parameters for any Cosmos SDK based application.
https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/baseapp/baseapp.go#L63-L191
Let us go through the most important components.
Note: Not all parameters are described, only the most important ones. Refer to the type definition for the full list.
First, the important parameters that are initialized during the bootstrapping of the application:
CommitMultiStore
: This is the main store of the application, which holds the canonical state that is committed at the end of each block. This store is not cached, meaning it is not used to update the application's volatile (un-committed) states. TheCommitMultiStore
is a multi-store, meaning a store of stores. Each module of the application uses one or multipleKVStores
in the multi-store to persist their subset of the state.- Database: The
db
is used by theCommitMultiStore
to handle data persistence. Msg
Service Router: ThemsgServiceRouter
facilitates the routing ofsdk.Msg
requests to the appropriate moduleMsg
service for processing. Here asdk.Msg
refers to the transaction component that needs to be processed by a service in order to update the application state, and not to ABCI message which implements the interface between the application and the underlying consensus engine.- gRPC Query Router: The
grpcQueryRouter
facilitates the routing of gRPC queries to the appropriate module for it to be processed. These queries are not ABCI messages themselves, but they are relayed to the relevant module's gRPCQuery
service. TxDecoder
: It is used to decode raw transaction bytes relayed by the underlying CometBFT engine.AnteHandler
: This handler is used to handle signature verification, fee payment, and other pre-message execution checks when a transaction is received. It's executed duringCheckTx/RecheckTx
andFinalizeBlock
.InitChainer
,PreBlocker
,BeginBlocker
andEndBlocker
: These are the functions executed when the application receives theInitChain
andFinalizeBlock
ABCI messages from the underlying CometBFT engine.
Then, parameters used to define volatile states (i.e. cached states):
checkState
: This state is updated duringCheckTx
, and reset onCommit
.finalizeBlockState
: This state is updated duringFinalizeBlock
, and set tonil
onCommit
and gets re-initialized onFinalizeBlock
.processProposalState
: This state is updated duringProcessProposal
.prepareProposalState
: This state is updated duringPrepareProposal
.
Finally, a few more important parameters:
voteInfos
: This parameter carries the list of validators whose precommit is missing, either because they did not vote or because the proposer did not include their vote. This information is carried by the Context and can be used by the application for various things like punishing absent validators.minGasPrices
: This parameter defines the minimum gas prices accepted by the node. This is a local parameter, meaning each full-node can set a differentminGasPrices
. It is used in theAnteHandler
duringCheckTx
, mainly as a spam protection mechanism. The transaction enters the mempool only if the gas prices of the transaction are greater than one of the minimum gas price inminGasPrices
(e.g. ifminGasPrices == 1uatom,1photon
, thegas-price
of the transaction must be greater than1uatom
OR1photon
).appVersion
: Version of the application. It is set in the application's constructor function.
Constructor
func NewBaseApp(
name string, logger log.Logger, db corestore.KVStoreWithBatch, txDecoder sdk.TxDecoder, options ...func(*BaseApp),
) *BaseApp {
// ...
}
The BaseApp
constructor function is pretty straightforward. The only thing worth noting is the
possibility to provide additional options
to the BaseApp
, which will execute them in order. The options
are generally setter
functions
for important parameters, like SetPruning()
to set pruning options or SetMinGasPrices()
to set
the node's min-gas-prices
.
Naturally, developers can add additional options
based on their application's needs.
State Updates
The BaseApp
maintains four primary volatile states and a root or main state. The main state
is the canonical state of the application and the volatile states, checkState
, prepareProposalState
, processProposalState
and finalizeBlockState
are used to handle state transitions in-between the main state made during Commit
.
Internally, there is only a single CommitMultiStore
which we refer to as the main or root state.
From this root state, we derive four volatile states by using a mechanism called store branching (performed by CacheWrap
function).
The types can be illustrated as follows:
InitChain State Updates
During InitChain
, the four volatile states, checkState
, prepareProposalState
, processProposalState
and finalizeBlockState
are set by branching the root CommitMultiStore
. Any subsequent reads and writes happen
on branched versions of the CommitMultiStore
.
To avoid unnecessary roundtrip to the main state, all reads to the branched store are cached.
CheckTx State Updates
During CheckTx
, the checkState
, which is based on the last committed state from the root
store, is used for any reads and writes. Here we only execute the AnteHandler
and verify a service router
exists for every message in the transaction. Note, when we execute the AnteHandler
, we branch
the already branched checkState
.
This has the side effect that if the AnteHandler
fails, the state transitions won't be reflected in the checkState
-- i.e. checkState
is only updated on success.
PrepareProposal State Updates
During PrepareProposal
, the prepareProposalState
is set by branching the root CommitMultiStore
.
The prepareProposalState
is used for any reads and writes that occur during the PrepareProposal
phase.
The function uses the Select()
method of the mempool to iterate over the transactions. runTx
is then called,
which encodes and validates each transaction and from there the AnteHandler
is executed.
If successful, valid transactions are returned inclusive of the events, tags, and data generated
during the execution of the proposal.
The described behavior is that of the default handler, applications have the flexibility to define their own
custom mempool handlers.
ProcessProposal State Updates
During ProcessProposal
, the processProposalState
is set based off of the last committed state
from the root store and is used to process a signed proposal received from a validator.
In this state, runTx
is called and the AnteHandler
is executed and the context used in this state is built with information
from the header and the main state, including the minimum gas prices, which are also set.
Again we want to highlight that the described behavior is that of the default handler and applications have the flexibility to define their own
custom mempool handlers.
FinalizeBlock State Updates
During FinalizeBlock
, the finalizeBlockState
is set for use during transaction execution and endblock. The
finalizeBlockState
is based off of the last committed state from the root store and is branched.
Note, the finalizeBlockState
is set to nil
on Commit
.
The state flow for transaction execution is nearly identical to CheckTx
except state transitions occur on
the finalizeBlockState
and messages in a transaction are executed. Similarly to CheckTx
, state transitions
occur on a doubly branched state -- finalizeBlockState
. Successful message execution results in
writes being committed to finalizeBlockState
. Note, if message execution fails, state transitions from
the AnteHandler are persisted.
Commit State Updates
During Commit
all the state transitions that occurred in the finalizeBlockState
are finally written to
the root CommitMultiStore
which in turn is committed to disk and results in a new application
root hash. These state transitions are now considered final. Finally, the checkState
is set to the
newly committed state and finalizeBlockState
is set to nil
to be reset on FinalizeBlock
.
ParamStore
During InitChain
, the RequestInitChain
provides ConsensusParams
which contains parameters
related to block execution such as maximum gas and size in addition to evidence parameters. If these
parameters are non-nil, they are set in the BaseApp's ParamStore
. Behind the scenes, the ParamStore
is managed by an x/consensus
module. This allows the parameters to be tweaked via
on-chain governance.
Service Routers
When messages and queries are received by the application, they must be routed to the appropriate module in order to be processed. Routing is done via BaseApp
, which holds a msgServiceRouter
for messages, and a grpcQueryRouter
for queries.
Msg
Service Router
sdk.Msg
s need to be routed after they are extracted from transactions, which are sent from the underlying CometBFT engine via the CheckTx
and FinalizeBlock
ABCI messages. To do so, BaseApp
holds a msgServiceRouter
which maps fully-qualified service methods (string
, defined in each module's Protobuf Msg
service) to the appropriate module's MsgServer
implementation.
The default msgServiceRouter
included in BaseApp
is stateless. However, some applications may want to make use of more stateful routing mechanisms such as allowing governance to disable certain routes or point them to new modules for upgrade purposes. For this reason, the sdk.Context
is also passed into each route handler inside msgServiceRouter
. For a stateless router that doesn't want to make use of this, you can just ignore the ctx
.
The application's msgServiceRouter
is initialized with all the routes using the application's module manager (via the RegisterServices
method), which itself is initialized with all the application's modules in the application's constructor.
gRPC Query Router
Similar to sdk.Msg
s, queries
need to be routed to the appropriate module's Query
service. To do so, BaseApp
holds a grpcQueryRouter
, which maps modules' fully-qualified service methods (string
, defined in their Protobuf Query
gRPC) to their QueryServer
implementation. The grpcQueryRouter
is called during the initial stages of query processing, which can be either by directly sending a gRPC query to the gRPC endpoint, or via the Query
ABCI message on the CometBFT RPC endpoint.
Just like the msgServiceRouter
, the grpcQueryRouter
is initialized with all the query routes using the application's module manager (via the RegisterServices
method), which itself is initialized with all the application's modules in the application's constructor.
Main ABCI 2.0 Messages
The Application-Blockchain Interface (ABCI) is a generic interface that connects a state-machine with a consensus engine to form a functional full-node. It can be wrapped in any language, and needs to be implemented by each application-specific blockchain built on top of an ABCI-compatible consensus engine like CometBFT.
The consensus engine handles two main tasks:
- The networking logic, which mainly consists in gossiping block parts, transactions and consensus votes.
- The consensus logic, which results in the deterministic ordering of transactions in the form of blocks.
It is not the role of the consensus engine to define the state or the validity of transactions. Generally, transactions are handled by the consensus engine in the form of []bytes
, and relayed to the application via the ABCI to be decoded and processed. At keys moments in the networking and consensus processes (e.g. beginning of a block, commit of a block, reception of an unconfirmed transaction, ...), the consensus engine emits ABCI messages for the state-machine to act on.
Developers building on top of the Cosmos SDK don't need to implement the ABCI themselves, as BaseApp
comes with a built-in implementation of the interface. Let us go through the main ABCI messages that BaseApp
implements:
Prepare Proposal
The PrepareProposal
function is part of the new methods introduced in Application Blockchain Interface (ABCI++) in CometBFT and is an important part of the application's overall governance system. In the Cosmos SDK, it allows the application to have more fine-grained control over the transactions that are processed, and ensures that only valid transactions are committed to the blockchain.
Here is how the PrepareProposal
function can be implemented:
- Extract the
sdk.Msg
s from the transaction. - Perform stateful checks by calling
Validate()
on each of thesdk.Msg
's. This is done after stateless checks as stateful checks are more computationally expensive. IfValidate()
fails,PrepareProposal
returns before running further checks, which saves resources. - Perform any additional checks that are specific to the application, such as checking account balances, or ensuring that certain conditions are met before a transaction is proposed. They are processed by the consensus engine, if necessary.
- Return the updated transactions to be processed by the consensus engine
Note that, unlike CheckTx()
, PrepareProposal
process sdk.Msg
s, so it can directly update the state. However, unlike FinalizeBlock()
, it does not commit the state updates. It's important to exercise caution when using PrepareProposal
as incorrect coding could affect the overall liveness of the network.
It's important to note that PrepareProposal
complements the ProcessProposal
method which is executed after this method. The combination of these two methods means that it is possible to guarantee that no invalid transactions are ever committed. Furthermore, such a setup can give rise to other interesting use cases such as Oracles, threshold decryption and more.
PrepareProposal
returns a response to the underlying consensus engine of type abci.PrepareProposalResponse
. The response contains:
Txs ([][]byte)
: List of transactions which will form a block
Process Proposal
The ProcessProposal
function is called by the BaseApp as part of the ABCI message flow, and is executed during the FinalizeBlock
phase of the consensus process. The purpose of this function is to give more control to the application for block validation, allowing it to check all transactions in a proposed block before the validator sends the prevote for the block. It allows a validator to perform application-dependent work in a proposed block, enabling features such as immediate block execution, and allows the Application to reject invalid blocks.
The ProcessProposal
function performs several key tasks, including:
- Validating the proposed block by checking all transactions in it.
- Checking the proposed block against the current state of the application, to ensure that it is valid and that it can be executed.
- Updating the application's state based on the proposal, if it is valid and passes all checks.
- Returning a response to CometBFT indicating the result of the proposal processing.
The ProcessProposal
is an important part of the application's overall governance system. It is used to manage the network's parameters and other key aspects of its operation. It also ensures that the coherence property is adhered to i.e. all honest validators must accept a proposal by an honest proposer.
It's important to note that ProcessProposal
complements the PrepareProposal
method which enables the application to have more fine-grained transaction control by allowing it to reorder, drop, delay, modify, and even add transactions as they see necessary. The combination of these two methods means that it is possible to guarantee that no invalid transactions are ever committed. Furthermore, such a setup can give rise to other interesting use cases such as Oracles, threshold decryption and more.
CometBFT calls it when it receives a proposal and the CometBFT algorithm has not locked on a value. The Application cannot modify the proposal at this point but can reject it if it is invalid. If that is the case, CometBFT will prevote nil
on the proposal, which has strong liveness implications for CometBFT. As a general rule, the Application SHOULD accept a prepared proposal passed via ProcessProposal
, even if a part of the proposal is invalid (e.g., an invalid transaction); the Application can ignore the invalid part of the prepared proposal at block execution time.
However, developers must exercise greater caution when using these methods. Incorrectly coding these methods could affect liveness as CometBFT is unable to receive 2/3 valid precommits to finalize a block.
ProcessProposal
returns a response to the underlying consensus engine of type abci.ProcessProposalResponse
. The response contains:
Status (ProposalStatus)
: Status of the proposal processing
where ProposalStatus
can be one of the following status value:
enum ProposalStatus {
UNKNOWN = 0; // Unknown status. Returning this from the application is always an error.
ACCEPT = 1; // Status that signals that the application finds the proposal valid.
REJECT = 2; // Status that signals that the application finds the proposal invalid.
}
CheckTx
CheckTx
is sent by the underlying consensus engine when a new unconfirmed (i.e. not yet included in a valid block)
transaction is received by a full-node. The role of CheckTx
is to guard the full-node's mempool
(where unconfirmed transactions are stored until they are included in a block) from spam transactions.
Unconfirmed transactions are relayed to peers only if they pass CheckTx
.
CheckTx()
can perform both stateful and stateless checks, but developers should strive to
make the checks lightweight because gas fees are not charged for the resources (CPU, data load...) used during the CheckTx
.
The Context
, which includes a GasMeter
that tracks how much gas is used during the execution of Tx
, is initialized at the beginning of CheckTx
. The user-provided amount of gas for Tx
is referred to as GasWanted
. If GasConsumed
, the amount of gas used during execution, exceeds GasWanted
, the execution is halted and the changes made to the cached copy of the state are not committed. Otherwise, CheckTx
sets GasUsed
equal to GasConsumed
and returns it in the result. After calculating the gas and fee values, validator-nodes ensure that the user-specified gas-prices
exceed their locally defined min-gas-prices
.
In the Cosmos SDK, after decoding transactions, CheckTx()
is implemented
to do the following checks:
- Extract the
sdk.Msg
s from the transaction. - Optionally perform stateless checks by calling
ValidateBasic()
on each of thesdk.Msg
s. This is done first, as stateless checks are less computationally expensive than stateful checks. IfValidateBasic()
fail,CheckTx
returns before running stateful checks, which saves resources. This check is still performed for messages that have not yet migrated to the new message validation mechanism defined in RFC 001 and still have aValidateBasic()
method. - Perform non-module related stateful checks on the account. This step is mainly about checking
that the
sdk.Msg
signatures are valid, that enough fees are provided and that the sending account has enough funds to pay for said fees. Note that no precisegas
counting occurs here, assdk.Msg
s are not processed. Usually, theAnteHandler
will check that thegas
provided with the transaction is superior to a minimum reference gas amount based on the raw transaction size, in order to avoid spam with transactions that provide 0 gas.
CheckTx
does not process sdk.Msg
s - they only need to be processed when the canonical state needs to be updated, which happens during FinalizeBlock
.
Steps 2. and 3. are performed by the AnteHandler
in the RunTx()
function, which CheckTx()
calls with the runTxModeCheck
mode. During each step of CheckTx()
, a
special volatile state called checkState
is updated. This state is used to keep
track of the temporary changes triggered by the CheckTx()
calls of each transaction without modifying
the main canonical state. For example, when a transaction goes through CheckTx()
, the
transaction's fees are deducted from the sender's account in checkState
. If a second transaction is
received from the same account before the first is processed, and the account has consumed all its
funds in checkState
during the first transaction, the second transaction will fail CheckTx
() and
be rejected. In any case, the sender's account will not actually pay the fees until the transaction
is actually included in a block, because checkState
never gets committed to the main state. The
checkState
is reset to the latest state of the main state each time a blocks gets committed.
CheckTx
returns a response to the underlying consensus engine of type abci.CheckTxResponse
.
The response contains:
Code (uint32)
: Response Code.0
if successful.Data ([]byte)
: Result bytes, if any.Log (string):
The output of the application's logger. May be non-deterministic.Info (string):
Additional information. May be non-deterministic.GasWanted (int64)
: Amount of gas requested for transaction. It is provided by users when they generate the transaction.GasUsed (int64)
: Amount of gas consumed by transaction. DuringCheckTx
, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction. Next is an example:
loading...
Events ([]cmn.KVPair)
: Key-Value tags for filtering and indexing transactions (eg. by account). Seeevents
for more.Codespace (string)
: Namespace for the Code.
RecheckTx
After Commit
, CheckTx
is run again on all transactions that remain in the node's local mempool
excluding the transactions that are included in the block. To prevent the mempool from rechecking all transactions
every time a block is committed, the configuration option mempool.recheck=false
can be set. As of
Tendermint v0.32.1, an additional Type
parameter is made available to the CheckTx
function that
indicates whether an incoming transaction is new (CheckTxType_New
), or a recheck (CheckTxType_Recheck
).
This allows certain checks like signature verification can be skipped during CheckTxType_Recheck
.
RunTx, AnteHandler, RunMsgs, PostHandler
RunTx
RunTx
is called from CheckTx
/Finalizeblock
to handle the transaction, with execModeCheck
or execModeFinalize
as parameter to differentiate between the two modes of execution. Note that when RunTx
receives a transaction, it has already been decoded.
The first thing RunTx
does upon being called is to retrieve the context
's CacheMultiStore
by calling the getContextForTx()
function with the appropriate mode (either runTxModeCheck
or execModeFinalize
). This CacheMultiStore
is a branch of the main store, with cache functionality (for query requests), instantiated during FinalizeBlock
for transaction execution and during the Commit
of the previous block for CheckTx
. After that, two defer func()
are called for gas
management. They are executed when runTx
returns and make sure gas
is actually consumed, and will throw errors, if any.
After that, RunTx()
calls ValidateBasic()
, when available and for backward compatibility, on each sdk.Msg
in the Tx
, which runs preliminary stateless validity checks. If any sdk.Msg
fails to pass ValidateBasic()
, RunTx()
returns with an error.
Then, the anteHandler
of the application is run (if it exists). In preparation of this step, both the checkState
/finalizeBlockState
's context
and context
's CacheMultiStore
are branched using the cacheTxContext()
function.
loading...
This allows RunTx
not to commit the changes made to the state during the execution of anteHandler
if it ends up failing. It also prevents the module implementing the anteHandler
from writing to state, which is an important part of the object-capabilities of the Cosmos SDK.
Finally, the RunMsgs()
function is called to process the sdk.Msg
s in the Tx
. In preparation of this step, just like with the anteHandler
, both the checkState
/finalizeBlockState
's context
and context
's CacheMultiStore
are branched using the cacheTxContext()
function.
AnteHandler
The AnteHandler
is a special handler that implements the AnteHandler
interface and is used to authenticate the transaction before the transaction's internal messages are processed. It is theoretically optional but serves as a crucial component in most public blockchain networks.
The AnteHandler
operates on a copy of the cached context, allowing it to perform stateful checks such as signature verification, sequence number incrementation, and fee deduction without altering the last committed state. If the execution fails, it can revert to the original state, ensuring that only successful transactions modify the blockchain state.
Key operations performed by the AnteHandler
include:
- Signature Verification: Ensures that the transaction's signatures are valid.
- Sequence Checking: Verifies and increments the sequence numbers to prevent replay attacks.
- Fee Deduction: Deducts the transaction fees from the accounts involved, typically starting with the first signer.
These operations are crucial for maintaining the security and integrity of transactions on the blockchain.
For more detailed examples, see the auth
module's AnteHandler
which is widely used for these purposes.
Ante handlers typically operate at the transaction level. By default, they process only the outermost message of a transaction. However, transactions that embed multiple messages, such as those found in modules like x/authz or x/gov, may have inner messages that are not automatically processed by these default ante handlers. These inner messages are generally routed directly to the message router bypassing the ante handlers. To ensure comprehensive processing, custom ante handlers can be designed to recursively inspect and apply necessary checks to all embedded messages within a transaction. This capability must be explicitly implemented to extend the awareness of ante handlers to inner messages.
The AnteHandler
is a primary line of defense against spam and a second line of defense (the first one being the mempool) against transaction replay with fees deduction and sequence
checking. It also performs preliminary stateful validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees, and plays a role in the incentivisation of stakeholders via the collection of transaction fees.
BaseApp
holds an anteHandler
as parameter that is initialized in the application's constructor. The most widely used anteHandler
is the auth
module.
Click here for more on the anteHandler
.
RunMsgs
RunMsgs
is called from RunTx
with runTxModeCheck
as parameter to check the existence of a route for each message the transaction, and with execModeFinalize
to actually process the sdk.Msg
s.
FinalizeBlock
, calls runMsgs
to fully execute each Msg
within the transaction. Since the transaction may have messages from different modules, BaseApp
needs to know which module to find the appropriate handler. This is achieved using BaseApp
's MsgServiceRouter
so that it can be processed by the module's Protobuf Msg
service.
For LegacyMsg
routing, the Route
function is called via the module manager to retrieve the route name and find the legacy Handler
within the module.
First, it retrieves the sdk.Msg
's fully-qualified type name, by checking the type_url
of the Protobuf Any
representing the sdk.Msg
. Then, using the application's msgServiceRouter
, it checks for the existence of Msg
service method related to that type_url
. At this point, if mode == runTxModeCheck
, RunMsgs
returns. Otherwise, if mode == execModeFinalize
, the Msg
service RPC is executed, before RunMsgs
returns.
PostHandler
PostHandler
is similar to AnteHandler
, but it, as the name suggests, executes custom post tx processing logic after RunMsgs
is called. PostHandler
receives the Result
of the RunMsgs
in order to enable this customizable behavior.
Like AnteHandler
s, PostHandler
s are theoretically optional.
Other use cases like unused gas refund can also be enabled by PostHandler
s.
loading...
Note, when PostHandler
s fail, the state from runMsgs
is also reverted, effectively making the transaction fail.
Other ABCI Messages
InitChain
The InitChain
ABCI message is sent from the underlying CometBFT engine when the chain is first started. It is mainly used to initialize parameters and state like:
- Consensus Parameters via
setConsensusParams
. checkState
andfinalizeBlockState
viasetState
.- The block gas meter, with infinite gas to process genesis transactions.
Finally, the InitChain(req abci.RequestInitChain)
method of BaseApp
calls the initChainer()
of the application in order to initialize the main state of the application from the genesis file
and, if defined, call the InitGenesis
function of each of the application's modules.
FinalizeBlock
The FinalizeBlock
ABCI message is sent from the underlying CometBFT engine when a block proposal created by the correct proposer is received. The previous BeginBlock, DeliverTx and Endblock
calls are private methods on the BaseApp struct.
loading...
PreBlock
- Run the application's
preBlocker()
, which mainly runs thePreBlocker()
method of each of the modules.
BeginBlock
Initialize
finalizeBlockState
with the latest header using thereq abci.RequestFinalizeBlock
passed as parameter via thesetState
function.baseapp/baseapp.goloading...
This function also resets the main gas meter.
Initialize the block gas meter with the
maxGas
limit. Thegas
consumed within the block cannot go abovemaxGas
. This parameter is defined in the application's consensus parameters.Run the application's
beginBlocker()
, which mainly runs theBeginBlocker()
method of each of the modules.Set the
VoteInfos
of the application, i.e. the list of validators whose precommit for the previous block was included by the proposer of the current block. This information is carried into theContext
so that it can be used during transaction execution and EndBlock.
Transaction Execution
When the underlying consensus engine receives a block proposal, each transaction in the block needs to be processed by the application. To that end, the underlying consensus engine sends the transactions in FinalizeBlock message to the application for each transaction in a sequential order.
Since FinalizeBlock
is an ABCI call, Tx
is received in the encoded []byte
form. Nodes first unmarshal the transaction, using the TxConfig
defined in the app, then call runTx
in execModeFinalize
, which is very similar to CheckTx
but also executes and writes state changes.
Before the first transaction of a given block is processed, a volatile state called finalizeBlockState
is initialized during FinalizeBlock. This state is updated each time a transaction is processed via FinalizeBlock
, and committed to the main state when the block is committed, after what it is set to nil
.
The FinalizeBlock
ABCI function defined in BaseApp
does the bulk of the state transitions: it is run for each transaction in the block in sequential order as committed to during consensus. Under the hood, transaction execution is almost identical to CheckTx
but calls the runTx
function in deliver mode instead of check mode.
Instead of using their checkState
, full-nodes use finalizeblock
:
https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/baseapp/baseapp.go#L756-L791
Transaction execution within FinalizeBlock
performs the exact same steps as CheckTx
, with a little caveat at step 3 and the addition of a fifth step:
- The
AnteHandler
does not check that the transaction'sgas-prices
is sufficient. That is because themin-gas-prices
valuegas-prices
is checked against is local to the node, and therefore what is enough for one full-node might not be for another. This means that the proposer can potentially include transactions for free, although they are not incentivised to do so, as they earn a bonus on the total fee of the block they propose. - For each
sdk.Msg
in the transaction, route to the appropriate module's ProtobufMsg
service. Additional stateful checks are performed, and the branched multistore held infinalizeBlockState
'scontext
is updated by the module'skeeper
. If theMsg
service returns successfully, the branched multistore held incontext
is written tofinalizeBlockState
CacheMultiStore
. Meaning, ProtobufMsg
service is responsible for executing each message in theTx
and causes state transitions to persist infinalizeBlockState
During the additional fifth step outlined in (2), each read/write to the store increases the value of GasConsumed
. You can find the default cost of each operation:
loading...
At any point, if GasConsumed > GasWanted
, the function returns with Code != 0
and the execution fails.
If there are any failed state changes resulting from a Tx
being invalid or GasMeter
running out, the transaction processing terminates and any state changes are reverted. Invalid transactions in a block proposal cause validator nodes to reject the block and vote for a nil
block instead.
Each transaction returns a response to the underlying consensus engine of type abci.ExecTxResult
. The response contains:
Code (uint32)
: Response Code.0
if successful.Data ([]byte)
: Result bytes, if any.Log (string):
The output of the application's logger. May be non-deterministic.Info (string):
Additional information. May be non-deterministic.GasWanted (int64)
: Amount of gas requested for transaction. It is provided by users when they generate the transaction.GasUsed (int64)
: Amount of gas consumed by transaction. During transaction execution, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction, and by adding gas each time a read/write to the store occurs.Events ([]cmn.KVPair)
: Key-Value tags for filtering and indexing transactions (eg. by account). Seeevents
for more.Codespace (string)
: Namespace for the Code.
EndBlock
EndBlock is run after transaction execution completes. It allows developers to have logic be executed at the end of each block. In the Cosmos SDK, the bulk EndBlock() method is to run the application's EndBlocker(), which mainly runs the EndBlocker() method of each of the application's modules.
loading...
Commit
The Commit
ABCI message is sent from the underlying CometBFT engine after the full-node has received precommits from 2/3+ of validators (weighted by voting power). This is the final step where nodes commit the block and state changes. Validator nodes perform the previous step of executing state transitions to validate the transactions, then sign the block to confirm it. Full nodes that are not validators do not participate in consensus but listen for votes to understand whether or not they should commit the state changes.
On the BaseApp
end, the Commit(res abci.CommitResponse)
function is implemented to commit all the valid state transitions that occurred during FinalizeBlock
and to reset state for the next block. It syncs all the state transitions by writing the finalizeBlockState.ms
into the application's internal state. finalizeBlockState.ms
is a branched multistore of the main store app.cms
. The Commit
function calls the Write()
function on finalizeBlockState.ms
, effectively committing the state transitions. Then, the Commit
function sets checkState
to the latest header (obtained from finalizeBlockState.ctx.BlockHeader
) and finalizeBlockState
to nil
.
Finally, Commit
returns the hash of the commitment of app.cms
back to the underlying consensus engine. This hash is used as a reference in the header of the next block. As soon as the state changes are committed, checkState
starts afresh from the most recently committed state and finalizeBlockState
resets to nil
in order to be consistent and reflect the changes.
Note that not all blocks have the same number of transactions and it is possible for consensus to result in a nil
block or one with none at all. In a public blockchain network, it is also possible for validators to be byzantine, or malicious, which may prevent a Tx
from being committed in the blockchain. Possible malicious behaviors include the proposer deciding to censor a Tx
by excluding it from the block or a validator voting against the block.
At this point, the transaction lifecycle of a Tx
is over: nodes have verified its validity, delivered it by executing its state changes, and committed those changes. The Tx
itself, in []byte
form, is stored in a block and appended to the blockchain.
Info
The Info
ABCI message is a simple query from the underlying consensus engine, notably used to sync the latter with the application during a handshake that happens on startup. When called, the Info(res abci.InfoResponse)
function from BaseApp
will return the application's name, version and the hash of the last commit of app.cms
.
Query
The Query
ABCI message is used to serve queries received from the underlying consensus engine, including queries received via RPC like CometBFT RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of gRPC queries in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the Query
method, which are outlined here.
Each CometBFT query
comes with a path
, which is a string
which denotes what to query. If the path
matches a gRPC fully-qualified service method, then BaseApp
will defer the query to the grpcQueryRouter
and let it handle it like explained above. Otherwise, the path
represents a query that is not (yet) handled by the gRPC router. BaseApp
splits the path
string with the /
delimiter. By convention, the first element of the split string (split[0]
) contains the category of query
(app
, p2p
, store
or custom
). The BaseApp
implementation of the Query(req abci.QueryRequest)
method is a simple dispatcher serving these 4 main categories of queries:
- Application-related queries like querying the application's version, which are served via the
handleQueryApp
method. - Direct queries to the multistore, which are served by the
handlerQueryStore
method. These direct queries are different from custom queries which go throughapp.queryRouter
, and are mainly used by third-party service provider like block explorers. - P2P queries, which are served via the
handleQueryP2P
method. These queries return eitherapp.addrPeerFilter
orapp.ipPeerFilter
that contain the list of peers filtered by address or IP respectively. These lists are first initialized viaoptions
inBaseApp
's constructor.
ExtendVote
ExtendVote
allows an application to extend a pre-commit vote with arbitrary data. This process does NOT have to be deterministic and the data returned can be unique to the validator process.
In the Cosmos-SDK this is implemented as a NoOp:
loading...
VerifyVoteExtension
VerifyVoteExtension
allows an application to verify that the data returned by ExtendVote
is valid. This process MUST be deterministic. Moreover, the value of ResponseVerifyVoteExtension.status MUST exclusively depend on the parameters passed in the call to RequestVerifyVoteExtension, and the last committed Application state.
In the Cosmos-SDK this is implemented as a NoOp:
loading...