From 54ea77886f2c9092a620e0d1806c30d0737a5d5c Mon Sep 17 00:00:00 2001 From: yingying Date: Mon, 29 Dec 2025 17:22:42 +0800 Subject: [PATCH 1/3] Add doc of resource reclamation upon undelegation --- docs/mechanism-algorithm/resource.md | 63 ++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/mechanism-algorithm/resource.md b/docs/mechanism-algorithm/resource.md index 011dbce9..016b4fe2 100644 --- a/docs/mechanism-algorithm/resource.md +++ b/docs/mechanism-algorithm/resource.md @@ -416,6 +416,69 @@ _**选票撤销的计算规则**_ * `withdraw_expire_amount`: 该字段显示了本次操作中，被自动提取到您账户余额中的、已到期的解质押 TRX 总额。 + +### 取消资源代理时的资源回收 + +**说明**：由于在 TRON 网络中，账户获得的资源数量取决于其 TRX 质押量 在全网总质押量中的占比。当代理方将资源代理给被代理方时，本质上是将其自身质押的一定数量的 TRX 份额借给被代理方。在计算资源配额时，系统对 TRX 的来源不作区分。账户**自持质押**与**接收代理**的 TRX 将被合并统计，统一作为获取资源的权重基数。因此，本章节所称“质押数额”除另有说明外，均指该账户的质押总额（含自身质押及他人代理），不再对其来源进行区分。 + +当代理方发起资源代理时，会将一定数量的 TRX 质押份额借给被代理方，使其获得相应资源的使用权；当代理方执行取消资源代理操作时，系统不仅收回对应的 TRX 质押份额，同时会按比例回收被代理方账户中的未恢复资源。 + +#### 未恢复资源的回收逻辑 + +##### 1. 计算公式 + +系统会根据取消代理的 TRX 数额，按比例回收被代理方账户中尚未恢复的资源。计算公式： + +``` +回收的未恢复资源数量 = (取消代理的 TRX 数额 / 被代理方该资源的总质押数额) * 被代理方的未恢复资源量 +``` +**注意**：回收的未恢复资源数量，不得超过本次取消代理的 TRX 数量按当前全网实时质押量计算出的最大资源容量。 + +* **取消代理的 TRX 数额**：在取消资源代理交易中，回收的 TRX 质押额度。 +* **被代理方该资源的总质押数额**：指被代理方持有的某项资源（能量或带宽）的质押总量（Stake 1.0 和 Stake 2.0 自身质押以及他人代理总和）。可通过 [wallet/getaccount](https://developers.tron.network/reference/account-getaccount#/) 接口查询。 +* **被代理方的未恢复资源量**：指被代理方账户中当前已消耗且正在处于恢复周期内的资源数量。可通过 [wallet/getaccount](https://developers.tron.network/reference/account-getaccount#/) 或 [wallet/getaccountresource](https://developers.tron.network/reference/getaccountresource#/) 接口查询。 + +##### 2.账户状态变化 +取消代理完成后，双方账户状态变化如下： + +**代理方** + +``` +质押数额 = 原质押数额 + 取消代理的 TRX 数额 + +未恢复资源量 = 原未恢复资源量 + 回收的未恢复资源量 +``` + +**被代理方** + +``` +质押数额 = 原质押数额 - 取消代理的 TRX 数额 + +未恢复资源量 = 原未恢复资源量 - 回收的未恢复资源量 +``` + +**注意：** 资源被消耗后会在 24 小时内匀速线性地恢复。如果在恢复期间，账户再次使用资源或收回代理资源，系统会将原有的恢复进度与新的恢复周期进行加权合并。因此，账户资源重新回满所需的实际剩余时间通常会小于 24 小时。 + +#### 示例 +假设当前全网资源倍率为：1 TRX 质押量 = 0.2 Energy，并且全网的质押总量不变。用户 X 将其持有的 200 TRX 额度的能量代理给了用户 Y。在用户 X 取消代理操作前，两个账户的状态如下： + +| 账户 | 角色 | 总质押数额（为获取能量） | 能量总量 | 未恢复的能量数量 | +| -------- | -------- | -------- |-------- | -------- | +| X | 代理方 | 1000 TRX |200 Energy | 75 Energy | +| Y | 被代理方 | 500 TRX |100 Energy | 50 Energy | + +当用户 X 取消对 用户 Y 的 200 TRX 的能量代理时： + +``` +回收的未恢复能量数量 = 200 / 500 * 50 = 20 Energy +``` +回收后，各账户的状态： +| 账户 | 身份 | 总质押数额（为获取能量） | 能量总量| 未恢复的能量数量 | +| -------- | -------- | -------- | -------- | -------- | +| X | 代理方 | 1200 TRX（1000 + 200 ）| 240 Energy | 95 Energy（ 75 + 20 ） | +| Y | 被代理方 | 300 TRX（500 - 200） | 60 Energy | 30 Energy（ 50 -20 ） | + + ### 相关 API 接口 下表为质押模型相关接口及其说明： From 0b0641a9b743200276457e97489f17046828196b Mon Sep 17 00:00:00 2001 From: yingying Date: Mon, 29 Dec 2025 18:03:37 +0800 Subject: [PATCH 2/3] add a empty line --- docs/mechanism-algorithm/resource.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/mechanism-algorithm/resource.md b/docs/mechanism-algorithm/resource.md index 016b4fe2..dd970495 100644 --- a/docs/mechanism-algorithm/resource.md +++ b/docs/mechanism-algorithm/resource.md @@ -473,6 +473,7 @@ _**选票撤销的计算规则**_ 回收的未恢复能量数量 = 200 / 500 * 50 = 20 Energy ``` 回收后，各账户的状态： + | 账户 | 身份 | 总质押数额（为获取能量） | 能量总量| 未恢复的能量数量 | | -------- | -------- | -------- | -------- | -------- | | X | 代理方 | 1200 TRX（1000 + 200 ）| 240 Energy | 95 Energy（ 75 + 20 ） | From 4070a249d5814a12874bedf31e7697b45fe7540a Mon Sep 17 00:00:00 2001 From: yingying Date: Sun, 4 Jan 2026 15:26:14 +0800 Subject: [PATCH 3/3] update resource.md --- docs/mechanism-algorithm/resource.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/mechanism-algorithm/resource.md b/docs/mechanism-algorithm/resource.md index dd970495..212be59a 100644 --- a/docs/mechanism-algorithm/resource.md +++ b/docs/mechanism-algorithm/resource.md @@ -439,7 +439,9 @@ _**选票撤销的计算规则**_ * **被代理方的未恢复资源量**：指被代理方账户中当前已消耗且正在处于恢复周期内的资源数量。可通过 [wallet/getaccount](https://developers.tron.network/reference/account-getaccount#/) 或 [wallet/getaccountresource](https://developers.tron.network/reference/getaccountresource#/) 接口查询。 ##### 2.账户状态变化 -取消代理完成后，双方账户状态变化如下： + +取消资源代理完成后，双方账户在资源相关的有效状态上将发生如下变化。 +以下表达仅用于描述逻辑层面的变化关系，其中“质押数额”为计算概念，并不对应链上的某一具体字段。 **代理方** @@ -457,7 +459,7 @@ _**选票撤销的计算规则**_ 未恢复资源量 = 原未恢复资源量 - 回收的未恢复资源量 ``` -**注意：** 资源被消耗后会在 24 小时内匀速线性地恢复。如果在恢复期间，账户再次使用资源或收回代理资源，系统会将原有的恢复进度与新的恢复周期进行加权合并。因此，账户资源重新回满所需的实际剩余时间通常会小于 24 小时。 +**注意：** 资源被消耗后会在 24 小时内匀速线性地恢复。如果在恢复期间，账户再次使用资源或收回代理资源，系统会将原有的恢复进度与新的恢复周期进行加权合并。 #### 示例 假设当前全网资源倍率为：1 TRX 质押量 = 0.2 Energy，并且全网的质押总量不变。用户 X 将其持有的 200 TRX 额度的能量代理给了用户 Y。在用户 X 取消代理操作前，两个账户的状态如下： @@ -470,7 +472,7 @@ _**选票撤销的计算规则**_ 当用户 X 取消对 用户 Y 的 200 TRX 的能量代理时： ``` -回收的未恢复能量数量 = 200 / 500 * 50 = 20 Energy +回收的未恢复能量数量 = (200 / 500) * 50 = 20 Energy ``` 回收后，各账户的状态：