/
onflow.org
Flow Playground

Monitoring Staking Events


Introduction

The resources used in node registration and for staking FLOW tokens emit events whenever an important action is performed.

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

Querying Events

To query events you will need to connect to a Flow access node using the SDK for the language that you are using.

Go SDK

You can find the Go SDK for Flow here:

https://github.com/onflow/flow-go-sdk

Documentation for how to handle events can be found here:

https://github.com/onflow/flow-go-sdk#querying-events

And sample code for doing so is here:

https://github.com/onflow/flow-go-sdk/tree/master/examples/query_events

JavaScript SDK

You can find the JavaScript SDK for Flow here:

https://github.com/onflow/flow-js-sdk

Documentation and sample code for handling events are forthcoming.

Event Descriptions

Global Staking and Epoch Events

NewEpoch

pub event NewEpoch(totalStaked: UFix64, totalRewardPayout: UFix64)
FieldTypeDescription
totalStakedUFix64The total number of tokens staked for the new Epoch
totalRewardPayoutUFix64The total number of tokens that will be paid as rewards for this epoch

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

NewWeeklyPayout

pub event NewWeeklyPayout(newPayout: UFix64)
FieldTypeDescription
newPayoutUFix64The new number of tokens that will be paid at the end of the epoch

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})
FieldTypeDescription
newRequirements{UInt8: UFix64}The new minimum staking requirements for all the node types.

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

NewDelegatorCutPercentage

pub event NewDelegatorCutPercentage(newCutPercentage: UFix64)
FieldTypeDescription
newCutPercentageUFix64The percentage of the delegator reward that goes to node operators.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. Usually the hash of the node's public key.
roleUInt8The node's role type. From 1 to 5 inclusive. For the meaning of the values see https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowIDTableStaking.cdc
amountCommittedUFix64The amount of FLOW tokens staked to register the node. This is determined by the role.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of FLOW tokens returned to the node.

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 commited 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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of additional FLOW tokens committed to the node.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of FLOW tokens staked to the node.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of FLOW tokens unstaked from the node.

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 to do so. 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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of FLOW tokens unstaked from the node.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of FLOW tokens paid to the node this epoch as a reward.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of unstaked FLOW tokens that the node operator is withdrawing.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
amountUFix64The amount of rewarded FLOW tokens that the node operator is withdrawing.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUFix64The ID for the new delegator. Unique within the node but not globally.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUInt32The ID for the delegator.
amountUFix64The amount of additional FLOW tokens committed to the node.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUInt32The ID for the delegator.
amountUFix64The amount of FLOW tokens staked to the node.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUInt32The ID for the delegator.
amountUFix64The amount of FLOW tokens unstaked from the node.

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 to do so. 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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUInt32The ID for the delegator.
amountUFix64The amount of FLOW tokens unstaked from the node.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUFix64The ID for the delegator. Unique within the node but not globally.
amountUFix64The amount of rewarded FLOW tokens that the delegator is paid.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUFix64The ID for the delegator. Unique within the node but not globally.
amountUFix64The amount of unstaked FLOW tokens that the delegator is withdrawing.

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)
FieldTypeDescription
nodeIDStringThe unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node.
delegatorIDUFix64The ID for the delegator. Unique within the node but not globally.
amountUFix64The amount of rewarded FLOW tokens that the delegator is withdrawing.

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.

Edit on GitHub