Stake 2.0 Solidity API

Stake 2.0 realizes the integration with TVM, users can perform staking/unstaking, delegating/undelegating, resource status query, etc. in the smart contract, the following introduces the Solidity APIs related to Stake 2.0.

freezebalancev2(uint amount, uint resourceType)

Description: stake TRX to obtain TRON Power (voting rights) and bandwidth or energy. If fails, the revert exception will be thrown

Params:

• amount — amount of TRX to be staked, unit is sun
• resourceType — resource type, 0 is “BANDWIDTH” and 1 is “ENERGY”

Returns: N/A

Example:

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)

Description: unstake TRX to release bandwidth and energy and at the same time TRON Power will be reduced and corresponding votes will be canceled. After executing this transaction, the users need to wait for N days, then they can call withdrawexpireunfreeze to withdraw their funds.

Params:

• amount — amount of TRX to be staked, unit is sun
• resourceType — resource type, 0 is “BANDWIDTH” and 1 is “ENERGY”

Returns: N/A

Example:

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()

Description: cancel all pending unstaking requests. Before calling selfdestruct(address) to destroy the contract, should cancel all pending unstaking requests, otherwise, the contract cannot be destroyed.

Params: N/A

Returns: N/A

Example:

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)

Description: withdraw unfrozen TRX, the user can call this API to withdraw funds to account after executing unfreezeBalanceV2 transaction and waiting N days, N is a network parameter.

Params: N/A

Returns: the amount of TRX successfully withdraw, the unit is sun

Example:

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)

Description: delegate bandwidth or energy resource to address

Params:

• amount — amount of TRX staked for resource to be delegated, unit is sun
• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: N/A

Example:

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)

Description: cancel the resource delegation for the address

Params:

• amount — amount of TRX staked for resource to be undelegated, unit is sun
• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: N/A

Example:

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: total bandwidth provision in the network, the current value is 43,200,000,000
• chain.totalNetWeight: total TRX staked for bandwidth, the unit is TRX
• chain.totalEnergyCurrentLimit: total energy provision in the network, the current value is 90,000,000,000
• chain.totalEnergyWeight: total TRX staked for energy, the unit is TRX
• chain.unfreezeDelayDays: unstaking waiting time, the unit is DAY

Example:

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)

Description: query the remaining times of executing unstake operation for address

Params:N/A

Returns: remaining times of executing unstake operation

Example:

pragma solidity ^0.8.17;

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

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

Description: query the unfreezable balance of a specified resourceType for address

Params:

• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY
  Returns: unfreezable TRX balance, the unit is sun

Example:

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)

Description: query the withdrawable balance at the specified timestamp for address

Params:

• timestamp — query cutoff timestamp, the unit is secounds

Returns: withdrawable TRX balance, the unit is sun

Example:

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)

Description: query the amount of delegatable resources share of the specified resourceType for address

Params:

• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: delegatable resources share, the unit is sun

Example:

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)

Description: query the amount of resources share of a specific resourceType delegated by from to address

Params:

• from — resource owner
• resourceType — Resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: resources share, the unit is sun

Example:

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)

Description: check whether the contract can recycle the specified amount of resources share of a specific resourceType that have been delegated to address

Params:

• amount — resource share, unit is sun
• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: available is the amount of available resource share, the unit sun, used is the amount of used resource share, the unit is sun, restoreTime is the restore time point for the used resources, the unit is seconds

Example:

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)

Description: query the usage of a specific resourceType of resources for address

Params:

• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: used is the amount of used resource share, the unit sun,, restoreTime is the restore time point for the used resources, the unit is seconds

Example:

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)

Description: query the total available resource share of a specific resourceType for address

Params:

• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: the amount of available resource share, the unit is sun

Example:

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)

Description: query delegated resources share of a specific resourceType for address

Params:

• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: the amount of delegated resource share, the uint is sun

Example:

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)

Description: query the acquired resource share of a specific resourceType for address

Params:

• resourceType — resource type, 0 is BANDWIDTH and 1 is ENERGY

Returns: the amount of acquired resource share, the unit is sun

Example:

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)

Description: Vote witness in srList array and every witness will get correspond TP in tpList array

Params:

• srList — SR list
• tpList — Number of votes for super representatives in srList

Returns: N/A

Below situations can cause revert exception:

• srList array length and tpList array length are different.
• Array length are greater than MAX_VOTE_NUMBER (30).
• There are normal account address in srList array.
• There are negative value in 'tpList' array.
• Total needed tron power is greater than current owned tron power of contract.

Example:

pragma solidity ^0.8.17;

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

withdrawReward() returns(uint)

Description: Withdraw all allowance and reward to contract balance

Params:N/A

Returns: Actually withdrawn balance of allowance and reward. unit is sun.

Below situations can cause revert exception:

• Contract address is in witness list of genesis block.
• Sum of contract balance and reward overflow long (8 bytes).

Example:

pragma solidity ^0.8.17;

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

rewardBalance() returns(uint)

Description: Query all allowance and reward of contract account

Params:N/A

Returns: Sum of allowance and reward of contradct account

Example:

pragma solidity ^0.8.17;

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

isSrCandidate(address sr) returns(bool)

Description: Judge whether the address is a candidate address

Params:

• sr - Address to query

Returns: If the address is a candidate address, return true, otherwise return false.

Example:

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)

Description: Query vote count of from account voting for to account

Params:

• from - vote address
• to - SR address

Returns: Corresponding vote count (tron-power, 1 trx = 1 tron-power).

Example:

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)

Description: Query owner used vote count

Params:

• owner - address to query

Returns: Used vote count of owner account (tron-power, 1 trx = 1 tron-power).

Example:

pragma solidity ^0.8.17;

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

ReceivedVoteCount(address owner) returns(uint)

Description: Query owner recevied vote count

Params:

• owner - address to query

Returns: Received vote count of owner account (tron-power, 1 trx = 1 tron-power)

Example:

pragma solidity ^0.8.17;

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

TotalVoteCount(address owner) returns(uint)

Description: Query total vote count of owner (Also can be called tron-power owned by contract)

Params:

• owner - address to query

Returns: Total vote count of owner account (tron-power, 1 trx = 1 tron-power)

Example:

pragma solidity ^0.8.17;

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