Staking

This document describes the functionality of the core identity table and staking smart contract. It gives an overview of the process of staking, epochs, and delegation. 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.

This document also describes how to read public staking data from the contract. Anyone with a Flow account on mainnet can read public data from the staking smart contract with these instructions.

The transactions described in this document are contained in the flow-core-contracts/transactions/idTableStaking/ directory. You can see the text of all the transactions used to interact with the smart contract there.

Terminology

If any of the definitions are confusing, you can find more detail in the Smart Contract Summary

Staker: Any user who has staked tokens for the Flow network. A node operator is a staker, and a delegator is a staker as well.

Node Operator: A user who operates a node on the Flow network. Each node operator has a unique NodeStaker object they store in their account to perform staking operations.

Delegator: A user who delegates tokens to a node operator and receives rewards for their staked tokens, minus a fee taken by the node operator. Each delegator stores a unique NodeDelegator object in their account that allows them to perform staking operations.

Identity Table: The record of all the stakers in the network. The identity table keeps separate lists for the info about node operators and delegators, which track the following info:

• Node Operators:

  • Node ID: 32 byte identifier for the node. Usually a hash of the node public key.
  • Role: Indicates what role the node operator is. (Collection, Consensus, Execution, Verification, Access)
  • Networking Address: The address that the node operator uses for networking.
  • Networking Key: The 64 byte node operator public key for networking.
  • Staking Key: The 96 byte public key for the account that manages staking.

• Delegators:

  • id: The ID associated with a delegator. These IDs are assigned to delegators automatically by the staking contract and are only unique within an individual node operators' record.
  • nodeID: The ID of the node operator a user delegates to.

• Both:

  • Tokens Committed: The tokens that a user has committed to stake in the next epoch.
  • Tokens Staked: The tokens that a user has staked in the current epoch.
  • Tokens Requested to Unstake: The amount of tokens that a user has requested to be unstaked at the end of the current epoch.
  • Tokens Unstaking: The tokens that were unstaked at the beginning of the current epoch and are being held for an additional epoch holding period before being released.
  • Tokens Unstaked: Tokens that used to be committed or staked and have been unstaked.
  • Tokens Rewarded: Tokens that the user has received via staking rewards.

Epoch: The period of time between reward payments and changes in the identity table. (Initially a week) At the end of every epoch, insufficiently staked node operators are refunded their stake, rewards are paid to those who are currently staked, committed tokens are marked as staked, unstaking tokens are marked as unstaked, and unstaking requests are changed from staked to unstaking.

Delegation Rewards Cut: The percentage of a delegator's rewards that the node operators take. Initially set to 8%.

Epoch Payout: The total amount of tokens paid in rewards at the end of an epoch. This value will change as the supply of FLOW changes. See the rewards page for more details.

Minimum Stake Requirement: Each node type has a requirement for the minimum number of FLOW they have to commit to stake to be considered a valid node and receive rewards. If a node operator does not meet the minimum stake, they will not be included in the next epoch and will not receive any rewards. Delegators are not subject to minimum stake requirements.

• Collection Nodes: 250,000 FLOW
• Consensus Nodes: 500,000 FLOW
• Execution Nodes: 1,250,000 FLOW
• Verification Nodes: 135,000 FLOW

There is no maximum stake limit

Smart Contract Summary

The Flow staking smart contract manages a record of stakers who have staked tokens for the network. Users who want to stake can register with the staking contract at any time, and their tokens will be locked for staking until they request to unstake them.

Before getting into the details of the contract, we need to discuss how time is organized on the Flow blockchain. The operation of the Flow network is divided into epochs, which are week-long periods in which various network maintenance operations are performed. The schedule for each epoch is exactly the same, though individual actions that users take in relation to staking with the network will be different.

Epoch Schedule:

1. Start of Epoch: Generic metadata about the current epoch is updated and shared.
2. Staking Auction: Stakers can perform any action they want to manage their stake, like initially registering, staking new tokens, unstaking tokens, or withdrawing rewards. This phase takes up the vast majority of time in the epoch.
3. Rewards Payout: Pay rewards to all the node operators staked in the current epoch.
4. Remove Insufficiently Staked Nodes: All node operators who don't meet the minimum or are not operating their node properly will be removed.
5. Move tokens between pools. (See the token pools section for the order of movements)

The FlowIDTableStaking contract manages the identity table, and all of these phases. Initially, control of these phases 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.

Staking as a Node Operator

For a node to stake, node operators first need to generate their staking key, networking address, and networking key.

The node operation guide describes how to run a node and generate node information.

To generate a node ID, simply hash the staking key.

Node operators need to determine the role of node they will be running (Collection, Consensus, Execution, Verification, or Access).

Once the info has been determined:

• Node role: UInt8 (1 = Collection, 2 = Consensus, 3 = Execution, 4 = Verification, 5 = Access)
• Node ID: 32 byte String
• Networking Address: String (Length must be less than 255 bytes (510 Hex characters))
• Networking Key: 64 byte String (128 hex characters)
• Staking Key: 96 byte String (192 hex characters)

The node operator is ready to register their node.

To create and submit a transaction to register a node, the node operator calls the addNodeRecord function on the staking contract, providing all the node info and the tokens that they want to immediately stake, if any.

This registers the node in the Flow node identity table and commits the specified tokens to stake during the next epoch. This also returns a special node operator object that is stored in the node operator's account. This object is used for staking, unstaking, and withdrawing rewards. Additionally, this transaction creates a public capability for the node that allows anyone to query information about a node from the account address that runs the node.

Every node operator will run the same transaction to register their node at any time throughout an epoch.

Once node operators have registered and have the special node object, they will be able to perform any of the valid staking options with it, assuming that they have the required amount of tokens to perform each operation.

When a new epoch starts, if a node operator has committed at least the minimum stake required, the tokens they have committed will be marked as staked and held in the protocol state. If a node operator does not meet the minimum requirement, their committed tokens are moved to their unstaked pool, which they can withdraw from at any time.

If a node operator has users delegating to them, they cannot withdraw their own tokens such that their own staked tokens would fall below the minimum requirement for that node type. If they have delegators and try to submit an unstaking transaction that would put their stake below the minimum, it will fail.

If they want to unstake below the minimum, they must unstake all of their tokens using the special unstakeAll method, which also unstakes all of the tokens that have been delegated to them.

Consequently, a node operator cannot accept delegation unless their own stake is above the minimum.

Staking as a Delegator

Every staked node in the Flow network is eligible for delegation by any other user. The user only needs to know the node ID of the node they want to delegate to.

To register as a delegator, the delegator submits a Register Delegator transaction, providing the ID of the node operator they want to delegate to. This transaction stores the NodeDelegator object in the user's account, which is what they use to perform staking operations. Additionally, this transaction creates a public capability for the delegator that allows anyone to query information about a node from the account address that runs the node.

Users are able to get a list of possible node IDs to delegate to via on-chain scripts. This information will also be provided off-chain, directly from the node operators or via third-party services. The Flow team lists available node IDs in a public repo.

The fee that node operators take from the rewards their delegators receive is 8%. A node operator cannot be delegated to unless the total tokens they have committed to stake are above the minimum requirement for their node types.

The delegation logic keeps track of the amount of tokens each delegator has delegated for the node operator. When rewards are paid, the protocol automatically takes the 8% cut of the delegator's rewards for the node operator and the delegator's rewards are deposited in the delegator's reward pool.

Staking Operations Available to All Stakers

Regardless of whether they are a node operator or delegator, a staker has access to all the same staking operations, outlined below.

Stake More Tokens

A staker can commit more tokens to stake for the next epoch at any time, and there are three different ways to do it.

1. They can commit new tokens to stake by submitting a stake_new_tokens transaction, which withdraws tokens from their account's flow token vault and commits them.
2. They can commit tokens that are in their unstaked token pool, which holds the tokens that they have unstaked. Submit a stake_unstaked_tokens transaction to move the tokens from the unstaked pool to the committed pool.
3. They can commit tokens that are in their rewarded token pool, which holds the tokens they have been awarded. They submit a stake_rewarded_tokens transaction to move the tokens from the rewards pool to the committed pool.

Cancel Committed Stake / Unstake Tokens

At any time, a staker can submit a request to unstake tokens with a request_unstaking transaction. If there are tokens that have been committed but are not staked yet, they are moved to the unstaked pool and are available to withdraw.

If the requested tokens are in the staked pool, it marks the specified amount of tokens to be unstaked at the end of the epoch. At the end of the epoch, the tokens are moved to the unstaking pool. They will sit in this pool for one (1) additional epoch, at which point they will be moved to the unstaked tokens pool.

Cancel an Unstake Request

Unstaking requests are not fulfilled until the end of the epoch where they are submitted, so a staker can cancel the unstaking request before it is carried out. A staker can do this by submitting a stake_unstaked_tokens transaction, specifying the number of tokens of their unstake request they would like to cancel. If the specified number of tokens have been requested to unstake, the request will be canceled.

Withdraw Unstaked Tokens

At any time, stakers are able to freely withdraw from their unstaked tokens pool with the withdraw_unstaked transaction.

Withdraw Rewarded Tokens

Staking rewards are paid out at the end of every epoch based on how many tokens are in a users tokensStaked pool. Every staker's rewards are deposited into their rewarded tokens pool. Rewards can be withdrawn at any time by submitting a withdraw_reward_tokens transaction.

These tokens are unlocked and can be transferred on-chain if desired, or re-staked.

Query Information from the Staking Contract

There is a lot of information that can be queried from the staking contract in different ways. See the scripts document for more detail about how to get info from the staking contract.

Appendix

Token Pools

Each node operator has five token pools allocated to them:

• Committed Tokens: Tokens that are committed for the next epoch. They are automatically moved to the staked pool when the next epoch starts.
• Staked Tokens: Tokens that are staked by the node operator for the current epoch. They are only moved at the end of an epoch and if the staker has submitted an unstaking request.
• Unstaking Tokens: Tokens that have been unstaked, but are not free to withdraw until the following epoch.
• Unstaked Tokens: Tokens that are freely available to withdraw or re-stake. Unstaked tokens go to this pool.
• Rewarded Tokens: Tokens that are freely available to withdraw or re-stake. Rewards are paid and deposited to the rewarded Pool after each epoch.

At the end of every epoch, tokens are moved between pools in this order:

1. All committed tokens will get moved either to the staked tokens pool, or to the unstaked tokens pool (depending on if the registered node has met the minimum stake requirements).
2. All committed tokens get moved to staked tokens pool.
3. All unstaking tokens get moved to the unstaked tokens pool.
4. All requested unstaking tokens get moved from the staked pool to the unstaking pool.