Time & Clock

The Clock sysvar provides slot, epoch, and unix_timestamp for time-based rules: expiries, vesting cliffs, and rate limits. Slots are discrete; timestamps are wall-clock approximations.

Recipe

let clock = Clock::get()?;
if clock.unix_timestamp > deadline { return Err(ProgramError::InvalidAccountData); }

When to reach for this:

• Escrow expiry.
• Vesting unlock.
• Cooldown between actions.

Working Example

pub fn assert_not_expired(deadline: i64) -> Result<(), ProgramError> {
    let now = Clock::get()?.unix_timestamp;
    if now > deadline { return Err(ProgramError::InvalidAccountData); }
    Ok(())
}

What this demonstrates:

• Clock::get() syscall.
• Compare unix_timestamp.
• Expired returns error.

Deep Dive

Slot vs Time

Manipulation

Validators have bounded timestamp drift - design grace periods.

Rust Notes

// Store i64 deadline at init from client or admin.

Gotchas

• Trust client timestamp arg alone - Forged if not from Clock. Fix: Always Clock::get().
• Slot assumption precise time - Slot duration varies slightly. Fix: Use unix for wall clock.
• No expiry on escrow - Locked forever. Fix: Mandatory deadline or cancel.
• Timestamp overflow - i64 bounds. Fix: Sanity check deadlines.
• Past deadline at init - Immediately expired. Fix: Validate on create.

Alternatives

FAQs

Related

• State Machines On-Chain - Timeouts
• Vault & Escrow - Escrow expiry
• Programs Basics - Runtime context

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.