资源模型¶

资源模型介绍¶

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 带宽。

注意：由于网络中总质押资金以及账户的质押资金随时可能发生变化，因此账户拥有的带宽不是固定值。

获取带宽¶

带宽可通过以下三种方式获取：

通过质押 TRX 获取：用户根据其为获取带宽而质押的 TRX 数量，按比例分享一个全网固定的总带宽池。
```
额度 = (为获取带宽质押的 TRX / 整个网络为获取带宽质押的 TRX 总额) * (Bandwidth 总量) 
```
Bandwidth 总量是一个可通过委员会提案修改的网络参数（#62），目前的值是 43,200,000,000。质押获取带宽操作 (wallet-cli 示例)
```
freezeBalanceV2 frozen_balance [ResourceCode:0 BANDWIDTH,1 ENERGY] 
```
通过他人代理获取：另一个帐户可以将其带宽委托给您。

代理获取带宽操作 (wallet-cli 示例)
```
delegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY),   ReceiverAddress [lock]
```
- 获取每日固定免费额度：每个账户每日可获得的固定免费带宽量。该额度是一个可通过委员会提案修改的网络参数（#61），当前值为 600。

带宽的消耗规则详解¶

除了查询操作，任何交易都需要消耗带宽。当您发起一笔交易时，系统会根据交易类型的不同，遵循一套严格的优先级顺序来扣除带宽费用。

场景一：普通交易

系统将按以下顺序尝试支付带宽费用：

消耗质押带宽：优先消耗发起者通过质押 TRX 获得的带宽。
消耗免费带宽：其次消耗交易发起者的 600 每日免费带宽。
燃烧 TRX 支付：若以上两者均不足，则会燃烧交易发起者的 TRX 来支付。
- 燃烧费用 = 交易字节数 × 1,000 sun

场景二：创建新账户的交易

创建新账户的交易在支付带宽时有其特殊规则，不使用每日免费带宽：

消耗质押带宽：优先尝试消耗交易发起者通过质押 TRX 获得的带宽。
燃烧 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

带宽的自动恢复¶

账户的免费带宽和质押 TRX 获取的带宽消耗后，会在 24 小时内逐步恢复。

账户带宽余额查询¶

您可以通过调用 wallet/getaccountresource HTTP 接口来获取一个账户当前的资源状态。在返回的 JSON 数据中，您可以使用以下公式来精确计算两种带宽的剩余额度。

免费带宽余额 = freeNetLimit - freeNetUsed
通过质押获取的带宽余额 = NetLimit - NetUsed

注：如果接口返回的结果中没有包含上述公式中的参数，表示该参数值为 0。

能量¶

能量 (Energy) 是在 TRON 虚拟机（TVM）中执行智能合约指令时所需消耗的计算资源的计量单位。本章将从以下三个方面全面介绍能量这一核心资源：

能量的获取、消耗与恢复
如何设置关键参数 fee_limit
TRON 网络的整体消耗机制

能量的获取与消耗¶

获取能量有两种方式，一种是通过质押 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 总额) * 能量总量

能量总量是一个由委员会设定的网络参数 (#19)，当前值为 180,000,000,000，可通过 TIP 修改。

计算示例

由于您的额度与全网总质押量挂钩，当其他用户质押或解押时，您的能量额度会随之变化。

如全网只有两个人 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 小时内逐步恢复。

如何填写 `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；相同合约每次消耗的能量基本相同¹，但由于动态能量模型机制，对于热门合约，不同时刻执行时可能需要的能量不同，具体请参考动态能量模型章节；执行合约时，逐条指令计算并扣除 Energy，如果超过 fee_limit 的限制，则合约执行失败，已扣除的能量不退还。
当前 fee_limit 是指调用者在执行合约时愿意支付的 TRX 上限²。需要注意的是，合约执行消耗的总能量，除了调用者支付的部分，也可能包含开发者为其承担的部分。
一个恶意合约，如果最终执行超时，或者因 bug 合约崩溃，则会扣除当前交易允许消耗的所有 Energy。这个总能量池由以下几部分相加构成：总消耗能量 = 调用者质押所得能量 + 开发者分摊能量 + 燃烧 TRX 所得能量。其中，“燃烧 TRX 所得能量”的上限由 fee_limit 决定。
开发者可以通过能量分摊机制承担一定比例的能量消耗（比如 90%）。但是，当开发者账户的 Energy 不足以支付时，剩余部分完全由调用者承担。在 fee_limit 限制范围内，如调用者的 Energy 不足，则会燃烧等价值的 TRX。²

示例: 下面将以一个合约 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。

TRON 网络能量消耗机制¶

基本能量消耗规则¶

在执行合约交易时，系统会逐条指令计算并扣除所需能量，账户能量的使用遵循以下优先级原则：

优先使用账户可用能量（通过质押或租赁获得）
若能量不足，不足的能量，按固定费率（0.0001 TRX / 能量）燃烧账户内的 TRX

合约能量分摊机制¶

对于合约调用，为降低调用者的成本，TRON支持合约部署者分担部分能量消耗，具体细节请参考合约能量分摊机制章节。

能量扣除规则：

合约部署者承担部分：
- 直接从部署者账户的可用能量中扣除，不会燃烧部署者的TRX
合约调用者承担部分：
- 优先使用账户中的可用能量
- 不足部分，按固定费率燃烧账户余额中的 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,000
increase_factor：0.2
max_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。

系统处理流程：
1. 回收需求：系统需要从 A 的账户中回收 1,500 TP。
2. 回收空闲 TP：首先回收全部 1,000 点空闲 TP。
3. 计算差额：仍需回收 1,500 - 1,000 = 500 TP。这部分必须通过撤销选票来获取。
4. 按比例撤票：
5. 从 SR1 撤销的票数 = 500 * (600 / 1000) = 300 票
6. 从 SR2 撤销的票数 = 500 * (400 / 1000) = 200 票
7. 最终结果：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	描述
`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`	取消全部解质押