Token vesting: unlocked is not the same as sold

Explainer6 min read

Understand token vesting, cliffs and linear schedules. Follow a worked example separating vested, releasable and released tokens from circulation and liquidity.

Brokzi checks fictional token T's day-90 ledger: 300 vested includes 100 released and 200 releasable, while 900 remain unvested. OpenZeppelin Docs is an implementation reference, not an asset logo or endorsement.
AI-assisted editorial illustration · Brokzi
On this page

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.

CheckpointVested TReleased TReleasable T
Day 20, before the cliff000
Day 30, before the example release1000100
Day 30, after releasing 100 T1001000
Day 90, with no further release300100200
Day 120, with no further release400100300
Day 360, with no further release1,2001001,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 quantityBefore the depositAfter the 400 T deposit
Token balance in the vesting wallet680 T1,080 T
Total allocation used by the formula800 T1,200 T
Vested at 60 of 120 days400 T600 T
Already released120 T120 T
Releasable at that timestamp280 T480 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:

  1. Is the number a cumulative vested amount, a newly available tranche, a remaining claim or a completed release?
  2. Does the cliff include earlier elapsed time, and what happens after it?
  3. Are the quantities displayed tokens or raw contract units? Our token-decimals guide explains the conversion.
  4. Does a transaction record establish a release, rather than merely a scheduled date?
  5. 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.

See something wrong? Brokzi logs material changes. Prepare a correction note.

About the byline

Brokzi Editorial

The accountable byline for Brokzi’s explainers, definitions, news notes, and corrections.

Editorial responsibility →