1. Core Vesting Architecture

Minimal Viable Implementation

module vesting::linear {  
    use sui::coin;  
    use sui::clock;  
    use sui::balance;  
    use sui::tx_context;  

    struct VestingSchedule has key {  
        id: UID,  
        recipient: address,  
        total_amount: u64,  
        start_time: u64,  // Clock timestamp  
        duration_ms: u64, // Total vesting period  
        claimed: u64  
    }  

    /// Initialize vesting  
    public entry fn create(  
        recipient: address,  
        total_amount: u64,  
        duration_ms: u64,  
        clock: &Clock,  
        ctx: &mut TxContext  
    ) {  
        let schedule = VestingSchedule {  
            id: object::new(ctx),  
            recipient,  
            total_amount,  
            start_time: clock.timestamp_ms,  
            duration_ms,  
            claimed: 0  
        };  
        transfer::transfer(schedule, recipient);  
    }  
}  

Key Components:

• Clock-based timestamps (not block numbers)
• Self-custodied schedule objects
• Linear vesting by default

---

2. Advanced Vesting Patterns

Cliff + Linear Vesting

public fun claimable_amount(  
    schedule: &VestingSchedule,  
    clock: &Clock  
): u64 {  
    let elapsed = clock.timestamp_ms.saturating_sub(schedule.start_time);  

    // Cliff period (e.g., 1 year)  
    if (elapsed < CLIFF_MS) return 0;  

    // Linear vesting after cliff  
    let vested = (schedule.total_amount * elapsed) / schedule.duration_ms;  
    vested - schedule.claimed  
}  

Graded Vesting (Multiple Milestones)

struct GradedVesting has key {  
    id: UID,  
    milestones: vector<Milestone>, // [{time: u64, percent: u8}]  
    claimed: u64  
}  

public fun graded_claimable(schedule: &GradedVesting, clock: &Clock): u64 {  
    let total_vested = 0;  
    let i = 0;  
    while (i < vector::length(&schedule.milestones)) {  
        let milestone = vector::borrow(&schedule.milestones, i);  
        if (clock.timestamp_ms >= milestone.time) {  
            total_vested = total_vested +  
                (schedule.total_amount * milestone.percent as u64) / 100;  
        };  
        i = i + 1;  
    };  
    total_vested - schedule.claimed  
}  

---

3. Security Enhancements

Revocable Vesting (Admin Controls)

struct AdminCap has key { id: UID }  

public entry fn revoke(  
    schedule: VestingSchedule,  
    admin_cap: &AdminCap,  
    ctx: &mut TxContext  
) {  
    assert!(address_of(signer) == admin_cap.admin, EUnauthorized);  
    let remaining = schedule.total_amount - schedule.claimed;  
    coin::transfer(remaining, admin_cap.admin, ctx);  
    object::delete(schedule);  
}  

Anti-Frontrunning

public entry fn claim(  
    schedule: &mut VestingSchedule,  
    clock: &Clock,  
    ctx: &mut TxContext  
) {  
    let amount = claimable_amount(schedule, clock);  
    assert!(amount > 0, ENothingToClaim);  
    assert!(tx_context::epoch(ctx) == clock.epoch(), EStaleClock);  

    schedule.claimed = schedule.claimed + amount;  
    transfer::public_transfer(coin::mint(amount, ctx), schedule.recipient);  
}  

---

4. Gas Optimization Techniques

Batch Vesting Schedules

struct BatchVesting has key {  
    id: UID,  
    schedules: Table<address, VestingSchedule>  
}  

// Claim all eligible in one TXN  
public entry fn batch_claim(batch: &mut BatchVesting, clock: &Clock) {  
    let iter = table::iter(&mut batch.schedules);  
    while (table::has_next(&iter)) {  
        let (addr, schedule) = table::next(&iter);  
        let amount = claimable_amount(schedule, clock);  
        if (amount > 0) transfer_coins(addr, amount);  
    }  
}  

Storage Rebates

// Use small types where possible  
struct CompactVesting {  
    start_time: u64,  
    duration_ms: u32, // Sufficient for 49-day periods  
    claimed: u64  
}  

---

5. Common Vulnerabilities

❌ Time Oracle Attacks

// UNSAFE: Trusting user-provided timestamps  
fun unsafe_claim(user_time: u64) { ... }  

❌ Rounding Errors

// May leave "dust" unclaimed  
let vested = (amount * elapsed) / duration; // Use checked_math  

❌ Missing Revocation Logic

// Irrevocable vesting may violate securities laws  
struct DangerousVesting { ... }  

---

6. Testing Strategies

Mock Clock Testing

#[test]  
fun test_cliff_period() {  
    let clock = mock_clock(0);  
    let schedule = create_vesting(CLIFF_MS * 2);  

    // Before cliff  
    test_clock::advance(&mut clock, CLIFF_MS - 1);  
    assert!(claimable(&schedule, &clock) == 0, ETestFail);  

    // After cliff  
    test_clock::advance(&mut clock, 1);  
    assert!(claimable(...) > 0, ETestFail);  
}  

Fuzz Testing

#[test]  
fun test_overflow_scenarios() {  
    let schedule = VestingSchedule {  
        start_time: u64::MAX - 1000,  
        duration_ms: 2000  
    };  
    // Should handle wrap-around correctly  
    claimable_amount(&schedule, &clock);  
}