4.6 KiB
order | synopsis |
---|---|
7 | `Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. |
Events
Pre-Requisite Readings {hide}
- Anatomy of an SDK application {prereq}
Events
Event
s are implemented in the Cosmos SDK as an alias of the ABCI event
type.
+++ bc572217c0/abci/types/types.pb.go (L2661-L2667)
They contain:
- A
type
of typestring
, which can refer to the type of action that led to theevent
's emission (e.g. a certain value going above a threshold), or to the type ofmessage
if the event is triggered at the end of thatmessage
processing. - A list of
attributes
, which are key-value pairs that give more information about theevent
. +++7d7821b9af/types/events.go (L51-L56)
Event
s are returned to the underlying consensus engine in the response of the following ABCI messages: CheckTx
, DeliverTx
, BeginBlock
and EndBlock
.
Typically, event
type
s and attributes
are defined on a per-module basis in the module's /internal/types/events.go
file, and triggered from the module's handler
via the EventManager
.
EventManager
In Cosmos SDK applications, event
s are generally managed by an object called the EventManager
. It is implemented as a simple wrapper around a slice of event
s:
+++ 7d7821b9af/types/events.go (L16-L20)
The EventManager
comes with a set of useful methods to manage event
s. Among them, the one that is used the most by module and application developers is the EmitEvent
method, which registers an event
in the EventManager
.
+++ 7d7821b9af/types/events.go (L29-L31)
Typically, module developers will implement event emission via the EventManager
in the handler
of modules, as well as in the BeginBlocker
and/orEndBlocker
functions. The EventManager
is accessed via the context ctx
, and event emission generally follows this pattern:
ctx.EventManager().EmitEvent(
sdk.NewEvent(
eventType, // e.g. sdk.EventTypeMessage for a message, types.CustomEventType for a custom event defined in the module
sdk.NewAttribute(attributeKey, attributeValue),
),
)
See the handler
concept doc for a more detailed view on how to typically implement events
and use the EventManager
in modules.
Subscribing to events
It is possible to subscribe to events
via Tendermint's Websocket. This is done by calling the subscribe
RPC method via Websocket:
{
"jsonrpc": "2.0",
"method": "subscribe",
"id": "0",
"params": {
"query": "tm.event='eventCategory' AND type.attribute='attributeValue'"
}
}
The main eventCategory
you can subscribe to are:
NewBlock
: Containsevents
triggered duringBeginBlock
andEndBlock
.Tx
: Containsevents
triggered duringDeliverTx
(i.e. transaction processing).ValidatorSetUpdates
: Contains validator set updates for the block.
These events are triggered from the state
package after a block is committed. You can get the full list of event
categories here.
The type
and attribute
value of the query
allow you to filter the specific event
you are looking for. For example, a transfer
transaction triggers an event
of type Transfer
and has Recipient
and Sender
as attributes
(as defined in the events
file of the bank
module). Subscribing to this event
would be done like so:
{
"jsonrpc": "2.0",
"method": "subscribe",
"id": "0",
"params": {
"query": "tm.event='Tx' AND transfer.sender='senderAddress'"
}
}
where senderAddress
is an address following the AccAddress
format.
Next {hide}
Learn about object-capabilities {hide}