Merge pull request #481 from CedarMist/CedarMist/rng-notes

Sapphire/Precompiles: add notes about <=0.5.2 eth_call RNG behavior + detail on how VRF works

Author: CedarMist

docs/dapp/sapphire/precompiles.md

@@ -60,14 +60,35 @@ Feel free to discover other convenient libraries for Solidity inside the
 * Gas cost: 10,000 minimum plus 240 per output word plus 60 per word of
   the personalization string.
 
-Generate `num_bytes` pseudo-random bytes, with an optional
-personalization string added into the hashing algorithm to increase
-domain separation when needed.
+Generate `num_bytes` pseudo-random bytes, with an optional personalization
+string (`pers`) added into the hashing algorithm to increase domain separation
+when needed.
 
 ```solidity
 bytes memory randomPad = Sapphire.randomBytes(64, "");
 ```
 
+### Implementation Details
+
+:::danger Prior to 0.6.0
+All view queries and simulated transactions (via `eth_call`) would receive the
+same entropy in-between blocks if they use the same `num_bytes` and `pers` parameters.
+If your contract requires confidentiality you should generate a secret in the constructor
+to be used with view calls:
+
+```solidity
+Sapphire.randomBytes(64, abi.encodePacked(msg.sender, this.perContactSecret));
+```
+:::
+
+The mode (e.g. simulation or 'view call' vs transaction execution) is fed to TupleHash (among other
+block-dependent components) to derive the "key id", which is then used to derive a per-block VRF key
+from epoch-ephemeral entropy (using KMAC256 and cSHAKE) so a different "key id" will result in a
+unique per-block VRF key. This per-block VRF key is then used to create the per-block root RNG which
+is then used to derive domain-separated (using Merlin transcripts) per-transaction random RNGs which
+are then exposed via this precompile. The KMAC, cSHAKE and TupleHash algorithms are SHA-3 derived functions
+defined in [NIST Special Publication 800-185](https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf).
+
 ## X25519 Key Derivation
 
 ### Overview