Token Vesting Contract

The core logic defining how and when tokens are released. Common patterns include:

• Cliff Period: An initial lock-up period where no tokens are released.
• Linear Vesting: Tokens are released in equal increments (e.g., daily, monthly) after the cliff.
• Graded Vesting: Tokens are released in large, discrete chunks at specific milestones.
• Custom Schedules: Can be tailored for complex scenarios like performance-based releases.

Defines the key parties involved in the vesting agreement.

• Beneficiary: The wallet address that receives the vested tokens over time.
• Granter (or Owner): The entity (e.g., project treasury, investor) that deposits the tokens into the contract and sets the terms. The granter often retains administrative rights to revoke or modify the schedule under defined conditions.

A critical feature determining if a vesting schedule can be altered or canceled.

• Revocable Vesting: The granter (e.g., a project DAO) retains the right to claw back unvested tokens, typically for cause (e.g., an employee leaving).
• Irrevocable Vesting: The schedule is immutable once initiated, providing maximum security for the beneficiary. This is common for investor and public sale allocations.

The process by which vested tokens become accessible.

• Automatic Release: Vested tokens are sent to the beneficiary's wallet automatically at each interval.
• Pull-Based Claim: The beneficiary must actively call a claim() or release() function to transfer the available vested balance to their wallet. This is the most gas-efficient and common design, putting the onus on the beneficiary.

Describes how the underlying tokens are secured during the vesting period.

• The total grant amount is transferred into the vesting contract's custody (escrow) upon initialization.
• The contract's balance represents the pool of locked tokens. Only the vested portion becomes claimable over time, preventing the granter from spending the committed funds.

Token vesting contracts are deployed in specific, high-stakes scenarios:

• Team & Advisor Allocations: To align long-term incentives, typically with 3-4 year schedules.
• Investor Lock-ups: To prevent immediate sell pressure after private sale rounds.
• Ecosystem Grants & Rewards: For releasing funds to developers or community members based on deliverables or milestones.
• Token Sale Vesting: For public sale participants, often with a short cliff to prevent bots and flippers.

A canonical example of team and investor vesting in a major decentralized protocol. Uniswap's UNI token allocated a significant portion to team, investors, and advisors with a 4-year linear vesting schedule and a 1-year cliff. This structure:

• Aligns Incentives: Ensures long-term commitment from core contributors.
• Manages Supply Inflation: Prevents large, immediate sell pressure.
• Sets a Precedent: Established a common vesting template for subsequent DeFi projects.

The de facto standard model for equity-like token distribution. It combines two phases:

• Cliff Period: A duration (e.g., 1 year) during which no tokens are released. Serves as a probationary period.
• Linear Vesting: After the cliff, tokens are released linearly over the remaining vesting period (e.g., monthly over 3 years). This model balances immediate incentive alignment (via the cliff) with long-term retention (via linear release).

Vesting contracts often have administrator roles with powerful privileges, such as pausing distributions, revoking unvested tokens, or modifying schedules. This creates a single point of failure and centralization risk. A compromised private key or malicious insider could freeze or steal funds. Best practices include:

• Using multi-signature wallets or DAO governance for administrative actions.
• Implementing timelocks on critical functions.
• Clearly documenting and limiting admin capabilities in the contract's Slither or MythX audit report.

Flaws in the vesting schedule calculation can lead to incorrect token distributions. Common issues include:

• Integer overflow/underflow in older Solidity versions, potentially allowing premature full unlocks.
• Rounding errors that advantage either the beneficiary or the treasury over time.
• Timestamp manipulation where block timestamps are used unreliably for schedule milestones, vulnerable to miner influence.
• Reentrancy attacks on the withdrawal function if state updates are not performed before external calls (check-effects-interaction pattern).

Risks related to the parties and assets involved include:

• Lost or Inaccessible Wallets: If a beneficiary loses their private key, vested tokens may be permanently locked in the contract.
• Non-Standard Token Compliance: The contract must safely handle ERC-20 tokens that may not follow the standard perfectly (e.g., tokens with fees on transfer, or ones that return false instead of reverting).
• Revocable vs. Irrevocable: The conditions under which the grantor can revoke unvested tokens must be unambiguous and tamper-proof to prevent abuse.

Many vesting contracts use proxy patterns (e.g., Transparent or UUPS) for upgradability, which introduces additional attack vectors:

• Storage collision between the proxy and implementation logic contracts.
• Uninitialized implementation contracts that an attacker could take over.
• Malicious upgrades that could change vesting terms or drain funds if upgrade permissions are not properly secured.
• Use of audited, standard upgradeability frameworks like OpenZeppelin's is strongly recommended to mitigate these risks.

The transparent nature of blockchain mempools can be exploited in vesting scenarios:

• Schedule Manipulation: An attacker could front-run a transaction that sets a vesting schedule to insert a more favorable one for themselves.
• Withdrawal Sniping: When a large vesting cliff expires, bots can monitor for the beneficiary's withdrawal transaction and front-run it to execute their own transactions first, potentially impacting token price (a form of MEV).
• Mitigations include using commit-reveal schemes for schedule setting or private transaction relays.

A comprehensive security review for a vesting contract should verify:

• Access Control: Are admin functions properly restricted and behind timelocks?
• Math: Are vesting calculations correct for all edge cases (start time, cliff, duration)?
• Token Handling: Does it handle all ERC-20 return values and potential fee-on-transfer tokens?
• State Integrity: Is the contract safe from reentrancy and protected against flash loan attacks if it involves governance tokens?
• Documentation: Is the NatSpec documentation clear and match the code? Always seek audits from multiple reputable firms.

A cliff period is an initial lock-up phase at the start of a vesting schedule during which no tokens are released. After the cliff expires, a large initial grant is typically unlocked, followed by regular linear vesting.

• Purpose: Prevents immediate dumping and ensures commitment.
• Example: A 1-year cliff with a 4-year vesting schedule means no tokens are released for the first year, then 25% unlock, followed by monthly releases for the remaining 3 years.

A token lockup is a broader mechanism that prevents the transfer or sale of tokens for a specified period. It is often implemented via a smart contract or a simple time-lock on a wallet. Unlike vesting, lockups are typically all-or-nothing releases.

• Common Use Cases: Team allocations, investor tokens post-ICO, or treasury funds.
• Key Difference: Vesting implies gradual release; a lockup implies a single release event after a deadline.

Linear vesting is the most common release schedule where tokens become available continuously over time, usually in equal increments per block, day, or month. It is defined by a start time, duration, and total grant amount.

• Mechanism: Tokens vest in a straight-line fashion. For example, 1,000 tokens vesting linearly over 1,000 days releases 1 token per day.
• Smart Contract Function: Often calculated as vestedAmount = (totalGrant * (currentTime - startTime)) / vestingDuration.

Accelerated vesting is a clause or event that causes tokens to vest faster than the original schedule. It is often triggered by specific conditions defined in the contract.

• Common Triggers: Company acquisition (single-trigger), or acquisition combined with employee termination (double-trigger).
• Contract Design: Requires mutable logic to adjust the vesting rate or cliff based on oracle inputs or authorized admin calls.

A time-lock contract is a smart contract that enforces a mandatory delay between the proposal and execution of a transaction. It is a core governance primitive for DAOs and protocol treasuries.

• Primary Function: Prevents sudden, unilateral changes by administrators or governance bodies.
• Relation to Vesting: While vesting releases assets to individuals, time-locks delay administrative actions (e.g., upgrading a contract, spending treasury funds).