# Proposal for Tezos eventlog

**Authors**: Xiang Fei Ding, YunYan Chi
**Target Protocol**: K
**Summary**: Add capability of on-chain event logging to Tezos contracts that is similar to Ethereum virtual machine event support
**Previous proposal**: [Eduardo](https://gitlab.com/tezos/tzip/-/blob/e36c5d8115ee646a4484de0dc37ee9f6ebf9c5bd/drafts/current/draft-onchain-events.md)

# Abstract
On-chain events enables external applications to respond to custom notification from smart contracts and triggers effects in other software systems.

# Motivation
We intend to enable native event logging in Tezos. This proposal will introduce a minimal support for contract events in Tezos, allowing Tezos-interfacing external applications and services to respond to change in contract states.

The primary motivation behind introduction of event is to allow contracts to trigger visible events with type safety.

Event logging is an important tool in smart contract ecosystem. This is a widely known pattern that applications interfacing with smart contracts should react to the change in contract states. The simplest use of events is to emit an on-chain event by a smart contract to trigger a change in the front end of a web application, which passively observing a stream of transaction submitted to the target smart contract. A more involved example could be cross-chain communication where an actively observing node watching on Tezos and other blockchains react and trigger further action in response to events on Tezos to support cross-chain operations.

Following the spirit of the event logging from EVM, we also make the following observation.
- There is a need to indexing the events by tags and a subset of data fields. While this proposal does not address this issue unfortunately, there is a possibility to extend this proposal to support indexing as well in a separate draft.
- EVM identifies event variants via a hash digest of event topic and data types, which makes event discovery harder. This proposal improves the event logging story in this aspect by clear event tagging and event type declaration, without hashing.

This proposal also aims to provide a standard interface to event logging patterns. Our implementation of event logs will serve as an answer to the coordination problem when the indexers and the contract need to agree on the channel of delivery of events and the format of event data. For more detailed discussion, we shall refer the reader to the discussion on [alternative solutions](#Comparison-with-alternatives) below.

# Specification

The idea is to introduce a new Michelson instruction, `EMIT`, to allow contracts to log information into the transaction receipt.

## Anatomy of event data attachment

Events consist of two data fields. The first will be of the address of the event. The second will be a data item of a *packable* type.

## Sending events

A contract may use a new Michelson instruction `EMIT` to emit events. This new Michelson primitive node accepts one argument and one annotation. The annotation shall be the string tag of the emitted event and the argument shall be the type of the data attachment. For instance, `EMIT %tag ty` indicates that this instruction will emit an event associated with the tag `tag` and the data attachment shall be of a *packable* type `ty`.

`EMIT` pops one data item off the stack and pushes one internal `operation` onto the stack. Therefore, the typing rule of `EMIT` is specified as follows.

EMIT %tag 'ty :: 'ty : 'S -> operation : 'S
EMIT %tag :: 'ty : 'S -> operation : 'S

To actually send out the events, most importantly, the produced `operation`s must be included into the list of operations that the main contract code returns along with other `operation`s that this contract wants to effect.

## Locating events

Events can be found as internal operation results. Event tags are stored as `entrypoint`s and event data as `value`s in the `parameters` fields.

Here is an example.

{
"protocol": "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK",
"hash": "opNX59asPwNZGu2kFiHFVJzn7QwtyaExoLtxdZSm3Q3o4jDdSmo",
// ... fields elided for brevity
"contents": [
{
"kind": "transaction",
// ... fields elided for brevity
"metadata": {
// ... fields elided for brevity
"internal_operation_results": [
{
"kind": "event",
"source": "KT1X4TgGdDMUTxG4i7xQKgZ7Fo5nQghTRdvj",
"nonce": 0,
"type": <Michelson data type>,
"tag": "<tag>",
"payload": <Michelson value>,
"result": {
"status": "applied",
"consumed_milligas": "<gas value>"
}
}
]
}
}
]
}

## Runtime specification
At the end of a successful contract execution, the list of operations are inspected.
The event emitting internal operations are plucked out and the corresponding event entries are instead written into the successful transaction operation receipt.

*From the Michelson's point of view*, the contract writer may declare `event` to be record types or enums.

Here is an example of Michelson type declaration and use of that event type.

parameter unit;
storage unit;
code { DROP ;
       UNIT ;
       PUSH string "right" ;
       RIGHT nat ;
       EMIT %tag1 (or (nat %int) (string %str)) ;
       PUSH nat 2 ;
       LEFT string ;
       EMIT ;
       NIL operation ;
       SWAP ;
       CONS ;
       SWAP ;
       CONS ;
       PAIR }

## Economic model
The fee chargeable for emitting events shall intuitively be proportional to the size of the data of the emitted events.

Specifically, the gas cost for obtaining a handle to the "event sink" is free; the standard `TRANSFER_TOKEN` gas cost applies for "sending" event data to the "event sink." The only other gas cost will incur after the successful contract evaluation when the event address is realized and event emission operations were plucked out and type-checked.

## Sink contract
There is a proposal to implement event logs on the contract level. The idea is to have one or a pool of contracts, or so called `sink contract`s, ready to accept calls. Those calls will naturally be recorded on-chain with event tags and data.

One issue with this arrangement is that it requires either the toolchain or the contract developers to originate and manage these sidecar contracts diligently. Meanwhile, these sidecars are trivial yet they need to be created separately for each event schema. The addresses of the sidecars need to be recorded correctly for origination of main contracts later. This process incurs great operational costs and risks.

On top of this, there remains the issue of coordination of event logging schema. While sink contracts are one of those schema as the basis of event communication, there is a lot of room for variation in implementation, leaving indexers to decide precise details in interpretation of sink contract calls. This event MVP serves as a canonical basis for communicating events to indexers, which is to read them off the transaction receipt and expect them to have the formats as specified here.

## Use of Global Table of Constants
There is a proposal to replace the arbitrary event tag with Global Table of Constants. As a recap, the Global Table of Constants, also known as GTOC, is a registration table of constant Michelson expressions. When the contract is selected for execution, the `H_constant` nodes are replaced with an actual Michelson value by looking up the constant expression hash in GTOC. Note that `H_constant` nodes can occur in any place of the contract Michelson, including the top-level type definitions and the contract code node. The transformed contract code will then be passed on for interpretation with the constant expressions properly substituted.

# Appendix

## A brief summary of EVM event logs

The primary source of the following information will be taken from the [Ethereum Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf).

### EVM event features
According to the yellow paper, EVM supports the following event features.
- Uniquely identify events with zero to four topic fields and types of data fields
- Up to four topic slots assigned to each event type
- Event logs are stored directly into transaction receipt.