Stake 2.0 Solidity API

Stake 2.0 Solidity API

Stake 2.0 seamlessly integrates with PVM, enabling users to engage in staking/unstaking, delegating/undelegating, resource status queries, and more within the smart contract realm. The following outlines the Solidity APIs associated with Stake 2.0.

freezebalancev2(uint amount, uint resourceType)

Description: Stake PRC to acquire Pollux Power (voting rights) along with bandwidth or energy. In case of failure, the process will trigger a revert exception.

Params:

  • Amount — the quantity of POX to be staked, measured in RAM.

  • Resource type — the type of resource, where 0 represents "BANDWIDTH" and 1 corresponds to "ENERGY".

Returns: N/A

pragma solidity ^0.8.17;

contract C {
    event BalanceFreezedV2(uint, uint);

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

unfreezeBalanceV2(uint amount, uint resourceType)

Description: Unstake POX to free up bandwidth and energy, simultaneously reducing Pollux Power and canceling corresponding votes. Following the execution of this transaction, users are required to wait for N days before being able to invoke withdraw expire unfreeze to retrieve their funds.

Params:

  • Amount — the amount of POX to be staked, measured in RAM

  • Resource type — the type of resource, where 0 corresponds to "BANDWIDTH" and 1 represents "ENERGY"

Returns: N/A

Example:

pragma solidity ^0.8.17;

contract C {
    event BalanceFreezedV2(uint, uint);

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

cancelAllUnfreezeV2()

Description: Canceling all outstanding unstaking requests is essential. Prior to invoking selfdestruct(address) for the contract's destruction, it is imperative to cancel any pending unstaking requests. Failure to do so would hinder the contract's ability to be successfully terminated.

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: Retrieve unfrozen POX—users can utilize this API to withdraw funds to their account following the execution of the unfreezeBalanceV2 transaction, subject to a waiting period of N days, where N is a network parameter.

Params: N/A

Returns: the quantity of POX successfully withdrawn, measured in RAM.

Example:

pragma solidity ^0.8.17;

contract C {
    event ExpireUnfreezeWithdrew(uint);

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

}

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

Description: Delegate bandwidth or energy resources to a specific address.

Params:

  • Amount — the quantity of POX staked for the delegated resource, measured in RAM

  • Resource type — the type of resource, where 0 represents BANDWIDTH and 1 corresponds to ENERGY

Returns: N/A

Example:

pragma solidity ^0.8.17;

contract C {
    event ExpireUnfreezeWithdrew(uint);

    // the contract delegates 1 POX 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: Revoke the resource delegation associated with the specified address.

Params:

  • Amount: the quantity of POX staked for the resource to be undelegated, measured in RAM.

  • Resource Type: the type of resource, where 0 represents BANDWIDTH and 1 represents ENERGY.

Returns: N/A

Example:

pragma solidity ^0.8.17;

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

    // the contract undelegates 1 POX 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: Overall network bandwidth allocation, presently set at 5,00,00,000.

  • chain.totalNetWeight: Cumulative POX staked for bandwidth, measured in POX.

  • chain.totalEnergyCurrentLimit: Total energy allocation in the network, currently set at 500,00,00,000.

  • chain.totalEnergyWeight: Cumulative POX staked for energy, measured in POX.

  • chain.unfreezeDelayDays: Waiting period for unstaking, measured in days.

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: Retrieve the remaining attempts for executing the unstake operation associated with a specific address.

Params:N/A

Returns: the remaining attempts for executing the 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: Retrieve the balance of a specified resource type that is eligible for unfreezing, associated with a given address.

Params:

  • resourceType — type of resource, 0 represents BANDWIDTH, and 1 represents ENERGY

  • Returns: non-freezable POX balance, measured in RAM

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: Retrieve the withdrawable balance for the given address at the designated timestamp.

Params:

  • timestamp — inquiry cutoff time, measured in seconds

  • Returns: withdrawable POX balance, measured in RAM

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: Retrieve the share of delegatable resources associated with the specified resourceType for a given address.

Params:

  • Resource type — designation of resource type, where 0 represents BANDWIDTH and 1 corresponds to ENERGY.

Return: divisible resource allocation, measured in RAM units.

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: Retrieve the allocated resource share for a designated resource type delegated from one address to another.

Params:

  • From — proprietor of resources

  • Resource type — Type of resource, with 0 denoting BANDWIDTH and 1 signifying ENERGY.

Return: Allocated resource portion, measured in units of RAM.

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: Verify if the contract is eligible to reclaim the designated resource share for a specific resource type that has been delegated to a given address.

Params:

  • Amount — allocated resource portion, measured in units of RAM

  • Resource Category — type of resource, with 0 representing BANDWIDTH and 1 indicating ENERGY.

Returns: Available designates the quantity of available resource share, measured in RAM. "Used" represents the amount of utilized resource share, with the unit specified as RAM. The "restore time" indicates the time point when the used resources are scheduled for restoration, measured in 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: Inquire about the usage of a particular resource type for the given address.

Params:

  • Resource Type — resource type; 0 represents BANDWIDTH, and 1 represents ENERGY

Results: Utilization signifies the allocated resource share, measured in RAM units. Replenishment time denotes the point in time when the utilized resources are regenerated, measured in 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: Retrieve the overall allocated resource allocation for a designated resource type associated with the given address.

Params:

  • Resource Type — resource type, 0 represents BANDWIDTH and 1 represents ENERGY.

Results: Indicates the quantity of accessible resource allocation, measured in RAM units.

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: Retrieve the allocated resource quota for a designated resource type associated with a given address.

Params:

  • resourceType — designation of resource, where 0 represents BANDWIDTH and 1 represents ENERGY.

Returns: the quantity of allocated resource share, expressed in uint as RAM.

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: Retrieve the obtained allocation of resource shares for a designated resource type associated with a given address.

Params:

  • resourceType — the type of resource, with 0 representing BANDWIDTH, and 1 representing ENERGY.

Returns: the quantity of obtained resource share, measured in the unit of RAM.

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: Cast your vote for a witness in the srList array, and each elected witness will receive the corresponding TP as listed in the tpList array.

Params:

  • srList — List of Super Representatives.

  • tpList — Number of votes allocated to the Super Representatives in the srList.

Returns: N/A

The following scenarios may lead to a revert exception:

  • Mismatch in the lengths of srList and tpList arrays.

  • The array lengths exceed the defined MAX_VOTE_NUMBER limit (30).

  • Presence of regular account addresses in the srList array.

  • Existence of negative values in the 'tpList' array.

  • The total required Pollux Power surpasses the current Tron Power owned by the 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 approved funds and incentives to the smart contract pool.

Params:N/A

Returns:Provides the realigned sum of withdrawn funds from both the approved allowance and rewards, measured in RAM units.

Instances leading to a revert exception encompass the following scenarios:

  • Inclusion of the contract address within the witness list of the genesis block.

  • Overflow of the total, combining contract balance and reward, exceeding the length of a long integer (8 bytes).

Example:

pragma solidity ^0.8.17;

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

rewardBalance() returns(uint)

Description: Retrieve the allowances and rewards associated with the contract account.

Params:N/A

Returns: Total amount comprising the allowance and reward associated with the contract account.

Example:

pragma solidity ^0.8.17;

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

isSrCandidate(address sr) returns(bool)

Description: Determine if the given address qualifies as a candidate address.

Params:

  • sr - Address to query

Returns: Returns true if the address is a qualified candidate address; otherwise, returns 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: Retrieve the vote count from the specified account that has voted for the designated recipient account.

Params:

  • from - vote address

  • to - SR address

Returns: The associated vote count measured in Pollux-power, where 1 POX equals 1 Pollux-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: Retrieve the vote count utilized by the owner.

Params:

  • owner - address to query

Returns: The vote count employed by the owner account, measured in Pollux-power, with 1 POX equivalent to 1 Pollux-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: Retrieve the vote count received by the owner.

Params:

  • owner - address to query

Returns: received votes for the owner account, measured in Pollux-power, where 1 POX equals 1 Pollux-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: Retrieve the overall vote count of the owner, alternatively referred to as the Pollux-power owned by the contract.

Params:

  • owner - address to query

Returns: The cumulative vote count associated with the owner account, measured in Pollux-power, with 1 POX equivalent to 1 Pollux-power.

Example:

pragma solidity ^0.8.17;

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

Last updated