The dynamic energy model is a scheme proposed by the community to dynamically adjust the future energy consumption of the contract based on the known energy usage of the contract, that is, TIP-491. If a contract uses too many resources in one cycle, then the next cycle in this contract, 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. Through this mechanism, the allocation of energy resources on the chain will be more reasonable, and excessive concentration of network resources on a few contracts will be prevented. In this article, we will give you a detailed introduction to the working principle of the dynamic energy model, related APIs, and how the community prepares.

Why Dynamic Energy Model?

At present, more than 85% of the resource consumption of the TRON network is concentrated in a few contracts, and some of the transactions that call these contracts are of low value or even fraudulent.

If this situation continues, not only will it affect the user experience, but it will also make it difficult for the dApp ecosystem to grow. The capacity of the network is limited, when the network is filled with a large number of queued low-value transactions, other transactions will have to wait longer, which is a very bad experience for the users and dApp developers. Therefore, it is necessary to introduce the dynamic energy model, which increases low-value transaction costs without affecting other dApps while ensuring the robustness, diversity, and balanced development of the ecosystem.

Principle of Dynamic Energy Model

The dynamic energy model introduces an energy_factor variable for each contract, and the initial value is 0. The final energy consumption calculation formula for the transaction that the user calls the contract is as follows:

Transaction energy consumption of calling the contract * （1 +  energy_factor）

During the maintenance period of a TRON network (currently 6 hours), when the basic energy consumption of the contract exceeds a certain threshold, the energy_factor will increase in the next maintenance period. After the energy_factor increases, according to the above formula, the user will send the same transaction, and the energy consumption generated will increase. However, the energy_factor will not increase infinitely, since there will be a maximum value for it. During a maintenance period, after the basic energy consumption of the contract drops below the threshold, the energy_factor will decrease, and the energy_factor will decrease to 0 at most.

In order to control the energy_factor variable, the dynamic energy model also introduces three network parameters, which can be modified through network governance voting. These three parameters are as follows:

• threshold: the threshold of the basic energy consumption of the contract. If the basic energy consumption of the contract exceeds this threshold, the energy_factor will be increased
• increase_factor: the ratio of each increase in the energy_factor variable
• max_factor： the maximum value of energy_factor

And there is also a variable decrease_factor for reducing energy_factor:

• decrease_factor: a quarter of increase_factor, the ratio of energy_factor reduction after the basic energy consumption of the contract is reduced below the threshold

Calculation of Energy Factor

During each maintenance period, the basic energy consumption of the contract will be counted. If the basic energy consumption of the contract exceeds the threshold in a maintenance period, its energy_factor will increase by the increase_factor in the next maintenance period, and the maximum will not exceed max_factor, calculated as follows:

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

When the basic energy consumption of the contract drops to the threshold and below, the energy_factor will decrease by the decrease_factor, 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)

How to obtain chain parameters of the dynamic energy model?

After the model is opened, users are able to call /wallet/getchainparameters API to get three network parameters related to the model, see below：

$ curl -X POST  http://127.0.0.1:8092/wallet/getchainparameters
{
   "chainParameter": [
       ……
       {
           "key": "getDynamicEnergyThreshold",
           "value": 2000000
       },
       {
           "key": "getDynamicEnergyIncreaseFactor",
           "value": 2000
       },
       {
           "key": "getDynamicEnergyMaxFactor",
           "value": 25000
       }
   ]
}

Here are the introductions for the parameters:

• getDynamicEnergyThreshold: the consumption threshold of the contract, the unit is energy
• getDynamicEnergyIncreaseFactor: indicates increase_factor, the precision is 10000, the value returned above is 2,000, which means the increase_factor is 0.2
• getDynamicEnergyMaxFactor: indicates max_factor, the precision is 10000, the value returned in the example is 25000, which shows the max_factor is 2.5

Example

Let’s take an example and see how the dynamic energy model works, assuming the parameters of network is as below:

• threshold: 5,000,000,000
• increase_factor: 0.5
• max_factor: 1
• decrease_factor: increase_factor / 4 = 0.125

Contract A has the following call:

• Contract_A.a_call(), a_call() method has an energy consumption of 10,000, let’s call it origin_A

In Maintenance Period of N+1

If the energy consumption of Contract_A in the maintenance period N exceeds the threshold, then the energy_factor of the contract in this maintenance period is:

• energy_factor_A: MIN((1 + prev_factor_A) * (1 + increase_factor) — 1, 1) = MIN(1 * 1.5–1, 1) = 0.5

Then, calling Contract_A.a_call() in the period of N+1 will consume,

• origin_A * (1 + energy_factor_A) = 10,000 * ( 1 + 0.5)= 15,000

In Maintenance Period of N+2

If the amount of energy consumed by contract A in the maintenance period N+1 continues to exceed the threshold, then the energy_factor of the N+2 maintenance period is:

• energy_factor_A: MIN( (1 + prev_factor_A) * (1 + increase_factor) — 1, max_factor) = MIN((1 + 0.5)*(1 + 0.5) — 1, max_factor) = MIN(1.25, 1) = 1

Then, calling Contract_A.a_call() in the period of N+2 will consume,

• origin_A * (1 + factor_A) = 10,000(1 + 1) = 20,000

In Maintenance Period of N+3

If the amount of energy consumed by contract A in the maintenance period N+2 falls below the threshold, then the energy_factor of the N+3 maintenance period contract is:

• factor_A: MAX((1 + prev_factor_A) * (1 — decrease_factor) — 1, 0) = MAX(( 1 + 1) * (1–0.5/4) — 1, 0) = MAX(0.75, 0) = 0.75

Then, calling Contract_A.a_call() in the period of N+3 will consume,

• origin_A * (1 + factor_A) = 10,000(1 + 0.75) = 17,500

How to prepare for Dynamic Energy Model?

The dynamic energy model will be deployed in a new version in the future. After the deployment is completed, it needs to be opened through the network governance voting.

The dApp users do not need to make special preparations, but they should fully understand the working method of the dynamic energy model. Because after the model is turned on, if a user calls a very hot smart contract, due to the existence of the penalty mechanism, consumption of the same type of transaction may vary in different periods.

The wallets, exchanges, and dApps generally involve the estimation and display of transaction fees. After the dynamic energy model is opened, when estimating the transaction fees of TRC20 token transfers and smart contract calls, the energy fee generated by punitive consumption should be included. In addition, if you need to show the details of the composition of transaction fees to the users, the punitive consumption should also be considered and included.

API Changes

After the dynamic energy model is enabled, in order to allow users to query related data, update the return values of multiple APIs, fields related to the dynamic energy model are added.

/wallet/getcontractinfo

Description: queries a contract’s information from the blockchain

Changes: Add the contract_state structure to the return data of the API:

• contract_state.energy_usage — the origin energy consumption of the contract in the current maintenance period
• contract_state.energy_factor — the penalty factor of the contract in the current maintenance period, the precision is 10_000, energy_factor equal to 1,000 means the penalty percentage is 10%
• contract_state.update_cycle — the current maintenance period number

Example:

{
  "runtimecode": "",
  "smart_contract": {},
  "contract_state": {
        "energy_usage": 2000,
        "energy_factor": 1000,
        "update_cycle": 500
  }
}

/wallet/triggerconstantcontract

Description: invoke the read-only function (modified by the view or pure modifier) of a contract for contract data query; or invoke the non-read-only function of a contract for predicting whether the transaction can be successfully executed or estimating the energy consumption

Changes: add energy_penalty in contract trigger results:

• energy_penalty — the total penalty energy in the transaction

Example:

{
    "...": "...",
    "energy_used": 643,
    "energy_penalty": 200
}

/wallet/gettransactioninfobyid

Description: query the transaction fee, block height by transaction id

Changes: add energy_penalty_total in transaction receipt

• receipt.energy_penalty_total — the total penalty energy in the transaction

Example:

{
    "...": "...",
    "receipt":
    {
        "energy_usage": 98115,
        "energy_usage_total": 98115,
        "net_usage": 379,
        "result": "SUCCESS",
        "energy_penalty_total": 5000
    }
}

/wallet/gettransactionreceiptbyid

Description: query the transaction receipt with fees, heights, etc.

Changes: add energy_penalty_total in transaction receipt

• Receipt.energy_penalty_total — the total penalty energy in the transaction

Example:

{
    "Receipt": {
        "result": "SUCCESS",
        "energy_fee": 618400,
        "energy_usage_total": 6184,
        "net_usage": 313,
        "energy_penalty_total": 719
    }
}

Compatibility

There is no compatibility issue with the dynamic energy model, and there is no compatibility issue with the modification of the API. The changes related to the dynamic energy model related APIs are to add fields, without any modification to the old fields.

Summary

The dynamic energy model dynamically adjusts the future energy consumption of calling a contract according to the known energy usage of the contract. Without affecting other dApps, it increases the cost of the resource-intensive contracts to reduce their future resource occupation. The dynamic energy model makes the allocation of energy resources on the chain more reasonable, prevents excessive concentration of network resources on a few contracts, and ensures the robustness, diversity, and balanced development of the ecosystem.