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
| Field | Use |
|---|---|
| slot | Leader schedule relative |
| unix_timestamp | Human expiry |
| epoch | Staking periods |
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
| Alternative | Use When | Don't Use When |
|---|---|---|
| Off-chain cron | Not binding | On-chain Clock |
| Slot-based only | Predictable | User confusion |
| Oracle time | Overkill | DeFi specific |
FAQs
Clock sysvar id?
Known constant - Sysvar::get.
Fake clock account?
Do not accept passed account - use get.
i64 negative?
Before 1970 rare - reject.
Duration lock?
store start + duration.
Vesting linear?
Compute unlocked = f(now).
Anchor Sysvar<Clock>?
Wrapper.
Test time?
LiteSVM warp clock.
Mainnet drift?
Small - not exploitable large.
Slot hash?
Different sysvar.
Rate limit?
last_action_ts in account.
Crank bots?
Anyone can call expire ix.
Agave 4.1.1?
Clock layout stable.
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.