diff --git a/docs/build/flow.md b/docs/build/flow.md index f9c5779192..c4ce056c58 100644 --- a/docs/build/flow.md +++ b/docs/build/flow.md @@ -162,4 +162,4 @@ The [FLOW] (or $FLOW) token is the native currency for the Flow network. Develop [Flow Technical Primer]: https://www.flow.com/primer [Three technical whitepapers]: https://www.flow.com/technical-paper [Flow Token Economics]: https://www.flow.com/flow-token-economics -[VRF]: ../evm/guides/vrf.md +[VRF]: ../tutorials/native-vrf/vrf-in-solidity.md diff --git a/docs/tutorials/cross-vm-apps/add-to-wagmi.md b/docs/tutorials/cross-vm-apps/add-to-wagmi.md index 273cfd03e1..f351790152 100644 --- a/docs/tutorials/cross-vm-apps/add-to-wagmi.md +++ b/docs/tutorials/cross-vm-apps/add-to-wagmi.md @@ -499,7 +499,6 @@ For a complete reference implementation, check out the [FCL + RainbowKit + wagmi [create an issue]: https://github.com/onflow/docs/issues/new/choose [Cadence]: https://cadence-lang.org [Solidity]: https://soliditylang.org/ -[native VRF]: ../../evm/guides/vrf.md [structure and call EVM transactions]: ./batched-evm-transactions.md [FLIP 316]: https://github.com/onflow/flips/pull/317 [Flow Client Library (FCL)]: ../../tools/clients/fcl-js diff --git a/docs/tutorials/cross-vm-apps/batched-evm-transactions.md b/docs/tutorials/cross-vm-apps/batched-evm-transactions.md index f43805c564..d1fdeeb881 100644 --- a/docs/tutorials/cross-vm-apps/batched-evm-transactions.md +++ b/docs/tutorials/cross-vm-apps/batched-evm-transactions.md @@ -714,7 +714,7 @@ Ready to level up your Cadence skills? Take a look at [these Cadence tutorials]. [Flow Wallet extension]: https://wallet.flow.com/download [Faucet guide]: ../../ecosystem/faucets.md [Cadence-controlled EVM account (COA)]: ./interacting-with-coa.md -[onchain VRF]: ../../evm/guides/vrf.md +[onchain VRF]: ../native-vrf/vrf-in-solidity.md [Overview]: #overview [Testnet]: https://evm-testnet.flowscan.io/token/0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e?tab=contract [Mainnet]: https://evm.flowscan.io/token/0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e?tab=contract diff --git a/docs/tutorials/cross-vm-apps/introduction.md b/docs/tutorials/cross-vm-apps/introduction.md index babecb2180..4da23fd775 100644 --- a/docs/tutorials/cross-vm-apps/introduction.md +++ b/docs/tutorials/cross-vm-apps/introduction.md @@ -812,7 +812,7 @@ Now that you have completed the tutorial, you should be able to: [create an issue]: https://github.com/onflow/docs/issues/new/choose [Cadence]: https://cadence-lang.org [Solidity]: https://soliditylang.org/ -[native VRF]: ../../evm/guides/vrf.md +[native VRF]: ../native-vrf/vrf-in-solidity.md [structure and call EVM transactions]: ./batched-evm-transactions.md [FLIP 316]: https://github.com/onflow/flips/pull/317 [Flow Client Library (FCL)]: ../../tools/clients/fcl-js diff --git a/docs/tutorials/flowtobooth/image-gallery.md b/docs/tutorials/flowtobooth/image-gallery.md index d6d5bbffa1..606043c55e 100644 --- a/docs/tutorials/flowtobooth/image-gallery.md +++ b/docs/tutorials/flowtobooth/image-gallery.md @@ -1104,7 +1104,7 @@ Now that you've completed this tutorial, you're ready to explore more complex on [Hardhat]: ../../evm/guides/hardhat.md [Foundry]: ../../evm/guides/foundry.md [Remix]: ../../evm/guides/remix.md -[native VRF]: ../../evm/guides/vrf.md +[native VRF]: ../native-vrf/vrf-in-solidity.md [OpenZeppelin]: https://www.openzeppelin.com/ [Ownable]: https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/access/Ownable.sol [evm-testnet.flowscan.io]: https://evm-testnet.flowscan.io/ diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 8891e28c81..433d050137 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -83,6 +83,7 @@ Learn how to build applications that interact with both Cadence and Flow EVM. Th Learn how to leverage Flow's native VRF capabilities in both Cadence and Solidity smart contracts. These tutorials demonstrate how to implement secure randomness without relying on external oracles. - [Secure Randomness with Commit-Reveal in Cadence] - Learn how to implement secure randomness in Cadence using Flow's commit-reveal scheme +- [VRF (Randomness) in Solidity] - Learn how to use Flow's native VRF capabilities in Solidity. - [Deploy a Solidity Contract Using Cadence] - Discover how to deploy and interact with Solidity contracts on Flow EVM using Cadence ## FlowtoBooth @@ -102,6 +103,7 @@ Explore Flow's unique capabilities through fun benchmark applications that showc [Build a Fully-Onchain Image Gallery]: flowtobooth/image-gallery.md [Secure Randomness with Commit-Reveal in Cadence]: native-vrf/commit-reveal-cadence.md [Deploy a Solidity Contract Using Cadence]: native-vrf/deploy-solidity-contract.md +[VRF (Randomness) in Solidity]: native-vrf/vrf-in-solidity.md [Add Flow Cadence to Your wagmi App]: ./cross-vm-apps/add-to-wagmi.md [Register Your Assets in Cadence]: ./token-launch/register-cadence-assets.md [Register Your ERC20 Token]: ./token-launch/register-erc20-token.md diff --git a/docs/tutorials/native-vrf/deploy-solidity-contract.md b/docs/tutorials/native-vrf/deploy-solidity-contract.md index 4fa3271f30..4a29727737 100644 --- a/docs/tutorials/native-vrf/deploy-solidity-contract.md +++ b/docs/tutorials/native-vrf/deploy-solidity-contract.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 title: Deploy a Solidity Contract Using Cadence description: Guide on how to deploy a Solidity contract using Cadence keywords: diff --git a/docs/evm/guides/vrf-1.png b/docs/tutorials/native-vrf/imgs/vrf-1.png similarity index 100% rename from docs/evm/guides/vrf-1.png rename to docs/tutorials/native-vrf/imgs/vrf-1.png diff --git a/docs/evm/guides/vrf-2.png b/docs/tutorials/native-vrf/imgs/vrf-2.png similarity index 100% rename from docs/evm/guides/vrf-2.png rename to docs/tutorials/native-vrf/imgs/vrf-2.png diff --git a/docs/evm/guides/vrf-3.png b/docs/tutorials/native-vrf/imgs/vrf-3.png similarity index 100% rename from docs/evm/guides/vrf-3.png rename to docs/tutorials/native-vrf/imgs/vrf-3.png diff --git a/docs/evm/guides/vrf-4.png b/docs/tutorials/native-vrf/imgs/vrf-4.png similarity index 100% rename from docs/evm/guides/vrf-4.png rename to docs/tutorials/native-vrf/imgs/vrf-4.png diff --git a/docs/evm/guides/vrf-5.png b/docs/tutorials/native-vrf/imgs/vrf-5.png similarity index 100% rename from docs/evm/guides/vrf-5.png rename to docs/tutorials/native-vrf/imgs/vrf-5.png diff --git a/docs/evm/guides/vrf-6.png b/docs/tutorials/native-vrf/imgs/vrf-6.png similarity index 100% rename from docs/evm/guides/vrf-6.png rename to docs/tutorials/native-vrf/imgs/vrf-6.png diff --git a/docs/tutorials/native-vrf/index.md b/docs/tutorials/native-vrf/index.md index 5e0afa79f6..9940354054 100644 --- a/docs/tutorials/native-vrf/index.md +++ b/docs/tutorials/native-vrf/index.md @@ -25,6 +25,7 @@ This series covers how to leverage Flow's native VRF (Verifiable Random Function ## Tutorials - **[Secure Randomness with Commit-Reveal in Cadence]** - Learn how to implement secure randomness in Cadence using Flow's commit-reveal scheme. +- **[VRF (Randomness) in Solidity]** - Learn how to use Flow's native VRF capabilities in Solidity. - **[Deploy a Solidity Contract Using Cadence]** - Discover how to deploy and interact with Solidity contracts on Flow EVM using Cadence. ## More Coming Soon @@ -32,4 +33,5 @@ This series covers how to leverage Flow's native VRF (Verifiable Random Function Stay tuned—more tutorials and advanced guides are on the way! [Secure Randomness with Commit-Reveal in Cadence]: ./commit-reveal-cadence.md +[VRF (Randomness) in Solidity]: ./vrf-in-solidity.md [Deploy a Solidity Contract Using Cadence]: ./deploy-solidity-contract.md diff --git a/docs/evm/guides/vrf.md b/docs/tutorials/native-vrf/vrf-in-solidity.md similarity index 59% rename from docs/evm/guides/vrf.md rename to docs/tutorials/native-vrf/vrf-in-solidity.md index 9787b44362..6e4fd47911 100644 --- a/docs/evm/guides/vrf.md +++ b/docs/tutorials/native-vrf/vrf-in-solidity.md @@ -1,21 +1,26 @@ --- +sidebar_position: 3 title: VRF (Randomness) in Solidity sidebar_label: VRF (Randomness) in Solidity -sidebar_position: 6 +keywords: + - VRF + - randomness + - Cadence + - Solidity + - Flow EVM + - smart contracts + - blockchain + - NFTs + - DeFi --- ## **Introduction** -Flow provides secure, native on-chain randomness that developers can leverage through Cadence Arch, a precompiled -contract available on the Flow EVM environment. This guide will walk through how Solidity developers can use Cadence -Arch to access Flow’s verifiable randomness using Solidity. +Flow provides secure, native on-chain randomness that developers can leverage through Cadence Arch, a precompiled contract available on the Flow EVM environment. This guide will walk through how Solidity developers can use Cadence Arch to access Flow's verifiable randomness using Solidity. ### **What is Cadence Arch?** -[Cadence Arch](https://github.com/onflow/flips/blob/main/protocol/20231116-evm-support.md#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 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. --- @@ -31,10 +36,10 @@ calls to retrieve random values and other information. | **Parameter** | **Value** | | ------------------- | ----------------------------------------------------------------------------- | | **Network Name** | Flow EVM Testnet | -| **RPC Endpoint** | [https://testnet.evm.nodes.onflow.org](https://testnet.evm.nodes.onflow.org/) | +| **RPC Endpoint** | [Flow EVM Testnet RPC] | | **Chain ID** | 545 | | **Currency Symbol** | FLOW | -| **Block Explorer** | [https://evm-testnet.flowscan.io](https://evm-testnet.flowscan.io/) | +| **Block Explorer** | [Flow EVM Testnet Explorer] | ## **Steps to Connect Flow EVM Testnet to Metamask** @@ -47,12 +52,12 @@ calls to retrieve random values and other information. - **Block Explorer**: `https://evm-testnet.flowscan.io` 3. Click **Save** and switch to the Flow EVM Testnet. -![image.png](./vrf-1.png) +![vrf-1.png] ## **Obtaining Testnet FLOW** -You can fund your account with testnet FLOW using the [Flow Faucet](https://testnet-faucet.onflow.org/fund-account). -Enter your Flow-EVM testnet address, and you’ll receive testnet FLOW tokens to interact with smart contracts. +You can fund your account with testnet FLOW using the [Flow Faucet]. +Enter your Flow-EVM testnet address, and you'll receive testnet FLOW tokens to interact with smart contracts. --- @@ -102,28 +107,27 @@ contract CadenceArchCaller { 1. Open Remix IDE. 2. Create a new file and paste the Solidity code above. -![image.png](./vrf-2.png) +![vrf-2.png] 3. Compile the contract by selecting the appropriate Solidity compiler version (0.8.x). -![image.png](./vrf-3.png) +![vrf-3.png] 4. Connect Remix to your Metamask wallet (with Flow EVM testnet) by selecting **Injected Web3** as the environment. -![image.png](./vrf-4.png) +![vrf-4.png] 5. Deploy the contract. -![image.png](./vrf-5.png) +![vrf-5.png] ### Call revertibleRandom 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 will fetch a pseudo-random -number generated by Flow’s VRF. +Call the `revertibleRandom()` function in the left sidebar on the deployed contract. This will fetch a pseudo-random number generated by Flow's VRF. -![image.png](./vrf-6.png) +![vrf-6.png] The result will be a `uint64` random number generated on Flow EVM. @@ -131,8 +135,7 @@ The result will be a `uint64` random number generated on Flow EVM. ## **Generating 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 @@ -150,42 +153,47 @@ contract RandomInRange { // Return the number in the specified range return (randomNumber % (max + 1 - min)) + min; - } + } } ``` :::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). +The above code is susceptible to the [modulo bias], 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]. ::: ## **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**. +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**. **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. -- 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. +- 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. +- 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. ## Read More -For further details on Flow’s randomness and secure development practices, check out the [Flow Randomness -Documentation](https://developers.flow.com/build/advanced-concepts/randomness). +For further details on Flow's randomness and secure development practices, check out the [Flow Randomness Documentation]. -You can also view an example in both Solidity and Cadence of a [random coin toss -implentation](https://github.com/onflow/random-coin-toss) using the VRF. +You can also view an example in both Solidity and Cadence of a [random coin toss implentation] using the VRF. -_This documentation was contributed by [Noah Naizir](https://x.com/noah_overflow), a community developer._ +_This documentation was contributed by [Noah Naizir] a community developer._ + +[vrf-1.png]: ./imgs/vrf-1.png +[vrf-2.png]: ./imgs/vrf-2.png +[vrf-3.png]: ./imgs/vrf-3.png +[vrf-4.png]: ./imgs/vrf-4.png +[vrf-5.png]: ./imgs/vrf-5.png +[vrf-6.png]: ./imgs/vrf-6.png + +[Cadence Arch]: https://github.com/onflow/flips/blob/main/protocol/20231116-evm-support.md#cadence-arch +[Flow EVM Testnet RPC]: https://testnet.evm.nodes.onflow.org/ +[Flow EVM Testnet Explorer]: https://evm-testnet.flowscan.io/ +[Flow Faucet]: https://testnet-faucet.onflow.org/fund-account +[modulo bias]: https://research.kudelskisecurity.com/2020/07/28/the-definitive-guide-to-modulo-bias-and-how-to-avoid-it/ +[this repository]: https://github.com/onflow/random-coin-toss +[Flow Randomness Documentation]: https://developers.flow.com/build/advanced-concepts/randomness +[random coin toss implentation]: https://github.com/onflow/random-coin-toss +[Noah Naizir]: https://x.com/noah_overflow diff --git a/vercel.json b/vercel.json index 4b7af502e5..33b85fbbaa 100644 --- a/vercel.json +++ b/vercel.json @@ -1110,6 +1110,11 @@ "destination": "/evm/build/guides/deploy-contract/using-remix", "permanent": true }, + { + "source": "/evm/guides/vrf", + "destination": "/tutorials/native-vrf/vrf-in-solidity", + "permanent": true + }, { "source": "/tutorials/contract-testing", "destination": "/build/smart-contracts/testing",