Introduction

The staking contract stores a lot of different state, and the state is constantly changing. As an external party, there are two ways to keep track of these state changes. You can either use Cadence scripts to query the state of the contract at any given time, or you can monitor events that are emitted by the staking contract to be notified of any important occurances.

Query Information with Scripts

Get the list of proposed nodes for the next epoch:

FlowIDTableStaking.getProposedNodeIDs(): Returns an array of node IDs for proposed nodes. Proposed nodes are nodes that have enough staked and committed for the next epoch to be above the minimum requirement.

You can use the Get Proposed Table(SC.05) script for retrieving this info.

This script requires no arguments.

Get the list of all nodes that are currently staked:

FlowIDTableStaking.getStakedNodeIDs(): Returns an array of nodeIDs that are currently staked. Staked nodes are nodes that currently have staked tokens above the minimum.

You can use the Get Current Table(SC.04) script for retrieving this info.

This script requires no arguments.

Get all of the info associated with a single node staker:

FlowIDTableStaking.NodeInfo(nodeID: String): Returns a NodeInfo struct with all of the metadata associated with the specified node ID. You can see the NodeInfo definition in the FlowIDTableStaking smart contract.

You can use the Get Node Info(SC.08) script with the following arguments:

You can also query the info from an address by using the Get Node Info From Address(SC.26) script with the following arguments:

Get the total committed balance of a node (with delegators):

FlowIDTableStaking.NodeInfo(_ nodeID: String).totalCommittedWithDelegators(): Returns the total committed balance for a node, which is their total tokens staked + committed, plus all of the staked + committed tokens of all their delegators.

You can use the Get Node Total Commitment(SC.09) script with the following argument:

Get the total committed balance of a node (without delegators):

FlowIDTableStaking.NodeInfo(_ nodeID: String).totalCommittedWithoutDelegators(): Returns the total committed balance for a node, which is their total tokens staked + committed, plus all of the staked + committed tokens of all their delegators.

You can use the Get Only Node Total Commitment(SC.09) script with the following argument:

Get all the info associated with a single delegator:

FlowIDTableStaking.DelegatorInfo(nodeID: String, delegatorID: UInt32): Returns a DelegatorInfo struct with all of the metadata associated with the specified node ID and delegator ID. You can see the DelegatorInfo definition in the FlowIDTableStaking smart contract.

You can use the Get Delegator Info(SC.10) script with the following arguments:

You can also query the info from an address by using the Get Delegator Info From Address(SC.27) script with the following arguments:

Get the delegation cut percentage:

FlowIDTableStaking.getRewardCutPercentage(): UFix64: Returns a UFix64 number for the cut of delegator rewards that each node operator takes.

You can use the Get Cut Percentage(SC.01) script to retrieve this info.

This script requires no arguments.

Get the minimum stake requirements:

FlowIDTableStaking.getMinimumStakeRequirements(): {UInt8: UFix64}: Returns a mapping for the stake requirements for each node type.

You can use the Get stake requirements(SC.02) script to retrieve this info.

This script requires no arguments.

Get the total weekly reward payout:

FlowIDTableStaking.getEpochTokenPayout(): UFix64: Returns a UFix64 value for the total number of FLOW paid out each epoch (week).

You can use the Get weekly payout(SC.03) script to retrieve this info.

This script requires no arguments.

Get the total FLOW staked:

You can use the Get total FLOW staked(SC.06) script to retrieve this info.

This script requires no arguments.

Get the total FLOW staked by all the nodes of a single node role:

You can use the Get total FLOW staked by node type(SC.07) script with the following arguments:

Staking Events

Staking events can be queried using the Go or JavaScript SDKs to extract useful notifications and information about the state of the staking process.

Global Staking and Epoch Events

NewEpoch

pub event NewEpoch(totalStaked: UFix64, totalRewardPayout: UFix64)

Emitted by FlowIDTableStaking.Admin.moveTokens() when the tokens are moved between pools, which signals a new epoch.

NewWeeklyPayout

pub event NewWeeklyPayout(newPayout: UFix64)

Emitted by FlowIDTableStaking.Admin.setEpochTokenPayout() when the Admin changes the total tokens paid at the end of the epoch.

After this event the epochTokenPayout is equal to the new value.

NewStakingMinimums

pub event NewStakingMinimums(newMinimums: {UInt8: UFix64})

Emitted by FlowIDTableStaking.Admin.setMinimumStakeRequirements() when the Admin changes the minimum requirements for node types.

NewDelegatorCutPercentage

pub event NewDelegatorCutPercentage(newCutPercentage: UFix64)

Emitted by FlowIDTableStaking.Admin.setCutPercentage() when the Admin changes the percentage of delegator rewards that every node operator takes.

Note that the percentage will be more than 0.0 and less than 1.0, with the actual percentage equal to this multiplied by 100.

Also note that the percentage is taken from the delegator reward to go to the node operator.

After this event the nodeDelegatingRewardCut is equal to the new value.

Node Events

These are events that concern the operation of a node.

NewNodeCreated

pub event NewNodeCreated(nodeID: String, role: UInt8, amountCommitted: UFix64)

Emitted by FlowIDTableStaking.NodeRecord.init() when a new node is successfully created.

After this event is emitted for your node, you can begin to perform staking transactions using it.

NodeRemovedAndRefunded

pub event NodeRemovedAndRefunded(nodeID: String, amount: UFix64)

Emitted by FlowIDTableStaking.Admin.endStakingAuction() if the node is being removed from the next epoch due to a failure to meet the minimum requirements of committed tokens for the next epoch.

After this event, the refunded FLOW tokens will be part of the node's tokensUnstaked balance.

Token Events

These are events that concern the direct usage of FLOW tokens - staking or unstaking locked tokens, withdrawing rewards, etc.

Events emitted when using delegation are described in the next section.

TokensCommitted

pub event TokensCommitted(nodeID: String, amount: UFix64)

Emitted whenever additional tokens are staked on the node for the following epoch. Specifically:

1. By FlowIDTableStaking.NodeStaker.stakeNewTokens() when new tokens (tokens that have not previously been staked) are added to the system to stake on the node during the next epoch.
2. By FlowIDTableStaking.NodeStaker.stakeUnstakedTokens() when unstaked tokens (tokens that were previously staked and then unstaked) are staked again with the node for the next epoch.
3. By FlowIDTableStaking.NodeStaker.stakeRewardedTokens() when reward tokens (tokens paid in return for previous staking) are staked with the node for the next epoch.

After this event, the FLOW tokens will be part of the node's tokensCommitted balance.

TokensStaked

pub event TokensStaked(nodeID: String, amount: UFix64)

Emitted by FlowIDTableStaking.Admin.moveTokens() at the end of an epoch if committed tokens are being added to the node's tokensStaked balance.

After this event, the tokens will be part of the node's staked balance.

TokensUnstaking

pub event TokensUnstaking(nodeID: String, amount: UFix64)

Emitted by FlowIDTableStaking.Admin.moveTokens() at the end of an epoch if a node operator's staked tokens are being unstaked in response to a request from the node operator. After this event, the tokens will be a part of the node operator's tokensUnstaking balance, where they are held for a whole epoch "unstaking period" with no rewards.

TokensUnstaked

pub event TokensUnstaked(nodeID: String, amount: UFix64)

Emitted by FlowIDTableStaking.NodeStaker.requestUnstaking() and FlowIDTableStaking.Admin.moveTokens() when tokens are deposited into the tokensUnstaked pool:

RewardsPaid

pub event RewardsPaid(nodeID: String, amount: UFix64)

Emitted by FlowIDTableStaking.Admin.payRewards() at the end of the epoch to pay rewards to node operators based on the tokens that they have staked.

After this event, the reward tokens will be part of the node's tokensRewarded balance.

The Delegator rewards are paid at the same time, see DelegatorRewardsPaid below.

UnstakedTokensWithdrawn

pub event UnstakedTokensWithdrawn(nodeID: String, amount: UFix64)

Emitted by FlowIDTableStaking.NodeStaker.withdrawUnstakedTokens() when the node operator calls that function to withdraw part or all of their unstaked tokens balance.

After this event, the FLOW tokens will be withdrawn to a newly created FungibleToken.Vault which the caller can deposit to the vault of their choice.

RewardTokensWithdrawn

pub event RewardTokensWithdrawn(nodeID: String, amount: UFix64)

Emitted by FlowIDTableStaking.NodeStaker.withdrawRewardedTokens() when the node operator calls that function to withdraw part or all of their reward tokens balance.

After this event, the FLOW tokens will be withdrawn to a newly created FungibleToken.Vault which the caller can deposit to the vault of their choice.

Delegator Events

These are events that concern FLOW token delegation.

NewDelegatorCreated

pub event NewDelegatorCreated(nodeID: String, delegatorID: UInt32)

Emitted by FlowIDTableStaking.Admin.registerNewDelegator() when the node operator registers a new delegator for the node.

Note that the delegatorID is unique within the node but is not globally unique.

After this event, the new delegator is registered with the node.

DelegatorTokensCommitted

pub event DelegatorTokensCommitted(nodeID: String, delegatorID: UInt32, amount: UFix64)

Emitted whenever additional tokens are committed for a delegator for the following epoch. Specifically:

1. By FlowIDTableStaking.NodeDelegator.delegateNewTokens() when new tokens (tokens that have not previously been staked) are added to the system to stake with the delegator during the next epoch.
2. By FlowIDTableStaking.NodeDelegator.delegateUnstakedTokens() when unstaked tokens (tokens that were previously staked and then unstaked) are staked again with the delegator for the next epoch.
3. By FlowIDTableStaking.NodeDelegator.delegateRewardedTokens() when reward tokens (tokens paid in return for previous staking) are staked with the delegator for the next epoch.

After this event, the FLOW tokens will be part of the delegator's tokensCommitted balance.

DelegatorTokensStaked

pub event DelegatorTokensStaked(nodeID: String, delegatorID: UInt32, amount: UFix64)

Emitted by FlowIDTableStaking.Admin.moveTokens() at the end of an epoch if committed tokens are being added to the delegator's tokensStaked balance.

After this event, the tokens will be part of the delegator's staked balance.

DelegatorTokensUnstaking

pub event DelegatorTokensUnstaking(nodeID: String, delegatorID: UInt32, amount: UFix64)

Emitted by FlowIDTableStaking.Admin.moveTokens() at the end of an epoch if a delegator's staked tokens are being unstaked in response to a request from the delegator. After this event, the tokens will be a part of the delegator's tokensUnstaking balance, where they are held for a whole epoch "unstaking period" with no rewards.

DelegatorTokensUnstaked

pub event DelegatorTokensUnstaked(nodeID: String, delegatorID: UInt32, amount: UFix64)

Emitted by FlowIDTableStaking.NodeDelegator.requestUnstaking() and FlowIDTableStaking.Admin.moveTokens() when tokens are deposited into the delegator's tokensUnstaked pool:

DelegatorRewardsPaid

pub event DelegatorRewardsPaid(nodeID: String, delegatorID: UInt32, amount: UFix64)

Emitted by FlowIDTableStaking.Admin.payRewards() at the end of an epoch when rewards are being paid.

After this event is emitted, the reward tokens will be part of the delegator's tokensRewarded balance.

The Node rewards are paid at the same time, see RewardsPaid above.

DelegatorUnstakedTokensWithdrawn

pub event DelegatorUnstakedTokensWithdrawn(nodeID: String, delegatorID: UInt32, amount: UFix64)

Emitted by FlowIDTableStaking.NodeDelegator.withdrawUnstakedTokens() when the delegator calls that function to withdraw part or all of their unstaked tokens balance.

After this event, the FLOW tokens will be withdrawn to a newly created FungibleToken.Vault which the caller can deposit to the vault of their choice.

DelegatorRewardTokensWithdrawn

pub event DelegatorRewardTokensWithdrawn(nodeID: String, delegatorID: UInt32, amount: UFix64)

Emitted by FlowIDTableStaking.NodeDelegator.withdrawRewardedTokens() when the delegator calls that function to withdraw part or all of their unstaked tokens balance.

After this event, the FLOW tokens will be withdrawn to a newly created FungibleToken.Vault which the caller can deposit to the vault of their choice.