TRON Developer Guide — 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

Deploy Contract

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

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.

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.

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.

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

Related Interface

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

getTransactionInfoById needs 1 parameter, transaction id

• Related Field

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)