If you haven't read the staking introduction, please read that first. That document provides a non-technical overview of staking on Flow for all users and is a necessary prerequisite to this document.
This document assumes you have some technical knowledge about the Flow blockchain and programming environment.
Epochs
The epoch preparation protocol defines how information about the next epoch is determined and propagated to the protocol state.
There are two primary actors in this protocol, the Epoch Smart Contracts, and the Consensus Committee:
Epoch Smart Contracts
- the smart contracts that manage epochs:FlowClusterQC
: Manages the quorum certificate generation for bootstrapping the hotstuff consensus algorithm for each collector cluster.FlowDKG
: Manages the Distributed Key Generation that consensus nodes participate in to initialize the random beacon for each epoch.FlowIDTableStaking
: Manages the source of truth for the identity table, and enforces rules related to staking FLOW, delegating, paying rewards, and allocating token movements between epochs.FlowEpoch
: Ties all of the previously mentioned contracts together to manage the high level epoch lifecycle.FlowEpoch
acts as a state machine that transitions between different epoch phases when specific conditions from the other contracts are met and triggers important operations in the other smart contracts when phase changes happen.
Consensus Committee
- the committee of consensus nodes for the current epoch
This document describes the communication protocol between these two actors and the impact on the protocol state.
It gives an overview of the process of epochs, the staking auction, and the epoch setup and commit phases. It is an important prerequisite to understand before proceeding with any other technical integration or interaction with the Flow Protocol, but does not provide step-by-step instructions for how to perform specific actions.
The transactions described in this document are contained in the flow-core-contracts/transactions/epoch/
directory. You can see the text of all the transactions used to interact with the smart contracts there.
Epochs Overview​
Only a pre-determined set of nodes is authorized to participate in the protocol at any given time. The set of authorized nodes is a-priori known to all network participants. This set is referred to as the Identity Table. An Epoch is defined as a period of time where the set of authorized nodes is constant (or can only shrink due to ejection of malicious nodes).
At an Epoch switchover, which is the time when the network transitions from one epoch to the next, the set of authorized nodes can change. For each of Flow's node roles, the Flow protocol admits a protocol-determined number of nodes.
For each Epoch, there is a Staking Auction in which new potential node operators may submit Staking Commitments. All this is completely smart-contract based and handled through conventional transactions.
After the Staking Auction is over, the protocol determines which commitments to accept and which to reject. The node operators whose staking commitments were accepted are added to the Identity Table for the next epoch, and become authorized participants at the next epoch switchover. Staked Nodes also can submit other operations to modify their existing stake, which are all carried out at the end of the current epoch.
The smart contract that determines the nodes for the next Epoch has special privileges. Specifically, it is allowed to emit Service Events, which are how the execution state updates the consensus node-based protocol state.
At the end of the staking auction, the epoch smart contracts conclude that they have now determined the set of nodes which will be running the network for the next Epoch, and the amount of FLOW that all the nodes have staked. The smart contract then emits a service event with this information.
When processing the block with seat assignment, all network nodes (including future ones which are supposed to monitor the chain in anticipation) are thereby informed about the upcoming change.
Note: At this point in the epoch (end of the staking auction), there is no change in participating nodes. The change in participating nodes happens at the end of the epoch.
After the staking auction, there is an interim period of time until the new Epoch starts for the following tasks to be completed:
- The epoch smart contract runs the cluster assignment algorithm for all the collector nodes and each collector node will vote for the root block of their respective clusters
- The Random Beacon Committee for the next Epoch (currently all consensus nodes) will run the Distributed Key Generation (DKG),
- When completing the QC generation and DKG, the smart contracts will emit a service event. After consensus nodes have collected all relevant information (public keys for the random beacon and cluster quorum certificates), they can update the identity table to include the information for the next Epoch.
If preparation for the next Epoch is not completed before the current Epoch ends, a spork is required to transition to the next Epoch.
Epoch Length​
The length of an Epoch is measured in terms of consensus views.
The number of views in an epoch and in the various epoch phases are determined before
the Epoch begins and stored as a field in the main epoch smart contract (FlowEpoch
).
Generally, there is not a block for every view, so the view number will not change at the same rate as the block height.
Because the length of a consensus view can vary depending on many different factors, the wall-clock time of an epoch is expected to vary from week to week. Under typical network conditions we expect the variance in epoch length to be less than 2 hours for a 1-week epoch (~1%). Under adverse network conditions the variance in epoch length will increase (typically this will result in longer epochs).
As the average view rate changes over time, the Service Account can change the epoch length to target a 1 week wall-clock epoch length.
Phases
The preparation for the next epoch is separated into distinct phases. Each phase occurs completely within the current epoch.
The Epoch Smart Contract acts as a state machine. The smart contract keeps a record of the current phase,
the number of views in the current phase, and the conditions that need to be met in order to advance to the next phase, or next epoch.
A special Heartbeat
resource is used to call the advanceBlock()
method during every single new block in Flow.
During these regular method calls, if all of the conditions are met to advance to the next phase,
the smart contract performs any relevant retreival and storage of information, emits a Service Event,
and transitions to the next phase, which often involves setting certain metadata
or enabling one of the connected smart contracts to begin its work.
From the perspective of the consensus committe, the phase transitions within epochs occur as a result of including a service event in a block, thus the phase transition only applies to the fork containing the block with the service event.
At the end of Phase 0 and beginning of Phase 1, the EpochSetup
service event is emitted
that contains the identity table and other initial metadata for the upcoming epoch.
At the end of Phase 1 and beginning of Phase 2, the EpochCommit
service event
is emitted that contains the results of the Epoch Setup phase.
The start of a new epoch is the first block with its view > the last view of the previous epoch, and its parent view ≤ the last view of the last epoch.
Phase Transitions​
The Consensus Committee triggers the phase transition coinciding with the Epoch switchover by publishing the block of the next Epoch. This block's execution state will also detect the the end view of an epoch has arrived and trigger the start of the new epoch. The state of the smart contracts reflect the latest epoch's new identity table and metadata.
For the Epoch-internal Phase transitions, meaning the phase transitions within an epoch, the Epoch Smart Contract provides the trigger by emitting a respective service event:
- The
EpochSetup
service event triggers the phase transitionStaking Auction Phase
→Epoch Setup Phase
- The
EpochCommit
service event triggers the phase transitionEpoch Setup Phase
→Epoch Committed Phase
Only one of each service event may be emitted each epoch, for a given fork.
EpochCommit
may only be emitted after EpochSetup
has been generated in the respective given fork.
The FlowEpoch
contract manages all of these phases, the FlowIDTableStaking
contract
manages the identity table and staking auction, the FlowClusterQC
contract manages
the Quorum Certificate generation for collector clusters, and the FlowDKG
contract manages
the Distributed Key Generation protocol for the consensus nodes.
Initially, control of these phases and contracts will be managed manually by the Flow Token Admin, but control will eventually be completely decentralized and managed by the node software, smart contracts, and democratically by all the stakers in the network.
Phase 0: Staking Auction​
Purpose: During the staking auction phase, operators can put up stake in exchange for being a part of the upcoming epoch. All voluntary commitments to register a new node, increase, or decrease stake for the next epoch must occur before the end of this phase.
Duration: The staking auction phase begins with the first block of the current Epoch
Its last block is the block in which the EpochSetup
service event is emitted.
Protocol Directives:​
Epoch Smart Contract
-
The
FlowEpoch
Smart Contract is responsible for ensuring that staking, un-staking, and stake-modification transactions for the next epoch are are only executed during the staking auction and fail otherwise. The contract enforces this by setting astakingEnabled
field in the staking contract. Every staking method checks to see if this is set before executing. -
The
FlowEpoch
Smart Contract must ensure that the subsequent phases are sufficiently long to perform all required tasks before the epoch ends. -
As part of the execution result for the last block of the staking auction, the
Epoch Smart Contract
computes the seat assignment information for the next epoch, and emits a specialized service event, theEpochSetup
event, with the timing and identity table information about the next epoch. See the Epoch Setup Event Documentation for a detailed breakdown of the epoch setup event.
Phase 1: Epoch Setup​
Purpose: During the epoch setup phase, all nodes participating in the upcoming epoch must perform setup tasks in preparation for the upcoming epoch.
Duration: The epoch setup phase begins right after the EpochSetup
service event is emitted.
It ends with the block where EpochCommit
service event is emitted.
Protocol Directives:​
Consensus:
-
When a primary constructs a block that seals the
EpochSetup
service event, the primary includes an update to the protocol state in the block. Specifically, it adds the nodes for thePendingEpoch
to the list of authorized nodes. When this block is propagated, all staked nodes will know about the participants in the next epoch and can communicate with them. -
Based on the
RandSeed
field in theEpochSetup
event, all nodes compute:- The seed to initialize the consensus node's primary selection algorithm for the next epoch
- The seeds to initialize the collector clusters' primary selection algorithm for the next epoch
-
The collector nodes generate the root block for their respective clusters in the next Epoch and submit a vote for the root block to a specialized smart contract,
FlowClusterQC
. -
The Random Beacon Committee for the next Epoch (currently all consensus nodes) will run the DKG through a specialized smart contract,
FlowDKG
.
Epoch Smart Contract:
-
The
FlowEpoch
Smart Contract is responsible for ensuring that Epoch Setup transactions are only executed during the Epoch Setup phase and fail otherwise. The contract enforces this by setting anenabled
field in theFlowClusterQC
andFlowDKG
contracts. Every state-changing method from these contracts checks to see if this is set before executing. -
The Epoch
Epoch Smart Contract
must ensure that the subsequent phase is sufficiently long to perform all required tasks before the epoch ends. -
As part of the execution of the last block of the Epoch Setup phase, the
Epoch Smart Contract
computes the public key shares generated by the DKG and theQC
s for the collector clusters and publishes these asEpochCommit
service event. TheFlowEpoch
Smart Contract should emit this event as soon as the artifacts are determined.
See the Epoch Commit Event Documentation for a detailed breakdown of the epoch commit event.
Phase 2: Epoch Committed​
Purpose: When the epoch committed phase starts, the precise role of each node is fully specified. From a protocol-perspective, all information is available for each node to start its operation for the next Epoch. This phase provides some time for nodes to establish the communication channels and synchronize with the network to seamlessly switch over to the next epoch.
Duration: The epoch committed phase begins right after the EpochCommit
service event
has been emitted. It ends when the epoch ends.
Protocol Directives:​
Consensus
- When a primary constructs a block that seals the
EpochCommit
service event, the primary includes an update to the protocol state in the block. Specifically, it: - adds the information generated in the setup phase to the Protocol State and
- marks the updated Protocol State as
committed
in this respective fork.
Query Information from the Epoch Contract
See the epoch scripts and events document for detailed documentation about you can use scripts events to learn information about the state of the epoch contracts.