From 3e229b248fb712275bf376b5c470be5cb6193b30 Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Sun, 5 Jan 2020 23:16:04 -0800
Subject: [PATCH] Update getBlockTime rpc docs (#7688) (#7689)

automerge
---
 book/src/api-reference/jsonrpc-api.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/book/src/api-reference/jsonrpc-api.md b/book/src/api-reference/jsonrpc-api.md
index 25ec503e2b..dff0f40db0 100644
--- a/book/src/api-reference/jsonrpc-api.md
+++ b/book/src/api-reference/jsonrpc-api.md
@@ -213,9 +213,17 @@ curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1, "m
 
 ### getBlockTime
 
-Returns the estimated production time of a block. Validators report their UTC
-time to the ledger on a regular interval. A block's time is calculated as an
-offset from the median value of the most recent validator time report.
+Returns the estimated production time of a block.
+
+Each validator reports their UTC time to the ledger on a regular interval by
+intermittently adding a timestamp to a Vote for a particular block. A requested
+block's time is calculated from the stake-weighted mean of the Vote timestamps
+in a set of recent blocks recorded on the ledger.
+
+Nodes that are booting from snapshot or limiting ledger size (by purging old
+slots) will return null timestamps for blocks below their lowest root +
+`TIMESTAMP_SLOT_RANGE`. Users interested in having this historical data must
+query a node that is built from genesis and retains the entire ledger.
 
 #### Parameters: