资源模型¶
资源模型介绍¶
TRON 网络的核心系统资源由三部分构成:投票权 (TRON Power, TP)、带宽 (Bandwidth) 和 能量 (Energy)。它们各自的定义和用途如下:
- 投票权 (TRON Power, TP): 用户通过质押 TRX 获得的治理凭证,用于为超级代表(Super Representative, SR) 选举中的候选人(Candidate)投票,以决定每个周期的 SR 及超级代表合伙人(Partner)。
- 带宽 (Bandwidth): 衡量交易数据在区块链上占用的字节大小。任何类型的交易(无论是普通转账还是合约交互)都必须消耗带宽。
- 能量 (Energy): 衡量智能合约在 TRON 虚拟机(TVM)中执行所需消耗的计算资源,可理解为“CPU 算力费”。能量仅在部署或执行智能合约时才会被消耗。
投票权¶
任何账户在给超级代表投票前,都需要先获得投票权,即 TRON Power (TP)。
- 获取方式:当通过质押 TRX 来换取带宽或能量时,同时会获得与质押 TRX 等量的 TP,这是获取 TP 的唯一途径。关于如何质押请参考 在 TRON 网络上质押 章节。
- 兑换比例:质押与 TP 的兑换比例为 1 : 1。即每质押 1 TRX,便会获得 1 TP。
- 累加特性:您可以分批多次进行质押。所有质押所获得的 TP 都会自动累加,计入您账户的总 TP 池中。
- 查询接口:您随时可以通过
wallet/getaccountresource
API 接口,查询自己账户当前拥有的总 TP 以及已使用的 TP 数量。
带宽¶
交易以字节数组的形式在网络中传输及存储,一条交易消耗的带宽(Bandwidth) = 交易字节数 * Bandwidth 费率
,当前 Bandwidth 费率 = 1。
假如一条交易的字节数为 200,那么该交易需要消耗 200 带宽。
注意:由于网络中总质押资金以及账户的质押资金随时可能发生变化,因此账户拥有的带宽不是固定值。
1. 获取带宽¶
带宽可通过以下三种方式获取:
- 通过质押 TRX 获取:
用户根据其为获取带宽而质押的 TRX 数量,按比例分享一个全网固定的总带宽池。
Bandwidth 总量是一个可通过委员会提案修改的网络参数(#62),目前的值是 43,200,000,000。
额度 = (为获取带宽质押的 TRX / 整个网络为获取带宽质押的 TRX 总额) * (Bandwidth 总量)
质押获取带宽操作 (wallet-cli
示例)
freezeBalanceV2 frozen_balance [ResourceCode:0 BANDWIDTH,1 ENERGY]
- 通过他人代理获取:
代理获取带宽操作 (
wallet-cli
示例)delegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress [lock]
- 获取每日固定免费额度:每个账户每日可获得的固定免费带宽量。该额度是一个可通过委员会提案修改的网络参数(#61),当前值为 600。
2. 带宽的消耗规则详解¶
除了查询操作,任何交易都需要消耗带宽。当您发起一笔交易时,系统会根据交易类型的不同,遵循一套严格的优先级顺序来扣除带宽费用。
场景一:普通交易
系统将按以下顺序尝试支付带宽费用:
1. 消耗质押带宽:优先消耗发起者通过质押 TRX 获得的带宽。
2. 消耗免费带宽:其次消耗交易发起者的 600 每日免费带宽。
*3. 燃烧 TRX 支付:若以上两者均不足,则会燃烧交易发起者的 TRX 来支付。
* 燃烧费用 = 交易字节数 × 1,000 sun
场景二:创建新账户的交易
创建新账户的交易在支付带宽时有其特殊规则,不使用每日免费带宽: 1. 消耗质押带宽:优先尝试消耗交易发起者通过质押 TRX 获得的带宽。 2. 燃烧 TRX 支付:若质押带宽不足,则直接燃烧 0.1 TRX 作为费用来完成账户创建。
场景三:TRC-10 通证转账
TRC-10 通证(Token)转账的消耗逻辑最为特殊,它引入了“通证发行方”作为潜在的费用承担者:
- 消耗发行方带宽 (优先):系统首先会尝试消耗由通证发行方为该通证预付的带宽。这需要同时满足三个条件(只有当这三项检查全部通过时,才会扣除发行方的带宽。否则,进入下一步,由转账发起者自己支付):
- 通证发行方剩余额度充足
- 查询方式:/wallet/getassetissuebyaccount
- 计算公式:
public_free_asset_net_limit - public_free_asset_net_usage
- 含义:通证发行方能为该通证转账支付的剩余额度
- 转账发起者的个人额度充足
- 查询方式:/wallet/getaccountnet
- 计算公式:
assetNetLimit['assetID'] - assetNetUsed['assetID']
- 含义:该通证持有者还能使用的由发行方提供的免费带宽额度
- 通证发行方通过质押获取的带宽充足
- 查询方式:/wallet/getaccountnet
- 计算公式:
NetLimit - NetUsed
- 含义:发行方通过质押获取的可用带宽数额
- 通证发行方剩余额度充足
- 消耗发起者质押带宽:尝试消耗交易发起者通过质押 TRX 获得的带宽。 若质押带宽不足,则进入下一步。
- 消耗发起者免费带宽:如果免费带宽也不足,则进入下一步。
- 燃烧 TRX 支付:若以上所有带宽资源均不足,则会燃烧发起者的 TRX 来支付费用。
- 燃烧费用 = 交易字节数 × 1,000 sun
3. 带宽的自动恢复¶
账户的免费带宽和质押 TRX 获取的带宽消耗后, 会在 24 小时内逐步恢复。
4. 账户带宽余额查询¶
您可以通过调用 wallet/getaccountresource
HTTP 接口来获取一个账户当前的资源状态。在返回的 JSON 数据中,您可以使用以下公式来精确计算两种带宽的剩余额度。
免费带宽余额 = freeNetLimit - freeNetUsed
通过质押获取的带宽余额 = NetLimit - NetUsed
注:如果接口返回的结果中没有包含上述公式中的参数,表示该参数值为 0
。
能量¶
能量 (Energy) 是在 TRON 虚拟机(TVM)中执行智能合约指令时所需消耗的计算资源的计量单位。本章将从以下三个方面全面介绍能量这一核心资源:
1. 能量的获取与消耗¶
获取能量有两种方式,一种是通过质押 TRX (即将持有的 TRX 锁定,作为抵押)获取,另外一种是通过他人代理获取。通过质押,用户可以按其贡献比例,分享一个全网固定的总能量池。
获取能量主要有两种方式:
- 通过质押 TRX 获取:用户通过质押自己持有的 TRX 获取能量。
- 通过他人代理获取:从其他账户接收其代理的能量。
质押获取能量操作 (wallet-cli
示例)¶
freezeBalanceV2 frozen_balance [ResourceCode:0 BANDWIDTH,1 ENERGY]
代理获取能量操作 (wallet-cli
示例)¶
delegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress [lock]
账户能量余额查询¶
您可以通过调用 wallet/getaccountresource
HTTP 接口来查询一个账户当前的能量资源状态。在返回的 JSON 数据中,然后通过如下公式计算能量余额:
能量余额 = EnergyLimit - EnergyUsed
注:如果接口返回的结果中没有包含上述公式中的参数,表示该参数值为 0
。
能量额度计算¶
您能获得的能量额度是一个动态值,它根据您的质押占全网总能量质押的比例实时计算:
您的能量额度 = (为获取 Energy 质押的 TRX / 整个网络为获取 Energy 质押的 TRX 总额) * 能量总量
计算示例¶
由于您的额度与全网总质押量挂钩,当其他用户质押或解押时,您的能量额度会随之变化。
如全网只有两个人 A,B 分别质押 2 TRX,2 TRX。
二人质押获得的可用 Energy 分别是:
A: 90,000,000,000
B: 90,000,000,000
当第三人 C 质押 1 TRX 时,三人质押获得的可用 Energy 调整为:
A: 72,000,000,000
B: 72,000,000,000
C: 36,000,000,000
能量的消耗¶
能量支付优先级¶
当一笔合约交易需要消耗能量时,系统按以下顺序支付:
- 消耗质押能量:优先消耗交易发起者通过质押 TRX 获得的能量。
- 燃烧 TRX 支付:如果质押获得的能量不足以支付所有指令,系统会自动开始燃烧发起者账户中的 TRX 来弥补差额,当前能量单价为 0.0001 TRX。
异常情况下的扣费规则¶
合约执行可能因不同原因中断,其能量扣除规则也大不相同:
- 对于正常中断 (
REVERT
指令): 如果合约中途由于抛出REVERT
异常而退出,则仅扣除已经执行的指令所对应的能量。 - 对于意外中断 (bug 或超时):
如果合约因代码 bug、执行超时或其他意外错误而崩溃,系统将扣除本次交易可用的全部能量作为惩罚,用户可以通过设置交易的
fee_limit
参数来限定这笔交易最多可以消耗的能量费用上限。
能量的恢复¶
账户的能量资源消耗后,会在 24 小时内逐步恢复。
2. 如何填写 fee_limit
(用户必读)¶
在本节范围内,将合约的开发部署人员,简称为“开发者”;将调用合约的用户或者其他合约,简称为“调用者”。
调用合约消耗的能量能以一定比例折合成 TRX(或者 sun),所以在本节范围内,指代合约消耗的资源时,并不严格区分 Energy 和 TRX;仅在作为数值的单位时,才区分 Energy、TRX 和 sun。
fee_limit
是调用智能合约时一个至关重要的安全参数。合理设置 fee_limit
,一方面能尽量保证正常执行;另外一方面,如果合约所需能量过多,又不会过多消耗调用者的 TRX。
在设置 fee_limit
之前,需要了解几个概念:
- 合法的
fee_limit
为 0 - 15,000,000,000 sun(折合 0 - 15,000 TRX)之间的整数。fee_limit
上限是一个可通过委员会提案修改的网络参数(#47),目前的值是 15,000 TRX。 - 不同复杂度的合约,每次正常执行消耗不同的 Energy;相同合约每次消耗的能量基本相同1,但由于动态能量模型机制,对于热门合约,不同时刻执行时可能需要的能量不同,具体请参考 动态能量模型 章节;执行合约时,逐条指令计算并扣除 Energy,如果超过
fee_limit
的限制,则合约执行失败,已扣除的能量不退还。 - 当前
fee_limit
是指调用者在执行合约时愿意支付的 TRX 上限2。需要注意的是,合约执行消耗的总能量,除了调用者支付的部分,也可能包含开发者为其承担的部分。 - 一个恶意合约,如果最终执行超时,或者因 bug 合约崩溃,则会扣除当前交易允许消耗的所有 Energy。这个总能量池由以下几部分相加构成:
总消耗能量 = 调用者质押所得能量 + 开发者分摊能量 + 燃烧 TRX 所得能量
。其中,“燃烧 TRX 所得能量”的上限由fee_limit
决定。 - 开发者可以通过 能量分摊机制 承担一定比例的能量消耗(比如 90%)。但是,当开发者账户的 Energy 不足以支付时,剩余部分完全由调用者承担。在
fee_limit
限制范围内,如调用者的 Energy 不足,则会燃烧等价值的 TRX。2
示例
下面将以一个合约 C
的执行,来具体举例,如何估算 fee_limit
:
- 假设合约
C
上一次成功执行时,消耗了 18000 Energy。通过调用 estimateenergy 接口进行预估,假设本次执行消耗的 Energy 上限约为 20,000 Energy; - 燃烧 TRX 时,由于能量单价目前为 100 sun,所以 10 TRX 固定可以兑换 100,000 Energy;
- 假设开发者承诺承担 90% 的 Energy,而且开发者账户有充足的 Energy。
fee_limit
的估算步骤如下:
- 步骤 1:计算交易总费用
首先,将预估的最高能量消耗乘以能量单价,得出交易的总费用。
20,000 Energy * 100 sun = 2,000,000 sun (即 2 TRX)
- 步骤 2:确定用户承担的份额
接着,根据开发者承诺的承担比例(90%),计算出用户需要承担的费用比例(10%):
2,000,000 sun * 10% = 200,000 sun
- 步骤 3:设定最终的
fee_limit
因此,建议用户将fee_limit
设置为 200,000 sun。
3. TRON 网络能量消耗机制¶
基本能量消耗规则¶
在执行合约交易时,系统会逐条指令计算并扣除所需能量,账户能量的使用遵循以下优先级原则:
- 优先使用账户可用能量(通过质押或租赁获得)
- 若能量不足,不足的能量,按固定费率(0.0001 TRX / 能量)燃烧账户内的 TRX
合约能量分摊机制¶
对于合约调用,为降低调用者的成本,TRON支持合约部署者分担部分能量消耗,具体细节请参考 合约能量分摊机制 章节。
能量扣除规则:
合约部署者承担部分: * 直接从部署者账户的可用能量中扣除,不会燃烧部署者的TRX
合约调用者承担部分: 1. 优先使用账户中的可用能量 2. 不足部分,按固定费率燃烧账户余额中的 TRX
动态能量模型¶
动态能量模型是波场网络的一个资源平衡机制,可以根据合约的资源占用情况动态调整每个合约的能量消耗量,从而使能量资源在链上的分配更加合理,防止网络资源过度集中在少数热门合约上,详情请参考 动态能量模型介绍。
工作原理¶
如果合约在一个维护周期(目前是 6 小时)内使用过多的能量,则在下一个维护周期内,用户向该合约发送相同的交易将产生更多的额外能量消量。当合约合理使用资源时,用户调用该合约所产生的能量消耗将逐渐恢复正常。
每一个合约有一个能量消耗放大系数 energy_factor
,表示该智能合约交易的能量消耗相对于基础能量消耗的增加倍数,初始值是 0
。
- 合约的
energy_factor
为0
时,表示该合约在合理的使用资源,调用该合约不会有额外的能量消耗。 - 当
energy_factor
大于0
时,表示该合约已经是热门合约,调用该合约时将消耗额外的能量。合约的能量消耗放大系数可以通过 getcontractinfo 接口查询。
合约调用交易最终需要消耗的能量的计算公式为:
合约交易能量消耗量 = 合约调用交易产生的基础能量消耗 * (1 + energy_factor)
动态能量模型引入了如下三个 TRON 网络参数,它们共同控制合约的 energy_factor
字段:
threshold
:合约基础能量消耗的阈值,如果合约在一个维护周期中的基础能量消耗超过这个阈值,下一个维护周期,该合约的能量消耗量就会增加。increase_factor
:合约在某个维护周期的能量消耗超过阈值,则在下一个维护周期,energy_factor
就会根据increase_factor
增加一定的比例。max_factor
:合约energy_factor
的最大值。
另外还有一个变量 decrease_factor
用于降低合约的 energy_factor
:
decrease_factor
:increase_factor
的四分之一,合约基础能耗降低到阈值以下后energy_factor
会根据decrease_factor
减少一定比例。
energy_factor
调整公式:
- 当合约的基础能量消耗量在一个维护周期内超过了
threshold
,那么在下一个维护周期它的energy_factor
将增加,但最大不会超过max_factor
,计算公式为:energy_factor = min((1 + energy_factor) * (1 + increase_factor)-1, max_factor)
- 当合约的基础能量消耗量在一个维护周期内下降到
threshold
及以下后,那么在下一个维护周期energy_factor
就会降低,但最小值不会低于 0,计算公式如下:energy_factor = max((1 + energy_factor) * (1 - decrease_factor)- 1, 0)
动态能量模型在主网已经开启,当前相关参数设置如下:
threshold
:5,000,000,000increase_factor
:0.2max_factor
:3.4
由于热门合约在不同的维护周期的能量消耗是不一样的,所以在调用合约时要为交易设置合适的 fee_limit
参数。
在 TRON 网络上质押¶
如何质押获取系统资源¶
在 TRON 网络中,质押 TRX 是获取能量、带宽和投票权这三大核心资源的统一机制。
如何执行质押¶
- 通过 HTTP API:调用
wallet/freezebalancev2
接口。 - 通过智能合约:在合约中调用 Stake 2.0 Solidity API 完成质押操作。
当您执行解质押操作时,对应的资源(能量/带宽)和投票权将会被同步释放和收回。
如何代理资源¶
账户在通过质押获取到能量或带宽后,可以选择将其代理给其他 TRON 账户。这允许资源富余的账户帮助资源不足的账户完成交易。
代理规则与核心限制 在执行资源代理前,必须了解以下关键规则:
- 可代理的资源:仅限能量和带宽。投票权(TP)无法被代理。
- 资源的来源:必须是来自 Stake 2.0 质押且尚未使用的资源。
- 接收方限制:接收方必须是一个已激活的外部账户,不能是合约地址。
时间锁选项 (Time Lock Option) 在代理资源时,您可以选择是否启用“时间锁”,这将影响您何时能收回资源。
- 带时间锁: 资源将被锁定,您需要在等待期后才能执行取消代理的操作。 重要:在此期间,如果您对同一个地址再次进行代理,等待期将重新开始计算。
- 不带时间锁: 您可以随时取消代理,立即收回资源。
相关 API 接口
delegateresource
: 执行资源代理操作。undelegateresource
: 取消资源代理(收回资源)。getcandelegatedmaxsize
: 查询您当前某种资源可供代理的最大份额。
如何解质押¶
您可以在质押 TRX 后随时进行解质押。在调用 unfreezebalancev2
API 发起解质押操作后,您的资金会进入一个 14 天的锁定期。此锁定期由 TRON 网络的 #70 号参数定义,未来可通过网络治理提议进行修改。14 天锁定期结束后,您便可以通过 withdrawexpireunfreeze
API 将这笔已解质押的 TRX 提取到您的账户中。
重要提示: 在执行解质押前,请务必了解以下关键限制:
- 已代理资源无法解质押
您不能解质押那些已代理给其他账户的资源所对应的 TRX。必须先通过
undelegateresource
收回已代理的资源,然后才能解质押这部分 TRX。 - 资源的回收 解质押将使得与该笔质押 TRX 对应的资源和 TRON Power (TP) 被系统同步收回。因此,您将失去相应的能量或带宽,以及等量的 TP。
- 并发操作次数限制
您最多只能同时保有 32 笔处于 14 天锁定期内的解质押操作。您可以通过
getavailableunfreezecount
接口查询剩余可用的解质押次数。
解质押的自动触发效果
调用 unfreezebalancev2
不仅将发起解质押,系统还将自动为您提取已结束 14 天锁定期、可以自由取回的 TRX。
如何验证提取金额
要查询单次解质押操作具体自动提取了多少已解锁的 TRX,您可以通过 gettransactioninfobyid
接口查询该笔解质押交易的详情,并关注以下字段:
withdraw_expire_amount
: 该字段显示了在本次交易中,自动提取到的已到期解质押 TRX 本金数量。
投票权资源回收¶
在 Stake 2.0 机制下,解质押 TRX 会同步回收等量的投票权(TP)。如果回收的 TP 数量超过了您账户中空闲的 TP,系统将按比例撤销您已投出的选票。
回收 TP 的优先级
系统回收 TP 时,遵循以下两步流程:
- 优先回收空闲 TP: 系统首先会回收您账户中所有未使用于投票的、空闲的投票权。
- 按需撤销已投选票: 如果空闲 TP 不足以满足回收需求,系统将开始撤销您已投出的选票,以回收剩余所需 TP。
选票撤销的计算规则
撤销操作并非随机,而是按比例公平地从您投票给的每一个超级代表/超级代理合伙人 身上撤回选票。
计算公式
从当前超级代表撤销的票数 = 总撤票数 * (给当前超级代表或超级代表合伙人的投票数 / 该账户总投票数)
假设用户 A
的账户状态如下:
初始状态:
- 总质押:2,000 TRX
- 总 TP:2,000 TP
- 已投票数:1,000票 (其中,为 SR1 投了 600 票,为 SR2 投了 400 票)
- 空闲 TP:1,000 TP
现在,用户 A 执行操作:解质押 1,500 TRX。
系统处理流程:
- 回收需求:系统需要从
A
的账户中回收 1,500 TP。 - 回收空闲 TP:首先回收全部 1,000 点空闲 TP。
- 计算差额:仍需回收
1,500 - 1,000 = 500 TP
。这部分必须通过撤销选票来获取。 - 按比例撤票:
- 从 SR1 撤销的票数 = 500 * (600 / 1000) = 300 票
- 从 SR2 撤销的票数 = 500 * (400 / 1000) = 200 票
- 最终结果: A 的账户成功解质押 1,500 TRX,其投票状态更新为:为 SR1 投 300 票,为 SR2 投 200 票。
重要提示:Stake 1.0 与 Stake 2.0 的关键区别
尽管当前网络主流为 Stake 2.0,但通过 Stake 1.0 质押的 TRX 依然有效,并可通过其对应的
wallet/unfreezebalance
接口赎回。
注意:如果解质押 Stake 1.0 质押的 TRX,会撤销账户所有的投票。
如何取消全部解质押¶
如果您发起了 TRX 解质押但中途改变了主意,Stake 2.0 提供了一个高效的“撤销”功能。您可以使用 cancelallunfreezev2
API 立即取消所有正在进行中的解质押,从而避免了漫长的 14 天锁定期,并可立刻获取资源。
请注意,调用此接口后,您账户中所有处于 14 天锁定期内、尚未完成的解质押请求都将被一次性全部撤销。
- TRX 状态:这些被撤销的 TRX 将立即被重新质押。
- 资源类型:重新质押后获取的资源类型(能量或带宽)将与您最初质押时选择的类型保持一致。
附加效果:自动提取已到期 TRX
如果您的账户中存在任何已经完成 14 天锁定期、正等待提取的解质押 TRX,本次操作会将这部分资金自动提取到您的账户余额中。
如何验证操作结果
您可以通过 gettransactioninfobyid
接口查询该笔交易的详情,并重点关注以下两个字段:
cancel_unfreezeV2_amount
: 该字段显示了本次操作中,被成功取消并重新用于质押的 TRX 总额。withdraw_expire_amount
: 该字段显示了本次操作中,被自动提取到您账户余额中的、已到期的解质押 TRX 总额。
API¶
下表为质押模型相关接口及其说明:
API | 描述 |
---|---|
wallet/freezebalancev2 |
质押 |
wallet/unfreezebalancev2 |
解质押 |
wallet/delegateresource |
资源代理 |
wallet/undelegateresource |
取消资源代理 |
wallet/withdrawexpireunfreeze |
提取已过锁定期的解质押 TRX |
wallet/getavailableunfreezecount |
查看剩余解质押次数 |
wallet/getcanwithdrawunfreezeamount |
查看可提取的已过锁定期的解质押 TRX |
wallet/getcandelegatedmaxsize |
查看可代理的资源份额数量 |
wallet/getdelegatedresourcev2 |
查看某地址代理给目标地址的资源情况 |
wallet/getdelegatedresourceaccountindexv2 |
查看某地址资源代理情况与资源被代理情况 |
wallet/getaccount |
查看账户质押情况、资源份额、解质押情况、投票情况 |
wallet/getaccountresource |
查看资源总量、已使用量、可用数量 |
wallet/cancelallunfreezev2 |
取消全部解质押 |