# Context
The context
is a data structure intended to be passed from function to function that carries information about the current state of the application. It provides access to a branched storage (a safe branch of the entire state) as well as useful objects and information like gasMeter
, block height
, consensus parameters
and more.
# Pre-requisites Readings
# Context Definition
The Cosmos SDK Context
is a custom data structure that contains Go's stdlib context
(opens new window) as its base, and has many additional types within its definition that are specific to the Cosmos SDK. The Context
is integral to transaction processing in that it allows modules to easily access their respective store in the multistore
and retrieve transactional context such as the block header and gas meter.
- Base Context: The base type is a Go Context (opens new window), which is explained further in the Go Context Package section below.
- Multistore: Every application's
BaseApp
contains aCommitMultiStore
which is provided when aContext
is created. Calling theKVStore()
andTransientStore()
methods allows modules to fetch their respectiveKVStore
using their uniqueStoreKey
. - Header: The header (opens new window) is a Blockchain type. It carries important information about the state of the blockchain, such as block height and proposer of the current block.
- Header Hash: The current block header hash, obtained during
abci.RequestBeginBlock
. - Chain ID: The unique identification number of the blockchain a block pertains to.
- Transaction Bytes: The
[]byte
representation of a transaction being processed using the context. Every transaction is processed by various parts of the Cosmos SDK and consensus engine (e.g. Tendermint) throughout its lifecycle, some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic[]byte
type using some kind of encoding format such as Amino. - Logger: A
logger
from the Tendermint libraries. Learn more about logs here (opens new window). Modules call this method to create their own unique module-specific logger. - VoteInfo: A list of the ABCI type
VoteInfo
(opens new window), which includes the name of a validator and a boolean indicating whether they have signed the block. - Gas Meters: Specifically, a
gasMeter
for the transaction currently being processed using the context and ablockGasMeter
for the entire block it belongs to. Users specify how much in fees they wish to pay for the execution of their transaction; these gas meters keep track of how much gas has been used in the transaction or block so far. If the gas meter runs out, execution halts. - CheckTx Mode: A boolean value indicating whether a transaction should be processed in
CheckTx
orDeliverTx
mode. - Min Gas Price: The minimum gas price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore not be used in any functions used in sequences leading to state-transitions.
- Consensus Params: The ABCI type Consensus Parameters (opens new window), which specify certain limits for the blockchain, such as maximum gas for a block.
- Event Manager: The event manager allows any caller with access to a
Context
to emitEvents
. Modules may define module specificEvents
by defining variousTypes
andAttributes
or use the common definitions found intypes/
. Clients can subscribe or query for theseEvents
. TheseEvents
are collected throughoutDeliverTx
,BeginBlock
, andEndBlock
and are returned to Tendermint for indexing. For example: - Priority: The transaction priority, only relevant in
CheckTx
.
# Go Context Package
A basic Context
is defined in the Golang Context Package (opens new window). A Context
is an immutable data structure that carries request-scoped data across APIs and processes. Contexts
are also designed to enable concurrency and to be used in goroutines.
Contexts are intended to be immutable; they should never be edited. Instead, the convention is
to create a child context from its parent using a With
function. For example:
The Golang Context Package (opens new window) documentation instructs developers to
explicitly pass a context ctx
as the first argument of a process.
# Store branching
The Context
contains a MultiStore
, which allows for branchinig and caching functionality using CacheMultiStore
(queries in CacheMultiStore
are cached to avoid future round trips).
Each KVStore
is branched in a safe and isolated ephemeral storage. Processes are free to write changes to
the CacheMultiStore
. If a state-transition sequence is performed without issue, the store branch can
be committed to the underlying store at the end of the sequence or disregard them if something
goes wrong. The pattern of usage for a Context is as follows:
- A process receives a Context
ctx
from its parent process, which provides information needed to perform the process. - The
ctx.ms
is a branched store, i.e. a branch of the multistore is made so that the process can make changes to the state as it executes, without changing the originalctx.ms
. This is useful to protect the underlying multistore in case the changes need to be reverted at some point in the execution. - The process may read and write from
ctx
as it is executing. It may call a subprocess and passctx
to it as needed. - When a subprocess returns, it checks if the result is a success or failure. If a failure, nothing
needs to be done - the branch
ctx
is simply discarded. If successful, the changes made to theCacheMultiStore
can be committed to the originalctx.ms
viaWrite()
.
For example, here is a snippet from the runTx
function in baseapp
:
Here is the process:
- Prior to calling
runMsgs
on the message(s) in the transaction, it usesapp.cacheTxContext()
to branch and cache the context and multistore. runMsgCtx
- the context with branched store, is used inrunMsgs
to return a result.- If the process is running in
checkTxMode
, there is no need to write the changes - the result is returned immediately. - If the process is running in
deliverTxMode
and the result indicates a successful run over all the messages, the branched multistore is written back to the original.
# Next
Learn about the node client