# Validator API Events
While there are a number of events it is useful to publish, validator clients only need a fairly small set of events in order to perform their functions successfully.

## Validator Client Operations
These are the key functions a validator client needs to perform and the guarantees they need in terms of timing.

### Schedule Duties
For either attestation or block creation, validator clients need to identify when their validators are scheduled to perform these duties. The key guarantee required, is that once the validator client loads the duties, it must receive a `reorg` event if there are any changes to the canonical chain that would affect them.

The earliest point block duties can be scheduled is the earlier of:
* Importing a block on the canonical chain for the last slot of the prior epoch
* The beacon node advancing with an empty slot in the last slot of the prior epoch (assuming that if the slot is later filled, it will trigger a reorg event). https://www.symphonious.net/2020/07/06/exploring-ethereum-2-the-curious-case-of-the-invisible-fork/ has some more detail on why filling a previously empty slot needs to be considered a reorg.

Additionally, the beacon node must either have already processed the epoch transition *or* process it when the request for duties is received.

### Create Blocks
Occurs at the start of a slot and only requires that the beacon node is in sync. As such can be triggered based off the validator's system clock so long as the beacon node allows creating a block for a slot in the near future. This tolerance is required because the validator client may tick over to the new slot before the beacon node, either because of a small amount of clock skew or simple race condition. A single slot tolerance should be sufficient.

### Create Attestations
Occurs at the earlier of when the block for the current slot is imported or 1/3rd through the slot. The beacon node should update its fork choice selection (potentially switching to a different chain) before attestations are created.

With the definition of `head` events below, attestations would be created when a `head` event is received for the attestation's slot.

### Create Aggregates
Occurs 2/3rds through the slot. The attestation for the slot must have previously been created. Since the validator client already has the attestation, this can be triggered completely independently by the validator client.

## Events
There are then two events which are required for correct operation of a validator client.

### head

Indicates that the chain the beacon node views as canonical has been updated, by being extended by a new block, extended by an empty slot or switching to a different chain.

A `head` event is published when the beacon node's chain head is updated. This may occur by importing a new block that builds on the current chain head (ie the block for the current slot) or when the beacon node considers the slot to be empty because a block hasn't been received. Suggest considering a slot to be empty when 1/3rd of the slot period has elapsed without a block being received on the canonical chain.

As a result a `head` event would be published every slot, even if there was no block in that slot.

The beacon node guarantees that once a `head` event is published for a slot, a `chain_reorg` event will be published if the blockRoot for that slot on the canonical chain changes either because fork choice switches to a different chain, or because a previously empty slot is filled.

### chain_reorg

Indicates that the beacon node has selected a different chain as the canonical chain.

A `chain_reorg` event must be published anytime the canonical state root changes for a slot less than or equal to the slot published in the last `head` event. Importantly as noted in the description of the `head` event, this includes when a previously empty slot is filled, even if the parent of the new block is the previous chain head block.

## Why `head` must be published for empty slots

This is essentially to avoid the issue described in https://www.symphonious.net/2020/07/06/exploring-ethereum-2-the-curious-case-of-the-invisible-fork/

Suppose we have a chain:

Slot | 27 | 28 | 29 | 30 | 31
------------|-------|------|-------|-------|-----
Block Root | 0x01 | 0x02 | 0x03 | 0x04 | *empty*
Parent Root | 0x00 | 0x01 | 0x02 | 0x03 | *empty*

This is the end of epoch 0, so attestation production duties can be calculated for epoch 2. However, if later a block is imported at slot 31, the validator client must recalcuate those duties as the new block at slot 31 changes the randao mix which affects the scheduling.

The validator client needs some guarantee from the beacon node that it's view of the chain head includes that empty slot (and thus that a `chain_reorg` will be published if it is later filled) before it can calculate duties safely.

### Alternative: `epoch` event

A `head` event could be published only when a new block is imported which becomes the new chain head, and a separate `epoch` event could be published at the start of each epoch when epoch processing has completed. The beacon node guarantees that a `chain_reorg` event is published if any blocks are later added to the canonical chain which would affect that scheduling for that epoch (ie any block prior to the epoch start).