github.com/ari-anchor/sei-tendermint@v0.0.0-20230519144642-dc826b7b56bb/docs/architecture/adr-058-event-hashing.md (about)

     1  # ADR 058: Event hashing
     2  
     3  ## Changelog
     4  
     5  - 2020-07-17: initial version
     6  - 2020-07-27: fixes after Ismail and Ethan's comments
     7  - 2020-07-27: declined
     8  
     9  ## Context
    10  
    11  Before [PR#4845](https://github.com/tendermint/tendermint/pull/4845),
    12  `Header#LastResultsHash` was a root of the Merkle tree built from `DeliverTx`
    13  results. Only `Code`, `Data` fields were included because `Info` and `Log`
    14  fields are non-deterministic.
    15  
    16  At some point, we've added events to `ResponseBeginBlock`, `ResponseEndBlock`,
    17  and `ResponseDeliverTx` to give applications a way to attach some additional
    18  information to blocks / transactions.
    19  
    20  Many applications seem to have started using them since.
    21  
    22  However, before [PR#4845](https://github.com/tendermint/tendermint/pull/4845)
    23  there was no way to prove that certain events were a part of the result
    24  (_unless the application developer includes them into the state tree_).
    25  
    26  Hence, [PR#4845](https://github.com/tendermint/tendermint/pull/4845) was
    27  opened. In it, `GasWanted` along with `GasUsed` are included when hashing
    28  `DeliverTx` results. Also, events from `BeginBlock`, `EndBlock` and `DeliverTx`
    29  results are hashed into the `LastResultsHash` as follows:
    30  
    31  - Since we do not expect `BeginBlock` and `EndBlock` to contain many events,
    32    these will be Protobuf encoded and included in the Merkle tree as leaves.
    33  - `LastResultsHash` therefore is the root hash of a Merkle tree w/ 3 leafs:
    34    proto-encoded `ResponseBeginBlock#Events`, root hash of a Merkle tree build
    35    from `ResponseDeliverTx` responses (Log, Info and Codespace fields are
    36    ignored), and proto-encoded `ResponseEndBlock#Events`.
    37  - Order of events is unchanged - same as received from the ABCI application.
    38  
    39  [Spec PR](https://github.com/tendermint/spec/pull/97/files)
    40  
    41  While it's certainly good to be able to prove something, introducing new events
    42  or removing such becomes difficult because it breaks the `LastResultsHash`. It
    43  means that every time you add, remove or update an event, you'll need a
    44  hard-fork. And that is undoubtedly bad for applications, which are evolving and
    45  don't have a stable events set.
    46  
    47  ## Decision
    48  
    49  As a middle ground approach, the proposal is to add the
    50  `Block#LastResultsEvents` consensus parameter that is a list of all events that
    51  are to be hashed in the header.
    52  
    53  ```
    54  @ proto/tendermint/abci/types.proto:295 @ message BlockParams {
    55    int64 max_bytes = 1;
    56    // Note: must be greater or equal to -1
    57    int64 max_gas = 2;
    58    // List of events, which will be hashed into the LastResultsHash
    59    repeated string last_results_events = 3;
    60  }
    61  ```
    62  
    63  Initially the list is empty. The ABCI application can change it via `InitChain`
    64  or `EndBlock`.
    65  
    66  Example:
    67  
    68  ```go
    69  func (app *MyApp) DeliverTx(req types.RequestDeliverTx) types.ResponseDeliverTx {
    70      //...
    71      events := []abci.Event{
    72          {
    73              Type: "transfer",
    74              Attributes: []abci.EventAttribute{
    75                  {Key: []byte("sender"), Value: []byte("Bob"), Index: true},
    76              },
    77          },
    78      }
    79      return types.ResponseDeliverTx{Code: code.CodeTypeOK, Events: events}
    80  }
    81  ```
    82  
    83  For "transfer" event to be hashed, the `LastResultsEvents` must contain a
    84  string "transfer".
    85  
    86  ## Status
    87  
    88  Declined
    89  
    90  **Until there's more stability/motivation/use-cases/demand, the decision is to
    91  push this entirely application side and just have apps which want events to be
    92  provable to insert them into their application-side merkle trees. Of course
    93  this puts more pressure on their application state and makes event proving
    94  application specific, but it might help built up a better sense of use-cases
    95  and how this ought to ultimately be done by Tendermint.**
    96  
    97  ## Consequences
    98  
    99  ### Positive
   100  
   101  1. networks can perform parameter change proposals to update this list as new events are added
   102  2. allows networks to avoid having to do hard-forks
   103  3. events can still be added at-will to the application w/o breaking anything
   104  
   105  ### Negative
   106  
   107  1. yet another consensus parameter
   108  2. more things to track in the tendermint state
   109  
   110  ## References
   111  
   112  - [ADR 021](./adr-021-abci-events.md)
   113  - [Indexing transactions](../app-dev/indexing-transactions.md)
   114  
   115  ## Appendix A. Alternative proposals
   116  
   117  The other proposal was to add `Hash bool` flag to the `Event`, similarly to
   118  `Index bool` EventAttribute's field. When `true`, Tendermint would hash it into
   119  the `LastResultsEvents`. The downside is that the logic is implicit and depends
   120  largely on the node's operator, who decides what application code to run. The
   121  above proposal makes it (the logic) explicit and easy to upgrade via
   122  governance.