Skip to main content

Lockup

A "vesting" smart contract that can implement token lockup with scheduled release and distribution:

  • Can enforce a scheduled release of tokens (e.g. investment lockups)
  • Smart contract enforced lockup schedules are used to control the circulating supply and can be an important part of tokenomics.
  • Some lockups are cancelable - such as employee vestings. When canceled, unlocked tokens remain in the recipients account address and locked tokens are returned to an address specified by the administrator that has an appropriate transfer group to receive the tokens.

Note that tokens in lockups cannot be burned by admins to avoid significant complexity. In order to burn those tokens, first cancelTimelock so they are removed from the timelock, and then burn them.

superBalanceOf​

There are 3 classes of token types: simple tokens, unlocked tokens, and locked tokens. Locked and unlocked tokens are tokens supplied to the user via either fundReleaseSchedule or mintReleaseSchedule, but still evaluated within the timelock.

Unlocked tokens become removed from the timelock once they are transferred, and then are converted into simple tokens. A user's full balance of tokens consists of the sum of their simple, unlocked, and locked tokens. Cancelling a timelock also converts the unlocked tokens into simple tokens that become burnable.

Convenience Balance Methods​

  • unlockedBalanceOf: tokens that are ONLY supplied via fundReleaseSchedule or mintReleaseSchedule that have been unlocked but not yet transferred out (ie not yet "removed" from the timelock). Includes unlocked tokens across all timelocks.
  • superBalanceOf: simple tokens belonging to the wallet. Does not include locked or unlocked tokens still within timelocks.
  • unlockedTotalBalanceOf: the sum of unlockedBalanceOf and superBalanceOf, ie the total amount of tokens available to the wallet to transfer. Includes unlocked tokens across all timelocks.
  • lockedBalanceOf: tokens that are ONLY supplied via fundReleaseSchedule or mintReleaseSchedule that are still locked. Includes unlocked tokens across all timelocks.
  • balanceOf: the sum of unlockedBalanceOf, lockedBalanceOf, and superBalanceOf. The total balance belonging to the wallet. Not all of this balance is tradeable though, as this includes locked tokens too.
  • lockedBalanceOfTimelock: locked balance for a wallet within a specific timelock.
  • unlockedBalanceOfTimelock: unlocked balance for a wallet within a specific timelock.

fundReleaseSchedule vs mintReleaseSchedule​

Lockups, also referred to as token release schedules, are distinguished between funded and minted types. Funded release schedules are done using already-minted tokens that are owned by any admin. These are akin to a type of token transfer and thus must adhere to transfer restrictions.

Release schedules can also be minted directly to recipients by the Reserve Admin. In this case, as it is akin to token minting, it does not have to adhere to transfer restrictions, and is purely under the discretion of the Reserve Admin.

This is described in RestrictedLockupToken.sol.