Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix randomness warning callouts #1183

Merged
merged 1 commit into from
Mar 21, 2025
Merged

Fix randomness warning callouts #1183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 18 additions & 10 deletions docs/build/advanced-concepts/randomness.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,11 @@ Cadence has historically provided the `unsafeRandom` function to return a pseudo
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.
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`**.

<Callout type="warning">
:::warning

⚠️ Note `unsafeRandom` is deprecated since the Cadence 1.0 release.
</Callout>

:::

## Guidelines for Safe Usage

Expand All @@ -76,15 +78,19 @@ Although Cadence exposes safe randomness generated by the Flow protocol via `rev
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).
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:

<Callout type="warning">
:::warning

🚨 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.
</Callout>

:::

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

<Callout type="info">
💡 **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/).
</Callout>
:::info

**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/).

:::

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

Expand All @@ -109,9 +115,11 @@ On Flow, we have absorbed all security complexity into the platform.
[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.
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.

<Callout type="info">
💡 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).
</Callout>
:::info

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).

:::

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

Expand Down
8 changes: 6 additions & 2 deletions docs/evm/guides/vrf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,11 +154,15 @@ contract RandomInRange {
}
```

:::warning The above code is susceptible to the [modulo
:::warning

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

:::

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

Expand Down