Token Vesting Contract

Create a simple linear ERC-20 token vesting contract, test it with Foundry, and generate a vesting schedule CSV using Python.

This repository is designed to be useful for:

• startup token vesting
• team allocation vesting
• advisor vesting
• community or treasury token release planning

Supported platforms:

• macOS / Linux
• Windows with WSL 2

What This Repository Includes

• Solidity token vesting contract
• Foundry test suite
• Python vesting schedule generator
• GitHub Actions CI
• Makefile for local DevOps workflow
• .env.example for deployment configuration

Contract Overview

The contract supports:

• one ERC-20 token
• one beneficiary
• one linear vesting schedule
• partial release after vesting starts
• final release after vesting ends

Useful view functions:

• vestedAmount(timestamp)
• releasableAt(timestamp)
• releasable()
• remainingAllocation()
• fundingShortfall()

Beginner Method (macOS / Linux)

1. Open repo on GitHub.
2. Click Code -> Download ZIP.
3. Extract ZIP.
4. Open terminal in extracted folder.
5. Run:

chmod +x easy_start.sh
./easy_start.sh

What this does automatically:

• checks required tools
• checks Solidity formatting
• runs Solidity lint checks
• builds contracts
• runs Foundry tests
• validates Python script
• creates sample output file

Sample output file:

output/sample-vesting-schedule.csv

CSV columns:

• step
• timestamp_utc
• elapsed_days
• vested_amount_wei
• vested_percent

Manual Method (macOS / Linux)

cp .env.example .env
make ci-local

Manual Method (Windows)

Use WSL 2, then run the same Linux commands inside WSL.

Prerequisites

• Foundry
• Python 3.10+
• make

Install Foundry:

curl -L https://foundry.paradigm.xyz | bash
foundryup

Local Commands

Format:

make fmt

Lint:

make lint

Build:

make build

Test:

make test

Validate Python:

make pycheck

Generate vesting schedule CSV:

make schedule

Run full local CI flow:

make ci-local

Python Vesting Schedule Generator

Generate your own schedule file:

python3 scripts/vesting_schedule.py \
  --total-allocation 1000000000000000000000 \
  --start-date 2026-03-01 \
  --duration-days 365 \
  --interval-days 30 \
  --output output/vesting-schedule.csv

Example:

• total allocation = 1000 tokens with 18 decimals
• vesting start date = 2026-03-01
• vesting duration = 365 days
• one row every 30 days

Environment Variables

Copy .env.example to .env:

cp .env.example .env

Set these values:

RPC_URL=https://your-rpc-endpoint
PRIVATE_KEY=your_private_key_without_0x
TOKEN_ADDRESS=0xYourTokenAddress
BENEFICIARY_ADDRESS=0xYourBeneficiaryAddress
START_TIMESTAMP=1772323200
DURATION_SECONDS=31536000
TOTAL_ALLOCATION_WEI=1000000000000000000000

What these mean:

• RPC_URL: blockchain RPC endpoint
• PRIVATE_KEY: deployer wallet private key without 0x
• TOKEN_ADDRESS: ERC-20 token contract address
• BENEFICIARY_ADDRESS: receiver of vested tokens
• START_TIMESTAMP: vesting start in Unix timestamp
• DURATION_SECONDS: total vesting duration
• TOTAL_ALLOCATION_WEI: total token amount in smallest unit

Deploy

If .env is filled correctly:

chmod +x deploy.sh
./deploy.sh

Or pass values directly:

./deploy.sh \
  0xTokenAddress \
  0xBeneficiaryAddress \
  1772323200 \
  31536000 \
  1000000000000000000000

Project Structure

src/
  LinearTokenVesting.sol
  MockERC20.sol

test/
  LinearTokenVesting.t.sol

scripts/
  vesting_schedule.py

.github/workflows/
  ci.yml

.env.example
deploy.sh
easy_start.sh
foundry.toml
Makefile
requirements.txt
README.md

CI

GitHub Actions automatically runs:

• forge fmt --check
• forge lint
• forge build
• forge test --force -vv
• python3 -m py_compile scripts/*.py
• sample schedule generation

Important

• This project does not deploy automatically by itself.
• You must fund the vesting contract with tokens before release() can work.
• If the contract balance is lower than remaining vested tokens, fundingShortfall() shows the missing amount.
• Never commit .env.

Security

• audit before production use
• verify constructor values carefully
• protect deployer private keys
• test on testnet before mainnet

License

MIT. See LICENSE.