Energy Consumption Mechanism

Introduction

Resource consumption mechanics in the TRON protocol govern smart contract execution. This guide walks developers through the governing rules in deploying, triggering, and executing smart contracts, the resource consumption process flow, and related interfaces/fields.

Governing Rules

Terminology

TermDefinition
DeveloperEnergyThe energy consumed by deploying the contract.
CallerEnergyThe energy consumed from calling the contract.
TotalEnergyDeveloperEnergy + CallerEnergy
EnergyOfFeelimitFeelimit / 10 SUN
EnergyOfAccountEnergy + (Balance of TRX / 10 SUN)

Deploy Contract

If DeveloperEnergy <= min(EnergyOfFeelimit, EnergyOfAccount), then the contract can successfully deploy. Otherwise, there is an OUT_OF_ENERGY error.

391391

Contract deployment logic flow

Trigger Contract

When consume_user_resource_percent (% ratio user pays) = 100, the caller pays the entire cost of the operation. The caller needs to meet:

CallerNeedEnergy <= min(EnergyOfFeelimit, EnergyOfAccount)

to successfully call the contract. Otherwise, OUT_OF_ENERGY is reported.

419419

Contract triggering logic flow

When 0 =< consume_user_resource_percent < 100, this indicates the operation cost is paid proportionally by the developer and the caller. If the developer has enough energy, the caller needs to meet:

  • CallerNeedEnergy = NeedEnergy * consume_user_resource_percent/100
  • CallerNeedEnergy <= min(EnergyOfFeelimit, EnergyOfAccount)

Developer:

DeveloperNeedEnergy = NeedEnergy * (100-consume_user_resource_percent) /100

In order to successfully call the contract, DeveloperNeedEnergy <= OriginEnergyLimit. Otherwise, report OUT_OF_ENERGY.

511511

If the developer has insufficient energy, the remaining energy consumption is provided by the caller and does not consume the developer's TRX. That is, the caller needs to satisfy:

TotalEnergy <= min(EnergyOfFeelimit, EnergyOfAccount) + DeveloperProvideEnergy

In order to successfully call the contract, DeveloperProvideEnergy <= OriginEnergyLimit. Otherwise, report OUT_OF_ENERGY.

543543

Contract Execution

When executing the contract method, OUT_OF_ENERGY can view details according to the interface. Call the /walletsolidity/gettransactionInfoByID interface and convert the returned resMessage field from hex to a string.

resMessages include: Not enough energy for 'AND' operation executing: curInvokeEnergyLimit[1000], curOpEnergy[3], usedEnergy[1000] Similar information.

TermDefinition
curInvokeEnergyLimitIndicates the maximum energy consumption, i.e. min(EnergyOfFeelimit, EnergyOfAccount).
curOpEnergyEnergy still needed for current operation.
usedEnergyEnergy used locally to call.

Out of Energy Solution

  1. If EnergyOFAccount < curInvokeEnergyLimit, indicating the caller has insufficient remaining energy and TRX balance, you need to recharge TRX.

  2. If EnergyOfFeelimit < curInvokeEnergyLimit, indicating the fee limit setting is too small, you need to increase the fee limit. The maximum fee limit is 1000 TRX.

The Consumption Process

  1. Consume the energy gained by the contract creator from freezing TRX, according to the consume_user_resource_percent ratio set in the contract. If that energy is not enough, continue consuming the contract creator's remaining energy. Any remaining energy shortage is provided by the contract caller.

  2. Contract caller consumption process: (First consume the Energy acquired by the caller via freezing TRX, to ensure the contract can be executed normally, and the insufficient part is offset by destroying the TRX).

  3. If the contract creator does not freeze TRX for the Energy resource, all consumption is required by the caller.

Glossary of Terms

TermMeaning
Contract CreatorThe account that created the contract.
Contract CallerThe account calling the contract.
EnergySmart contract runtime consumes resources, measurable by Energy.
FreezeFreezing TRX allows users to gain Energy. The energy gain calculation also depends on the total amount of TRX frozen in the entire network.
Fee LimitThe maximum acceptable TRX cost consumed by the user when calling or creating a smart contract, including resources obtained from freezing TRX.
Call ValueThe number of TRX the user transfers to the account of the smart contract when it is invoked or created. During Fee Limit determination, the value of this part is omitted.
consume_user_resource_percentThis parameter refers to the proportion that the smart contract caller pays to run the smart contract.
origin_energy_limitThe upper limit of the energy set by the developer that is consumed by the developer during a contract call must be greater than zero. For the old contract, if the parameter that sets the value is not provided, it is saved as 0, but it will be calculated according to the 10 million energy limit. Developers can reset this value via the updateEnergyLimit interface, which must be greater than 0 when setting new values.

Related Interface

The parameter getTransactionInfoById queries transaction information containing the result of a contract call or contract creation.

getTransactionInfoById needs 1 parameter, transaction id
energy_usage: // The amount of Energy consumed by contract caller
0
energy_fee: // This contract caller consumes the number of TRX (SUN)
120
origin_energy_usage: // The amount of Energy provided by contract creator
0
energy_usage_total: // The total amount of Energy consumed in contract(including the number of Energy corresponding to energy_usage, origin_energy_usage, and energy_fee)
252
net_usage: // 
0
net_fee: // TRX consumed by contract due to insufficient Bandwith
0

FreezeBalance Freeze TRX to obtain Bandwidth or Energy

freezeBalance frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH,1 ENERGY]

Instructions

The parameter "fee_limit" is passed in the process of deploying the contract and calling the contract. The TRX amount corresponds to Energy consumed in this execution.

The Energy section is frozen: (frozen balance amount / freeze to get total Energy) * Energy consumption. Destroy TRX to get the Energy section: the number of TRX consumed in proportion.