A calendar says tokens unlock today. That leaves several unanswered questions: which allocation, what rule, whether anyone claimed it, and whether any tokens reached a market.
This token vesting explainer follows a time-based Ethereum contract example. It is a way to read a schedule, not a claim that every project uses the same implementation or that an upcoming unlock predicts a price move.
Three balances that an unlock headline can blur
OpenZeppelin's finance documentation describes a wallet that holds assets for a beneficiary under a customizable schedule. Its default curve is linear. The names of its separate balance functions are useful even if you never write Solidity:
- Vested: the cumulative amount the schedule makes available by a particular time.
- Released: the amount already transferred out through the release mechanism.
- Releasable: the vested amount minus what was released.
In the version 5.6.1 implementation, reading a releasable balance does not move tokens. A separate release call transfers the available amount to the owner. Reaching a time threshold and completing that transfer are different events.
A fictional 1,200-token schedule
Assume a normal token T with no rebases, fees or extra deposits. A wallet starts with 1,200 T. It follows a linear schedule lasting 360 days, with a 30-day cliff. Days here are fixed 24-hour periods, not calendar months. These are teaching quantities, not an actual token's dates or allocation.
For this example, nothing vests before the cliff. From day 30, cumulative vesting follows time elapsed since the original start:
vested T = 1,200 × elapsed days / 360
At day 30, 1,200 × 30 / 360 = 100 T. Suppose the full 100 T is then released. At day 90, cumulative vesting is 1,200 × 90 / 360 = 300 T. With no further release, 300 − 100 = 200 T remains releasable. The previously released amount still counts toward the cumulative 300 T.
| Checkpoint | Vested T | Released T | Releasable T |
|---|---|---|---|
| Day 20, before the cliff | 0 | 0 | 0 |
| Day 30, before the example release | 100 | 0 | 100 |
| Day 30, after releasing 100 T | 100 | 100 | 0 |
| Day 90, with no further release | 300 | 100 | 200 |
| Day 120, with no further release | 400 | 100 | 300 |
| Day 360, with no further release | 1,200 | 100 | 1,100 |
After the 100 T release, the wallet still holds 1,100 T. At day 90 that balance consists of 200 T available now plus 900 T not yet vested. Calling the entire balance "locked" or "unlocked" would hide that split.
What the cliff does, and what it does not promise
The checked OpenZeppelin cliff extension returns zero before its cliff, then uses the inherited curve. In our example, the first available amount therefore includes time counted from the original start. It does not restart a fresh 360-day clock at day 30.
Other designs can use different rules. Read the actual schedule rather than inferring a lump sum or a new linear period from the word "cliff."
The base wallet's documentation also warns that later deposits follow the original timeline, ownership can be transferred, and rebasing assets need special accounting. Our fixed-allocation arithmetic excludes those cases. It is not a deployed-contract audit.
What happens if tokens arrive after vesting starts?
In the plain linear OpenZeppelin VestingWallet v5.6.1, a deposit joins the existing schedule. The ERC-20 calculation uses the wallet’s current token balance plus the amount already released. If half the schedule has elapsed, half of a new deposit can become releasable as soon as the wallet receives it.
Take a separate fictional example with 800 T, a 120-day schedule and no cliff. The wallet released 120 T on day 30, when 200 T had vested. On day 60, the beneficiary still has only that earlier release. The wallet receives another 400 T. Compare the two states at the same day-60 timestamp, with no release between them.
| Day-60 quantity | Before the deposit | After the 400 T deposit |
|---|---|---|
| Token balance in the vesting wallet | 680 T | 1,080 T |
| Total allocation used by the formula | 800 T | 1,200 T |
| Vested at 60 of 120 days | 400 T | 600 T |
| Already released | 120 T | 120 T |
| Releasable at that timestamp | 280 T | 480 T |
The deposit adds 200 T to the amount available for release. The other 200 T from the deposit follows the rest of the original schedule. The 120 T already released stays in the calculation of total allocation and is subtracted when calculating the amount still available. A separate release would have to occur for the newly available tokens to reach the beneficiary.
This example assumes a conventional ERC-20 token with a full 400 T credit, no rebasing or transfer fees, and the unmodified base wallet. A custom schedule can use a different rule. The cliff example above keeps its original fixed allocation.
An unlock is not a circulating-supply measurement
CoinGecko's methodology describes its token circulating-supply calculation using total supply minus identified locked balances, with information obtained from token teams and checked by CoinGecko. That is a provider's methodology, not a universal output from a vesting calendar.
Consider our 100 T release. It proves only the modeled movement to the beneficiary. We have not established how a particular provider classifies that holder's balance, when its data updates or whether a restriction still applies elsewhere. Adding the calendar's entire allocation to every circulating-supply field would skip those checks.
Nor did the release create a buyer. Our example has no order book, trading pair or pool reserves. It therefore cannot calculate sale proceeds, market impact or cash available for holders. The market-cap versus liquidity explainer covers those separate measurements.
How to read an unlock entry without guessing the outcome
Keep the exact token and network together with the beneficiary allocation, schedule source and timestamp. Then check:
- Is the number a cumulative vested amount, a newly available tranche, a remaining claim or a completed release?
- Does the cliff include earlier elapsed time, and what happens after it?
- Are the quantities displayed tokens or raw contract units? Our token-decimals guide explains the conversion.
- Does a transaction record establish a release, rather than merely a scheduled date?
- Which provider defines circulation, and what independent evidence supports any claim about trading?
Use the network-and-contract checklist if the asset itself is ambiguous. A familiar ticker and a precise-looking unlock countdown do not resolve identity.
You can understand this distinction without connecting a wallet, making a claim or sending funds. A schedule tells you what its rules permit. Evidence of a release, circulation and a sale must answer their own questions.
Sources
Sources checked 17 October 2026. The OpenZeppelin documentation and v5.6.1 base wallet were checked again on 15 November 2026. Numerical balances, day counts and release events above are fictional and independently calculated. No live unlock calendar, deployed allocation, liquidity or price was measured.
- OpenZeppelin Contracts 5.x: Finance: schedule API and implementation caveats.
- OpenZeppelin VestingWallet.sol, version 5.6.1: separate vested, released and releasable accounting.
- OpenZeppelin VestingWalletCliff.sol, version 5.6.1: zero before the cliff, then the inherited schedule.
- CoinGecko methodology: its circulating-supply definitions, not evidence of a sale.
See something wrong? Brokzi logs material changes. Prepare a correction note.




