tip: 542
Title: Resource delegating supports customizable lock period
Author: Tee <[email protected]>
Discussions-to: https://github.com/tronprotocol/tips/issues/542
Status: Final
Type: Standards Track
Category: Core
Created: 2023-05-12
Add a lock_period parameter in the wallet/delegateresource API in Stake 2.0, to support delegating bandwidth or energy resource with a specified lockup time.
Besides the current API wallet/delegateresource that allows users to lockup a solid 3 days before the resouce could be undelegated, it is proposed to add a parameter lock_period in this API to support customizable lock period in resource delegating, with the unit of blocks. And the new resource delegating to the same address of same type should have this lock_period value larger than the lockup blocks left of the address.
Currently in Stake 2.0, the lock parameter in the wallet/delegateresource is a bool type. If it is set to false, the delegated resources does not have a lockup time, it can be unstaked anytime after delegation. If it is set to true, the delegated resources cannot be undelegated within 3 days.
The solid lockup time of 3 days can not meet all the scenarios and is not conducive to the two parties to agree on a lease time in advance. If it can not be defined in the transaction, there is risk that the owner may undelegate the resource before the appointed time. Making the lockup time a customizable time will enhance the flexibility and security in delegation transactions.
Modify wallet/delegateresource API, the user can call this API to delegate bandwidth or energy resource with a customized lockup time to another address.
Params:
owner_address - Address of transaction initiator, data type is string
receiver_address - Receiver address of resource to be delegated to, data type is string
balance - Amount of TRX staked for resources to be delegated, unit is sun, data type is unit256
resource - Resource type, "BANDWIDTH" or "ENERGY", data type is string
lock - Whether it is locked. If it is set to false, there will not be any lockup time no matter what the lock_period value is. If it is set to true, the delegating transaction will have a lockup time, and the time is decided by the lock_period value.
lock_period - The lockup period, unit is blocks, data type is int256, It indicates how many blocks the resource delegating is locked before it can be undelegated. If the lock time is not over, and the owner delegates the same type of resource with a new lockup time to the same address, the lockup time of all the resource of the same type will be reset to the new lockup time.That new lockup time cannot be less than (old lockup time + old transaction timestamp) - current time.
visible - Whether the address is in base58 format, data type is bool
Returns: unsigned transaction, data type is JSON string
Example:
curl -X POST https://127.0.0.1:8092/wallet/delegateresource -d \
'{
"owner_address":"TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM",
"receiver_address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
"balance":1000000000,
"resource":"BANDWIDTH",
"lock": true,
"lock_period": 86400,
"visible":true
}'
It will not influence the existed staking and unstaking related transactions.
If the lock is set to true, and lock_period is set to 0, or left blank, it also have the same consequence with that the lock_period is set to 86400.