TokenVestingLib

Central library containing vesting calculations and data structures used across all vesting contracts in the TokenOps system.

Library Information

File Location: contracts/libraries/TokenVestingLib.sol

Usage Pattern:

using TokenVestingLib for TokenVestingLib.Vesting;

Overview

The TokenVestingLib library serves as the core computational engine for major vesting operations in the TokenOps ecosystem. It provides gas-optimized calculations, standardized data structures, and consistent vesting logic across all manager types.

Key Features

• Gas-optimized calculations for vesting amounts with minimal computational overhead
• Packed struct design for efficient storage and reduced gas costs
• Consistent vesting logic across all manager types (standard, native, votes, milestone)
• Flexible schedule support with cliff periods, linear vesting, and initial unlocks
• Precision handling with truncated calculations for predictable release intervals

Data Structures

Vesting Struct

The core data structure representing a complete vesting schedule:

struct Vesting {
    address recipient;
    uint32 startTimestamp;
    uint32 endTimestamp;
    uint32 deactivationTimestamp;
    uint32 timelock;
    uint32 releaseIntervalSecs;
    uint32 cliffReleaseTimestamp;
    uint256 initialUnlock;
    uint256 cliffAmount;
    uint256 linearVestAmount;
    uint256 claimedAmount;
    bool isRevocable;
}

Field Descriptions:

Field	Type	Description	Constraints
recipient	address	Beneficiary who can claim vested tokens	Cannot be zero address
startTimestamp	uint32	When vesting schedule begins	Must be > 0, ≤ endTimestamp
endTimestamp	uint32	When vesting schedule completes	Must be ≥ startTimestamp
deactivationTimestamp	uint32	When vesting was revoked (0 = active)	Set by revocation, freezes vesting
timelock	uint32	Earliest time tokens can be claimed	Optional delay before first claim
releaseIntervalSecs	uint32	Frequency of linear releases	Must be > 0, divides vesting period
cliffReleaseTimestamp	uint32	When cliff amount is released	Between start and end if used
initialUnlock	uint256	Tokens unlocked immediately at start	Available regardless of time
cliffAmount	uint256	Tokens released at cliff timestamp	Released all at once
linearVestAmount	uint256	Tokens vested linearly over time	Released in intervals
claimedAmount	uint256	Tokens already withdrawn	Increases with claims
isRevocable	bool	Whether admin can revoke vesting	Determines revocation capability

VestingParams Struct

Parameter structure for vesting creation to avoid stack-too-deep errors:

struct VestingParams {
    bytes32 _vestingId;           // Unique vesting identifier
    address _recipient;           // Beneficiary address
    uint32 _startTimestamp;       // Vesting start time
    uint32 _endTimestamp;         // Vesting end time
    uint32 _timelock;             // Claim timelock
    uint256 _initialUnlock;       // Initial unlock amount
    uint32 _cliffReleaseTimestamp; // Cliff release time
    uint256 _cliffAmount;         // Cliff amount
    uint32 _releaseIntervalSecs;  // Release interval
    uint256 _linearVestAmount;    // Linear vesting amount
    bool _isRevocable;            // Revocable flag
}

Purpose: This struct is used exclusively for passing parameters to vesting creation functions, avoiding Solidity's stack depth limitations while maintaining code readability.

Functions

calculateVestedAmount

Calculate the vested amount for a given Vesting, at a given timestamp.

function calculateVestedAmount(Vesting memory _vesting, uint32 _referenceTimestamp) internal pure returns (uint256);

Parameters

Name	Type	Description
_vesting	Vesting	The vesting in question
_referenceTimestamp	uint32	Timestamp for which we're calculating

The TokenVestingLib library provides the mathematical foundation for vesting operations in the TokenOps ecosystem, ensuring consistent, efficient, and secure token distribution across all manager types.