FIP-0095: Document existing get_beacon_randomness syscall behaviour (#…

…1054)

FIPS/fip-0095.md

@@ -47,12 +47,42 @@ The precompile is callable at Ethereum address `0xfe00..06`.
 
 The call errors with `PrecompileError::InvalidInput` if the epoch is not a valid, prior epoch number.
 
-This calls directly to the FVM's `get_beacon_randomness` syscall, which returns a Blake2b hash digest of the 
-randomness value from the drand beacon at the associated Filecoin epoch.
+This calls directly to the FVM's `get_beacon_randomness` syscall.
 
-The existing syscall has a gas cost function that scales linearly with the number of epochs that have elapsed since 
+### Syscall Behaviour
+This section documents the semantics of the existing `get_beacon_randomness` syscall.
+It is descriptive, not normative.
+This FIP does not propose any change to the implemented behaviour, even if it differs from this description. 
+
+The `get_beacon_randomness` syscall returns a Blake2b-256 hash digest of the
+randomness value from the drand beacon corresponding to the requested Filecoin epoch. 
+This syscall has a gas cost function that scales linearly with the number of epochs that have elapsed since
 the requested epoch.
 
+#### Canonical behaviour
+Each Filecoin epoch maps to a drand round number.
+The drand round number for an epoch is given by `(epoch_time - drand_genesis_time) / drand_period + 1`.
+The drand beacon for this round number is expected to be found in the block header `BeaconEntries` field
+in every block in the tipset at that epoch.
+If the epoch number addresses an empty tipset, the beacon is found in the next non-empty tipset, 
+which `BeaconEntries` includes a beacon for each preceding null round.
+
+Note that not every drand beacon necessarily appears in a Filecoin tipset.
+Where the drand network has a faster epoch time than Filecoin, as is the case with Filecoin mainnet and
+the drand quicknet, only those drand beacons that correspond to a Filecoin tipset are accessible.
+
+#### Filecoin mainnet historical behaviour
+Due to changes in protocol specification over time, nodes participating in the Filecoin mainnet
+do not implement the canonical behaviour for all requested epochs.
+
+When the requested epoch corresponds to a null round and is:
+- prior to 892800 (network version 13): selects the last beacon entry from the preceding non-empty tipset;
+- between 892800 (v13) and 1231620 (v14): selects the last beacon entry from the next subsequent non-empty tipset;
+- between 1231620 (v14) and 1594680 (v15): calculates drand round number as `(epoch_time - drand_genesis_time) / drand_period` (off-by-one)
+
+In these cases, the beacon round number will not canonically correspond to the Filecoin epoch number.
+For requests from epoch 1594680 (v15) onwards, the canonical behaviour is implemented.
+
 ## Design Rationale
 The beacon value is provided in as raw a form as possible, given the FVM already hashes the beacon randomness.
 Including further entropy is left to the caller.
@@ -95,8 +125,5 @@ and one that is specifically useful for proofs of space and storage.
 ## Implementation
 Draft PR: https://github.com/filecoin-project/builtin-actors/pull/1577
 
-## TODO
-- Describe existing semantics of looking up beacon entries from chain
-
 ## Copyright
 Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).