How to build a smart contract for a token vesting schedule?

A token vesting contract ensures gradual token release for investors and team members, promoting long-term commitment and market stability.

Jul 12, 2025 at 02:01 pm

Understanding Token Vesting Schedules in Smart Contracts

Token vesting schedules are mechanisms used in blockchain projects to gradually release tokens to investors, team members, or advisors over a set period. This ensures long-term commitment and prevents sudden market dumps that could destabilize the token price. Building a smart contract for a token vesting schedule involves defining parameters such as start time, cliff duration, vesting duration, and release frequency.

A well-structured vesting contract must include logic for locking tokens initially and releasing them incrementally based on predefined conditions.

---

Selecting the Right Blockchain and Tools

Most token vesting contracts are built on Ethereum-compatible blockchains using Solidity, though alternatives like Rust (for Solana) or Vyper exist. For this guide, we focus on Solidity-based development for EVM-compatible chains.

• Choose a development framework like Hardhat or Truffle to streamline compilation, testing, and deployment.
• Use OpenZeppelin libraries for secure and audited implementations of ERC20 and vesting contracts.
• Set up a local node environment using tools like Ganache or Alchemy for testing purposes.

---

Designing the Structure of the Vesting Contract

The core structure of a vesting contract revolves around tracking beneficiaries, their allocation, and the schedule for token release.

Key components include:

• Beneficiary addresses – who receives the vested tokens.
• Release start timestamp – when the vesting begins.
• Cliff duration – a waiting period before any tokens are released.
• Vesting duration – total time over which tokens are released.
• Revocability flag – optional feature allowing cancellation under certain conditions.

Each beneficiary’s data should be stored in a struct for clarity and efficient access.

---

Implementing the Vesting Logic in Solidity

To implement a basic vesting contract:

1. Import necessary OpenZeppelin contracts – especially IERC20 and SafeERC20.

2. Define the VestingSchedule struct with fields like totalAllocation, releasedAmount, startTime, cliffDuration, and vestingDuration.

3. Create a mapping from address to VestingSchedule to track each beneficiary's details.

4. Add a function to initialize vesting schedules for multiple beneficiaries by the owner.

5. Write a claim function that calculates how much can be withdrawn based on elapsed time since the start.

6. Ensure proper access control using Ownable or Roles-based permissions.

Here’s a simplified code snippet:

pragma solidity ^0.8.0;
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
contract TokenVesting is Ownable {
using SafeERC20 for IERC20;

struct VestingSchedule {
    uint256 totalAllocation;
    uint256 releasedAmount;
    uint256 startTime;
    uint256 cliffDuration;
    uint256 vestingDuration;
}

IERC20 public token;
mapping(address => VestingSchedule) public vestingSchedules;

constructor(address _tokenAddress) {
    token = IERC20(_tokenAddress);
}

function addVestingSchedule(
    address beneficiary,
    uint256 totalAllocation,
    uint256 startTime,
    uint256 cliffDuration,
    uint256 vestingDuration
) external onlyOwner {
    require(vestingSchedules[beneficiary].totalAllocation == 0, "Schedule already exists");

    vestingSchedules[beneficiary] = VestingSchedule({
        totalAllocation: totalAllocation,
        releasedAmount: 0,
        startTime: startTime,
        cliffDuration: cliffDuration,
        vestingDuration: vestingDuration
    });
}

function claim() external {
    VestingSchedule storage schedule = vestingSchedules[msg.sender];
    require(schedule.totalAllocation > 0, "No vesting schedule found");

    uint256 amount = releasableAmount(msg.sender);
    require(amount > 0, "Nothing to claim");

    schedule.releasedAmount += amount;
    token.safeTransfer(msg.sender, amount);
}

function releasableAmount(address beneficiary) public view returns (uint256) {
    VestingSchedule memory schedule = vestingSchedules[beneficiary];

    if (block.timestamp < schedule.startTime + schedule.cliffDuration) {
        return 0;
    }

    uint256 elapsedTime = block.timestamp - schedule.startTime;
    if (elapsedTime >= schedule.vestingDuration) {
        return schedule.totalAllocation - schedule.releasedAmount;
    }

    uint256 vestedAmount = (schedule.totalAllocation * elapsedTime) / schedule.vestingDuration;
    return vestedAmount - schedule.releasedAmount;
}
}

---

Testing and Deploying the Vesting Contract

Before deploying to a live network, thorough testing is essential.

• Write unit tests covering edge cases like claiming before cliff, after full vesting, and partial claims.
• Simulate different timestamps using Hardhat’s time helpers.
• Check ownership controls to ensure only authorized parties can add schedules.
• Deploy the contract using scripts and verify it on block explorers like BscScan or Etherscan.
• Fund the contract with the appropriate number of tokens before initializing schedules.

Once deployed, use front-end interfaces or direct calls via wallets like MetaMask or tools like Remix to interact with the contract.

---

Frequently Asked Questions

Q: Can I modify a vesting schedule after it has been set?

A: Typically, once a vesting schedule is added, it cannot be modified unless explicitly coded with an update function. Most projects prefer immutability for trust reasons.

Q: What happens if a beneficiary loses access to their wallet?

A: The tokens remain locked in the contract until claimed. There is no recovery mechanism unless the contract includes an emergency transfer function, which is discouraged for security reasons.

Q: Is revoking a vesting schedule possible?

A: Yes, but only if the contract supports revocation logic. Revocable vesting allows the owner to cancel future claims, typically used for team members leaving a project.

Q: How do I handle multiple token types in a single vesting contract?

A: You would need to either deploy separate contracts per token or design a multi-token vesting contract with additional mappings and checks for each token address.