Skip to content

Update randomness doc #1281

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

Merged
merged 4 commits into from
May 12, 2025
Merged

Update randomness doc #1281

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9b29e4a
randomness doc
tarakby May 12, 2025
1c1577d
Update docs/tools/kit/index.md
briandoyle81 May 12, 2025
2726b23
Update docs/tools/kit/index.md
briandoyle81 May 12, 2025
c7b66b6
Update docs/tools/kit/index.md
tarakby May 12, 2025
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
11 changes: 6 additions & 5 deletions docs/tools/kit/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,11 +377,12 @@ function RandomValues() {

#### Notes:

* Randomness is generated using Flow’s **on-chain `revertibleRandom`**, producing pseudorandom values tied to block and transaction execution.
* The value returned for identical calls within the same block will be identical.
* This hook is designed for simple use cases that **don’t require a [commit-reveal scheme]**, such as randomized UIs.
* For **more advanced use cases** that **do** require a [commit-reveal scheme], Flow provides built-in support for that pattern.
* Values are **deterministic**: if a transaction fails and retries, the same random value will be regenerated.
* Randomness is generated using the **on-chain `revertibleRandom`** function on Flow, producing pseudorandom values tied to block and script execution.
* Values are **deterministic**: The values returned for identical calls within the same block will be identical.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is described here in determinism, so I moved the "deterministic" note here

* If `count ` is larger than one, the returned values are disctinct.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added this so that developers don't think determinism means all count values are equal

* This hook is designed for simple use cases that don't require unpredictability, such as randomized UIs.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

commit-reveal solves the reversibility issue, but here in the script nothing is reversible so commit-reveal doesn't add any advantage.

The main thing developers should be aware of is that the block random source in the lib is publicly known (since this is script-based). There is nothing wrong with that in many applications like the example mentioned here (UIs)

Since the hook uses script executions on existing blocks, the random source is already public and the randoms are predictable.
* For **more advanced use cases** that **do** require on-chain randomness logic via transactions, Flow provides built-in support using Cadence's `revertibleRandom` and [commit-reveal scheme].
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The more advanced cases are the ones with the logic fully on-chain via transactions (not scripts). This is where randomness is unpredictable, and reversibility can or cannot be an issue, so I added the mention of transactions here. Both "reversibleRandom" and "commit-reveal" work in that case depending on the app.


---

Expand Down