github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/docs/core/events.md (about)

     1  <!--
     2  order: 7
     3  synopsis: "`Event`s are objects that contain information about the execution of the application.
     4  They are mainly used by service providers like block explorers and wallet to track the execution of
     5  various messages and index transactions."
     6  -->
     7  
     8  # Events
     9  
    10  ## Pre-Requisite Readings {hide}
    11  
    12  - [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
    13  
    14  ## Events
    15  
    16  Events are implemented in the Cosmos SDK as an alias of the ABCI `Event` type and
    17  take the form of: `{eventType}.{eventAttribute}={value}`.
    18  
    19  +++ https://github.com/tendermint/tendermint/blob/bc572217c07b90ad9cee851f193aaa8e9557cbc7/abci/types/types.pb.go#L2661-L2667
    20  
    21  Events contain:
    22  
    23  - A `type`, which is meant to categorize an event at a high-level (e.g. by module or action).
    24  - A list of `attributes`, which are key-value pairs that give more information about
    25    the categorized `event`.
    26    +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/events.go#L51-L56
    27  
    28  Events are returned to the underlying consensus engine in the response of the following ABCI messages:
    29  
    30  - [`BeginBlock`](./baseapp.md#beginblock)
    31  - [`EndBlock`](./baseapp.md#endblock)
    32  - [`CheckTx`](./baseapp.md#checktx)
    33  - [`DeliverTx`](./baseapp.md#delivertx)
    34  
    35  Events, the `type` and `attributes`, are defined on a **per-module basis** in the module's
    36  `/internal/types/events.go` file, and triggered from the module's [`handler`](../building-modules/handler.md)
    37  via the [`EventManager`](#eventmanager). In addition, each module documents its events under
    38  `spec/xx_events.md`.
    39  
    40  ## EventManager
    41  
    42  In Cosmos SDK applications, events are managed by an abstraction called the `EventManager`.
    43  Internally, the `EventManager` tracks a list of `Events` for the entire execution flow of a
    44  transaction or `BeginBlock`/`EndBlock`.
    45  
    46  +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/events.go#L16-L20
    47  
    48  The `EventManager` comes with a set of useful methods to manage events. Among them, the one that is
    49  used the most by module and application developers is the `EmitEvent` method, which tracks
    50  an `event` in the `EventManager`.
    51  
    52  +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/events.go#L29-L31
    53  
    54  Module developers should handle event emission via the `EventManager#EmitEvent` in each message
    55  `Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via
    56  the [`Context`](./context.md), where event emission generally follows this pattern:
    57  
    58  ```go
    59  ctx.EventManager().EmitEvent(
    60      sdk.NewEvent(eventType, sdk.NewAttribute(attributeKey, attributeValue)),
    61  )
    62  ```
    63  
    64  See the [`Handler`](../building-modules/handler.md) concept doc for a more detailed
    65  view on how to typically implement `Events` and use the `EventManager` in modules.
    66  
    67  ## Subscribing to Events
    68  
    69  It is possible to subscribe to `Events` via Tendermint's [Websocket](https://tendermint.com/docs/app-dev/subscribing-to-events-via-websocket.html#subscribing-to-events-via-websocket).
    70  This is done by calling the `subscribe` RPC method via Websocket:
    71  
    72  ```json
    73  {
    74      "jsonrpc": "2.0",
    75      "method": "subscribe",
    76      "id": "0",
    77      "params": {
    78          "query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'"
    79      }
    80  }
    81  ```
    82  
    83  The main `eventCategory` you can subscribe to are:
    84  
    85  - `NewBlock`: Contains `events` triggered during `BeginBlock` and `EndBlock`.
    86  - `Tx`: Contains `events` triggered during `DeliverTx` (i.e. transaction processing).
    87  - `ValidatorSetUpdates`: Contains validator set updates for the block.
    88  
    89  These events are triggered from the `state` package after a block is committed. You can get the
    90  full list of `event` categories [here](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants).
    91  
    92  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](https://github.com/cosmos/cosmos-sdk/blob/master/x/bank/internal/types/events.go)). Subscribing to this `event` would be done like so:
    93  
    94  ```json
    95  {
    96      "jsonrpc": "2.0",
    97      "method": "subscribe",
    98      "id": "0",
    99      "params": {
   100          "query": "tm.event='Tx' AND transfer.sender='senderAddress'"
   101      }
   102  }
   103  ```
   104  
   105  where `senderAddress` is an address following the [`AccAddress`](../basics/accounts.md#addresses) format. 
   106  
   107  ## Next {hide}
   108  
   109  Learn about [object-capabilities](./ocap.md) {hide}