Clarify that Timestamp is not reliably close to real time

[algoanne]

Is your addition related to a problem? Please describe. In traditional development, we're used to being able to count on getting a timestamp whenever we want, and it'll reflect real time very closely. In the blockchain world, this is no longer always the case - it's hard to get everyone to agree on the exact time in a distributed system, because of the inherent latency of communication.

On Algorand, this is the relevant piece of code: https://github.com/algorand/go-algorand/blob/1504f5f39ec2893d2b0ac9b60d1b87f6e7d4e2fc/data/bookkeeping/block.go#L478-L485 In other words, unless block proposers are colluding evilly, timestamp will only ever be at most a few seconds ahead of real time. However, it can be significantly behind real time if there is ever network downtime: each block can only move forward at most 25 seconds in timestamp.

For example, if the network is down for 1 hour, timestamp will fall behind real time by 3600 seconds, and then every round it's catching up by 25-4.5 sec (current lambda) so 20.5 seconds closer to current time. So it takes 3600/20.5 = 175 rounds to catch up, or 175*4.5 = 790 seconds = 13 minutes. Or something like that!

Describe the solution you'd like I leave it to you exactly where we need to document this better, but anyone writing a smart contract needs to understand this.

Describe alternatives you've considered I've thought about us renaming timestamp to something like "rough timestamp" but not sure that's actually something we want to do.

Additional context We know for a fact that some existing dapp devs have missed this detail, and it could cause serious problems for their app if we ever do have downtime.