How does token vesting work, and how is it different from a lock-up?

Three words

• Vesting. Releasing tokens to their owner over time, according to a schedule. In OpenZeppelin's code, the default schedule is a straight line.¹
• Cliff. A date before which nothing is released. OpenZeppelin's cliff version counts as vested zero tokens until the cliff date.¹
• Lock-up. For company shares, the SEC's investor website says a lock-up stops insiders selling for a set time after an initial public offering (IPO), when a company first sells shares to the public. Most last 180 days.²

Module 28 used vesting and cliffs for grant tokens.¹ This lesson looks inside the contract that does the work.

People mix the words up

Token projects often use the two words loosely. Arbitrum's documents say its team and investor tokens are subject to "4 year lockups", yet those tokens unlock every month after the first year.⁴ The SEC's lock-up page also says some share lock-ups limit how many shares can be sold over a period, not only when.²

In April 2025, staff at the US Securities and Exchange Commission (SEC) listed vesting and lock-ups among the supply details they had seen issuers disclose when offering crypto-related securities.⁵ So when you read a token's documents, look for the actual rule, whatever word is used.^5,4

How a vesting contract works

OpenZeppelin publishes open-source smart contract code. Its VestingWallet is a contract that holds tokens and releases them to an owner, called the beneficiary, on a schedule.¹

• Set-up. You give it a beneficiary, a start time and a duration.¹
• Late deposits. Tokens sent to it later follow the schedule "as if they were locked from the beginning".¹
• Vested so far. Before the start, nothing has vested. After the end, everything has. In between, the code works out total × time since the start ÷ duration.³
• Ready to release. What can be released now = what has vested − what was already released.³
• Release. The release function sends that amount to the wallet's owner.³

The cliff version adds one more rule. The cliff is measured from the start and can't be longer than the whole schedule.⁶ Before the cliff, the vested amount is 0. From the cliff on, it is the normal straight line, counted from the start.⁶ So every month before the cliff vests at once, on the cliff date.^6,3

A lock-up in code

OpenZeppelin says that if you set the duration to 0, the same contract acts as a timelock. It holds tokens for the beneficiary until a set time.¹ That is a lock-up in code: nothing, then everything at once.¹

What the code can't stop

OpenZeppelin warns that the vesting wallet itself can change hands, so "it is possible to sell unvested tokens".¹ A contract shows when tokens are released. It does not prove that nobody has sold the right to them.¹