Stake 2.0 Solidity SDK 参考

📘

前置阅读

• TRON 上的 Solidity
• Stake 2.0 质押模型

在 TRON 智能合约开发中，Stake 2.0 的相关接口与属性通过两条核心路径暴露给 Solidity 编译器：一类是直接作为 address / address payable 类型的内置辅助方法；另一类则是只读的全局 chain.* 属性。本文为您提供这些内置函数与属性的完整接口参考。

📘

TRON 网络共识角色术语映射

在 TRON 网络底层的 Protobuf、JSON API 以及底层系统配置文件中，共识节点与候选人通常被称为 witness（例如 witness_permission、WitnessCreateContract 等）。而在文档叙述以及日常开发交流中，我们统一使用社区普遍接受的术语——超级代表（Super Representative, 简称 SR）。本页的代码示例中仍保留系统级别的 API 原生字段名以确保编译正确，但在文案描述中均统一称为超级代表（SR）。

质押与解除质押接口

freezeBalanceV2(uint amount, uint resourceType)

描述： 向系统发起质押 TRX 操作，以获取对应的 TRON Power（TP，即投票权）以及带宽或能量资源。若操作失败，交易将触发 revert 中断。

参数：

• amount — 要质押的 TRX 数量（单位为 sun，1 TRX = 1e6 sun）
• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 无

代码示例：

pragma solidity 0.8.17;

contract C {
    event BalanceFreezedV2(uint amount, uint resourceType);

    // 质押 1 TRX 获取能量
    function example() external {
        freezeBalanceV2(1000000, 1);
        emit BalanceFreezedV2(1000000, 1);
    }
}

unfreezeBalanceV2(uint amount, uint resourceType)

描述： 向系统申请解除指定数额的 TRX 质押，同时扣减对应的带宽或能量配额，并自动回收相应的投票权（TP）。申请成功后将进入解质押等待期（主网当前默认为 14 天，由链参数 getUnfreezeDelayDays 动态控制）。等待期结束后，需手动调用 withdrawExpireUnfreeze 接口将资金提取回合约账户余额。

参数：

• amount — 要解除质押的 TRX 数量（单位为 sun）
• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 无

代码示例：

pragma solidity 0.8.17;

contract C {
    event BalanceUnfreezedV2(uint amount, uint resourceType);

    // 解除 1 TRX 的能量质押
    function example() external {
        unfreezeBalanceV2(1000000, 1);
        emit BalanceUnfreezedV2(1000000, 1);
    }
}

cancelAllUnfreezeV2()

描述： 撤销合约账户下所有处于等待期内（待处理）的解质押请求。根据虚拟机规则，在调用 selfdestruct(address) 销毁合约前，必须确保账户下不存在任何未完结的解质押请求，否则合约销毁交易将失败。

参数： 无

返回值： 无

代码示例：

pragma solidity 0.8.17;

contract C {
    event AllUnFreezeV2Canceled();

    // 取消所有待处理的解质押请求并销毁合约
    function killme(address payable target) external {
        cancelAllUnfreezeV2();
        emit AllUnFreezeV2Canceled();

        selfdestruct(target);
    }
}

withdrawExpireUnfreeze() returns(uint amount)

描述： 提取已过等待期的解质押本金。当通过 unfreezeBalanceV2 发起的解质押申请度过了指定的等待期（即 N 天，N 由主网的 70 号链参数 getUnfreezeDelayDays 控制，当前值为 14 天），即可调用此函数将解质押到期的 TRX 提回至合约余额中。

参数： 无

返回值： 成功提取并返回给合约账户的 TRX 数量（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    event ExpireUnfreezeWithdrew(uint amount);

    // 提取解质押已到期的 TRX
    function example() external {
        uint amount = withdrawExpireUnfreeze();
        emit ExpireUnfreezeWithdrew(amount);
    }
}

资源代理接口

address.delegateResource(uint amount, uint resourceType)

描述： 将当前合约通过质押获得的带宽或能量资源代理给指定的接收地址。

参数：

• amount — 要代理的资源对应的质押 TRX 数量（单位为 sun）
• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 无

代码示例：

pragma solidity 0.8.17;

contract C {
    event ResourceDelegated(uint amount, uint resourceType, address receiver);

    // 合约将 1 TRX 的带宽资源份额代理给接收地址 receiver
    function example(address payable receiver) external {
        receiver.delegateResource(1000000, 0);
        emit ResourceDelegated(1000000, 0, receiver);
    }
}

address.unDelegateResource(uint amount, uint resourceType)

描述： 收回（取消）已代理给该指定地址的带宽或能量资源份额。

参数：

• amount — 要取消代理的资源对应的质押 TRX 数量（单位为 sun）
• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 无

代码示例：

pragma solidity 0.8.17;

contract C {
    event ResourceUnDelegated(uint amount, uint resourceType, address receiver);

    // 合约取消对接收地址 receiver 的 1 TRX 带宽资源份额代理
    function example(address payable receiver) external {
        receiver.unDelegateResource(1000000, 0);
        emit ResourceUnDelegated(1000000, 0, receiver);
    }
}

链参数查询属性

以下全局只读属性供智能合约实时获取整个 TRON 网络当前的资源配置状态，属于 Solidity 规范中的 view 类操作：

• chain.totalNetLimit — 全网每天分发的可调用的总带宽配额。由链参数 getTotalNetLimit 动态管理，当前主网值为 43,200,000,000。
• chain.totalNetWeight — 全网用户为获取带宽而进行质押的 TRX 总量（以 TRX 为单位）。
• chain.totalEnergyCurrentLimit — 整个 TRON 网络当前的能量限制配额总量。由链参数 getTotalEnergyCurrentLimit 动态管理（自适应能量未启用时等于 getTotalEnergyLimit，即提案 #17 的设置值），当前主网值为 180,000,000,000。
• chain.totalEnergyWeight — 全网用户为获取能量而进行质押的 TRX 总量（以 TRX 为单位）。
• chain.unfreezeDelayDays — 全网统一执行的解质押等待期（单位为天，由链参数 getUnfreezeDelayDays 管理，当前值为 14 天）。

代码示例：

pragma solidity 0.8.17;

contract C {
    function getChainParameters() view public returns(uint, uint, uint, uint, uint) {
        return (
            chain.totalNetLimit, 
            chain.totalNetWeight,
            chain.totalEnergyCurrentLimit, 
            chain.totalEnergyWeight,
            chain.unfreezeDelayDays
        );
    }
}

address.availableUnfreezeV2Size() returns(uint)

描述： 查询指定地址当前可以发起的解质押操作的剩余可执行次数。系统为了减轻计算开销，会对地址并行的解质押请求队列长度进行限制。

参数： 无

返回值： 当前剩余可进行解质押操作的槽位数（次数）

代码示例：

pragma solidity 0.8.17;

contract C {
    function getAvailableUnfreezeV2Size(address target) view public returns(uint) {
        return target.availableUnfreezeV2Size();
    }
}

address.unfreezableBalanceV2(uint resourceType) returns(uint amount)

描述： 查询指定账户下针对特定资源类型可执行解冻（解质押）操作的 TRX 余额。

参数：

• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 当前允许发起解质押的 TRX 余额（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    function getUnfreezableBalance(address target) view public returns(uint amount) {
        return target.unfreezableBalanceV2(1);
    }
}

address.expireUnfreezeBalanceV2(uint timestamp) returns(uint amount)

描述： 查询指定地址在给定的时间戳时刻，可以执行提款操作的已到期解质押 TRX 余额总量。

参数：

• timestamp — 目标截止时间戳（单位为秒）

返回值： 届时已到期且可提取的 TRX 余额总量（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    function getExpireUnfreezeBalanceV2(address target) view public returns(uint amount) {
        return target.expireUnfreezeBalanceV2(block.timestamp);
    }
}

address.delegatableResource(uint resourceType) returns(uint amount)

描述： 查询指定地址针对特定资源类型，当前依然能够代理分配给外部地址的可用 TRX 质押份额。

参数：

• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 当前还可以代理的 TRX 质押份额（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    // 查询目标地址当前可用于代理的能量份额
    function getDelegatableResource(address target) view public returns(uint) {
        return target.delegatableResource(1);
    }
}

address.resourceV2(address from, uint resourceType) returns(uint amount)

描述： 查询地址 from 代理给当前目标账户的特定资源类型的资源折算份额。

参数：

• from — 资源所有者（代理发起者）地址
• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 代理过来的资源份额（单位为 sun 计价的 TRX 质押量）

代码示例：

pragma solidity 0.8.17;

contract C {
    // 查询 a 代理给 b 的能量资源份额
    function getResourceV2(address b, address a) view public returns(uint) {
        return b.resourceV2(a, 1);
    }
}

address.checkUnDelegateResource(uint amount, uint resourceType) returns(uint available, uint used, uint restoreTime)

描述： 模拟并评估收回（取消代理）特定资源份额时，这部分份额中已被接收方实际使用以及当前可退还的资源情况。

参数：

• amount — 欲回收的资源质押额度（单位为 sun）
• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值：

• available：表示能够立即完成收回并释放的资源质押量，单位为 sun。
• used：表示当前由于接收方已实际消耗而在锁定期内的资源质押量，单位为 sun。
• restoreTime：已被消耗的资源完全恢复且允许回收的到期时间戳，单位为秒。

代码示例：

pragma solidity 0.8.17;

contract C {
    function checkUnDelegate(address target) view public returns(uint, uint, uint) {
        (uint available, uint used, uint restoreTime) = target.checkUnDelegateResource(1000000, 1);
        return (available, used, restoreTime);
    }
}

address.resourceUsage(uint resourceType) returns(uint used, uint restoreTime)

描述： 查询指定地址在特定资源类型上的实际已消耗资源额度与恢复周期。

参数：

• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值：

• used：当前账户中已经实际被消费的资源额度（单位为 sun 折算的资源值）。
• restoreTime：账户中已消耗的资源额度完全恢复到 100% 的时间点时间戳，单位为秒。

代码示例：

pragma solidity 0.8.17;

contract C {
    function getUsage(address target) view public returns(uint, uint) {
        (uint used, uint restoreTime) = target.resourceUsage(1);
        return (used, restoreTime);
    }
}

address.totalResource(uint resourceType) returns(uint amount)

描述： 查询指定账户下所拥有的特定资源类型的可用资源折算总量（包含自身质押获取以及他人代理赠予的部分）。

参数：

• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 可用资源的总量折算值（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    // 查询目标账户可用的总能量配额折算值
    function getTotalResource(address target) view public returns(uint) {
        return target.totalResource(1);
    }
}

address.totalDelegatedResource(uint resourceType) returns(uint amount)

描述： 查询该账户对外代理赠予出去的特定资源类型的资源总量。

参数：

• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 已代理给外部地址的资源总量折算值（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    // 查询目标账户已经代理送出的能量总量
    function getTotalDelegated(address from) view public returns(uint) {
        return from.totalDelegatedResource(1);
    }
}

address.totalAcquiredResource(uint resourceType) returns(uint amount)

描述： 查询外部账户代理并注入到当前地址的特定资源类型的资源总量。

参数：

• resourceType — 资源类型，0 代表“带宽”，1 代表“能量”

返回值： 接收自外部的被动资源代理总量折算值（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    // 查询目标地址被动接收并获取的能量代理总量
    function getTotalAcquired(address target) view public returns(uint) {
        return target.totalAcquiredResource(1);
    }
}

投票与奖励

vote(address[] srList, uint[] tpList)

描述： 为传入的超级代表（SR）账户列表 srList 进行投票。数组 tpList 对应每个目标超级代表所分配的具体投票权（TRON Power, TP）数量。

参数：

• srList — 超级代表（SR）地址数组列表
• tpList — 与超级代表列表一一对应、欲分配的投票权（TP）数量数组

返回值： 无

在以下异常场景中，交易将触发 revert 中断：

• 超级代表列表 srList 和投票分配列表 tpList 的数组长度不一致。
• 单次交互提交的候选人数组长度超出了系统上限 MAX_VOTE_NUMBER（当前设置为 30）。
• 超级代表列表 srList 中混入了未登记为 SR 候选人的普通账户地址。
• 本次投票所需的 TP 总量超出了合约账户当前实际拥有的可用 TP 余额。

代码示例：

pragma solidity 0.8.17;

contract C {
    function voteWitness(address[] calldata srList, uint[] calldata tpList) external {
        vote(srList, tpList);
    }
}

withdrawReward() returns(uint)

描述： 将当前合约账户投票累积的所有超级代表分红奖励（分发奖）提取至本合约的 TRX 余额中。

参数： 无

返回值： 成功提取的投票分红奖励总额（单位为 sun）

在以下异常场景中，交易将触发 revert 中断：

• 当前调用合约的地址本身被列在了创世区块的超级代表列表中。
• 提取奖励后，合约账户的 TRX 余额溢出了系统 uint64 内部能表示的最大值上限。

代码示例：

pragma solidity 0.8.17;

contract C {
    function claimReward() external returns(uint) {
        return withdrawReward();
    }
}

rewardBalance() returns(uint)

描述： 查询该合约账户当前已累积但尚未领取（提取）的投票红利奖金余额。

参数： 无

返回值： 当前可领取的奖励额度（单位为 sun）

代码示例：

pragma solidity 0.8.17;

contract C {
    function queryRewardBalance() external view returns(uint) {
        return rewardBalance();
    }
}

isSrCandidate(address sr) returns(bool)

描述： 查询指定的地址是否注册为合法的超级代表（SR）候选人。

参数：

• sr — 被检测的账户地址

返回值： 若该账户在链上已登记为 SR 候选人则返回 true，否则返回 false。

代码示例：

pragma solidity 0.8.17;

contract C {
    function isWitness(address sr) external view returns(bool) {
        return isSrCandidate(sr);
    }
}

voteCount(address from, address to) returns(uint)

描述： 查询指定账户 from 投给目标超级代表 to 的当前票数。

参数：

• from — 发起投票的账户地址
• to — 被投票的超级代表候选人地址

返回值： 对应的投票张数（单位为 TP，1 TRX 质押折合 1 票 TP）

代码示例：

pragma solidity 0.8.17;

contract C {
    function queryVoteCount(address from, address to) external view returns(uint) {
        return voteCount(from, to);
    }
}

usedVoteCount(address owner) returns(uint)

描述： 查询指定账户当前已实际投给各个超级代表的累积票数。

参数：

• owner — 欲检测的投票账户地址

返回值： 已投票消耗的 TP 数量（单位为 TP）

代码示例：

pragma solidity 0.8.17;

contract C {
    function queryUsedVoteCount(address owner) external view returns(uint) {
        return usedVoteCount(owner);
    }
}

receivedVoteCount(address owner) returns(uint)

描述： 查询身为超级代表候选人的特定账户，当前从全网所有投票者处收到的投票票数总和。

参数：

• owner — 超级代表候选人的账户地址

返回值： 收到的投票总数（单位为 TP）

代码示例：

pragma solidity 0.8.17;

contract C {
    function queryReceivedVoteCount(address owner) external view returns(uint) {
        return receivedVoteCount(owner);
    }
}

totalVoteCount(address owner) returns(uint)

描述： 查询指定账户当前拥有的总投票权配额总量（即因质押 TRX 获取的所有 TP 投票权总量，含已投和未投的部分）。

参数：

• owner — 目标账户地址

返回值： 合约拥有的投票权（TP）总量（单位为 TP）

代码示例：

pragma solidity 0.8.17;

contract C {
    function queryTotalVoteCount(address owner) external view returns(uint) {
        return totalVoteCount(owner);
    }
}

相关资源

• Stake 2.0 质押模型 —— TRON 质押系统的高层逻辑设计与操作介绍
• TVM 与 EVM 的区别 —— 探讨本章内置接口底层的虚拟机操作码（Opcodes）机制
• TRON 上的 Solidity —— 梳理 TRON 对 Solidity 语言所作的定制化语法扩展
• Opcodes 操作码参考 —— FREEZEBALANCEV2、UNFREEZEBALANCEV2 等系统指令的底层参数细节
• TIP-467 —— Stake 2.0 的设计规范与提案草案