Token Vesting Contract Example With Lumos: A Detailed Guide

by Alex Johnson 60 views

In the realm of blockchain and tokenomics, token vesting plays a crucial role in ensuring the long-term sustainability and equitable distribution of tokens. This article delves into creating a comprehensive token vesting contract example using Lumos, a powerful tool for generating code from schemas. We will explore the schema design, code generation, and the implementation of a full-stack example that demonstrates the practical application of token vesting.

Understanding Token Vesting

Token vesting is a mechanism used to distribute tokens over a specific period, rather than all at once. This approach is beneficial for several reasons:

  • Incentivizing long-term commitment: Vesting schedules encourage stakeholders, such as team members, advisors, and investors, to remain committed to the project's success over time.
  • Preventing market dumping: By releasing tokens gradually, vesting reduces the risk of large amounts of tokens being sold off at once, which can negatively impact the token's price.
  • Aligning incentives: Vesting aligns the interests of token holders with the long-term goals of the project, as they benefit from the token's success over time.

There are several common types of vesting schedules, including:

  • Cliff vesting: Tokens are locked for an initial period (the "cliff"), after which they are released in a single batch.
  • Linear vesting: Tokens are released gradually over a specific period, typically on a monthly or quarterly basis.
  • Cliff and linear vesting: A combination of both, where tokens are locked for a cliff period and then released linearly over time.

In this article, we will focus on implementing a token vesting contract that supports cliff and linear vesting, providing a flexible solution for token distribution.

Goal: Building a Token Vesting Contract with Lumos

Our primary goal is to construct a complete token vesting contract example that showcases Lumos' capabilities for token distribution. This involves creating a contract that allows for the scheduling and management of token vesting, ensuring that tokens are released to beneficiaries according to predefined rules. Lumos simplifies this process by enabling us to define the structure of our contract using a schema, from which code can be automatically generated.

Key Objectives

To achieve our goal, we will focus on the following key objectives:

  1. Define a .lumos schema for vesting: This schema will specify the structure of our vesting contract, including details such as the beneficiary, token mint, vesting schedule, and other relevant parameters.
  2. Generate Rust and TypeScript code: Using the .lumos schema, we will generate both Rust code for the smart contract logic and TypeScript code for the frontend interface.
  3. Develop a full-stack example: We will build a complete application with an Anchor vesting program, a TypeScript frontend for managing vesting schedules, and the necessary logic for cliff and linear vesting calculations.
  4. Deploy to devnet: Finally, we will deploy our token vesting contract to a development network (devnet) to demonstrate its functionality in a live environment.

Scope: Defining the Components of Our Token Vesting Contract

To build a robust token vesting contract example, we need to define the scope of our project carefully. This involves identifying the key components and functionalities that our contract will support. The following elements are within the scope of our project:

1. .lumos Schema for Vesting

We will create a .lumos schema that defines the structure of our vesting contract. This schema will include the following elements:

  • VestingSchedule: This struct will hold information about individual vesting schedules, including the beneficiary's public key, the token mint address, the total amount of tokens to be vested, the amount already released, the start time of the vesting period, the cliff duration, the vesting duration, and whether the schedule is revocable.
  • VestingPool: This struct will represent a pool of tokens available for vesting. It will include the authority responsible for managing the pool, the token mint address, the total number of vesting schedules, and the total amount of tokens allocated to the pool.
  • VestingType: This enum will define the different types of vesting schedules supported by our contract, such as linear, cliff, and cliff-linear vesting.

2. Generated Rust + TypeScript Code

Using the .lumos schema, we will generate Rust code for the smart contract logic and TypeScript code for the frontend interface. This will significantly reduce the amount of manual coding required and ensure consistency between the backend and frontend.

  • Rust Code: The generated Rust code will include the data structures and functions necessary to manage vesting schedules, calculate token releases, and handle other contract-related logic.
  • TypeScript Code: The generated TypeScript code will provide the necessary types and functions for interacting with the smart contract from the frontend, making it easier to build a user interface for managing vesting schedules.

3. Full-Stack Example

We will develop a full-stack example application that demonstrates the functionality of our token vesting contract. This application will include:

  • Anchor Vesting Program: We will use the Anchor framework to build our vesting program, leveraging its features for smart contract development on Solana.
  • TypeScript Frontend: We will create a TypeScript frontend that allows users to manage vesting schedules, view released tokens, and perform other actions related to vesting.
  • Cliff and Linear Vesting Calculations: We will implement the necessary logic for calculating token releases based on cliff and linear vesting schedules.

4. Deployment to Devnet

To showcase the practical application of our token vesting contract, we will deploy it to a development network (devnet). This will allow users to interact with the contract in a live environment and test its functionality.

Expected Schemas: Defining the Data Structures

To create a functional token vesting contract, we need to define the data structures that will store information about vesting schedules and pools. Lumos allows us to define these structures using a schema, which can then be used to generate code. Here are the schemas we expect to use:

#[solana]
#[account]
struct VestingSchedule {
    beneficiary: PublicKey,
    token_mint: PublicKey,
    total_amount: u64,
    released_amount: u64,
    start_time: i64,
    cliff_duration: i64,
    vesting_duration: i64,
    revocable: bool,
}

#[solana]
#[account]
struct VestingPool {
    authority: PublicKey,
    token_mint: PublicKey,
    total_schedules: u64,
    total_allocated: u64,
}

#[solana]
enum VestingType {
    Linear,
    Cliff,
    CliffLinear,
}

VestingSchedule

The VestingSchedule struct holds the details of an individual vesting schedule. Let's break down each field:

  • beneficiary: The PublicKey of the individual or entity who will receive the vested tokens.
  • token_mint: The PublicKey of the token that will be vested.
  • total_amount: The total number of tokens to be vested, represented as a u64.
  • released_amount: The number of tokens that have already been released to the beneficiary, also represented as a u64.
  • start_time: The timestamp (in seconds since the Unix epoch) when the vesting period begins, represented as an i64.
  • cliff_duration: The duration (in seconds) of the cliff period, represented as an i64.
  • vesting_duration: The total duration (in seconds) of the vesting period, including the cliff period, represented as an i64.
  • revocable: A boolean value indicating whether the vesting schedule can be revoked by the authority.

VestingPool

The VestingPool struct represents a pool of tokens that can be distributed according to vesting schedules. Here are its fields:

  • authority: The PublicKey of the individual or entity who has the authority to manage the vesting pool.
  • token_mint: The PublicKey of the token that is held in the pool.
  • total_schedules: The total number of vesting schedules associated with the pool, represented as a u64.
  • total_allocated: The total number of tokens allocated to vesting schedules within the pool, represented as a u64.

VestingType

The VestingType enum defines the different types of vesting schedules that our contract will support:

  • Linear: Tokens are released gradually over time, starting after the cliff period (if any).
  • Cliff: All tokens are released at the end of the cliff period.
  • CliffLinear: A combination of both, where tokens are locked for a cliff period and then released linearly over the remaining vesting duration.

Location: Organizing Our Project

To maintain a well-structured project, we will add our token vesting contract example to the awesome-lumos/examples/token-vesting/ directory. This location will help keep our example organized and easily accessible to others who want to learn about Lumos and token vesting.

Success Criteria: Measuring Our Progress

To ensure that our token vesting contract example meets our goals, we have defined several success criteria. These criteria will help us measure our progress and ensure that we deliver a high-quality example.

  • Working Anchor vesting program: Our Anchor program should function correctly, allowing users to create, manage, and interact with vesting schedules.
  • TypeScript frontend for schedule management: The frontend should provide a user-friendly interface for managing vesting schedules, viewing released tokens, and performing other related actions.
  • Cliff and linear vesting logic: The contract should accurately calculate token releases based on cliff and linear vesting schedules.
  • Deployed to devnet with live demo: We should successfully deploy our contract to a development network and provide a live demo to showcase its functionality.
  • Complete documentation: We will provide comprehensive documentation that explains how to use our token vesting contract and the underlying Lumos concepts.
  • Schedule visualization (optional): As an added bonus, we may include a visualization of the vesting schedules to make it easier for users to understand the token release timeline.

Phase and Type

This project falls under Phase 4.2 - Community Examples, indicating that it is a community-driven effort to showcase Lumos' capabilities. The Type of this project is an Example Application, as it aims to provide a practical demonstration of how Lumos can be used to build a token vesting contract.

Conclusion

In conclusion, building a token vesting contract example using Lumos is a valuable endeavor that will demonstrate the power and flexibility of Lumos for token distribution. By defining a clear schema, generating code, and creating a full-stack example, we can provide a comprehensive resource for developers interested in implementing token vesting mechanisms. This article has laid out the goals, scope, expected schemas, and success criteria for our project, setting the stage for a successful implementation. Understanding token vesting is crucial for projects looking to incentivize long-term commitment and ensure fair token distribution. By using Lumos, we can streamline the development process and create robust, reliable vesting contracts.

For further reading on blockchain development and smart contracts, you might find valuable information on websites like ConsenSys. This resource can provide additional insights and best practices for building secure and efficient blockchain applications.