Resource Model

Voting Right, bandwidth and energy are important system resources of the TRON network. Among them, voting rights are used to vote for super representatives; Bandwidth is the unit that measures the size of the transaction bytes stored in the blockchain database. The larger the transaction, the more bandwidth resources will be consumed. Energy is the unit that measures the amount of computation required by the TRON virtual machine to perform specific operations on the TRON network. Since smart contract transactions require computing resources to execute, each smart contract transaction requires to pay for the energy fee.

Voting Right

Before any account can vote for super representatives, it needs to obtain voting rights, that is, TRON Power (TP). Voting rights can be obtained by staking TRX. In addition to obtaining bandwidth or energy, staking TRX will also obtain voting rights at the same time. Voters who stake 1TRX will receive 1TP. For how to stake, please refer to the Staking on TRON Network chapter.

Voters can stake multiple times, and the voting rights obtained by multiple stake will be added to the voter's account. Voters can query the total number of voting rights owned by the account and the number of used voting rights through the wallet/getaccountresource interface.

Bandwidth

All types of transactions need to consume Bandwidth Points. Transactions are transmitted and stored in the TRON network in the form of byte arrays. One byte requires one Bandwidth Point, so the Bandwidth Points that a transaction needs to consume is equal to the number of transaction bytes.

When the available bandwidth is insufficient, TRX needs to be burned to pay for Bandwidth Points:

Burned TRX =  the amount of bandwidth consumed * the unit price of bandwidth

Currently, the unit price of bandwidth is 1000sun.

How to Get Bandwidth Points

Each external account has 600 free bandwidth per day, and more bandwidth can be obtained by staking TRX. All users share the fixed amount of bandwidth according to the number of staked TRX. The total fixed bandwidth supply for the entire network is 43,200,000,000 per day. The following formula can be used to calculate how much bandwidth can be obtained by staking a certain amount of TRX:

The amount of bandwidth obtained = the amount of TRX staked for obtaining bandwidth / the total amount of TRX staked for obtaining bandwidth in the whole network  * 43_200_000_000

You can get the total amount of TRX staked for obtaining bandwidth in the whole network through the wallet/getaccountresource interface.

You can send a FreezeBalanceV2Contract type of transaction to stake TRX to obtain bandwidth. The following will use wallet-cli as an example to create a FreezeBalanceContract type of transaction:

wallet> freezeBalanceV2 1000000 0

Bandwidth Points Consumption

In addition to query operations, any transaction needs to consume bandwidth. The bandwidth points consumption rules are: first, check whether the transaction initiator's bandwidth obtained by staking TRX is sufficient, if it is sufficient, consume the bandwidth obtained by staking TRX; Otherwise, check whether the free bandwidth of the transaction initiator is sufficient, and if so, consume the free bandwidth, otherwise, TRX will be burned to pay for the bandwidth of the transaction according to the unit price of 0.001TRX per bandwidth.

Bandwidth Points Recovery

After the account's free bandwidth and the bandwidth obtained by staking TRX are consumed, they will gradually recover within 24 hours.

Account Bandwidth Balance Query

First, call the node HTTP interface wallet/getaccountresource to obtain the current resource status of the account, and then calculate the bandwidth balance by the following formula:

Free bandwidth balance = freeNetLimit - freeNetUsed

Bandwidth balance obtained by staking TRX = NetLimit - NetUsed

Note: If the result returned by the interface does not contain the parameters in the above formula, it means that the parameter value is 0.

Energy

The execution of each instruction of smart contract consume a certain amount of energy while running. so contracts of different complexity consume different amounts of energy. When the contract is executed, Energy is calculated and deducted according to instruction one by one. When the available energy of the account is insufficient, TRX needs to be burned to pay for the corresponding energy.

Burned TRX = Energy quantity * the unit price of Energy

Currently, the unit price of Energy is 420sun.

How to Get Energy

Energy can only be obtained by staking TRX. All users share the fixed amount of energy according to the number of staked TRX. The daily fixed total energy supply of the entire network is 90,000,000,000. Please use the following formula to calculate how much energy can be obtained by staking a certain amount of TRX:

The amount of energy obtained = the amount of TRX staked for obtaining energy / the total amount of TRX staked for obtaining energy in the whole network * 90_000_000_000

You can get the total amount of TRX staked for obtaining energy in the whole network through the wallet/getaccountresource interface.

You can send a FreezeBalanceV2Contract type of transaction to stake TRX to obtain energy. The following will use wallet-cli as an example to create a FreezeBalanceContract type of transaction:

wallet> freezeBalanceV2 1000000 1

Energy Consumption

When the contract is executed, Energy is calculated and deducted according to instruction one by one. The priority of account energy consumption is as follows:

  • Energy obtained by staking TRX
  • Burn TRX

First, the energy obtained by staking TRX will be consumed. If this part of energy is not enough, the account's TRX will continue to be burned to pay for the energy resources required for the transaction, according to the unit price of 0.00042TRX per energy.

If the contract exits due to throwing a revert exception while execution, only the energy consumed by instructions that have already been executed will be deducted. But for abnormal contracts, such as contract execution timeout, or abnormal exit due to bug, the maximum available energy of this transaction will be deducted. You can limit the maximum energy cost of this transaction by setting the fee_limit parameter of the transaction.

Energy Recovery

After the energy resource of the account is consumed, it will gradually recover within 24 hours.

Account Energy Balance Query

First call the node HTTP interface wallet/getaccountresource to obtain the current resource status of the account, and then calculate the energy balance by the following formula:

Energy Balance = EnergyLimit - EnergyUsed

Note: If the result returned by the interface does not contain the parameters in the above formula, it means that the parameter value is 0.

Dynamic Energy Model

The dynamic energy model is a resource balancing mechanism of the TRON network, which can dynamically adjust the energy consumption of each contract according to the resource occupancy of the contract, so as to make the allocation of energy resources on the chain more reasonable and prevent excessive concentration of network resources on a few popular contracts. For more details, please refer to Introduction to Dynamic Energy Model.

Principle

If a contract uses too many resources in one maintenance cycle, then in the next maintenance cycle, a certain percentage of punitive consumption will be added, and users who send the same transaction to this contract will cost more energy than before. When the contract uses resources reasonably, the energy consumption generated by the user calling the contract will gradually return to normal.

Each contract has an energy_factor field, which indicates the increase ratio of the energy consumption of the smart contract transaction relative to the base energy consumption and the initial value is 0. When the energy_factor of the contract is 0, it means that the contract is using resources reasonably, and there will be no additional energy consumption for calling the contract. When the energy_factor is greater than 0, it means that the contract is already a popular contract, and additional energy will be consumed when calling the contract. The energy_factor of a contract can be queried through the getcontractinfo API.

The calculation formula for the final energy consumed by the contract invocation transaction is as follows:

energy consumption by a contract invocation transaction  = the basic energy consumption generated by the transaction * (1 +  energy_factor)

The dynamic energy model introduces the following three parameters of the TRON network , which jointly control the energy_factor field of the contract:

  • threshold: The threshold of contract basic energy consumption. In a maintenance cycle, if the basic energy consumption of the contract exceeds this threshold, the energy consumption of the contract will increase at the next maintenance cycle.
  • increase_factor: If the basic energy consumption of the contract exceeds the threshold during a certain maintenance cycle, the energy_factor will increase by a certain percentage according to the increase_factor in the next maintenance cycle.
  • max_factor: the maximum value of energy_factor.

There is also a variable decrease_factor used to reduce the energy_factor of the contract:

  • decrease_factor: 1/4 of increase_factor. After the basic energy consumption of the contract falls below the threshold, energy_factor will be reduced by a certain percentage according to decrease_factor.

When the basic energy consumption of the contract exceeds threshold during a maintenance cycle, its energy_factor will increase in the next maintenance cycle, but the maximum will not be Exceeding max_factor, the calculation formula is:

energy_factor = min((1 + energy_factor) * (1 + increaese_factor)-1, max_factor)

When the basic energy consumption of the contract drops below the threshold in a maintenance cycle, the energy_factor will decrease in the next maintenance cycle, but the minimum value will not be lower than 0. The calculation formula is as follows:

energy_factor = max((1 + energy_factor) * (1 - decrease_factor)- 1, 0)

The dynamic energy model has been enabled on the main network, and the relevant parameters are set as follows:

  • threshold:3,000,000,000
  • increase_factor:0.2
  • max_factor:1.2

Since the energy consumption of popular contracts is different in different maintenance cycles, it is necessary to set the appropriate feelimit parameter for the transaction when calling the contract. For more information, please refer to set transaction feelimit.

API

The following table shows the relevant interfaces of the dynamic energy model and their descriptions:

APIDescriptionReturn value related to dynamic energy model
getcontractinfoQuery contract informationcontract_state.energy_usage: indicates the total amount of basic energy usage of the contract in the current maintenance cycle; contract_state.energy_factor: the energy factor of the contract, 0 means non-popular contract, bigger than zero means a popular contract; contract_state.update_cycle: the number of the current maintenance cycle
triggerconstantcontractQuery contract data or estimate energyenergy_penalty indicates the penalty energy ; energy_used indicates the total energy (the sum of the base energy and the penalty energy)
gettransactioninfobyidQuery transaction informationreceipt.energy_penalty_total indicates the penalty energy
gettransactionreceiptbyidQuery transaction execution results, fees and other informationreceipt.energy_penalty_total indicates the penalty energy