Stake 2.0 Solidity API

TVM虚拟机集成了Stake2.0质押和网络资源管理、以及投票相关的指令，用户可以在智能合约中执行TRX质押、解质押、资源代理、解代理、投票、提取奖励等操作，本文详细介绍Stake 2.0相关Solidity API的用法。

freezebalancev2(uint amount, uint resourceType)

描述： 质押 TRX 以获得 TRON Power（投票权）和带宽或能量，如果失败，则抛出 revert 异常

参数：

amount — 质押的TRX数量，单位为sun
resourceType — 资源类型，0表示带宽，1表示能量

返回值： N/A

示例：

pragma solidity ^0.8.17;

contract C {
    event BalanceFreezedV2(uint, uint);

    // stake 1 TRX to obtain energy
    function example() external {
        freezebalancev2(1000000, 1);
        emit BalanceFreezedV2(1000000, 1);
    }
}

unfreezeBalanceV2(uint amount, uint resourceType)

描述： 解锁通过Stake2.0机制质押的TRX, 释放所相应数量的带宽和能量，同时回收相应数量的投票权(TP)，用户解质押后，需要等待N天，然后才能调用withdrawexpireunfreeze接口提取本次解质押的本金

参数：

amount — 解质押的TRX数量，单位为sun
resourceType — 资源类型，0表示带宽，1表示能量

返回值： N/A

示例：

pragma solidity ^0.8.17;

contract C {
    event BalanceFreezedV2(uint, uint);

    // unstake 1 TRX staked for energy
    function example() external {
        unfreezebalancev2(1000000, 1);
        emit BalanceUnfreezedV2(1000000, 1);
    }
}

cancelAllUnfreezeV2()

描述： 取消所有待处理的质押请求。在调用 selfdestruct(address) 销毁合约之前，应取消所有未处理的质押请求，否则合约无法销毁

参数： N/A

返回值： N/A

示例：

pragma solidity ^0.8.17;

contract C {
    event AllUnFreezeV2Canceled();

   // cancel all pending unstaking requests and destroy the contract
   function killme(address payable target) external {
         cancelallunfreezev2();
         emit AllUnFreezeV2Canceled();
    
         selfdestruct(target);
   }

}

withdrawExpireUnfreeze() returns(uint amount)

描述： 提取已过锁定期的解质押的本金。通过unfreezeBalanceV2解质押，并等待14天后，合约可以通过该接口提取已过锁定期的本金

参数： N/A

返回值： 成功提取的TRX数量，单位为sun

示例：

pragma solidity ^0.8.17;

contract C {
    event ExpireUnfreezeWithdrew(uint);

    // withdraw unfrozen TRX
    function example() external{
        amount = withdrawexpireunfreeze();
        emit ExpireUnfreezeWithdrew(amount);
    }

}

<address payable>.delegateResource(uint amount, uint resourceType)

描述： 将带宽或者能量资源代理给address

参数：

amount — 代理质押的TRX数量，单位为sun
resourceType — 资源类型，0表示带宽，1表示能量

返回值： N/A

示例：

pragma solidity ^0.8.17;

contract C {
    event ExpireUnfreezeWithdrew(uint);

    // the contract delegates 1 TRX bandwidth resource share to receiver
    function example(address payable receiver) external {
        receiver.delegateResource(1000000, 0);
        emit ResourceDelegated(1000000, 0, receiver);
    }

}

<address payable>.unDelegateResource(amount, resourceType)

描述： 取消为address代理的带宽或者能量

参数：

amount — 取消代理amount数量的TRX所对应的资源, 单位为sun
resourceType — 资源类型，0表示带宽，1表示能量

返回值： N/A

示例：

pragma solidity ^0.8.17;

contract C {
    event ResourceUnDelegated(uint, uint, address);

    // the contract undelegates 1 TRX bandwidth resource share from the receiver
    function example(address payable receiver) external {
        receiver.unDelegateResource(1000000, 0);
        emit ResourceDelegated(1000000, 0, receiver);
    }
}

Chain Properties

chain.totalNetLimit: 全网带宽供应总量，目前为 43,200,000,000
chain.totalNetWeight: 全网为获取带宽而质押的TRX总量，单位为TRX
chain.totalEnergyCurrentLimit: 全网能量供应总量，目前为 90,000,000,000
chain.totalEnergyWeight: 全网为获取能量而质押的TRX总量，单位为TRX
chain.unfreezeDelayDays: 解质押后本金锁定时间，单位为DAY，目前为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)

描述： 查询address当前解质押剩余次数

参数：N/A

返回值： 解质押的剩余次数

示例：

pragma solidity ^0.8.17;

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

<address>.unfreezableBalanceV2() returns(uint amount)

描述： 查询某账户地址address可解质押的TRX数量

参数：

resourceType — 资源类型，0表示带宽，1表示能量

返回值： unfreezable TRX balance, the unit is sun

示例：

pragma solidity ^0.8.17;

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

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

描述： 查询在某时刻账户address可提取的解质押本金数量

参数：

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)

描述： 针对某类型的资源，查询某地址可代理的资源份额

参数：

resourceType — 资源类型，0表示带宽，1表示能量

返回值： 可代理的资源份额，单位为sun

示例：

pragma solidity ^0.8.17;

contract C {
    //query the amount of delegatable resources share of energy for target address
    function getDelegatableResource(address target) view public returns(uint) {
        return target.delegatableResource(1);
    }
}

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

描述： 查询某地址from代理给目标地址address的指定类型资源的份额

参数：

from — 资源代理地址
resourceType — 资源类型，0表示带宽，1表示能量

返回值： 资源份额，单位为sun

示例：

pragma solidity ^0.8.17;

contract C {
    //query the amount of resources share of energy delegated by a to b
    function getResourceV2(address b, address a) view public returns(uint) {
        return b.resourceV2(a, 1);
    }
}

<address>.checkUnDelegateResource(uint amount, uint resourceTyp) 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 checkUnDelegateResource(address target) view public returns(uint, uint, uint) {
        (uint available, uint used, uint restoreTime) = target.checkUnDelegateResource(1000000, 1);
        return (available, used, restoreTime);
    }
}

<address>.getResourceUsage(uint resourceTyp) returns(uint used, uint restoreTime)

描述： 查询某地址的某种类型资源的已使用份额

参数：

resourceType — 资源类型，0表示带宽，1表示能量

返回值：

used - 已使用资源份额的数量，单位 sun
restoreTime - 已使用资源的恢复时间，单位是秒

示例：

pragma solidity ^0.8.17;

contract C {

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

}

<address>.totalResource(uint resourceTyp) returns(uint amount)

描述： 查询某地址的某种类型资源的总可用份额

参数：

resourceType — 资源类型，0表示带宽，1表示能量

返回值： 可用资源份额，单位为sun

示例：

pragma solidity ^0.8.17;

contract C {
    //query the available resource share of energy for the target address
    function getTotalResource(address target) view public returns(uint) {
        return target.totalResource(1);
    }

}

<address>.totalDelegatedResource(uint resourceTyp) returns(uint amount)

描述： 查询某地址代理出去的某种类型资源的总份额

参数：

resourceType — 资源类型，0表示带宽，1表示能量

返回值： 代理的资源份额，单位为sun

示例：

pragma solidity ^0.8.17;

contract C {
    //query the delegated resource share of energy for the target address
    function getTotalDelegatedResource(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 {
    //query the acquired resource share of energy for the target address
    function getTotalAcquiredResource(address target) view public returns(uint) {
        return target.totalAcquiredResource(1);
    }
}

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

描述： 为超级代表投票

参数：

srList — 投票的超级代表列表
tpList — 为srList中的超级代表投的票数

返回值： N/A

以下情况将导致revert异常：

srList 和 tpList 长度不同
列表长度大于允许的最大值30
srList 中存在非超级代表地址
tpList中存在负数
总得投票数大于合约当前可用投票数

示例：

pragma solidity ^0.8.17;

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

withdrawReward() returns(uint)

描述： 提取投票奖励

参数：N/A

返回值： 提取到的奖励数额，单位为sun

以下情况将导致revert异常：

合约地址为创世块中的witness
合约地址的余额超过了long（8字节）最大值

示例：

pragma solidity ^0.8.17;

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

rewardBalance() returns(uint)

描述： 查询该合约可提取的奖励数量

参数：N/A

返回值： 可提取到的奖励总额，单位为sun

示例：

pragma solidity ^0.8.17;

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

isSrCandidate(address sr) returns(bool)

描述： 查询某地址是否为超级代表候选人

参数：

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

示例：

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已使用的投票数量

参数：

owner - 要查询的地址

返回值： 投票权已使用量，单位为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获得的票数

参数：

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)

描述： 查询某地址拥有的投票权总数

参数：

owner - 要查询的地址

返回值： 投票权总数，单位为TP

示例：

pragma solidity ^0.8.17;

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