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)
| Field | Type | Description |
|---|---|---|
| totalStaked | UFix64 | The total number of tokens staked for the new Epoch |
| totalRewardPayout | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| newPayout | UFix64 | The 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})
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| newCutPercentage | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. Usually the hash of the node's public key. |
| role | UInt8 | The 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 |
| amountCommitted | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The 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 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The amount of additional FLOW tokens committed to the node. |
Emitted whenever additional tokens are staked on the node for the following epoch. Specifically:
- 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. - 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. - 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UInt32 | The ID for the delegator. |
| amount | UFix64 | The amount of additional FLOW tokens committed to the node. |
Emitted whenever additional tokens are committed for a delegator for the following epoch. Specifically:
- 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. - 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. - 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UInt32 | The ID for the delegator. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UInt32 | The ID for the delegator. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UInt32 | The ID for the delegator. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UFix64 | The ID for the delegator. Unique within the node but not globally. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UFix64 | The ID for the delegator. Unique within the node but not globally. |
| amount | UFix64 | The 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)
| Field | Type | Description |
|---|---|---|
| nodeID | String | The unique ID string for the node. 32 bytes. The same value emitted in the NewNodeCreated event for the node. |
| delegatorID | UFix64 | The ID for the delegator. Unique within the node but not globally. |
| amount | UFix64 | The 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.