/
onflow.org
Flow Playground

How to Stake Locked FLOW


This guide is for developers who wish to stake FLOW with the help of a node operator. If you wish to operate your own node, please read the power user guide.

Introduction

This guide covers the technical integration required for a token holder (TH) and node operator (NO) to jointly fund and operate a staked Flow node.

Both parties have separate roles in this relationship:

  • Node Operator: Manages the node infrastructure but does not hold any FLOW tokens.
  • Token Holder: Provides restricted, indirect access to their FLOW tokens for the sole purpose of staking.

This guide assumes that the token holder has already established a trusted relationship with a node operator.

Setup

These are the steps required to set up the integration between a token holder and a node operator.

Note: The corresponding node operator steps are outlined in a separate guide for node operators.

1. Fetch node operator information

After a node operator has agreed to run a node for you, they will create a NodeInfo object holding the IP address and public keys for your new node. This NodeInfo object will be stored in an account owned by the node operator (operator account).

The node operator should provide you with their operator account address and the nodeID for your new node. These values can be passed into the Get Operator Node Info (TH.06) script to confirm your node information:

ArgumentTypeDescription
accountAddressThe address of the node operator's account.
nodeIDStringThe unique ID of the node.

This script returns a StakingProxy.NodeInfo struct containing the details for the node. If no NodeInfo is available, the script will fail.

If this node information is correct, continue to step 2.

2. Register node & grant staking access to the node operator

After confirming that the node information is correct, the token holder can register the node with the central staking contract by using the using the Register Node (TH.07) transaction with the following arguments:

ArgumentTypeDescription
addressAddressThe node operator address.
nodeIDStringThe unique ID of the node (from NodeInfo).
amountUFix64The number of FLOW tokens to stake.

This transaction fetches the node info from the operator account, registers the node in the central staking contract, and creates a StakingProxy.NodeStakerProxy capability to pass to the node operator, who will be able to use it to perform staking actions on behalf of the token holder. Token holder retains control of the main staking capability and still has full control to manage their own staking actions as well.

Staking Actions

Once the token holder has registered their node using the info provided by the node operator, their tokens and info are committed to the central staking contract for the next epoch. They now have access to various staking operations that they can perform, assuming they have the correct number of tokens to perform the action.

Stake New Tokens

The token holder can stake additional tokens at any time.

Note: This transaction stakes additional tokens to the same node that was registered in the setup phase. It is currently not possible to stake to multiple nodes from the same account.

To stake new tokens via the NodeStakerProxy, the token holder can use the Stake New Locked FLOW (TH.08) transaction with the following arguments:

ArgumentTypeDescription
amountUFix64The number of FLOW tokens to stake.

This transaction commits tokens to stake from the token holder's locked token account.

Re-stake Unstaked Tokens

After tokens become unstaked, the token holder can choose to re-stake the unstaked tokens to the same node.

To staked unstaked tokens via the NodeStakerProxy, the token holder can use the Re-stake Unstaked FLOW (TH.09) transaction with the following arguments:

ArgumentTypeDescription
amountUFix64The number of unstaked FLOW tokens to stake.

Re-stake Rewarded Tokens

After earning rewards from staking, the token holder can choose to re-stake the rewarded tokens to the same node.

To staked rewarded tokens via the NodeStakerProxy, the token holder can use the Re-stake Rewarded FLOW (TH.10) transaction with the following arguments:

ArgumentTypeDescription
amountUFix64The number of rewarded FLOW tokens to stake.

Since rewarded tokens are considered to be unlocked for the purposes of the vesting schedule, and staked tokens are considered locked, staking rewarded tokens marks the staked tokens as locked and marks an equal amount of tokens in the token holder's LockedTokens.LockedTokenManager as unlocked.

Unstake Tokens

The token holder can submit a request to unstake their tokens at any time.

To unstake staked tokens via the NodeStakerProxy, the token holder can use the Unstake FLOW (TH.11) transaction.

This transaction requires no arguments.

Warning: this will unstake all of the user's staked tokens.

Note: unstaked tokens will be held by the central staking contract until the end of the following epoch. Once the tokens are released (unstaked), they can be claimed via the Withdraw Unstaked Tokens action below.

Withdraw Unstaked Tokens

After tokens become unstaked, the token holder can withdraw them from the central staking contract.

To withdraw unstaked tokens via the NodeStakerProxy, the token holder can use the Withdraw Unstaked FLOW (TH.12) transaction with the following arguments:

ArgumentTypeDescription
amountUFix64The number of unstaked FLOW tokens to withdraw.

This transaction moves the unstaked tokens back into the LockedTokens.Lockbox owned by the token holder.

Withdraw Rewarded Tokens

After earning rewards from staking, the token holder can withdraw them from the central staking contract.

To withdraw rewarded tokens via the NodeStakerProxy, the token holder can use the Withdraw Rewarded FLOW (TH.13) transaction with the following arguments:

ArgumentTypeDescription
amountUFix64The number of rewarded FLOW tokens to withdraw.

This transaction moves the rewarded tokens back into the LockedTokens.Lockbox owned by the token holder. However, unlike unstaked tokens, rewards are unlocked FLOW and can be immediately withdrawn from the lockbox.

Getting Info about an accounts Stake

To return a struct with all the information associated with a node, anyone can use the Get Node Info (TH.06) script with the following arguments:

ArgumentTypeDescription
nodeIDStringThe 32 byte ID of the node

This script returns a FlowIDTableStaking.NodeInfo struct.

Register to stake for a different node

Currently, the locked tokens contract only supports token holders staking to one node. If a token holder wants to create a second staking relationship, they must create a new account and transfer their locked tokens to the new account by requesting authorization from the token admin.

We plan on adding functionality in the future to allow accounts to stake to multiple nodes.

Edit on GitHub