From 3a1e125ce38cc58b3593bb17e1789318af087824 Mon Sep 17 00:00:00 2001
From: Tyera Eulberg <tyera@solana.com>
Date: Wed, 28 Oct 2020 17:01:24 -0600
Subject: [PATCH] Add Clock sysvar details, update struct docs

---
 docs/src/apps/sysvars.md | 22 ++++++++++++++++++++++
 sdk/program/src/clock.rs |  5 +++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/src/apps/sysvars.md b/docs/src/apps/sysvars.md
index 42a59de7a8..0af3cfa4a7 100644
--- a/docs/src/apps/sysvars.md
+++ b/docs/src/apps/sysvars.md
@@ -20,6 +20,28 @@ epoch, and estimated wall-clock Unix timestamp. It is updated every slot.
 
 - Address: `SysvarC1ock11111111111111111111111111111111`
 - Layout: [Clock](https://docs.rs/solana-program/VERSION_FOR_DOCS_RS/solana_program/clock/struct.Clock.html)
+- Fields:
+  - `slot`: the current slot
+  - `epoch_start_timestamp`: the Unix timestamp of the first slot in this epoch. In the first slot of an epoch, this timestamp is identical to the `unix_timestamp` (below).
+  - `epoch`: the current epoch
+  - `leader_schedule_epoch`: the most recent epoch for which the leader schedule has already been generated
+  - `unix_timestamp`: the Unix timestamp of this slot.
+
+  Each slot has an estimated duration based on Proof of History. But in reality,
+  slots may elapse faster and slower than this estimate. As a result, the Unix
+  timestamp of a slot is generated based on oracle input from voting validators.
+  This timestamp is calculated as the stake-weighted median of timestamp
+  estimates provided by votes, bounded by the expected time elapsed since the
+  start of the epoch.
+
+  More explicitly: for each slot, the most recent vote timestamp provided by
+  each validator is used to generate a timestamp estimate for the current slot
+  (the elapsed slots since the vote timestamp are assumed to be
+  Bank::ns_per_slot). Each timestamp estimate is associated with the stake
+  delegated to that vote account to create a distribution of timestamps by
+  stake. The median timestamp is used as the `unix_timestamp`, unless the
+  elapsed time since the `epoch_start_timestamp` has deviated from the expected
+  elapsed time by more than 25%.
 
 ## EpochSchedule
 
diff --git a/sdk/program/src/clock.rs b/sdk/program/src/clock.rs
index 26244aa1c2..1a55a81ff5 100644
--- a/sdk/program/src/clock.rs
+++ b/sdk/program/src/clock.rs
@@ -86,7 +86,8 @@ pub struct Clock {
     /// the future Epoch for which the leader schedule has
     ///  most recently been calculated
     pub leader_schedule_epoch: Epoch,
-    /// computed from genesis creation time and network time
-    ///  in slots, drifts!
+    /// originally computed from genesis creation time and network time
+    /// in slots (drifty); corrected using validator timestamp oracle as of
+    /// timestamp_correction and timestamp_bounding features
     pub unix_timestamp: UnixTimestamp,
 }