TimeLock on ParaSpace Withdrawals and Borrows

Rather than directly transferring the withdrawn or borrowed funds to the user's wallet, a time-locked agreement is established. This agreement specifies that the user has the right to receive certain assets after a designated release time. The funds are then transferred to a time-locked contract assigned to the user. This is done by the help of two smart contracts. TimeLockStrategy and TimeLock.

TimeLock Strategy

TimeLock Documentation
TimeLockStrategy is a smart contract implementation which calculates time-lock release times based on defined thresholds and wait times. It enforces limits on the total amount that can be time-locked in a given period and introduces an additional waiting period if this limit is exceeded.

Specs

  1. 1.
    Flexible Thresholds and Wait Times: DefaultTimeLockStrategy supports three tiers of time-lock amounts, each with a distinct wait time. These thresholds and wait times can be configured during contract deployment.
  2. 2.
    Period Limit: The contract enforces a limit on the total amount that can be time-locked within a specific period.
  3. 3.
    Extra Waiting Period: An additional waiting period is imposed if the total amount time-locked within a period exceeds the defined limit.
  4. 4.
    Period Reset: The contract automatically resets the total amount in the current period and emits a PeriodReset event when the period has elapsed.

Usage

  1. 1.
    Calculate Time-Lock Parameters: The calculateTimeLockParams function is called by the associated pool to determine the release time for a new time-lock agreement, based on the provided TimeLockFactorParams.
  2. 2.
    View Time-Lock Strategy Data: Users can call the getTimeLockStrategyData function to view the current state of the time-lock strategy, including thresholds, wait times, period limit, and total amount time-locked in the current period.

Smart Contract Data Structures and APIs

Data Structures

TimeLockParams

A struct representing the time lock parameters for an agreement.
Name
Type
Description
releaseTime
uint48
The timestamp when the locked asset can be claimed by the beneficiary.
actionType
TimeLockActionType
The action to perform on the locked asset (BORROW or WITHDRAW).

TimeLockFactorParams

A struct representing the factor parameters for a time lock agreement.
Name
Type
Description
assetType
AssetType
The type of asset locked (ERC20 or ERC721).
asset
address
The contract address of the locked asset.
amount
uint256
The amount of the locked asset (for ERC20) or the token ID (for ERC721).

TimeLockActionType

Enum representing the types of actions that can be performed on the locked asset.
Name
Value
Description
BORROW
0
Represents a borrow action on the locked asset.
WITHDRAW
1
Represents a withdraw action on the locked asset.

TimeLockStrategyData

A struct representing the current state of the time-lock strategy.
Name
Type
Description
minThreshold
uint256
The minimum threshold amount for applying time-lock.
midThreshold
uint256
The middle threshold amount for determining wait times.
minWaitTime
uint48
The minimum wait time for locked assets (applied when the amount is below the midThreshold).
midWaitTime
uint48
The middle wait time for locked assets.
maxWaitTime
uint48
The maximum wait time for locked assets (applied when the amount is above midThreshold).
poolPeriodWaitTime
uint48
The wait time for the entire pool during the current period.
poolPeriodLimit
uint256
The limit of locked assets allowed during the current period.
period
uint256
The current period number.
totalAmountInCurrentPeriod
uint128
The total amount of assets locked in the current period.
lastResetTimestamp
uint48
The timestamp of the last reset for the time-lock strategy.

Functions

calculateTimeLockParams

function calculateTimeLockParams(DataTypes.TimeLockFactorParams memory params) external returns (DataTypes.TimeLockParams memory)
Calculates the release time for a new time-lock agreement based on the provided TimeLockFactorParams (including AssetType, asset, and amount). Can only be called by the associated pool. Returns a TimeLockParams object with the calculated release time and TimeLockActionType (either BORROW or WITHDRAW).
Call Params
Name
Type
Description
params
DataTypes.TimeLockFactorParams
TimeLockFactorParams object containing asset information
Return Values
Type
Description
DataTypes.TimeLockParams
TimeLockParams object with the calculated release time and action type

getTimeLockStrategyData
function getTimeLockStrategyData() external view returns (TimeLockStrategyData memory)
Returns the current state of the time-lock strategy, including thresholds, wait times, period limit, and total amount time-locked in the current period. Returns a TimeLockStrategyData object containing the mentioned data.
Return Values
Type
Description
TimeLockStrategyData
Object containing the current state of the time-lock strategy

TimeLock Contract

TimeLock is a smart contract solution designed to facilitate the secure time-locking of assets, including ERC20, ERC721, and custom ERC721 tokens like MoonBirds. TimeLock enables users to create time-bound agreements, ensuring that assets are only accessible to the intended beneficiary after a predefined release time. The contract is managed by the ParaSpace TimeLock governance.

Specs

  1. 1.
    Support for Multiple Asset Types: TimeLock supports ERC20, ERC721, and custom ERC721 assets, such as MoonBirds.
  2. 2.
    Secure Time-Locking: Assets can only be claimed by the intended beneficiary after the specified release time has passed.
  3. 3.
    Flexible Management by Governance: TimeLock allows ParaSpace TimeLock governance to freeze or unfreeze individual or all agreements.
  4. 4.
    Bulk Claiming: Beneficiaries can claim multiple agreements at once, improving efficiency and reducing gas costs.

Usage


  1. 1.
    Create a Time-Locked Agreement: Create a new agreement using the createAgreement function, specifying the asset type, action type, asset address, token IDs or amounts, beneficiary, and release time.
  2. 2.
    Claim Assets: The beneficiary can claim the assets using either the claim or claimMoonBirds functions when the release time is reached. Bulk claiming is supported for multiple agreements.

Smart Contract Data Structures and APIs

Data Structures

Agreement

A struct representing an asset lock agreement.
Name
Type
Description
assetType
AssetType
The type of asset locked (ERC20 or ERC721).
actionType
TimeLockActionType
The action to perform on the locked asset (BORROW or WITHDRAW).
asset
address
The contract address of the locked asset.
tokenIdsOrAmounts
uint256[]
An array of token IDs (ERC721) or a single-element array containing the amount (ERC20).
beneficiary
address
The address of the beneficiary who can claim the locked asset.
releaseTime
uint48
The timestamp when the locked asset can be claimed by the beneficiary.
isFrozen
bool
Indicates whether the agreement is frozen, preventing any claims.

TimeLockParams

A struct representing the time lock parameters for an agreement.
Name
Type
Description
releaseTime
uint48
The timestamp when the locked asset can be claimed by the beneficiary.
actionType
TimeLockActionType
The action to perform on the locked asset (BORROW or WITHDRAW).

TimeLockFactorParams

A struct representing the factor parameters for a time lock agreement.
Name
Type
Description
assetType
AssetType
The type of asset locked (ERC20 or ERC721).
asset
address
The contract address of the locked asset.
amount
uint256
The amount of the locked asset (for ERC20) or the token ID (for ERC721).

Functions

createAgreement

function createAgreement(DataTypes.AssetType assetType, DataTypes.TimeLockActionType actionType, address asset, uint256[] calldata tokenIdsOrAmounts, address beneficiary, uint48 releaseTime) external returns (uint256)
Creates a new asset lock agreement. Can only be called by the asset's xToken. Returns the agreement ID.
Name
Type
Description
assetType
DataTypes.AssetType
The type of asset locked (ERC20 or ERC721).
actionType
DataTypes.TimeLockActionType
The action to perform on the locked asset.
asset
address
The contract address of the locked asset.
tokenIdsOrAmounts
uint256[]
An array of token IDs (ERC721) or a single element array with the amount (ERC20).
beneficiary
address
The address that can claim the locked asset after the release time.
releaseTime
uint48
The timestamp when the asset can be claimed by the beneficiary.
Return Values
Type
Description
uint256
The agreement ID.

claim

function claim(uint256[] calldata agreementIds) external
Claims the locked assets for the provided agreement IDs. Can only be called by the beneficiary and if the release time has passed.
Name
Type
Description
agreementIds
uint256[]
An array of agreement IDs to claim.

claimMoonBirds

function claimMoonBirds(uint256[] calldata agreementIds) external
Claims the locked MoonBird ERC721 tokens for the provided agreement IDs. Can only be called by the beneficiary and if the release time has passed.
Name
Type
Description
agreementIds
uint256[]
An array of agreement IDs to claim.

freezeAgreement

function freezeAgreement(uint256 agreementId) external onlyEmergencyAdminOrPoolAdmins
Freezes a specific agreement. Can only be called by an emergency admin or a pool admin.
Name
Type
Description
agreementId
uint256
The ID of the agreement to freeze.

unfreezeAgreement

function unfreezeAgreement(uint256 agreementId) external onlyPoolAdmin
Unfreezes a specific agreement. Can only be called by a pool admin.
Name
Type
Description
agreementId
uint256
The ID of the agreement to unfreeze.

freezeAllAgreements

function freezeAllAgreements() external onlyEmergencyAdminOrPoolAdmins
Freezes all agreements. Can only be called by an emergency admin or a pool admin.

unfreezeAllAgreements

function unfreezeAllAgreements() external onlyPoolAdmin
Unfreezes all agreements. Can only be called by a pool admin.

getAgreement

function getAgreement(uint256 agreementId) external view returns (Agreement memory agreement)
Returns the Agreement struct for a specific agreement ID.
Name
Type
Description
agreementId
uint256
The ID of the agreement to get.
Return Values
Type
Description
Agreement
The Agreement struct for the specified agreement ID.

Events

AgreementCreated

Emitted when a new agreement is created.
Name
Type
Description
agreementId
uint256
The ID of the newly created agreement.
assetType
DataTypes.AssetType
The type of asset locked (ERC20 or ERC721).
actionType
DataTypes.TimeLockActionType
The action to perform on the locked asset.
asset
address
The contract address of the locked asset.
tokenIdsOrAmounts
uint256[]
An array of token IDs (ERC721) or a single element array with the amount (ERC20).
beneficiary
address
The address that can claim the locked asset after the release time.
releaseTime
uint48
The timestamp when the asset can be claimed by the beneficiary.

AgreementClaimed

Emitted when an agreement is claimed and deleted.
Name
Type
Description
agreementId
uint256
The ID of the claimed agreement.
assetType
DataTypes.AssetType
The type of asset locked (ERC20 or ERC721).
actionType
DataTypes.TimeLockActionType
The action to perform on the locked asset.
asset
address
The contract address of the locked asset.
tokenIdsOrAmounts
uint256[]
An array of token IDs (ERC721) or a single element array with the amount (ERC20).
beneficiary
address
The address that claimed the locked asset.

AgreementFrozen

Emitted when an agreement is frozen or unfrozen.
Name
Type
Description
agreementId
uint256
The ID of the frozen or unfrozen agreement.
isFrozen
bool
A boolean indicating if the agreement is frozen (true) or unfrozen (false).

TimeLockFrozen

Emitted when all agreements are frozen or unfrozen.
Name
Type
Description
isFrozen
bool
A boolean indicating if all agreements are frozen (true) or unfrozen (false).

TimeLock V2 Suggestions:

  1. 1.
    Implement a protocol limit
    • Status: Under consideration
  2. 2.
    Remove waiting times for small transactions
    • Status: Under consideration
  3. 3.
    Introduce custom calculations for Uniswap V3 (decrease liquidity)
    • Status: Under consideration
  4. 4.
    Develop custom calculations for rebasing tokens (account for amount changes during extended timelocks)
    • Status: Under consideration
  5. 5.
    Enable support for Punk and ETH withdrawals
    • Status: Under consideration
  6. 6.
    Add specialized functionality for BorrowApeAndStake and flash claim operations
    • Status: Under consideration
  7. 7.
    Establish different pool limit waiting times tiers
    • Status: Under consideration
  8. 8.
    Integrate decentralized consensus for TimeLock
    • Status: Under consideration
  9. 9.
    AirDrop Support
    • Status: Under consideration