资源代理

📘

前置阅读

• Stake 2.0 概览

Stake 2.0 把质押和代理拆成两个独立操作：质押获得资源后，不解除质押也能把资源借给其他账户——TRX 仍记在原账户名下，带宽或能量则供对方使用。

可代理的资源类型

协议强制约束：

• 可代理额 = 已质押资源 − 近期已用 — 上限是质押获得的带宽 / 能量，减去 24 小时窗口内尚未恢复的消耗。近期用过资源，可代理额就低，待窗口恢复后回升。
• 最低 1 TRX（1,000,000 sun） — 单次代理的 TRX 等值不能低于 1 TRX；低于该值（1 ~ 999,999 sun）会校验失败并被拒绝，返回 "delegateBalance must be greater than or equal to 1 TRX"。
• 不可代理给自己 — receiver_address 必须与 owner_address 不同。
• 不可代理给合约地址 — 接收方不能是合约地址，否则校验失败并被拒绝，返回 "Do not allow delegate resources to contract addresses"。
• 只能代理带宽或能量 — TP 不能代理（见上）。
• 仅 Stake 2.0 — 代理是 Stake 2.0 的功能；Stake 1.0 下质押的 TRX 需先迁移到 Stake 2.0 才能代理。

查询某种资源当前可代理的数量，调用 wallet/getcandelegatedmaxsize。

如何代理

使用 wallet/delegateresource：

BASE_URL=https://api.trongrid.io   # 示例 — 可替换为任意 TRON 节点（TronGrid、第三方或自托管）
curl -X POST ${BASE_URL}/wallet/delegateresource \
  -d '{
    "owner_address": "TTGhREx2pDSxFX555NWz1YwGpiBVPvQA7e",
    "receiver_address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
    "balance": 100000000,
    "resource": "ENERGY",
    "lock": false,
    "visible": true
  }'

balance 填写的是资源对应的 TRX 等值（单位 sun），不是带宽 / 能量的实际数量。例如 balance: 100000000（相当于 100 TRX 质押额），接收方获得的能量等于 100 TRX 质押所对应的份额，具体随全网能量总供给浮动。

lock 与 lock_period 选项

代理时可以加锁，锁定期内这些资源必定归接收方使用。

lock = true 时必须指定 lock_period（锁定周期，以区块数为单位）。 TRON 每 3 秒产出一个区块，因此 锁定时长（秒）= 区块数 × 3。

例如锁定 24 小时：86,400 / 3 = 28,800 块。

lock_period 上限由链参数 #78 控制：默认 86,400 块（约 3 天），最高可调至 10,512,000 块（约 365 天）。主网当前为 864,000 块（约 30 天），实时值可通过 wallet/getchainparameters 查询。

📘

锁定期内的重新代理

同一组代理关系（所有者、接收方、资源类型均相同）下，锁定代理和未锁定代理是两条独立记录，互不影响。

向同一接收方、同一资源类型重新代理时，行为取决于新交易的 lock 标志：

• lock = true：新 lock_period 不能小于剩余锁定时间，否则校验失败。通过后，到期时间重置为 当前时间 + 新 lock_period，新金额累加进锁定记录。因此锁定期只能延长、不能缩短；持续以 lock=true 重新代理，可使接收方资源无限期保持锁定。
• lock = false（或不填）：锁定记录（金额、到期时间）保持不变；新金额写入未锁定记录，随时可撤销。此时 lock_period 被忽略，无法用于缩短或解除已有锁定。

接收方应事先确认锁定方式，不要以为新增一笔未锁定代理就解除了原有的锁定。

📘

过期锁定记录会被下一次代理自动归档

如果对同一接收方的锁定记录已经到期，下一次对该接收方发起 delegateresource（无论 lock 是否为 true）时，协议会先把过期的锁定余额自动迁移到未锁定记录（unLockExpireResource），再处理本次新代理。代理人无需手动操作，但要注意该接收方对应的资源状态已从"锁定"变为"未锁定"，可被随时撤销。

如何撤销代理

使用 wallet/undelegateresource：

BASE_URL=https://api.trongrid.io   # 示例 — 可替换为任意 TRON 节点（TronGrid、第三方或自托管）
curl -X POST ${BASE_URL}/wallet/undelegateresource \
  -d '{
    "owner_address": "TTGhREx2pDSxFX555NWz1YwGpiBVPvQA7e",
    "receiver_address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
    "balance": 100000000,
    "resource": "ENERGY",
    "visible": true
  }'

未锁定代理可随时撤销；锁定代理须等锁定期满才能撤销。TRX 始终质押在原账户下，改变的只是资源的使用归属。

🚧

接收方可能已使用部分资源

撤销代理时，网络会按比例回收接收方_尚未恢复_的那部分资源（仍在 24 小时窗口内的部分）。因此即使接收方未做任何操作，其资源池也可能因撤销而减少。完整公式见撤销代理时的资源回收。

示例演练

某 DApp 运营商把 1,000 TRX 等值的能量代理给新用户，使其无需自行质押即可与 DApp 交互，并锁定 1 天（28,800 块）。

# 步骤 1 — 运营商将能量代理给用户，锁定 1 天
BASE_URL=https://api.trongrid.io   # 示例 — 可替换为任意 TRON 节点（TronGrid、第三方或自托管）
curl -X POST ${BASE_URL}/wallet/delegateresource \
  -d '{
    "owner_address": "<DApp_operator>",
    "receiver_address": "<user>",
    "balance": 1000000000,
    "resource": "ENERGY",
    "lock": true,
    "lock_period": 28800,
    "visible": true
  }'
# → 签名并广播。用户现在持有价值 1,000 TRX 质押额的能量份额，
#   有效期为接下来的 24 小时（28,800 块 × 3 秒）。

24 小时后，运营商决定撤销代理：

# 步骤 2 — 锁定期到期后，运营商撤销代理
BASE_URL=https://api.trongrid.io   # 示例 — 可替换为任意 TRON 节点（TronGrid、第三方或自托管）
curl -X POST ${BASE_URL}/wallet/undelegateresource \
  -d '{
    "owner_address": "<DApp_operator>",
    "receiver_address": "<user>",
    "balance": 1000000000,
    "resource": "ENERGY",
    "visible": true
  }'

如果用户在这 24 小时内用掉部分能量、且仍处于恢复窗口，网络会按比例扣除尚未恢复的那部分。计算方式见撤销代理时的资源回收。

查询代理状态

相关资源

• Stake 2.0 概览 — 代理前先质押 TRX
• 撤销代理时的资源回收 — 回收未恢复资源的计算公式
• 解除质押与取消 — 注意：已代理的 TRX 无法直接解除质押
• 质押与奖励 API — 完整 API 参考表
• Stake 2.0 Solidity SDK 参考 — 在智能合约内部进行代理