diff --git a/developers/governance/index.html b/developers/governance/index.html index 4aed5e3..63a3978 100644 --- a/developers/governance/index.html +++ b/developers/governance/index.html @@ -191,7 +191,7 @@

发起提议投票的讨论标题

我们希望TRON生态所有用户都能参与到网络治理中，为了能够在社区进行更好的宣传，建议您为提议投票进行命名，并将名称写在标题的最前面，下面是一个示例： -

Palma Upgrade：proposal to change the unit price of energy to 420 sun
+
Palma Upgrade：proposal to change the unit price of energy to 210 sun
 

 
主体内容

 
讨论中应详细介绍该提议的内容，包括动机、预估的发起提案的时间及生效时间、如何发起提议投票、该提案的技术规范或背景信息等：

diff --git a/index.html b/index.html
index 8c87ef6..a059d1f 100644
--- a/index.html
+++ b/index.html
@@ -224,5 +224,5 @@ 
欢迎访问Java-tron用户手册!
diff --git a/mechanism-algorithm/resource/index.html b/mechanism-algorithm/resource/index.html
index 5f62a11..47f08ea 100644
--- a/mechanism-algorithm/resource/index.html
+++ b/mechanism-algorithm/resource/index.html
@@ -96,16 +96,22 @@
     
  • 3. Bandwidth Points的计算规则
     
    • 
     
  • 4. 带宽的自动恢复
+    
    • 
+    
  • 5. 账户带宽余额查询
     
    • 
         
     
     
  • 能量
         
     
    • 
+    
  • 动态能量模型
+        
+    
    • 
     
  • 在TRON网络上质押
         
     
    • 
-    
  • 其他交易费
-    
    • 
     
                   
                   
  • 智能合约
@@ -228,7 +240,7 @@ 
    投票权&pa
 
    选民可以分批多次质押，多次质押获取到的投票权会被累加到选民账户内，选民可以通过wallet/getaccountresource接口查询账户拥有的投票权总数以及已使用的投票权数量。
    
 
    带宽
    
 
    交易以字节数组的形式在网络中传输及存储，一条交易消耗的 Bandwidth Points = 交易字节数 * Bandwidth Points费率。当前 Bandwidth Points费率 = 1.
    
-
    如一条交易的字节数组长度为200，那么该交易需要消耗 200 Bandwidth Points。
    
+
    如一条交易的字节数为200，那么该交易需要消耗 200 Bandwidth Points。
    
 
    
 
    Note
    
 
    由于网络中总质押资金以及账户的质押资金随时可能发生变化，因此账户拥有的 Bandwidth Points 不是固定值。
    
@@ -236,15 +248,14 @@ 
    带宽
    1. Bandwidth Points的来源
    
 
    Bandwidth Points的获取分两种：
    
 
      
-
    • 通过质押TRX获取的Bandwidth Points， 额度 = 为获取Bandwidth Points质押的TRX / 整个网络为获取Bandwidth Points质押的TRX 总额 * 43_200_000_000. 也就是所有用户按质押TRX平分固定额度的Bandwidth Points.
      • 
+
    • 通过质押TRX获取的Bandwidth Points， 额度 = 为获取Bandwidth Points质押的TRX / 整个网络为获取Bandwidth Points质押的TRX 总额 * 43_200_000_000，也就是所有用户按质押的TRX数量平分固定额度的Bandwidth Points.
      • 
 
    • 每个账号每天有固定免费额度的带宽，为600。
      • 
 
    
 
    2. Bandwith Points的消耗
    
 
    除了查询操作，任何交易都需要消耗 bandwidth points。
    
-
    有一种特殊情况需要注意，如果是转账，包括普通转账或 TRC10 Token 转账，如果目标账户不存在，转账操作则会创建账户并转账，只会扣除创建账户消耗的Bandwidth Points，转账不会再消耗额外的Bandwidth Points.
    
 
    3. Bandwidth Points的计算规则
    
 
    Bandwidth Points是一个账户1天内能够使用的总字节数。一定时间内，整个网络能够处理的Bandwidth为确定值。
    
-
    如果交易需要创建新账户，Bandwidth Points消耗如下：
    
+
    如果交易需要创建新账户(如创建新账户交易，向未激活的账户转账TRX或者TRC10代币)，Bandwidth Points消耗如下：
    
 
      
 
    1. 尝试消耗交易发起者质押获取的Bandwidth Points。如果交易发起者Bandwidth Points不足，则进入下一步
      2. 
 
    2. 尝试消耗交易发起者的TRX，这部分烧掉0.1TRX
      3. 
@@ -264,36 +275,54 @@ 
      3. Bandwidth Points的计算规则4. 带宽的自动恢复
      
 
      账户的免费带宽和质押TRX获取的带宽消耗后， 会在24小时内逐步恢复。
      
+
      5. 账户带宽余额查询
      
+
      首先调用节点HTTP接口wallet/getaccountresource来获取账户当前的资源状态，然后通过如下公式计算带宽余额：
      
+
      免费带宽余额 = freeNetLimit - freeNetUsed
+通过质押获取的带宽余额 = NetLimit - NetUsed
+
      
+
      注：如果接口返回的结果中没有包含上述公式中的参数，表示该参数值为0。
      
 
      能量
      
 
      智能合约运行时执行每一条指令都需要消耗一定的系统资源，资源的多少用Energy的值来衡量。
      
-
      1. Energy的获取
      
+
      1. Energy的获取与消耗
      
 
      质押获取Energy，即将持有的trx锁定，无法进行交易，作为抵押，并以此获得免费使用Energy的权利。具体计算与全网所有账户质押有关，可参考相关部分计算。
      
 
      质押获得能量
      
 
      freezeBalanceV2 frozen_balance [ResourceCode:0 BANDWIDTH,1 ENERGY]
 
      
-
      通过质押TRX获取的Energy， 额度 = 为获取Energy质押的TRX / 整个网络为获取Energy质押的TRX 总额 * 90_000_000_000。
-也就是所有用户按质押TRX平分固定额度的Energy。
      
-
      示例：
      
+
      通过质押TRX获取的Energy 额度 = 为获取Energy质押的TRX / 整个网络为获取Energy质押的TRX 总额 * 150_000_000_000。
      
+
      也就是所有用户按质押的TRX数量平分固定额度的Energy，示例：
      
 
      如全网只有两个人A，B分别质押2TRX，2TRX。
 
 二人质押获得的可用Energy分别是
 
-A: 25_000_000_000 且energy_limit 为25_000_000_000
+A: 75_000_000_000 且energy_limit 为75_000_000_000
 
-B: 25_000_000_000 且energy_limit 为25_000_000_000
+B: 75_000_000_000 且energy_limit 为75_000_000_000
 
 当第三人C质押1TRX时。
 
 三人质押获得的可用Energy调整为
 
-A: 20_000_000_000 且energy_limit调整为20_000_000_000
+A: 60_000_000_000 且energy_limit调整为60_000_000_000
 
-B: 20_000_000_000 且energy_limit调整为20_000_000_000
+B: 60_000_000_000 且energy_limit调整为60_000_000_000
 
-B: 10_000_000_000 且energy_limit 为10_000_000_000
+B: 30_000_000_000 且energy_limit 为30_000_000_000
 
      
-
      能量的恢复
      
+
      能量的消耗
      
+
      在执行合约时，逐条指令计算并扣除账户能量，账户能量消耗的优先级如下：
      
+
        
+
      • 质押TRX获取的能量
        • 
+
      • 燃烧TRX
        • 
+
      
+
      首先会消耗交易发起者质押TRX获取的能量，如果消耗完这部分能量后还不够，会继续燃烧账户的TRX来支付交易所需的能量资源，按照每一个能量0.00021TRX的单价来支付。
      
+
      如果合约中途由于抛出revert异常而退出，则仅扣除已经执行的指令所对应的能量，但是对于异常合约，比如合约执行超时，或因bug异常退出，会扣除本次交易最大可用的能量，用户可以通过设置交易的fee_limit参数来限定这笔交易最多可以消耗的能量费用上限。
      
+
      能量的恢复
      
 
      账户的能量资源消耗后，会在24小时内逐步恢复。
      
+
      账户能量余额查询
      
+
      首先调用节点HTTP接口wallet/getaccountresource来获取账户当前的资源状态，然后通过如下公式计算能量余额：
      
+
      能量余额 = EnergyLimit - EnergyUsed
+
      
+
      注：如果接口返回的结果中没有包含上述公式中的参数，表示该参数值为0。
      
 
      2. 如何填写 feeLimit(用户必读)
      
 
      
 
      在本节范围内，将合约的开发部署人员，简称为“开发者”；将调用合约的用户或者其他合约，简称为“调用者”。
      
@@ -301,8 +330,8 @@ 
      2. 如何填写 feeLimit(用户必读)
 
      合理设置feeLimit，一方面能尽量保证正常执行；另外一方面，如果合约所需Energy过大，又不会过多消耗调用者的trx。在设置feeLimit之前，需要了解几个概念：
      
 
        
-
      1. 合法的feeLimit为0 - 10^9 之间的整数值，单位是sun，折合0 - 1000 trx；
        2. 
-
      2. 不同复杂度的合约，每次正常执行消耗不同的Energy；相同合约每次消耗的Energy基本相同[^1]；执行合约时，逐条指令计算并扣除Energy，如果超过feeLimit的限制，则合约执行失败，已扣除的Energy不退还；
        3. 
+
      3. 合法的feeLimit为0 - 15*10^9 之间的整数值，单位是sun，折合0 - 15000 trx；
        4. 
+
      4. 不同复杂度的合约，每次正常执行消耗不同的Energy；相同合约每次消耗的Energy基本相同[^1]，但由于动态能量模型机制，对于热门合约，不同时刻执行时可能需要的能量不同，具体请参考动态能量模型章节；执行合约时，逐条指令计算并扣除Energy，如果超过feeLimit的限制，则合约执行失败，已扣除的Energy不退还；
        5. 
 
      5. 目前feeLimit仅指调用者愿意承担的Energy折合的trx[^2]；执行合约允许的最大Energy还包括开发者承担的部分；
        6. 
 
      6. 一个恶意合约，如果最终执行超时，或者因bug合约崩溃，则会扣除该合约允许的所有energy；
        7. 
 
      7. 开发者可能会承担一定比例的Energy消耗（比如承担90%）。但是，当开发者账户的Energy不足以支付时，剩余部分完全由调用者承担。在feeLimit限制范围内，如调用者的Energy不足，则会燃烧等价值的trx。[^2]
        8. 
@@ -311,23 +340,20 @@ 
        2. 如何填写 feeLimit(用户必读)示例
 下面将以一个合约C的执行，来具体举例，如何估算feeLimit：
        
 
          
-
        • 假设合约C上一次成功执行时，消耗了18000 Energy，那么预估本次执行消耗的Energy上限为20000 Energy；[^3]
          • 
-
        • 质押trx时，当前全网用于CPU质押的TRX总量和Energy总量的比值，假设是质押1 trx，可以获得400 Energy；
          • 
-
        • 燃烧trx时，4 trx固定可以兑换100000 Energy；[^4]
          • 
+
        • 假设合约C上一次成功执行时，消耗了18000 Energy，那么预估本次执行消耗的Energy上限为20000 Energy；
          • 
+
        • 燃烧trx时，由于能量单价目前为210sun，所以 21 trx固定可以兑换100000 Energy；
          • 
 
        • 假设开发者承诺承担90%的Energy，而且开发者账户有充足的Energy；
          • 
 
        
 
        则，feeLimit的预估方法为：
        
 
          
-
        1. A = 20000 energy * (1 trx / 400 energy) = 50 trx = 50_000_000 sun,
          2. 
-
        2. B = 20000 energy * (4 trx / 10000 energy) = 0.8 trx = 800_000 sun，
          3. 
-
        3. 取A和B的最大值，为50_000_000 sun，
          4. 
+
        4. A = 20000 energy * 210sun = 4_200_000 sun  = 4.2 trx,
          5. 
 
        5. 开发者承诺承担90%，用户需要承担10%，
          6. 
 
        
-
        那么，建议用户填写的feeLimit为 50_000_000 sun * 10% = 5_000_000 sun。
        
+
        那么，建议用户填写的feeLimit为 4_200_000 sun * 10% = 420_000 sun。
        
 
        3. Energy的计算(开发者必读)
        
 
        在讨论本章节前，需要了解：
        
 
          
-
        1. tron为了惩罚恶意开发者，对于异常合约，如果执行超时（超过50ms），或因bug异常退出（不包含revert），会扣除本次的最大可用Energy。若合约正常执行，或revert，则仅扣除执行相关指令所需的Energy；
          2. 
+
        2. tron为了惩罚恶意开发者，对于异常合约，如果执行超时（超过80ms），或因bug异常退出（不包含revert），会扣除本次的最大可用Energy。若合约正常执行，或revert，则仅扣除执行相关指令所需的Energy；
          3. 
 
        3. 开发者可以设置执行合约时，消耗Energy中自己承担的比例，该比例后续可修改。一次合约调用消耗的Energy，若开发者的Energy不足以支付其承担的部分，剩余部分全由调用者支付；
          4. 
 
        4. 目前执行一个合约，可用的Energy总数由 调用者调用时设置的feeLimit 和 开发者承担部分共同决定；
          5. 
 
        
@@ -347,14 +373,14 @@ 
        3. Energy的计算(开发者必读)
 
      8. 
 
        A质押剩余的Energy
        
-
        这部分的价格是根据账户A当前质押的TRX和当前质押所获得的Energy总量按比例计算出来的，也就是：1 Energy = (10 / 100000) TRX，还剩100000 Energy，价值10 TRX，小于feeLimit，则能获得所有的100000 Energy，价值的10 TRX算进feeLimit中。
        
+
        这部分是根据账户A当前质押的TRX和当前质押所获得的Energy总量按比例计算出来的，也就是：1 Energy = (10 / 100000) TRX，还剩100000 Energy，价值10 TRX，小于feeLimit，则在本次调用中，可以使用所有的100000 Energy，价值的10 TRX。
        
 
        9. 
 
      9. 
-
        按照固定比例换算出来的Energy
        
-
        如果feeLimit大于质押剩余Energy价值的TRX，那么需要使用balance中的TRX来换算。固定比例是： 1 Energy = 100 SUN, feeLimit还有(30 - 10) TRX = 20 TRX，获得的Energy是 20 TRX / 100 SUN = 200000 Energy
        
+
        按照能量单价换算出来的Energy
        
+
        如果feeLimit大于质押剩余Energy价值的TRX，那么需要使用balance中的TRX来换算。能量单价是： 1 Energy = 210 sun, feeLimit还有(30 - 10) TRX = 20 TRX，则这部分可用的Energy是 20 TRX / 210 sun = 95238 Energy
        
 
        10. 
 
-
        所以，A此次调用能够使用的Energy是 (100000 + 200000) = 300000 Energy
        
+
        所以，A此次调用能够使用的Energy是 (100000 + 95238) = 195238 Energy
        
 
        如果合约执行成功，没有发生任何异常，则会扣除合约运行实际消耗的Energy，一般都远远小于此次调用能够使用的Energy。如果发生了Assert-style异常，则会消耗feeLimit对应的所有的Energy。
        
 
        Assert-style异常的介绍详见异常介绍
        
 
        示例2
@@ -366,11 +392,11 @@ 
        3. Energy的计算(开发者必读)
 
      10. 
 
        调用者A质押剩余的Energy（X Energy）
        
-
        这部分的价格是根据账户A当前质押的TRX和当前质押所获得的Energy总量按比例计算出来的，也就是：1 Energy = (10 / 100000) TRX，还剩100000 Energy，价值10 TRX，小于剩下的feeLimit，则能获得所有的100000 Energy，价值的10 TRX算进feeLimit中。
        
+
        这部分是根据账户A当前质押的TRX和当前质押所获得的Energy总量按比例计算出来的，也就是：1 Energy = (10 / 100000) TRX，还剩100000 Energy，价值10 TRX，小于剩下的feeLimit，则在本次调用中，可以使用所有的100000 Energy，价值的10 TRX。
        
 
        11. 
 
      11. 
 
        从调用者A的balance中，按照固定比例换算出来的Energy （Y Energy）
        
-
        如果feeLimit大于1和2的和，那么需要使用A的balance中的TRX来换算。固定比例是： 1 Energy = 100 SUN, feeLimit还有(200 - 10)TRX = 190 TRX，但是A的balance只有90 TRX，按照min(190 TRX, 90 TRX) = 90 TRX来计算获得的Energy，即为 90 TRX / 100 SUN = 900000 Energy
        
+
        如果feeLimit大于质押剩余Energy价值的TRX，那么需要使用A的balance中的TRX来换算。能量单价是： 1 Energy = 210 sun, feeLimit还有(200 - 10) TRX = 190 TRX，但是A的balance只有90 TRX，按90TRX来计算可用的energy为 90 TRX / 210 SUN = 428571 Energy。
        
 
        12. 
 
      12. 
 
        开发者D质押剩余的Energy (Z Energy)
        
@@ -384,19 +410,47 @@ 
        3. Energy的计算(开发者必读)
 
        若A此次调用能够使用的Energy是 Q Energy
        
 
        同上，如果合约执行成功，没有发生任何异常，消耗总Energy小于Q Energy，如消耗 500000 Energy ，会按照比例扣除合约运行实际消耗的Energy，调用者A消耗 500000 * 40\% =200000 Energy，开发者D消耗 500000 * 60\% = 300000 Energy。
        
-
        一般实际消耗Energy都远远小于此次调用能够使用的Energy。如果发生了Assert-style异常，则会消耗feeLimit对应的所有的Energy。
        
-
        Assert-style异常的介绍详见异常介绍
        
+
        一般实际消耗Energy都远远小于此次调用能够使用的Energy。如果发生了Assert-style异常，则会消耗feeLimit对应的所有的Energy。Assert-style异常的介绍详见异常介绍
        
 
        注意：
 开发者创建合约的时候，consume_user_resource_percent不要设置成0，也就是开发者自己承担所有资源消耗。
-开发者自己承担所有资源消耗，意味着当发生了Assert-style异常时，会消耗开发者质押的所有Energy。
-Assert-style异常的介绍详见异常介绍
        
-
        为避免造成不必要的损失consume_user_resource_percent建议值是10-100。
        
+开发者自己承担所有资源消耗，意味着当发生了Assert-style异常时，会消耗开发者质押的所有Energy。为避免造成不必要的损失consume_user_resource_percent建议值是10-100。
        
+
        动态能量模型
        
+
        动态能量模型是波场网络的一个资源平衡机制，可以根据合约的资源占用情况动态调整每个合约的能量消耗量，从而使能量资源在链上的分配更加合理，防止网络资源过度集中在少数热门合约上，详情请参考动态能量模型介绍。
        
+
        工作原理
        
+
        如果合约在一个维护周期(目前是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减少一定比例。
          • 
+
        
+
        当合约的基础能量消耗量在一个维护周期内超过了threshold，那么在下一个维护周期它的energy_factor将增加，但最大不会超过max_factor，计算公式为：
        
+
        energy_factor = min((1 + energy_factor) * (1 + increaese_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
          • 
+
        
+
        由于热门合约在不同的维护周期的能量消耗是不一样的，所以在调用合约时要为交易设置合适的feelimit参数。
        
 
        在TRON网络上质押
        
-
        如何质押获取系统资源
        
-
        能量和带宽资源由帐户所有者通过质押来获取，请使用wallet/freezebalancev2HTTP API完成质押操作、或者使用Stake2.0 Solidity API通过合约完成质押操作。
        
+
        如何质押获取系统资源
        
+
        能量和带宽资源由帐户所有者通过质押来获取，请使用wallet/freezebalancev2HTTP API完成质押操作、或者使用Stake2.0 Solidity API通过合约完成质押操作。
        
 
        TRON通过质押机制分配网络资源。质押TRX除了可以获取带宽或者能量资源外，还将同时获得与质押量等量的投票权（TRON Power，简称TP），质押1TRX，获得1TP。质押获取到的带宽或者能量资源用于支付交易费用，获取到的投票权用于给超级代表投票以获取投票奖励。
        
 
        解质押操作会释放对应的资源。
        
-
        如何代理资源
        
+
        如何代理资源
        
 
        账户在通过质押获取到能量或者带宽资源后，可以通过代理操作delegateresource将资源代理给其它地址，也可以通过取消代理操作undelegateresource收回分配出去的资源，代理资源需要注意以下情况：