Event Hooks

[aaronc]

Hooks have been added to many modules as a way to observe state changes and sometimes allow/disallow them (ex. #9133 #9571). This is likely a composable way of extending a module's functionality that we want to generalize.

One observation is that hooks are almost always injected at the same place where an event is emitted. With ADR 032 Typed Events, events would essentially be struct types defined in protobuf files. We could create a framework for event listener hooks that allow modules to listen to any event emitted by another module and possibly cancel the state change with an error.

There are specifics that would need to be worked out as to how event listeners are registered (in the context of #9182), but this would basically involve a module registering functions like this:

func OnEventSend(ctx sdk.Context, evtSend bank.EventTransfer) error {
  ...
}

where EventTransfer might be:

package cosmos.bank.v1

message EventTransfer {
   string sender = 1;
   string recipient = 2;
   repeated Coin amount = 3;
}

It is even possible, that complex things like vesting and staking encumbrances could be managed with event hooks (basically restricting transfers if coins are locked or delegated). This is something that would need to be explored, but it seems like the utility of hooks has been demonstrated in many use cases and we should generalize this rather than doing it one by one for every case.

/cc @robert-zaremba @fdymylja @jgimeno @sunnya97

[fdymylja]

Thank you aaron! The approach looks good to me. But I was wondering, can't we, even in this case, leverage ADR-033?

Pseudo code:

func (r ADR033Router) Invoke(ctx context.Context, request, response, interface{}, ...options) {
   preExecHooks := r.getPreExecHooksFor(request)
   for _, preHook := range preExecHooks {
      err := preHook(ctx, request)
      if err != nil {
       return err // rollback
      }
   }
   
   handler := r.getHandlerFor(request)
   resp, err := handler(ctx, request)
   if err != nil { blablabla }
   copyToResponse(resp, response)
   
   postExecHooks := r.getPostExecHooksFor(request)
   for _, postHook := range postExecHooks {
  err := postHook(ctx, request, response)
  if err != nil { blablabla }
  }
}

I think the infrastructure we're setting up for ADR-033 can solve this issues, and it might be a good excuse to start core modules migration towards it (staking, gov for example).

It is even possible, that complex things like vesting and staking encumbrances could be managed with event hooks (basically restricting transfers if coins are locked or delegated). This is something that would need to be explored, but it seems like the utility of hooks has been demonstrated in many use cases and we should generalize this rather than doing it one by one for every case.

Yes this is what in our PoC we called "admission handlers", they can read state only and allow modules to extend rejection behaviour of messages of other modules.

Also we could define admission handlers, pre exec hooks, post exec hooks as protobuf services and mark them with protobuf service options as "admission handlers/pre exec hooks..." and facilitate wiring too.

example:

package vesting.v1;

import "somewhere/cosmos.proto"
import "somewhere/bank./tx.proto"

service AdmissionService {
   option (cosmos_proto.msgserver_extension) = {
   type: cosmos_proto.admission_handler,
   }
   rpc AdmitSendCoins(bank.v1.MsgSendCoins) returns (protobuf.EmptyResponse) {};
}

something like this approximately...

[aaronc]

So I think the main distinction is event vs Msg hooks. Event hooks are the use case I've seen pop up most often. Msg hooks could also be useful, but a) they would only apply to inter-module cases if every module uses ADR 033 and only ADR 033, and b) sometimes the same event can come from multiple Msgs (ex. MsgSend and MsgMultiSend). Events imply that a state changing is happening regardless of how the state change was initiated (i.e. from a client, an inter-module call, begin/end blocker, etc.).

[alexanderbez]

Agree with @aaronc here.

I would also suggest that we consider slightly different nomenclature of these specific kinds of events. We have many types of events -- message events, block events, and these events that we're talking about in this context. I suggest we refer to these as (reactive) module hook events.

[robert-zaremba]

Observation: if we fire the hooks immediately, then the event based hooks shouldn't do any off-chain action - because events will be cancelled if the transaction will fail.

[ValarDragon]

I think we should be adding events to failed txs somehow. Or perhaps only a subset of events, but definitely events somehow.

On mintscan when looking at your history of txs, its nice that you have the simple classification for what the type of the tx was, even though a tx failed. (That classification is currently based on events)

[aaronc]

@ValarDragon could you provide some concrete examples?

[sunnya97]

If we do that, we very clearly need a way to show that an event was REVERTED

[ValarDragon]

If we do that, we very clearly need a way to show that an event was REVERTED

Thats done atm by mintscan with the red X next to a failed tx, maybe we can make this happen w/ every event having a reverted attribute

[robert-zaremba]

I think including events of failed transaction (even if we add an additional attribute: reverted) is error prone and can make more damage then benefits. When the transaction execution fails, there is no trace of it except charged gas.