cosmos-sdk/docs/core/events.md

Events

Pre-Requisite Readings {hide}

• Anatomy of an SDK application {prereq}

Events

Events 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 type string, which can refer to the type of action that led to the event's emission (e.g. a certain value going above a threshold), or to the type of message if the event is triggered at the end of that message processing.
• A list of attributes, which are key-value pairs that give more information about the event. +++ 7d7821b9af/types/events.go (L51-L56)

Events are returned to the underlying consensus engine in the response of the following ABCI messages: CheckTx, DeliverTx, BeginBlock and EndBlock.

Typically, event types 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, events are generally managed by an object called the EventManager. It is implemented as a simple wrapper around a slice of events:

+++ 7d7821b9af/types/events.go (L16-L20)

The EventManager comes with a set of useful methods to manage events. 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: Contains events triggered during BeginBlock and EndBlock.
• Tx: Contains events triggered during DeliverTx (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}