Stake 2.0 Adaption FAQ
--
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 sunaccount_resource.frozen_balance_for_energy.frozen_balance
is the energy share balance of Stake 1.0, the unit is sundelegated_frozen_balance_for_bandwidth
is the balance of delegated bandwidth share under Stake 1.0, the unit is sunaccount_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 sunfrozenV2[1].amount
is the energy balance of Stake 2.0, the unit is sundelegated_frozenV2_balance_for_bandwidth
is the balance of delegated bandwidth under Stake 2.0, the unit is sunaccount_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 initiatedunfrozenV2[0].unfreeze_amount
is the TRX amount of the unstaking, the unit is sununfrozenV2[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.
- 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 accountfreeNetLimit
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 accountfreeNetUsed
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 accountNetUsed
is the amount of used bandwidth obtained from staking and delegating in the accountfreeNetLimit
is the amount of free bandwidth in the accountfreeNetUsed
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 accountEnergyUsed
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 timeexpire_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 timeexpire_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 witnessvote[0].vote_count
is the amount of TRON power that used to vote to thevote_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