Skip to content

Commit 625e22d

Browse files
fix randomness warning callouts (#1183)
1 parent b1a8402 commit 625e22d

File tree

2 files changed

+24
-12
lines changed

2 files changed

+24
-12
lines changed

docs/build/advanced-concepts/randomness.md

+18-10
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,11 @@ Cadence has historically provided the `unsafeRandom` function to return a pseudo
4747
1. The sequence of random numbers is potentially predictable by transactions within the same block and by other smart contracts calling into your smart contract.
4848
2. A transaction calling into your smart contract can potentially bias the sequence of random numbers which your smart contract internally generates. Currently, the block hash seeds `unsafeRandom`. Consensus nodes can *easily* bias the block hash and **influence the seed for `unsafeRandom`**.
4949

50-
<Callout type="warning">
50+
:::warning
51+
5152
⚠️ Note `unsafeRandom` is deprecated since the Cadence 1.0 release.
52-
</Callout>
53+
54+
:::
5355

5456
## Guidelines for Safe Usage
5557

@@ -76,15 +78,19 @@ Although Cadence exposes safe randomness generated by the Flow protocol via `rev
7678
The `revertibleRandom` function can be used safely in some applications where the transaction results are _not_ deliberately reverted after the random number is revealed (i.e. a trusted contract distributing random NFTs to registered users or onchain lucky draw).
7779
However, if applications require a non-trusted party (for instance app users) to submit a transaction calling a randomized (non-deterministic) contract, the developer must explicitly protect the stream of random numbers to not break the security guarantees:
7880

79-
<Callout type="warning">
81+
:::warning
82+
8083
🚨 A transaction can atomically revert all its action during its runtime and abort. Therefore, it is possible for a transaction calling into your smart contract to post-select favorable results and revert the transaction for unfavorable results.
81-
</Callout>
84+
85+
:::
8286

8387
In other words, transactions submitted by a non-trusted party are able to reject their results after the random is revealed.
8488

85-
<Callout type="info">
86-
💡 **Post-selection** - the ability for transactions to reject results they don't like - is inherent to any smart contract platform that allows transactions to roll back atomically. See this very similar [Ethereum example](https://consensys.github.io/smart-contract-best-practices/development-recommendations/general/public-data/).
87-
</Callout>
89+
:::info
90+
91+
**Post-selection** - the ability for transactions to reject results they don't like - is inherent to any smart contract platform that allows transactions to roll back atomically. See this very similar [Ethereum example](https://consensys.github.io/smart-contract-best-practices/development-recommendations/general/public-data/).
92+
93+
:::
8894

8995
The central aspect that a contract developer needs to think about is the following scenario:
9096

@@ -109,9 +115,11 @@ On Flow, we have absorbed all security complexity into the platform.
109115
[FLIP 123: On-chain Random beacon history for commit-reveal schemes](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#flip-123-on-chain-random-beacon-history-for-commit-reveal-schemes) was introduced to provide a safe pattern to use randomness in transactions so that it's not possible to revert unfavorable randomized transaction results.
110116
We recommend this approach as a best-practice example for implementing a commit-reveal scheme in Cadence. The `RandomBeaconHistory` contract provides a convenient archive, where for each past block height (starting Nov 2023) the respective "source of randomness" can be retrieved. The `RandomBeaconHistory` contract is automatically executed by the system at each block to store the next source of randomness value.
111117

112-
<Callout type="info">
113-
💡 While the commit-and-reveal scheme mitigates post-selection of results by adversarial clients, Flow's secure randomness additionally protects against any pre-selection vulnerabilities (like biasing attacks by byzantine miners).
114-
</Callout>
118+
:::info
119+
120+
While the commit-and-reveal scheme mitigates post-selection of results by adversarial clients, Flow's secure randomness additionally protects against any pre-selection vulnerabilities (like biasing attacks by byzantine miners).
121+
122+
:::
115123

116124
A commit-reveal scheme can be implemented as follows. The coin toss example described earlier will be used for illustration:
117125

docs/evm/guides/vrf.md

+6-2
Original file line numberDiff line numberDiff line change
@@ -154,11 +154,15 @@ contract RandomInRange {
154154
}
155155
```
156156

157-
:::warning The above code is susceptible to the [modulo
157+
:::warning
158+
159+
The above code is susceptible to the [modulo
158160
bias](https://research.kudelskisecurity.com/2020/07/28/the-definitive-guide-to-modulo-bias-and-how-to-avoid-it/),
159161
particularly if the random number range is not a multiple of your desired range. To avoid this, you can use a more
160162
complex algorithm like rejection sampling, an example for which is provided in [this
161-
repository](https://github.com/onflow/random-coin-toss). :::
163+
repository](https://github.com/onflow/random-coin-toss).
164+
165+
:::
162166

163167
## **Secure Randomness with Commit-Reveal Scheme in Solidity**
164168

0 commit comments

Comments
 (0)