Skip to content

资源模型

资源模型介绍

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 数量,按比例分享一个全网固定的总带宽池。
    额度 = (为获取带宽质押的 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。

2. 带宽的消耗规则详解

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

场景一:普通交易

系统将按以下顺序尝试支付带宽费用: 1. 消耗质押带宽:优先消耗发起者通过质押 TRX 获得的带宽。 2. 消耗免费带宽:其次消耗交易发起者的 600 每日免费带宽。 *3. 燃烧 TRX 支付:若以上两者均不足,则会燃烧交易发起者的 TRX 来支付。 * 燃烧费用 = 交易字节数 × 1,000 sun

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

创建新账户的交易在支付带宽时有其特殊规则,不使用每日免费带宽: 1. 消耗质押带宽:优先尝试消耗交易发起者通过质押 TRX 获得的带宽。 2. 燃烧 TRX 支付:若质押带宽不足,则直接燃烧 0.1 TRX 作为费用来完成账户创建。

场景三:TRC-10 通证转账

TRC-10 通证(Token)转账的消耗逻辑最为特殊,它引入了“通证发行方”作为潜在的费用承担者:

  1. 消耗发行方带宽 (优先):系统首先会尝试消耗由通证发行方为该通证预付的带宽。这需要同时满足三个条件(只有当这三项检查全部通过时,才会扣除发行方的带宽。否则,进入下一步,由转账发起者自己支付):
    • 通证发行方剩余额度充足
      • 查询方式:/wallet/getassetissuebyaccount
      • 计算公式: public_free_asset_net_limit - public_free_asset_net_usage
      • 含义:通证发行方能为该通证转账支付的剩余额度
    • 转账发起者的个人额度充足
      • 查询方式:/wallet/getaccountnet
      • 计算公式: assetNetLimit['assetID'] - assetNetUsed['assetID']
      • 含义:该通证持有者还能使用的由发行方提供的免费带宽额度
    • 通证发行方通过质押获取的带宽充足
      • 查询方式:/wallet/getaccountnet
      • 计算公式: NetLimit - NetUsed
      • 含义:发行方通过质押获取的可用带宽数额
  2. 消耗发起者质押带宽:尝试消耗交易发起者通过质押 TRX 获得的带宽。 若质押带宽不足,则进入下一步。
  3. 消耗发起者免费带宽:如果免费带宽也不足,则进入下一步。
  4. 燃烧 TRX 支付:若以上所有带宽资源均不足,则会燃烧发起者的 TRX 来支付费用。
  5. 燃烧费用 = 交易字节数 × 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 总额) * 能量总量
能量总量是一个由委员会设定的网络参数(#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 小时内逐步恢复。

2. 如何填写 fee_limit (用户必读)

在本节范围内,将合约的开发部署人员,简称为“开发者”;将调用合约的用户或者其他合约,简称为“调用者”。

调用合约消耗的能量能以一定比例折合成 TRX(或者 sun),所以在本节范围内,指代合约消耗的资源时,并不严格区分 Energy 和 TRX;仅在作为数值的单位时,才区分 Energy、TRX 和 sun。

fee_limit 是调用智能合约时一个至关重要的安全参数。合理设置 fee_limit,一方面能尽量保证正常执行;另外一方面,如果合约所需能量过多,又不会过多消耗调用者的 TRX。

在设置 fee_limit 之前,需要了解几个概念:

  1. 合法的 fee_limit 为 0 - 15,000,000,000 sun(折合 0 - 15,000 TRX)之间的整数。fee_limit 上限是一个可通过委员会提案修改的网络参数(#47),目前的值是 15,000 TRX。
  2. 不同复杂度的合约,每次正常执行消耗不同的 Energy;相同合约每次消耗的能量基本相同1,但由于动态能量模型机制,对于热门合约,不同时刻执行时可能需要的能量不同,具体请参考 动态能量模型 章节;执行合约时,逐条指令计算并扣除 Energy,如果超过 fee_limit 的限制,则合约执行失败,已扣除的能量不退还。
  3. 当前 fee_limit 是指调用者在执行合约时愿意支付的 TRX 上限2。需要注意的是,合约执行消耗的总能量,除了调用者支付的部分,也可能包含开发者为其承担的部分。
  4. 一个恶意合约,如果最终执行超时,或者因 bug 合约崩溃,则会扣除当前交易允许消耗的所有 Energy。这个总能量池由以下几部分相加构成:总消耗能量 = 调用者质押所得能量 + 开发者分摊能量 + 燃烧 TRX 所得能量。其中,“燃烧 TRX 所得能量”的上限由 fee_limit 决定。
  5. 开发者可以通过 能量分摊机制 承担一定比例的能量消耗(比如 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 网络能量消耗机制

基本能量消耗规则

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

  1. 优先使用账户可用能量(通过质押或租赁获得)
  2. 若能量不足,不足的能量,按固定费率(0.0001 TRX / 能量)燃烧账户内的 TRX

合约能量分摊机制

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

能量扣除规则:

合约部署者承担部分: * 直接从部署者账户的可用能量中扣除,不会燃烧部署者的TRX

合约调用者承担部分: 1. 优先使用账户中的可用能量 2. 不足部分,按固定费率燃烧账户余额中的 TRX

动态能量模型

动态能量模型是波场网络的一个资源平衡机制,可以根据合约的资源占用情况动态调整每个合约的能量消耗量,从而使能量资源在链上的分配更加合理,防止网络资源过度集中在少数热门合约上,详情请参考 动态能量模型介绍

工作原理

如果合约在一个维护周期(目前是 6 小时)内使用过多的能量,则在下一个维护周期内,用户向该合约发送相同的交易将产生更多的额外能量消量。当合约合理使用资源时,用户调用该合约所产生的能量消耗将逐渐恢复正常。

每一个合约有一个能量消耗放大系数 energy_factor,表示该智能合约交易的能量消耗相对于基础能量消耗的增加倍数,初始值是 0

  • 合约的 energy_factor0 时,表示该合约在合理的使用资源,调用该合约不会有额外的能量消耗。
  • 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_factorincrease_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 时,遵循以下两步流程:

  1. 优先回收空闲 TP: 系统首先会回收您账户中所有未使用于投票的、空闲的投票权。
  2. 按需撤销已投选票: 如果空闲 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

下表为质押模型相关接口及其说明:

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 取消全部解质押

  1. 若开发者不确定合约是否正常,请勿将用户承担比例设置为 0%,否则在被判为恶意执行时,会扣除开发者的所有 Energy。 

  2. 因此建议开发者设置的用户承担的比例为 10%~100%。