Skip to content

tip-157.md

Latest commit

 

History

History
124 lines (78 loc) · 3.51 KB

tip-157.md

File metadata and controls

124 lines (78 loc) · 3.51 KB
tip: 157
title: Freeze instructions in TVM
author: taihao.fu@gmail.com
status: Final
type: Standards Track
category: Core
created: 2020-06-03

Simple Summary

To provide freeze related operations in TVM.

Abstract

Freeze & Unfreeze operation in system contract are introduced, smart contract can freeze and get resource from the system.

Motivation

Common user can freeze TRX to get resource, such as TRON power, bandwidth, energy. However, none privatekey accounts, like smart contracts, can't get resources from the staking mechanism. This TIP provide instructions to get resource, so that smart contracts can provide tron power for voting and also provide resource delegation to others.

Specification

New instructions in TVM

0xd5: FREEZE

The FREEZE takes 3 operands pop up from stack:

receiverAddress: account address to receive generated resource.

freezeAmount: amount to freeze in SUN.

resourceType: 0 as bandwidth, 1 as energy.

If operation succeed, push 1 to stack, otherwise push 0 to stack.

0xd6: UNFREEZE

The UNFREEZE takes 2 operands pop up from stack.

receiverAddress: account address which received resource.

resourceType: 0 as bandwidth, 1 as energy.

If operation succeed, push 1 to stack, otherwise push 0 to stack.

0xd7: FREEZEEXPIRETIME

The FREEZEEXPIRETIME takes 2 operands pop up from stack.

targetAddress: target account address.

resourceType: 0 as bandwidth, 1 as energy.

If operation succeed, push the expire time to stack, otherwise push 0 to stack.

Notice

For FREEZE or UNFREEZE, if receiverAddress == contractAddress, means that contract freeze or unfreeze for itself.

For FREEZE or UNFREEZE, if receiverAddress != contractAddress, receiverAddress must not be address of contract.

For FREEZE, automatically active non-existent account and consume additional energy.

For FREEZE, amount must not be less than 1 TRX = 10e6 SUN.

For FREEZEEXPIRETIME, return value is in seconds.

Solidity example

contract TestFreeze {

    /**
     * @dev Freeze `amount` balance of contract to get resource for `receiver` 
     * which type is `res` (0 for bandwidth, 1 for energy). Return frozen time
     * which the default is set to three days.
     */
    function freeze(address payable receiver, uint amount, uint res) external returns(uint) {
        receiver.freeze(amount, res);
        return this.getExpireTime(receiver, res) - now;
    }
    
    /**
     * @dev Unfreeze specific balance to get corresponding balance.You can use 
     * `receiver' and 'res'  (0 for bandwidth, 1 for energy) parameters to 
     * unfreeze specific balance.
     */
    function unfreeze(address payable receiver, uint res) external returns(uint) {
        receiver.unfreeze(res);
        return 1;
    }
    
    /**
     * @dev Return the timestamp which the specific balance can be unfreezed.
     */
    function getExpireTime(address payable target, uint res) external view returns(uint) {
        return target.freezeExpireTime(res);
    }
}

Notice

receiver or target must have address payable type, means that calling those methods on non-payable address will cause a complier error.

Rationale

Tier

FREEZE tier.ExtTier

UNFREEZE tier.ExtTier

FREEZEEXPIRETIME tier.ExtTier

Selfdestruct

If contract still has unfreezed balance for others, selfdestruct will case REVERT exception.

Unfreezed balance for contract itself will be unfreezed and transfer to inheritor`s balance after selfdesturct executed.