tip: 542
Title: Resource delegating supports customizable lock period
Author: Tee <[e-mail]>
Discussions-to: https://github.com/tronprotocol/tips/issues/542
Status: Accepted
Type: Standards Track
Category: Core
Created: 2023-05-12

# Simple Summary

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.

# Abstract

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.

The maximum `lock_period` value is to be decided by another propsal. To be backward compatible, the `lock_period` coresponding lockup time should be at least longer 3 days, which equals to:

3 * 24 * 60 * 60 / 3 = 86400 blocks

It means the maximum `lock_period` value should be larger than 86400.

# Motivation

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.

# Specifications

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:

1. `owner_address` - Address of transaction initiator, data type is string
2. `receiver_address` - Receiver address of resource to be delegated to, data type is string
3. `balance` - Amount of TRX staked for resources to be delegated, unit is sun, data type is unit256
4. `resource` - Resource type, "BANDWIDTH" or "ENERGY", data type is string
5. `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.
6. `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.
7. `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
}'

# Backward Compatibility

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.