From 1564fd4d29159de67460d1110b9aabf8553ecd95 Mon Sep 17 00:00:00 2001 From: cshannon1218 Date: Tue, 11 Nov 2025 16:08:34 -0600 Subject: [PATCH 1/6] Native VRF doc edits --- .../native-vrf/commit-reveal-cadence.md | 93 ++++++++++--------- .../native-vrf/index.md | 18 ++-- .../native-vrf/vrf-in-solidity.md | 26 +++--- 3 files changed, 70 insertions(+), 67 deletions(-) diff --git a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md index 77a16a3ecf..7907d113fc 100644 --- a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md +++ b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md @@ -19,68 +19,70 @@ keywords: # Secure Randomness with Commit-Reveal in Cadence -Randomness is a critical component in blockchain applications, enabling fair and unpredictable outcomes for use cases like gaming, lotteries, and cryptographic protocols. The most basic approach to generating a random number on EVM chains is to utilize block hashes, which combines the block hash with a user-provided seed and hashes them together. The resulting hash can be used as a pseudo-random generator seed. However, this approach has limitations. The block hash can be manipulated by a validator influencing the random source used to compute transactions. The block proposer has the freedom to decide what to include into a block and can through different combinations till they find a favorable random source. +Randomness is a critical component in blockchain applications. It allows fair and unpredictable outcomes for use cases like gaming, lotteries, and cryptographic protocols. -[Chainlink VRF][chainlink-vrf] is a popular tool that improves on this by providing another approach for generating provably random values on Ethereum and other blockchains by relying on a decentralized oracle network to deliver cryptographically secure randomness from off-chain sources. However, this dependence on external oracles introduces several weaknesses, such as cost, latency, and scalability concerns. +The most basic approach that you can use to generate a random number on EVM chains is to use block hashes, which combines the block hash with a user-provided seed and hashes them together. You can use the has that results as a pseudo-random generator seed. However, this approach has limitations. A validator that influences the random source used to compute transactions can manipulate the block hash. The block proposer can decide what to include into a block and can through different combinations until they find a favorable random source. -In contrast, Flow offers a simpler and more integrated approach with its native onchain Randomness Beacon at the protocol level, eliminating reliance on external oracles and sidestepping their associated risks. +[Chainlink VRF][chainlink-vrf] is a popular tool that improves on this. It provides another approach you can use to generate provably random values on Ethereum and other blockchains. It relies on a decentralized oracle network to deliver cryptographically secure randomness from off-chain sources. However, this dependence on external oracles introduces several weaknesses, such as cost, latency, and scalability concerns. -In addition to instant randomness that is available to any transaction (via `revertibleRandom` function), Flow provides a solution to reverted transaction. Commit-Reveal schemes on Flow also rely on protocol-native secure randomness and they fix the issue of post-selection by trustless users. Commit-Reveal tools on Flow can be used within both Cadence and Solidity smart contracts. This tutorial will focus on the Cadence case. +In contrast, Flow offers a simpler and more integrated approach with its native onchain Randomness Beacon at the protocol level, which eliminates reliance on external oracles and sidestepping their associated risks. + +In addition to instant randomness that is available to any transaction (via `revertibleRandom` function), Flow provides a solution to reverted transaction. Commit-Reveal schemes on Flow also rely on protocol-native secure randomness and they fix the issue of post-selection by trustless users. Commit-Reveal tools on Flow can be used within both Cadence and Consumer Decentralized Finance (DeFi) contracts. This tutorial focuses on Cadence. ## Objectives By the end of this guide, you will be able to: -- Deploy a Cadence smart contract on the Flow blockchain -- Implement commit-reveal pattern for randomness to ensure fairness -- Interact with onchain randomness features on Flow -- Build and test the Coin Toss game using the Flow Testnet +- Deploy a Cadence smart contract on the Flow blockchain. +- Implement commit-reveal pattern for randomness to ensure fairness. +- Interact with onchain randomness features on Flow. +- Build and test the Coin Toss game with the Flow Testnet. ## Prerequisites You'll need the following: -- Flow Testnet Account: An account on the Flow Testnet with test FLOW tokens for deploying contracts and executing transactions (e.g., via [Flow Faucet][flow-faucet]). -- Flow CLI or Playground: The Flow CLI or Flow Playground for deploying and testing contracts (install via [Flow Docs][flow-docs]). +- Flow Testnet Account: an account on the Flow Testnet with test FLOW tokens to deploy contracts and execute transactions (for example, via [Flow Faucet][flow-faucet]). +- Flow CLI or Playground: the Flow CLI or Flow Playground to deploy and test contracts (install via [Flow Docs][flow-docs]). ## Overview In this guide, we will explore how to use a commit-reveal scheme based on the Flow Random Beacon to achieve secure, non-revertible randomness. This mechanism mitigates post-selection attacks, where participants attempt to reject unfavorable random outcomes after they are revealed. -To illustrate this concept, we will build a Coin Toss game on Flow, demonstrating how smart contracts can leverage a commit-reveal scheme for fair, tamper-resistant results. +To illustrate this concept, we will build a Coin Toss game on Flow, which demonstrates how smart contracts can leverage a commit-reveal scheme for fair, tamper-resistant results. ![Commit Reveal](./imgs/commit-reveal.png) ### What is the Coin Toss Game? -The Coin Toss Game is a decentralized betting game that showcases the commit-reveal pattern. Players place bets without knowing the random outcome, ensuring fairness and resistance to manipulation. +The Coin Toss Game is a decentralized betting game that showcases the commit-reveal pattern. Players place bets without knowing the random outcome, which ensures fairness and resistance to manipulation. The game consists of two distinct phases: -1. Commit Phase - The player places a bet by sending Flow tokens to the contract. The contract records the commitment to use a future random value from the Flow Random Beacon. The player receives a Receipt, which they will use to reveal the result later. -2. Reveal Phase - Once the random value becomes available in the `RandomBeaconHistory` contract, the player submits their Receipt to determine the outcome: +1. Commit Phase - To place a bet, the player sends Flow tokens to the contract. The contract records the commitment to use a future random value from the Flow Random Beacon. The player receives a Receipt, which they will use to reveal the result later. +2. Reveal Phase - When the random value becomes available in the `RandomBeaconHistory` contract, the player submits their Receipt to determine the outcome: - If the result is 0, the player wins and receives double their bet. - If the result is 1, the player loses, and their bet remains in the contract. -### Why Use a Commit-Reveal scheme? +### Why use a Commit-Reveal scheme? Similarly to revertible randomness, Commit-Reveal inherits the security of Flow native randomness beacon: - Ensures security - The Flow Random Beacon provides cryptographically unpredictable and non-biased randomness. - Ensure fairness - The Flow Random Beacon uses a Verifiable Random Function (VRF) under the hood which allows any external client or user to verify that randoms were generated fairly. -- Reduces reliance on external oracles - The randomness is generated natively onchain, avoiding additional complexity, third party risk and cost. +- Reduces reliance on external oracles - The randomness is generated natively onchain, and avoids additional complexity, third party risk and cost. In addition, commit-reveal patterns solve the issue of revertible randoms: -- Prevents user manipulation - Players cannot selectively reveal results after seeing the random results. +- Prevents user manipulation - Players cannot selectively reveal results after they see the random results. -## Building the Coin Toss Contract +## Build the Coin Toss contract -In this section, we'll walk through constructing the `CoinToss.cdc` contract, which contains the core logic for the Coin Toss game. To function properly, the contract relies on supporting contracts and a proper deployment setup. +In this section, we'll walk through how to construct the `CoinToss.cdc` contract, which contains the core logic for the Coin Toss game. To function properly, the contract relies on supporting contracts and a proper deployment setup. -This tutorial will focus specifically on writing and understanding the `CoinToss.cdc` contract, while additional setup details can be found in the [original GitHub repo][github-repo]. +This tutorial will focus specifically on how to write and understand the `CoinToss.cdc` contract, while you can find additional setup details in the [original GitHub repo][github-repo]. -### Step 1: Defining the `CoinToss.cdc` Contract +### Step 1: Define the `CoinToss.cdc` contract Let's define our `CoinToss.cdc` and bring the other supporting contracts. @@ -105,9 +107,9 @@ access(all) contract CoinToss { } ``` -### Step 2: Implementing the Commit Phase With `flipCoin` +### Step 2: Implement the commit phase with `flipCoin` -Let's define the first step in our scheme; the commit phase. We do this through a `flipCoin` public function. In this method, the caller commits a bet. The contract takes note of a future block height and bet amount, returning a `Receipt` resource which is used by the former to reveal the coin toss result and determine their winnings. +Let's define the first step in our scheme; the commit phase. We do this through a `flipCoin` public function. In this method, the caller commits a bet. The contract takes note of a future block height and bet amount and returns a `Receipt` resource, which the former uses to reveal the coin toss result and determine their winnings. ```cadence access(all) fun flipCoin(bet: @{FungibleToken.Vault}): @Receipt { @@ -124,10 +126,11 @@ access(all) fun flipCoin(bet: @{FungibleToken.Vault}): @Receipt { } ``` -### Step 3: Implementing the Reveal Phase With `revealCoin` +### Step 3: Implement the reveal phase With `revealCoin` + +Now we implement the reveal phase with the `revealCoin` function. Here, the caller provides the Receipt they recieve at commitment. The contract then "flips a coin" with `_randomCoin()` providing the Receipt's contained Request. The reveal step is possible only when the protocol random source at the committed block height becomes available. -Now we implement the reveal phase with the `revealCoin` function. Here the caller provides the Receipt given to them at commitment. The contract then "flips a coin" with `_randomCoin()` providing the Receipt's contained Request. The reveal step is possible only when the protocol random source at the committed block height becomes available. -If result is 1, user loses, but if it's 0 the user doubles their bet. Note that the caller could condition the revealing transaction, but they've already provided their bet amount so there's no loss for the contract if they do. +If result is 1, the user loses, but if it's 0, the user doubles their bet. Note that the caller could condition the revealed transaction, but they've already provided their bet amount, so there's no loss for the contract if they do. ```cadence access(all) fun revealCoin(receipt: @Receipt): @{FungibleToken.Vault} { @@ -155,18 +158,18 @@ access(all) fun revealCoin(receipt: @Receipt): @{FungibleToken.Vault} { } ``` -The final version of `CoinToss.cdc` should look like [this contract code][coin-toss-contract-code]. +The final version of `CoinToss.cdc` will look like [this contract code][coin-toss-contract-code]. -## Testing CoinToss on Flow Testnet +## Test CoinToss on Flow Testnet -To make things easy, we've already deployed the `CoinToss.cdx` contract for you at this address: [0xb6c99d7ff216a684][coin-toss-contract]. We'll walk through placing a bet and revealing the result using [run.dnz][run-dnz], a Flow-friendly tool similar to Ethereum's Remix. +To make things easy, we've already deployed the `CoinToss.cdx` contract for you at this address: [0xb6c99d7ff216a684][coin-toss-contract]. We'll walk through how to place a bet and reveal the result with [run.dnz][run-dnz], a Flow-friendly tool similar to Ethereum's Remix. -### Placing a Bet with flipCoin +### Place a bet with flipCoin -First, you'll submit a bet to the CoinToss contract by withdrawing Flow tokens and storing a receipt. Here's how to get started: +First, you'll submit a bet to the CoinToss contract. To do this, you'll withdraw Flow tokens and store a receipt. Here's how to get started: -1. Open Your Dev Environment: Head to [run.dnz][run-dnz]. -2. Enter the Transaction Code: Paste the following Cadence code into the editor: +1. Open Your Dev Environment: head to [run.dnz][run-dnz]. +2. Enter the Transaction Code: paste the following Cadence code into the editor: ```cadence import FungibleToken from 0x9a0766d93b6608b7 @@ -197,16 +200,16 @@ transaction(betAmount: UFix64) { } ``` -3. Set Your Bet: A modal will pop up asking for the betAmount. Enter a value (e.g., 1.0 for 1 Flow token) and submit -4. Execute the Transaction: Click "Run," and a WalletConnect window will appear. Choose Blocto, sign in with your email, and hit "Approve" to send the transaction to Testnet. +3. Set Your Bet: a window will appear that asks for the betAmount. Enter a value (such as 1.0 for 1 Flow token) and submit. +4. Execute the Transaction: click "Run," and a WalletConnect window will appear. Choose Blocto, sign in with your email, and click "Approve" to send the transaction to Testnet. ![remix5-sc](./imgs/remix5.png) 5. Track it: You can take the transaction id to [FlowDiver][flow-diver][.io](https://testnet.flowdiver.io/tx/9c4f5436535d36a82d4ae35467b37fea8971fa0ab2409dd0d5f861f61e463d98) to have a full view of everything that's going on with this `FlipCoin` transaction. -### Revealing the Coin Toss Result +### Reveal the coin toss result -Let's reveal the outcome of your coin toss to see if you've won. This step uses the receipt from your bet, so ensure you're using the same account that placed the bet. Here's how to do it: +Let's reveal the outcome of your coin toss to see if you've won. This step uses the receipt from your bet, so ensure you use the same account that placed the bet. Here's how to do it: 1. Return to your Dev Environment: Open [run.dnz][run-dnz] again. 2. Enter the Reveal Code: Paste the following Cadence transaction into the editor: @@ -215,7 +218,7 @@ Let's reveal the outcome of your coin toss to see if you've won. This step uses import FlowToken from 0x7e60df042a9c0868 import CoinToss from 0xb6c99d7ff216a684 -/// Retrieves the saved Receipt and redeems it to reveal the coin toss result, depositing winnings with any luck +/// Retrieves the saved Receipt, redeems it to reveal the coin toss result, and deposits the winnings with any luck /// transaction { @@ -238,27 +241,27 @@ transaction { } ``` -After running this transaction, we reveal the result of the coin flip and it's 1! Meaning we have won nothing this time, but keep trying! +After we run this transaction, we reveal the result of the coin flip and it's 1! It means we haven't won anything this time, but keep trying! You can find the full transaction used for this example, with its result and events, at [FlowDiver.io/tx/][flow-diver-tx]. ## Conclusion -The commit-reveal scheme, implemented within the context of the Flow Randomness Beacon, provides a robust solution for generating secure and non-revertible randomness in decentralized applications. By leveraging this mechanism, developers can ensure that their applications are: +The commit-reveal scheme, implemented within the context of the Flow Randomness Beacon, provides a robust solution to generate secure and non-revertible randomness in decentralized applications. When developers leverage this mechanism, they can ensure that their applications are: -- Fair: Outcomes remain unbiased and unpredictable. -- Resistant to post-selection: Protects against trustless users who cannot reverse their commitments. +- Fair: outcomes remain unbiased and unpredictable. +- Resistant to post-selection: protects against trustless users who cannot reverse their commitments. -The CoinToss game serves as a practical example of these principles in action. By walking through its implementation, you've seen firsthand how straightforward yet effective this approach can be—balancing simplicity for developers with robust security for users. As blockchain technology advances, embracing such best practices is essential to creating a decentralized ecosystem that upholds fairness and integrity, empowering developers to innovate with confidence. +The CoinToss game serves as a practical example of these principles in action. Now that you've walked through its implementation, you've seen firsthand how straightforward yet effective this approach can be, as it balances simplicity for developers with robust security for users. As blockchain technology advances, it's essential that you embrace such best practices to create a decentralized ecosystem that upholds fairness and integrity, which empowers developers to innovate with confidence. This tutorial has equipped you with hands-on experience and key skills: - You deployed a Cadence smart contract on the Flow blockchain. - You implemented commit-reveal to ensure fairness. - You interacted with onchain randomness features on Flow. -- You built and tested the Coin Toss game using the Flow Testnet. +- You built and tested the Coin Toss game with the Flow Testnet. -By harnessing the built-in randomness capabilities on Flow, you can now focus on crafting engaging, user-centric experiences without grappling with the complexities or limitations of external systems. This knowledge empowers you to create secure, scalable, and fair decentralized applications. +When you harness the built-in randomness capabilities on Flow, you can create engaging, user-centric experiences without grappling with the complexities or limitations of external systems. This knowledge empowers you to create secure, scalable, and fair decentralized applications. [chainlink-vrf]: https://docs.chain.link/vrf [flow-faucet]: https://faucet.flow.com/fund-account diff --git a/docs/blockchain-development-tutorials/native-vrf/index.md b/docs/blockchain-development-tutorials/native-vrf/index.md index d23ddd1564..9babac89a0 100644 --- a/docs/blockchain-development-tutorials/native-vrf/index.md +++ b/docs/blockchain-development-tutorials/native-vrf/index.md @@ -20,29 +20,29 @@ keywords: # Native VRF (Built-in Randomness) Tutorials -Flow is a **blockchain with built-in randomness**, powered by its native **VRF (Verifiable Random Function)** capabilities. Unlike other blockchains that require external oracles, Flow's **Random Beacon** provides cryptographically secure randomness **at the protocol level**. Eliminating extra costs, reducing latency, and improving reliability for decentralized applications. +Flow is a **blockchain with built-in randomness**, powered by its native **VRF (Verifiable Random Function)** capabilities. Unlike other blockchains that require external oracles, Flow's **Random Beacon** provides cryptographically secure randomness **at the protocol level**. This elimiates extra costs, reduces latency, and improves reliability for decentralized applications. -These tutorials cover how to implement secure randomness directly in both **Cadence** and **Solidity** smart contracts on Flow. Whether you're building on Flow's native environment or Flow EVM, you can generate unbiased, verifiable random values without third-party dependencies. +These tutorials cover how to implement secure randomness directly in both **Cadence** and **Solidity** smart contracts on Flow. Whether you build on Flow's native environment or Flow EVM, you can generate unbiased, verifiable random values without third-party dependencies. ## Tutorials ### [Secure Randomness with Commit-Reveal in Cadence] -Learn how to implement secure randomness in Cadence using Flow's commit-reveal scheme, ensuring fairness and resistance to manipulation. +Learn how to implement secure randomness in Cadence with Flow's commit-reveal scheme, which ensures fairness and resistance to manipulation. ### [VRF (Randomness) in Solidity] -Learn how to use Flow's **native verifiable randomness** in Solidity smart contracts on Flow EVM, including best practices, security considerations, and complete code examples. +Learn how to use Flow's **native verifiable randomness** in Consumer Decentralized Finance (DeFi) contracts on Flow EVM, which includes best practices, security considerations, and complete code examples. -## Why Flow for Randomness? +## Why Flow for randomness? -- Protocol-level randomness: No need for external oracles or APIs. +- Protocol-level randomness: no need for external oracles or APIs. -- Lower costs: Built-in randomness means no extra transaction fees. +- Lower costs: built-in randomness means no extra transaction fees. -- Enhanced security: Cryptographically secure and verifiable onchain. +- Enhanced security: cryptographically secure and verifiable onchain. -- Cross-language support: Works seamlessly in both Cadence and Solidity. +- Cross-language support: Wwrks seamlessly in both Cadence and Consumer DeFi. - Speed: Flow is a [fast blockchain] with the design goal of 1,000,000 transactions per second. diff --git a/docs/blockchain-development-tutorials/native-vrf/vrf-in-solidity.md b/docs/blockchain-development-tutorials/native-vrf/vrf-in-solidity.md index 15c85ff004..1a9eaf61ee 100644 --- a/docs/blockchain-development-tutorials/native-vrf/vrf-in-solidity.md +++ b/docs/blockchain-development-tutorials/native-vrf/vrf-in-solidity.md @@ -14,17 +14,17 @@ keywords: - DeFi --- -## Introduction +# VRF (Randomness) in Solidity -Flow provides secure, native onchain randomness that developers can leverage through Cadence Arch, a precompiled contract available on the Flow EVM environment. This guide walks you through how Solidity developers can use Cadence Arch to access Flow's verifiable randomness using Solidity. +Flow provides secure, native onchain randomness that developers can leverage through Cadence Arch, a precompiled contract available on the Flow EVM environment. This guide walks you through how Consumer Decentralized Finance (DeFi) developers can use Cadence Arch to access Flow's verifiable randomness with Consumer DeFi. ### What is Cadence Arch? -[Cadence Arch] is a precompiled smart contract that allows Solidity developers on Flow EVM to interact with Flow's randomness and other network features like block height. This contract can be accessed using its specific address, and Solidity developers can make static calls to retrieve random values and other information. +[Cadence Arch] is a precompiled smart contract that allows DeFi developers on Flow EVM to interact with Flow's randomness and other network features like block height. This contract can be accessed with its specific address, and DeFi developers can make static calls to retrieve random values and other information. ## Prerequisites -- Basic Solidity knowledge +- Basic DeFi knowledge - Installed Metamask extension - Remix IDE for compilation and deployment - Flow EVM Testnet setup in Metamask @@ -43,7 +43,7 @@ Make sure you review the Solidity version of the [commit reveal] to learn more a ## Obtaining testnet FLOW -You can fund your account with testnet FLOW using the [Flow Faucet]. +You can fund your account with testnet FLOW with the [Flow Faucet]. Enter your Flow-EVM testnet address, and you'll receive testnet FLOW tokens to interact with smart contracts. @@ -81,7 +81,7 @@ contract CadenceArchCaller { The `revertibleRandom()` function makes a static call to the `revertibleRandom()` function to fetch a pseudo-random number. If the call is successful, it decodes the result as a `uint64` random value. -## Deploying and testing the contract +## Deploy and test the contract ### Compile and deploy the contract @@ -90,11 +90,11 @@ contract CadenceArchCaller { ![Creating file in Remix](./imgs/vrf-2.png) -3. Compile the contract by selecting the appropriate Solidity compiler version (0.8.x). +3. To compile the contract, select the appropriate Consumer DeFi compiler version (0.8.x). ![Compiling in Remix](./imgs/vrf-3.png) -4. Connect Remix to your Metamask wallet (with Flow EVM testnet) by selecting **Injected Web3** as the environment. +4. Connect Remix to your Metamask wallet (with Flow EVM testnet). To do this, select **Injected Web3** as the environment. ![Connecting to MetaMask](./imgs/vrf-4.png) @@ -106,15 +106,15 @@ contract CadenceArchCaller { After deployment, you can interact with the contract to retrieve a random number. -Call the `revertibleRandom()` function in the left sidebar on the deployed contract. This fetches a pseudo-random number generated by Flow's VRF. +Call the `revertibleRandom()` function in the left sidebar on the deployed contract. This fetches a pseudo-random number that Flow's VRF generates. ![Calling revertibleRandom function](./imgs/vrf-6.png) The result will be a `uint64` random number generated on Flow EVM. -## Generating random numbers in a range +## Generate random numbers in a range -For use-cases like games and lotteries, it's useful to generate a random number within a specified range, the following example shows how to get a value between a min and max number. +For use-cases like games and lotteries, it's useful to generate a random number within a specified range. The following example shows how to get a value between a min and max number. ```solidity // SPDX-License-Identifier: GPL-3.0 @@ -144,12 +144,12 @@ The above code is susceptible to the [modulo bias], particularly if the random n ## Secure randomness with commit-reveal scheme in Solidity -The **`revertibleRandom()`** function can be directly used to generate a pseudo-random number. However, in certain situations, especially involving untrusted callers, this function exposes a vulnerability: the ability of a transaction to **revert after seeing the random result**. +You can use the **`revertibleRandom()`** function directly to generate a pseudo-random number. However, in certain situations, especially with untrusted callers, this function exposes a vulnerability: the ability of a transaction to **revert after seeing the random result**. **The Issue with Using `revertibleRandom()` Directly** - When an untrusted party calls a contract function that uses `revertibleRandom()`, they receive the random number **during the transaction execution**. -- **Post-selection** is the ability of the caller to abort the transaction if the random outcome is unfavorable. In this case, the user could choose to revert the transaction (for example, if they lose a bet) and attempt to call the function again in hopes of a better outcome. +- **Post-selection** is the caller's ability to abort the transaction if the random outcome is unfavorable. In this case, the user could choose to revert the transaction (for example, if they lose a bet) and attempt to call the function again in hopes of a better outcome. - This can lead to a form of _transaction reversion attack_, where the randomness can be exploited by repeatedly attempting transactions until a favorable result is obtained. ## Further reading From 349765d6ae237bb0217f556e7ffaeabe08cb8596 Mon Sep 17 00:00:00 2001 From: Brian Doyle Date: Wed, 12 Nov 2025 10:13:37 -0500 Subject: [PATCH 2/6] Apply suggestion from @briandoyle81 --- .../native-vrf/commit-reveal-cadence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md index 7907d113fc..12407ff4c4 100644 --- a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md +++ b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md @@ -21,7 +21,7 @@ keywords: Randomness is a critical component in blockchain applications. It allows fair and unpredictable outcomes for use cases like gaming, lotteries, and cryptographic protocols. -The most basic approach that you can use to generate a random number on EVM chains is to use block hashes, which combines the block hash with a user-provided seed and hashes them together. You can use the has that results as a pseudo-random generator seed. However, this approach has limitations. A validator that influences the random source used to compute transactions can manipulate the block hash. The block proposer can decide what to include into a block and can through different combinations until they find a favorable random source. +The most basic approach that you can use to generate a random number on EVM chains is to use block hashes, which combines the block hash with a user-provided seed and hashes them together. You can use the has that results as a pseudo-random generator seed. However, this approach has limitations. A validator that influences the random source used to compute transactions can manipulate the block hash. The block proposer can decide what to include into a block and can iterate through different combinations until they find a favorable random source. [Chainlink VRF][chainlink-vrf] is a popular tool that improves on this. It provides another approach you can use to generate provably random values on Ethereum and other blockchains. It relies on a decentralized oracle network to deliver cryptographically secure randomness from off-chain sources. However, this dependence on external oracles introduces several weaknesses, such as cost, latency, and scalability concerns. From 59c7b129f0fd8124086c0db210a6ab042168a6b1 Mon Sep 17 00:00:00 2001 From: Brian Doyle Date: Wed, 12 Nov 2025 10:15:10 -0500 Subject: [PATCH 3/6] Apply suggestion from @briandoyle81 --- .../native-vrf/commit-reveal-cadence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md index 12407ff4c4..4b09178651 100644 --- a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md +++ b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md @@ -27,7 +27,7 @@ The most basic approach that you can use to generate a random number on EVM chai In contrast, Flow offers a simpler and more integrated approach with its native onchain Randomness Beacon at the protocol level, which eliminates reliance on external oracles and sidestepping their associated risks. -In addition to instant randomness that is available to any transaction (via `revertibleRandom` function), Flow provides a solution to reverted transaction. Commit-Reveal schemes on Flow also rely on protocol-native secure randomness and they fix the issue of post-selection by trustless users. Commit-Reveal tools on Flow can be used within both Cadence and Consumer Decentralized Finance (DeFi) contracts. This tutorial focuses on Cadence. +In addition to instant randomness that is available to any transaction (via `revertibleRandom` function), Flow provides a solution to the problem of a user reverting a transaction with an unfavorable outcome. Commit-Reveal schemes on Flow also rely on protocol-native secure randomness and they fix the issue of post-selection by trustless users. Commit-Reveal tools on Flow can be used within both Cadence and Consumer Decentralized Finance (DeFi) contracts. This tutorial focuses on Cadence. ## Objectives From e07024fb48a0bb44e0a1d4056204d2e609cbd821 Mon Sep 17 00:00:00 2001 From: Brian Doyle Date: Wed, 12 Nov 2025 10:29:22 -0500 Subject: [PATCH 4/6] Apply suggestion from @briandoyle81 --- .../native-vrf/commit-reveal-cadence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md index 4b09178651..a67d603777 100644 --- a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md +++ b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md @@ -74,7 +74,7 @@ Similarly to revertible randomness, Commit-Reveal inherits the security of Flow In addition, commit-reveal patterns solve the issue of revertible randoms: -- Prevents user manipulation - Players cannot selectively reveal results after they see the random results. +- Prevents user manipulation - Players cannot simulate an outcome and choose to revert the transaction if they do not like the result. ## Build the Coin Toss contract From 57e767fb341d8fb746669188332512ac6ea852d5 Mon Sep 17 00:00:00 2001 From: Brian Doyle Date: Wed, 12 Nov 2025 10:33:39 -0500 Subject: [PATCH 5/6] Apply suggestion from @briandoyle81 --- .../native-vrf/commit-reveal-cadence.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md index a67d603777..0361925e0f 100644 --- a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md +++ b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md @@ -74,7 +74,15 @@ Similarly to revertible randomness, Commit-Reveal inherits the security of Flow In addition, commit-reveal patterns solve the issue of revertible randoms: -- Prevents user manipulation - Players cannot simulate an outcome and choose to revert the transaction if they do not like the result. +- Prevents user manipulation - Players cannot evaluate the outcome and choose to revert the transaction if they do not like the result. +- + + +:::info + +One of the powers of Cadence transactions is that a developer can set post-conditions that must be true, or the transaction will revert. This is very useful for scenarios such as guaranteeing a user receives their purchase in a complex and multi-step transaction, but it also means that they can set conditions to reject the transaction. In an instant-win lottery, this would allow users to test large numbers of tickets for a win without paying the purchase price. + +::: ## Build the Coin Toss contract From 8723b449d5ada1dcf1161afb4241682743421e7c Mon Sep 17 00:00:00 2001 From: Brian Doyle Date: Wed, 12 Nov 2025 10:35:21 -0500 Subject: [PATCH 6/6] Apply suggestion from @briandoyle81 --- .../native-vrf/commit-reveal-cadence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md index 0361925e0f..7ac97d51f7 100644 --- a/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md +++ b/docs/blockchain-development-tutorials/native-vrf/commit-reveal-cadence.md @@ -208,7 +208,7 @@ transaction(betAmount: UFix64) { } ``` -3. Set Your Bet: a window will appear that asks for the betAmount. Enter a value (such as 1.0 for 1 Flow token) and submit. +3. Set Your Bet: a window will appear that asks for the `betAmount`. Enter a value (such as 1.0 for 1 Flow token) and submit. 4. Execute the Transaction: click "Run," and a WalletConnect window will appear. Choose Blocto, sign in with your email, and click "Approve" to send the transaction to Testnet. ![remix5-sc](./imgs/remix5.png)