TokenVesting Contract

⚠️ Important Notes

Read these carefully before using this contract to understand its limitations and proper usage.

• The deploying DAO/organization must ensure the native token follows the standard ERC20 implementation. Tokens with transfer restrictions, blocklists, or rebasing may cause issues.
• Only supports native tokens with 18 decimals—deployment will revert otherwise.
• Do not use rebasing tokens that decrease in balance, as this may cause calculation errors in vesting.
• Supports schedules up to 50 years and token amounts up to 2²⁰⁰ (~1.6 Tredecillion). Extreme cases require a custom solution.

Overview

The TokenVesting contract is an on-chain vesting solution that releases tokens gradually based on predefined schedules. The contract supports:

• Multiple vesting schedules per beneficiary.
• Revokable and non-revokable schedules.
• Non-transferable virtual ERC20 functionality.
• Role-based access control for security and flexibility.

Roles & Permissions

The contract uses AccessControl to manage permissions. Below are the key roles:

1. Owner

• The Owner has full administrative control.
• The owner automatically has both:
  • DEFAULT_ADMIN_ROLE
  • ROLE_CREATE_SCHEDULE
• Can perform the following actions:
  • Create vesting schedules for beneficiaries.
  • Revoke vesting schedules (if revocable).
  • Pause or unpause the contract.
  • Withdraw unvested tokens.
  • Grant or revoke roles (DEFAULT_ADMIN_ROLE holders can manage other roles).

2. DEFAULT_ADMIN_ROLE

• This is the highest level role and is assigned to the contract deployer (initial owner).
• Holders of this role can:
  • Grant and revoke roles, including ROLE_CREATE_SCHEDULE and DEFAULT_ADMIN_ROLE (admins can create more admins).
  • Transfer or renounce ownership (if the account is the owner).
• However, this role alone does NOT grant the ability to create or revoke schedules.
  • The account must also have ROLE_CREATE_SCHEDULE or be the owner.

3. ROLE_CREATE_SCHEDULE

• This role allows an account to create new vesting schedules.
• Initially granted to the contract deployer (owner).
• Cannot revoke vesting schedules (only the owner can revoke).
• Additional accounts can be assigned this role by the owner or a DEFAULT_ADMIN_ROLE holder.

4. Beneficiary

• A Beneficiary is an address that receives vested tokens.
• Can have multiple vesting schedules.
• Can release vested tokens once they become available.

Owner-Specific Functions

Only the Owner can perform the following actions:

Revoke a Vesting Schedule

• Only the owner can revoke a vesting schedule (if it was set as revocable).
• When revoked:
  • Any vested tokens are immediately released to the beneficiary.
  • Unvested tokens are returned to the contract balance.

🔹 NOTE: ROLE_CREATE_SCHEDULE holders cannot revoke schedules. Only the owner has this power.

Pause or Unpause Token Releases

• The owner can pause the contract to:
  • Prevent the release of vested tokens.
  • Stop the claiming of vesting schedules.
• Can be unpaused by the owner later.

Withdraw Unvested Tokens

• The owner can withdraw unallocated tokens (tokens not locked in a vesting schedule).

Renouncing Ownership

The owner has the ability to renounce ownership, which permanently removes their control over the contract.

What Happens When Ownership is Renounced?

• The owner loses all administrative rights.
• DEFAULT_ADMIN_ROLE is retained, but it does not grant direct control over the contract's core functions.
• The owner also loses ROLE_CREATE_SCHEDULE automatically.
• The following actions can no longer be performed:
  • Creating new vesting schedules.
  • Revoking vesting schedules.
  • Pausing or unpausing the contract.
  • Withdrawing unvested tokens.

What CAN Still Be Done After Ownership is Renounced?

• Beneficiaries can still release their vested tokens as usual.
• Existing vesting schedules will continue according to their defined rules.
• DEFAULT_ADMIN_ROLE holders can still manage roles, but since ROLE_CREATE_SCHEDULE is required for new schedules, no new schedules can be created unless it was previously assigned to another address.

🔹 If ownership is renounced and no other address has ROLE_CREATE_SCHEDULE, no new vesting schedules can ever be created.

Revoking Roles

Admins can revoke roles from any address using:

revokeRole(<ROLE_NAME_KECCAK>, userAddress);

Renouncing a Role

Users can voluntarily remove their own role with the renounceRole() function