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

Term	Definition
DeveloperEnergy	The energy consumed by deploying the contract.
CallerEnergy	The energy consumed from calling the contract.
TotalEnergy	DeveloperEnergy + CallerEnergy
EnergyOfFeelimit	Feelimit / 10 SUN
EnergyOfAccount	Energy + (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.

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.

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.

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.

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.

Term	Definition
curInvokeEnergyLimit	Indicates the maximum energy consumption, i.e. min(EnergyOfFeelimit, EnergyOfAccount).
curOpEnergy	Energy still needed for current operation.
usedEnergy	Energy used locally to call.

Out of Energy Solution

If EnergyOFAccount < curInvokeEnergyLimit, indicating the caller has insufficient remaining energy and TRX balance, you need to recharge TRX.
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

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.
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).
If the contract creator does not freeze TRX for the Energy resource, all consumption is required by the caller.

Glossary of Terms

Term	Meaning
Contract Creator	The account that created the contract.
Contract Caller	The account calling the contract.
Energy	Smart contract runtime consumes resources, measurable by Energy.
Freeze	Freezing TRX allows users to gain Energy. The energy gain calculation also depends on the total amount of TRX frozen in the entire network.
Fee Limit	The maximum acceptable TRX cost consumed by the user when calling or creating a smart contract, including resources obtained from freezing TRX.
Call Value	The 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_percent	This parameter refers to the proportion that the smart contract caller pays to run the smart contract.
origin_energy_limit	The 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.