Document caveats about timestamp and blockhash

2 files changed, 12 insertions, 18 deletions

diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst
index 8fd0c041..e4eee32b 100644
--- a/docs/frequently-asked-questions.rst
+++ b/docs/frequently-asked-questions.rst
@@ -125,24 +125,6 @@ Example::
         }
     }
 
-Are timestamps (``now,`` ``block.timestamp``) reliable?
-=======================================================
-
-This depends on what you mean by "reliable".
-In general, they are supplied by miners and are therefore vulnerable.
-
-Unless someone really messes up the blockchain or the clock on
-your computer, you can make the following assumptions:
-
-You publish a transaction at a time X, this transaction contains same
-code that calls ``now`` and is included in a block whose timestamp is Y
-and this block is included into the canonical chain (published) at a time Z.
-
-The value of ``now`` will be identical to Y and X <= Y <= Z.
-
-Never use ``now`` or ``block.hash`` as a source of randomness, unless you know
-what you are doing!
-
 Can a contract function return a ``struct``?
 ============================================
 
diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst
index 64795306..887535da 100644
--- a/docs/units-and-global-variables.rst
+++ b/docs/units-and-global-variables.rst
@@ -73,6 +73,18 @@ Block and Transaction Properties
     This includes calls to library functions.
 
 .. note::
+    Do not rely on ``block.timestamp``, ``now`` and ``block.blockhash`` as a source of randomness,
+    unless you know what you are doing.
+
+    Both the timestamp and the block hash can be influenced by miners to some degree.
+    Bad actors in the mining community can for example run a casino payout function on a chosen hash
+    and just retry a different hash if they did not receive any money.
+
+    The current block timestamp must be strictly larger than the timestamp of the last block,
+    but the only guarantee is that it will be somewhere between the timestamps of two
+    consecutive blocks in the canonical chain.
+
+.. note::
     If you want to implement access restrictions in library functions using
     ``msg.sender``, you have to manually supply the value of
     ``msg.sender`` as an argument.