Stake 2.0 Adaption FAQ

TRON Core Devs
TRON
Published in
12 min readFeb 23, 2023

Stake 2.0 is a new stake model of the TRON network, which has been deployed on the Nile testnet. Stake 2.0 separates resource delegating from staking. Delegating and undelegating resources do not need to unstake anymore. The granularity of staking and resource management is also more refined, which greatly improves flexibility in resource management. And the TRON virtual machine (TVM) now supports all instructions related to Stake 2.0 and can implement more application layer protocols like TRC-484 based on smart contracts, bringing richer application scenarios to the TRON smart contract ecosystem. For more details on Stake 2.0, please see the What is Stake 2.0?

After Stake 2.0 is opened, staking can only be done through Stake 2.0 API, assets staked and correlated resources and votes under Stake 1.0 would remain and can be only reclaimed through 1.0 unstake API.

In order to make it easier for the community to adapt to Stake 2.0, this article provides an adaptation method for specific needs. After reading this article, you will learn the following:

Stake & Unstake

  • How to obtain the staking balance under Stake 1.0, Stake 2.0 and the total staking balance?
  • How to obtain the TRX balance available for staking under Stake 2.0?
  • How to initiate a staking?
  • How to obtain the TRX balance available for unstaking under Stake 2.0?
  • How to obtain the number of unstaking lefts?
  • How to initiate an unstaking?
  • How to obtain the list of ongoing unstakings?
  • How to obtain the withdrawable balance of TRX?
  • How to withdraw unstaked TRX?

Resource Management

  • How to obtain the total amount of energy and bandwidth in an account?
  • How to obtain the usage of energy and bandwidth in an account?
  • How to obtain the useable amount of energy and bandwidth in an account?
  • How to obtain the amount of delegatable balance of energy and bandwidth?
  • How to delegate resources?
  • How to obtain the list of ongoing delegatings?
  • How to undelegate resources?
  • How to obtain the amount of total TRON power and spare TRON power in an account?
  • How to convert resource share to amount?

Note: if the field in the API example in this article does not exist in the actual test, it means that the value of the field is 0.

Stake & Unstake

How to obtain the staking balance under Stake 1.0, Stake 2.0 and the total staking balance?

Call wallet/getaccount to query the staking balance and details:

curl -X POST https://api.nileex.io/wallet/getaccount -d \
'{"address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{

"frozen": [
{
"frozen_balance": 1000000000,
"expire_time": 1676800755000
}
],
"account_resource": {
"frozen_balance_for_energy": {
"frozen_balance": 2000000000,
"expire_time": 1676607966000
},
"latest_consume_time_for_energy": 1672122558000
"delegated_frozen_balance_for_energy": 4000000000
"delegated_frozenV2_balance_for_energy": 800000000
},
"frozenV2": [
{
"amount": 5000000000
},
{
"type": "ENERGY",
"amount": 6000000000
},
{
"type": "TRON_POWER"
}
],
"delegated_frozen_balance_for_bandwidth": 3000000000
"delegated_frozenV2_balance_for_bandwidth": 700000000,

}

Staking balance of Stake 1.0 = frozen[0].frozen_balance +

account_resource.frozen_balance_for_energy.frozen_balance +

delegated_frozen_balance_for_bandwidth +

account_resource.delegated_frozen_balance_for_energy

= 1,000,000,000 +

2,000,000,000 +

3,000,000,000 +

4,000,000,000

= 10,000,000,000 (10,000 TRX)

  • frozen[0].frozen_balance is the bandwidth share balance of Stake 1.0, the unit is sun
  • account_resource.frozen_balance_for_energy.frozen_balance is the energy share balance of Stake 1.0, the unit is sun
  • delegated_frozen_balance_for_bandwidth is the balance of delegated bandwidth share under Stake 1.0, the unit is sun
  • account_resource.delegated_frozen_balance_for_energy is the balance of delegated energy share under Stake 1.0, the unit is sun

Staking balance of Stake 2.0 = frozenV2[0].amount +

frozenV2[1].amount +

delegated_frozenV2_balance_for_bandwidth +

account_resource.delegated_frozenV2_balance_for_energy

= 5,000,000,000 +

6,000,000,000 +

7,000,000,000 +

8,000,000,000

= 26,000,000,000 (26,000 TRX)

  • frozenV2[0].amount is the bandwidth balance of Stake 2.0, the unit is sun
  • frozenV2[1].amount is the energy balance of Stake 2.0, the unit is sun
  • delegated_frozenV2_balance_for_bandwidth is the balance of delegated bandwidth under Stake 2.0, the unit is sun
  • account_resource.delegated_frozenV2_balance_for_energy is the balance of delegated energy under Stake 2.0, the unit is sun

Total staking balance = Staking balance of Stake 1.0 + Staking balance of Stake 2.0

= 10,000,000,000 + 26,000,000,000

= 36,000,000,000 (36,000 TRX)

How to obtain the TRX balance available for staking under Stake 2.0?

Call wallet/getaccount to obtain the balance available for staking:

curl -X POST https://api.nileex.io/wallet/getaccount -d \
'{"address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{

"address": "TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"balance": 1000000000,

}

Balance available for staking = balance = 1,000,000,000 (1,000 TRX)

  • balance is the TRX available for staking, the unit is sun

How to initiate a staking?

Call wallet/freezebalancev2 to create a transaction to stake TRX:

// stake 1000 TRX to obtain TP and bandwidth
curl -X POST https://api.nileex.io/wallet/freezebalancev2 -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"frozen_balance":1000000000,
"resource":"BANDWIDTH",
"visible":true
}'

// stake 2000 TRX to obtain TP and energy
curl -X POST https://api.nileex.io/wallet/freezebalancev2 -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"frozen_balance":2000000000,
"resource":"ENERGY",
"visible":true
}'

The return above in the example is an unsigned transaction, it should be signed and broadcasted then.

How to obtain the TRX balance available for unstaking under Stake 2.0?

Call wallet/getaccount to get the balance available for unstaking:

curl -X POST https://api.nileex.io/wallet/getaccount -d \
'{"address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{

"frozen": [
{
"frozen_balance": 1000000,
"expire_time": 1676800755000
}
],
"account_resource": {
"frozen_balance_for_energy": {
"frozen_balance": 2000000,
"expire_time": 1676607966000
},
"latest_consume_time_for_energy": 1672122558000
},
"frozenV2": [
{
"amount": 3000000000
},
{
"type": "ENERGY",
"amount": 4000000000
},
{
"type": "TRON_POWER"
}
],

}

TRX available for unstaking under Stake 2.0(resource type: bandwidth) = frozenV2[0].amount = 3,000,000,000 (3,000 TRX)

  • frozenV2[0].amount is the balance of bandwidth under Stake 2.0, the unit is sun

TRX available for unstaking under Stake 2.0(resource type: energy) =

frozenV2[1].amount = 4,000,000,000 (4,000 TRX)

  • frozenV2[1].amount is the balance of energy under Stake 2.0. unit is sun

How to obtain the number of unstaking lefts?

Call wallet/getavailableunfreezecount to obtain the number of unstaking left:

curl -X POST https://api.nileex.io/wallet/getavailableunfreezecount -d \
'{
"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"visible":true
}'

{
"count": 31
}

The number of unstaking left = count =31

  • count is the number of unstaking left that can be initiated by this account

How to initiate an unstaking?

Call wallet/unfreezebalancev2 to initiate an unstaking transaction:

// unstake 1000 TRX to release the TP and bandwidth obtained
curl -X POST https://api.nileex.io/wallet/unfreezebalancev2 -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"unfreeze_balance":1000000000,
"resource":"BANDWIDTH",
"visible":true
}'
// unstake 2000 TRX to release the TP and energy obtained
curl -X POST https://api.nileex.io/wallet/unfreezebalancev2 -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"unfreeze_balance":2000000000,
"resource":"ENERGY",
"visible":true
}'

The return above in the example is an unsigned transaction, it should be signed and broadcasted then.

How to obtain the list of ongoing unstakings?

Call wallet/getaccount to get the ongoing unstakings list of the account:

curl -X POST https://api.nileex.io/wallet/getaccount -d \
'{"address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{

"unfrozenV2": [
{
"unfreeze_amount": 1000000000,
"unfreeze_expire_time": 1676890260000
},
{
"type": "ENERGY",
"unfreeze_amount": 2000000,
"unfreeze_expire_time": 1677210528000
}
],

}

Unstakings List = unfrozenV2

  • unfrozenV2 is a list with a maximum of 32 objects, each object stands for an ongoing unstaking in the waiting period. The list is sorted by the initiation time of each unstaking, unfrozenV2[0] is the first unstaking initiated
  • unfrozenV2[0].unfreeze_amount is the TRX amount of the unstaking, the unit is sun
  • unfrozenV2[0].unfreeze_expire_time is the end of the waiting period, the unit is millisecond

How to obtain the withdrawable balance of TRX?

After an unstaking is initiated, the TRX unstaked cannot be withdrawn until the N-day waiting period passes. Users may call wallet/getcanwithdrawunfreezeamount to obtain the withdrawable balance at a given time:

curl -X POST https://api.nileex.io/wallet/getcanwithdrawunfreezeamount -d \
'{
"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"timestamp":1706448129000,
"visible":true
}'

{
"amount": 1000000000
}

Obtain the withdrawable balance of TRX at a given time, the timestamp unit is millisecond. By appointing the present timestamp, a user may get the withdrawable balance at the moment.

Balance of withdrawable amount = amount = 1,000,000,000 (1,000 TRX)

  • amount is the withdrawable TRX amount at the given timestamp, the unit is sun

How to withdraw unstaked TRX?

After the N-day waiting period, call wallet/withdrawexpireunfreeze to create a transaction to withdraw the TRX unstaked:

curl -X POST https://api.nileex.io/wallet/withdrawexpireunfreeze -d \
'{
"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"visible":true
}'

The return above in the example is an unsigned transaction, it should be signed and broadcasted then.

Resource Management

How to obtain the total amount of energy and bandwidth in an account?

First, a user should get the energy and bandwidth share of his or her account, and then calculate the actual amount of the resources according to the total staking amount for resources and the resources supplied in the whole network.

  1. Call wallet/getaccountresource to get the total amount of energy and bandwidth in an account:
curl -X POST  https://api.nileex.io/wallet/getaccountresource -d  \
'{"Address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{
...
"freeNetUsed": 500,
"freeNetLimit": 1500,
"NetUsed": 3000,
"NetLimit": 10000,
"EnergyUsed": 4000,
"EnergyLimit": 20000,
...
}

The total amount of bandwidth in the account

= NetLimit + freeNetLimit

= 10,000 + 1,500

= 11,500

  • NetLimit is the amount of bandwidth obtained from staking and delegating in the account
  • freeNetLimit is the amount of free bandwidth in the account

The total amount of energy in the account = EnergyLimit = 20,000

  • EnergyLimit is the amount of energy obtained from staking and delegating in the account

How to obtain the usage of energy and bandwidth in an account?

Call wallet/getaccountresource to obtain the amount of usage of energy and bandwidth in the account:

curl -X POST  https://api.nileex.io/wallet/getaccountresource -d  \
'{"Address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{
...
"freeNetUsed": 500,
"freeNetLimit": 1500,
"NetUsed": 3000,
"NetLimit": 10000,
"EnergyUsed": 4000,
"EnergyLimit": 20000,
...
}

Usage of bandwidth = NetUsed + freeNetUsed = 3,000 + 500 = 3,500

  • NetUsed is the amount of used bandwidth obtained from staking and delegating in the account
  • freeNetUsed is the amount of used free bandwidth in the account

Usage of energy = EnergyUsed = 4,000

  • EnergyUsed is the amount of used energy in the account

How to obtain the useable amount of energy and bandwidth in an account?

Call wallet/getaccountresource to obtain the useable amount of energy and bandwidth:

curl -X POST  https://api.nileex.io/wallet/getaccountresource -d  \
'{"Address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{
...
"freeNetUsed": 500,
"freeNetLimit": 1500,
"NetUsed": 3000,
"NetLimit": 10000,
"EnergyUsed": 4000,
"EnergyLimit": 20000,
...
}

Useable amount of bandwidth

= NetLimit - NetUsed + freeNetLimit -freeNetUsed

= 10,000 -3,000 + 1,500–500

= 8,000

  • NetLimit is the amount of bandwidth obtained from staking and delegating in the account
  • NetUsed is the amount of used bandwidth obtained from staking and delegating in the account
  • freeNetLimit is the amount of free bandwidth in the account
  • freeNetUsed is the amount of used free bandwidth in the account

Useable amount of energy

= EnergyLimit -EnergyUsed

= 20,000–4,000

= 16,000

  • EnergyLimit is the amount of energy obtained from staking and delegating in the account
  • EnergyUsed is the amount of used energy in the account

How to obtain the amount of delegatable balance of energy and bandwidth?

First, a user should get the delegatable share of energy and bandwidth of his or her account, and then calculate the actual amount of the delegatable resources according to the total staking amount for resources and the resources supplied in the whole network.

The resource obtained through Stake 1.0, and the resource already used or delegated to this account through Stake 2.0 are not delegatable to others.

1. Call wallet/getcandelegatedmaxsize to obtain the delegatable resource share:

// when type is set to 0, query the delegatable bandwidth
curl -X POST https://api.nileex.io/wallet/getcandelegatedmaxsize -d \
'{
"owner_address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"type": 0,
"visible": true
}'

{
"max_size": 100000000
}
// when type is set to 1, query the delegatable energy
curl -X POST https://api.nileex.io/wallet/getcandelegatedmaxsize -d \
'{
"owner_address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"type": 1,
"visible": true
}'
{
"max_size": 2000000000
}

max_size is the maximum delegatable resource share for the account, the unit is sun.

Note: If the delegating transaction has a memo, it would consume more bandwidth, therefore the actual delegatable share would be less than the return of this API.

2. Then, calculate the actual amount of the delegatable resources according to the total staking amount for resources and the resources supplied in the whole network, how to convert resource share to the actual amount, please refer to the chapter: How to convert resource share to amount?

How to delegate resources?

Call wallet/delegateresource to create a transaction to delegate resources:

// delegate 1,000,000,000 bandwidth share(1000 TRX)to an account, without lock period
curl -X POST https://api.nileex.io/wallet/delegateresource -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"receiver_address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"balance":1000000000,
"resource":"BANDWIDTH",
"lock": false,
"visible":true
}'

// delegate 2,000,000,000 energy share(2000 TRX)to an account, with lock period
curl -X POST https://api.nileex.io/wallet/delegateresource -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"receiver_address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"balance":2000000000,
"resource":"ENERGY",
"lock": true,
"visible":true
}'

The return above in the example is an unsigned transaction, it should be signed and broadcasted then.

Note: balance parameter of wallet/delegateresource stand for resource share, not actual amount, to learn how to convert resource share to the actual amount we use, please refer to the chapter: How to convert resource share to amount?.

How to obtain the list of ongoing delegatings?

First, a user should obtain the list of ongoing delegatings, and then query the delegated resource share between the two addresses, and then calculate the actual amount of the resources according to the total staking amount for resources and the resources supplied in the whole network.

1. Obtain the list of ongoing delegatings for a certain account

Call wallet/getdelegatedresourceaccountindexv2 to get the list of all delegating involved with this account:

curl -X POST https://api.nileex.io/wallet/getdelegatedresourceaccountindexv2 -d \
'{
"value":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"visible": true
}'

{
"account": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"fromAccounts": ["TUznHJfHe6gdYY7gvWmf6bNZHuPHDZtowf"],
"toAccounts": ["TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g"]
}

In the return, fromAccounts show all the addresses that have delegated resources to the account, and toAccounts shows all the recipient addresses the account has delegated resources to.

2. Obtain the delegating made through Stake 2.0 between two accounts

Call wallet/getdelegatedresourcev2 to obtain the delegating data between two accounts:

curl -X POST https://api.nileex.io/wallet/getdelegatedresourcev2 -d \
'{"fromAddress":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"toAddress":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"visible":true
}'

{
"delegatedResource": [
{
"from": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"to": "TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"frozen_balance_for_bandwidth": 1000000000,
"frozen_balance_for_energy": 2000000000
},
{
"from": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"to": "TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"frozen_balance_for_bandwidth": 3000000000,
"frozen_balance_for_energy": 4000000000,
"expire_time_for_bandwidth": 1677134343000,
"expire_time_for_energy": 1677134487000
}
]
}

In the return above, delegatedResource[0] represents the resource delegating data without a lock period between two addresses.

  • delegatedResource[0].frozen_balance_for_bandwidth is the bandwidth share delegated to to address by from address, the unit is sun.
  • delegatedResource[0].frozen_balance_for_energy is the energy share delegated to to address by from address, from address may undelegate the resource share anytime, the unit is sun.

In the return above, delegatedResource[1] represents the resource delegating data with a lock period between two addresses.

  • delegatedResource[1].frozen_balance_for_bandwidth is the bandwidth share delegated to to address by from address, the unit is sun, from address may only undelegate the resource share after the time expire_time_for_bandwidth indicated.
  • delegatedResource[1].frozen_balance_for_energy is the energy share delegated to to address by from address, the unit is sun, from address may only undelegate the resource share after the time expire_time_for_energy indicated.

3. Then, calculate the actual amount of the resources according to the total staking amount for resources and the resources supplied in the whole network, how to convert resource share to the actual amount, please refer to the chapter: How to convert resource share to amount?

How to undelegate resources?

Call wallet/undelegateresource to create a transaction to undelegate resource to a certain recipient:

// undelegate bandwidth to a recipient for 1,000,000,000 shares (1,000 TRX)
curl -X POST https://api.nileex.io/wallet/undelegateresource -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"receiver_address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"balance":1000000000,
"resource":"BANDWIDTH",
"visible":true
}'

// undelegate energy to a recipient for 2,000,000,000 shares (2,000 TRX)
curl -X POST https://api.nileex.io/wallet/undelegateresource -d \
'{"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"receiver_address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"balance":2000000000,
"resource":"ENERGY",
"visible":true
}'

The return above in the example is an unsigned transaction, it should be signed and broadcasted then.

Note: balance parameter of wallet/delegateresource represents resource share, not the actual amount to use, to learn how to convert resource share to the actual amount we use, please refer to the chapter: How to convert resource share to amount?.

How to obtain the amount of total TRON power and spare TRON power in an account?

After staking TRX, an account will get resources together with voting rights, namely TRON power, and the amount of TRON power equals to the amount of staked TRX, meaning by staking 1 TRX, the account can get 1 TRON power. So the amount of total TRON power equals the amount of total staked TRX. About how to obtain the amount of total TRON power, please refer to the chapter How to obtain the staking balance under Stake 1.0, Stake 2.0 and the total staking balance? Taking the data in this chapter as an example, the amount of total TRON power in the account equals to 36,000.

Call wallet/getaccount to query the voting information in an account:

curl -X POST https://api.nileex.io/wallet/getaccount -d \
'{"Address":"TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible":true
}'

{

"votes": [
{
"vote_address": "TFFLWM7tmKiwGtbh2mcz2rBssoFjHjSShG",
"vote_count": 10000
},
{
"vote_address": "TPffmvjxEcvZefQqS7QYvL1Der3uiguikE",
"vote_count": 20000
}
],

}

The above return value votes is a list, and every element in the list represents the voting information to a witness address:

  • vote[0].vote_address is the address of a witness
  • vote[0].vote_count is the amount of TRON power that used to vote to the vote_address

amount of used TRON power in an account

= votes[0].vote_count + votes[1].vote_count + … + votes[n].vote_count

= 10,000 + 20,000

= 30,000

amount of spare TRON power in an account

= amount of total TRON power in an account —

amount of used TRON power in an account

= 36,000–30,000

= 6,000

How to convert resource share to amount?

Resource share is a measure of the user’s ability to obtain resources from the network resource pool. The TRON network supplies a fixed amount of bandwidth and energy resources every day and allocates resources to users according to the proportion of TRX staked by users. The amount of TRX staked by users to obtain energy/bandwidth resources is the energy/bandwidth resource share.

According to the energy/bandwidth resource share, the energy/bandwidth resource amount of the account can be calculated:

  • Bandwidth amount = (bandwidth share / TRX staked for bandwidth in total)* bandwidth supplied in the whole network
  • Energy amount = (energy share / TRX staked for energy in total )* energy supplied in the whole network

Call wallet/getaccountresource to obtain the total staking amount for resources and the resources supplied in the whole network:

curl -X POST https://api.trongrid.io/wallet/getaccountresource -d
'{"address" : "TLFEA6nAXBsBBzGKEeamAqurY6ZdqWCum6",
"visible": true
}'
{

"TotalNetLimit": 43200000000,
"TotalNetWeight": 36821429384,

"TotalEnergyLimit": 90000000000,
"TotalEnergyWeight": 7190739624

}

Bandwidth supplied in the whole network = TotalNetLimit = 43,200,000,000

Total TRX staked for bandwidth = TotalNetWeight = 36,821,429,384 TRX

Energy supplied in the whole network = TotalEnergyLimit = 90,000,000,000

Total TRX staked for energy = TotalEnergyWeight = 7,190,739,624 TRX

--

--