diff --git a/docs/blockchain-development-tutorials/cross-vm-apps/add-to-wagmi.md b/docs/blockchain-development-tutorials/cross-vm-apps/add-to-wagmi.md index ff14e148fe..42e3e37b58 100644 --- a/docs/blockchain-development-tutorials/cross-vm-apps/add-to-wagmi.md +++ b/docs/blockchain-development-tutorials/cross-vm-apps/add-to-wagmi.md @@ -23,7 +23,7 @@ keywords: # Add Flow Cadence to your wagmi app -This tutorial demonstrates how to enhance your existing wagmi/RainbowKit application with Flow Cadence capabilities. When you integrate the Flow Client Library (FCL) with your EVM stack, you can unlock powerful features like batch transactions with a single signature. +This tutorial demonstrates how to enhance your current wagmi/RainbowKit application with Flow Cadence capabilities. When you integrate the Flow Client Library (FCL) with your EVM stack, you can unlock powerful features like batch transactions with a single signature. ## Video overview @@ -42,7 +42,7 @@ This tutorial demonstrates how to enhance your existing wagmi/RainbowKit applica After you complete this guide, you'll be able to: -- Add FCL to your existing wagmi/RainbowKit application. +- Add FCL to your current wagmi/RainbowKit application. - Configure FCL to work alongside your EVM wallet connections. - Implement batch transactions that execute multiple EVM calls in a single Cadence transaction. - Display both Cadence and EVM addresses in your application. @@ -491,12 +491,14 @@ This approach gives you several advantages: ## Conclusion -You've successfully integrated Flow Cadence with your wagmi/rainbowkit application! This integration allows you to leverage the power of Cadence while maintaining the familiar EVM development experience. +You've successfully integrated Flow Cadence with your wagmi/rainbowkit application! This integration allows you to leverage the power of Cadence and maintain the familiar EVM development experience. -## Reference Implementation +## Reference implementation For a complete reference implementation, check out the [FCL + RainbowKit + wagmi Integration Demo] repository. + + [Cadence]: https://cadence-lang.org/docs [Next.js]: https://nextjs.org/docs/app/getting-started/installation [npm]: https://www.npmjs.com/ diff --git a/docs/blockchain-development-tutorials/cross-vm-apps/batched-evm-transactions.md b/docs/blockchain-development-tutorials/cross-vm-apps/batched-evm-transactions.md index 16c17e6379..9adb490f7c 100644 --- a/docs/blockchain-development-tutorials/cross-vm-apps/batched-evm-transactions.md +++ b/docs/blockchain-development-tutorials/cross-vm-apps/batched-evm-transactions.md @@ -6,12 +6,9 @@ sidebar_position: 3 # Batched EVM transactions using Cadence -Developers who integrate Cadence into EVM applications on Flow lets them leverage the best of both worlds. This guide -demonstrates how to batch EVM transactions with Cadence, which applications to embed multiple EVM transactions in a -single Cadence transaction while conditioning final execution on the success of all EVM transactions. +Developers who integrate Cadence into EVM applications on Flow lets them leverage the best of both worlds. This guide demonstrates how to batch EVM transactions with Cadence, which applications to embed multiple EVM transactions in a single Cadence transaction while conditioning final execution on the success of all EVM transactions. -This feature can unlock experiences otherwise impossible on traditional EVM -platforms, which supercharges your EVM application. +This feature can unlock experiences otherwise impossible on traditional EVM platforms, which supercharges your EVM application. ## Objectives @@ -19,7 +16,7 @@ After you complete this guide, you'll be able to - Construct a Cadence transaction that executes several EVM transactions such that if any EVM transaction fails, the entire set will revert. - Read and write from smart contract functions on [EVM Flowscan]. -- Run a Cadence transaction from the browser using [Flow Runner]. +- Run a Cadence transaction from the browser with [Flow Runner]. - Install conceptual understanding of Cadence X EVM interactions. - Inspect multiple EVM transactions embedded in a Cadence transaction with [Flowscan] block explorer. - Write code that interacts with the EVM via a CadenceOwnedAccount (COA). @@ -38,7 +35,7 @@ For the purposes of demonstration, this walkthrough will focus on relatively sim - Wrap FLOW as WFLOW. - Approve an ERC721 to transfer WFLOW in exchange for an NFT mint. -- Mint an ERC721 token - this ERC721 has a 50% chance of failing (using [onchain VRF] to determine success). +- Mint an ERC721 token - this ERC721 has a 50% chance of failure (via [onchain VRF] to determine success). These operations let us focus on the **core concepts** of this guide: @@ -47,7 +44,7 @@ These operations let us focus on the **core concepts** of this guide: However, with these same principles, you'll have the power to address more complex use cases. For instance, replace wrapping FLOW with a DEX swap. Or instead of minting an ERC721, purchase an NFT listing from a marketplace. -Combine these two, and suddenly you can purchase NFTs with any ERC20 token, all in a single Cadence transaction, reverting everything if a single step fails. +Combine these two, and suddenly you can purchase NFTs with any ERC20 token, all in a single Cadence transaction, and revert everything if a single step fails. The point is, while a simple use case, this guide will give you the tools to build much more complex and interesting applications. So let's get started! @@ -55,16 +52,15 @@ The point is, while a simple use case, this guide will give you the tools to bui As mentioned in the [Overview], this guide involves three main actions: -- Wrapping FLOW as WFLOW. -- Approving an ERC721 to transfer WFLOW in exchange for an NFT mint. -- Minting an ERC721 token. +- Wrap FLOW as WFLOW. +- Approve an ERC721 to transfer WFLOW in exchange for an NFT mint. +- Mint an ERC721 token. Before we interact with these contracts, let's dig bit more into the components of this guide. ### Wrap FLOW as WFLOW -On Flow EVM, FLOW is the native currency and similar to other EVM platforms, the native currency is not accessible as an ERC20 token. To interact with ERC20 contracts, you need to wrap FLOW as WFLOW (Wrapped FLOW). This is Flow's equivalent -of WETH on Ethereum. +On Flow EVM, FLOW is the native currency and similar to other EVM platforms, the native currency is not accessible as an ERC20 token. To interact with ERC20 contracts, you need to wrap FLOW as WFLOW (Wrapped FLOW). This is Flow's equivalent of WETH on Ethereum. :::tip @@ -76,11 +72,11 @@ You can find WFLOW deployed to `0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e` on F Our example `MaybeMintERC721` contract accepts WFLOW in exchange for minting an NFT. However, the contract cannot move WFLOW without your permission. To allow the contract to move your WFLOW, you must approve the contract to transfer enough of your WFLOW to mint the NFT. -### Mint ERC721 Token +### Mint ERC721 token -Finally, we'll mint an ERC721 token using the `MaybeMintERC721` contract. This contract has a 50% chance of failing, wheich simpluates a real-world scenario where purchasing an NFT might fail - say a listing was purchased before your transaction was processed. +Finally, we'll mint an ERC721 token using the `MaybeMintERC721` contract. This contract has a 50% chance of failure, which simpluates a real-world scenario where an NFT purchase might fail - say a listing was purchased before your transaction was processed. -Importantly, if this transaction fails, we want to revert the entire sequence of transactions. After all, you wrapped FLOW to WFLOW and approved the ERC721 transfer specifically to mint this NFT. If the mint fails, you want to unwind everything. As we'll see shortly, this is where batching EVM transactions using Cadence is extremely powerful. +Importantly, if this transaction fails, we want to revert the entire sequence of transactions. After all, you wrapped FLOW to WFLOW and approved the ERC721 transfer specifically to mint this NFT. If the mint fails, you want to unwind everything. As we'll see shortly, this is where batching EVM transactions with Cadence is extremely powerful. ## Interact with the contracts @@ -99,7 +95,7 @@ Recall in [Prerequisites] that you need to have both [MetaMask] and [Flow Wallet Our first action will be to wrap enough FLOW to cover the cost of minting the `MaybeMintERC721` token. To do this, we'll interact with the `WFLOW` contract on Testnet. -There are a number of ways we could interact with this contract - Remix IDE, Foundry's CLI, Hardhat, and so on. - but for the purposes of this guide, we'll use the [Flowscan EVM block explorer]. +There are a number of ways we could interact with this contract - Remix IDE, Foundry's CLI, Hardhat, and so on. For the purposes of this guide, we'll use the [Flowscan EVM block explorer]. Navigate to the WFLOW Testnet contract on Flowscan: [WFLOW]. Make sure you're on the `Write Contract` tab, which allows you to interact with the contract's mutating functions. @@ -108,7 +104,7 @@ explorer]. Click `Connect` in the top right corner and follow the prompts to con :::warning -There are two **separate** block explorers for Flow - one for Cadence activity and another for EVM activity. This is unique to Flow and is due to the fact that Cadence & EVM are separate runtimes, with EVM effectively emulated within Cadence. This orientation - that of EVM running within Cadence - means that the Cadence-side explorer has visibility to EVM transactions embedded within a Cadence transaction. +There are two **separate** block explorers for Flow - one for Cadence activity and another for EVM activity. This is unique to Flow and is due to the fact that Cadence and EVM are separate runtimes, with EVM effectively emulated within Cadence. This orientation - that of EVM running within Cadence - means that the Cadence-side explorer has visibility to EVM transactions embedded within a Cadence transaction. Practically, this means that you can view any transactions run with a Flow native account on the Cadence explorer, while you can view any transactions run with an EVM account on the EVM explorer. @@ -118,7 +114,7 @@ Practically, this means that you can view any transactions run with a Flow nativ After you connect, you will see your address in the top right corner and above the contract's functions. -Now we can wrap FLOW. Click the `deposit` method which will drop down an input field for the amount of FLOW you want to wrap. The mint amount for the `MaybeMintERC721` contract is 1 whole FLOW which in EVM terms is `1e18 wei` - `wei` being the smallest unit of an EVM's native currency (inherited from Ethereum's units - more on Ether units [here]). +Now we can wrap FLOW. Click the `deposit` method which will drop down an input field for the amount of FLOW you want to wrap. The mint amount for the `MaybeMintERC721` contract is one whole FLOW which in EVM terms is `1e18 wei` - `wei` is the smallest unit of an EVM's native currency (inherited from Ethereum's units - more on Ether units [here]). As shown below, put `1 000 000 000 000 000 000` in the input field for `deposit`. @@ -136,7 +132,7 @@ When confirmed, you can see WFLOW balance in your tokens list in MetaMask - if n ![WFLOW in MetaMask](./imgs/wflow-in-metamask-tokens.png) -#### 2. Approve WFLOW Transfer +#### 2. Approve WFLOW transfer Now that you have your WFLOW, you'll need to approve the `MaybeMintERC721` contract to transfer your WFLOW. From the same WFLOW page in Flowscan, click the `approve` method. This time, you'll need to input the `MaybeMintERC721` contract address - `0x2E2Ed0Cfd3AD2f1d34481277b3204d807Ca2F8c2` - and the amount of WFLOW you want to approve - again `1 000 000 000 000 000 000` WFLOW. @@ -144,13 +140,13 @@ Now that you have your WFLOW, you'll need to approve the `MaybeMintERC721` contr Click `Write` to submit the transaction. To be clear, this does not complete a transfer, but allows the `MaybeMintERC721` contract to transfer your WFLOW on your behalf which will execute in the next step. -#### 3. Mint ERC721 Token +#### 3. Mint ERC721 token -Finally, we'll attempt to mint the ERC721 token using the `MaybeMintERC721` contract. Navigate to the `MaybeMintERC721` contract on Flowscan: [MaybeMintERC721]. +Finally, we'll attempt to mint the ERC721 token with the `MaybeMintERC721` contract. Navigate to the `MaybeMintERC721` contract on Flowscan: [MaybeMintERC721]. Again, you'll see the contract functions on the `Write Contract` tab. Click the `mint` function which takes no arguments - just click `Write` and then `Confirm` in the MetaMask window. -This contract has a 50% chance of failing on mint using onchain randomness. If it fails, simply mint again until it succeeds. +This contract has a 50% chance of failue on mint with onchain randomness. If it fails, simply mint again until it succeeds. When it succeeds, you can click your NFTs in MetaMask to see your newly minted token. @@ -160,15 +156,15 @@ When it succeeds, you can click your NFTs in MetaMask to see your newly minted t #### Recap -This process is cumbersome and requires multiple transactions, each of which could fail. Given the intent of the process - minting an NFT - if this were a case where the NFT was a limited edition or time-sensitive, you'd be left with WFLOW wrapped and approved for transfer, but no NFT and would need to manually unwind the process. +This process is cumbersome and requires multiple transactions, each of which could fail. Given the intent of the process - to mint an NFT - if this were a case where the NFT was a limited edition or time-sensitive, you'd be left with WFLOW wrapped and approved for transfer, but no NFT and would need to manually unwind the process. Or you could just use Cadence to batch these transactions and revert everything if the mint fails. Let's do that. ### Use Flow Wallet -Before we dive into the "how", let's execute the batched version of everything we just did with Flow Wallet. This will give you a sense of the power of Cadence and the Flow blockchain. +Before we dive into the "how", let's execute the batched version of everything we just did with Flow Wallet. This will give you a sense of Cadence's power and the Flow blockchain. -The transaction below, like all Cadence transactions, is scripted, allowing us to execute a series of actions. It may look like a lot at first, but we will break it down step by step in the following sections. +The transaction below, like all Cadence transactions, is scripted, which allows us to execute a series of actions. It may look like a lot at first, but we will break it down step by step in the following sections.
@@ -327,19 +323,17 @@ This transaction takes two arguments: - WFLOW contract address: `0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e` - MaybeMintERC721 contract address: `0x2E2Ed0Cfd3AD2f1d34481277b3204d807Ca2F8c2` -Before you run the tool, ensure that the network section - bottom right corner - displays Testnet. If not, click and select `Testnet` as your network and refresh. Once you've confirmed you're Flow Runner is targeting Testnet, copy these addresses and paste them into the respective fields on the Flow Runner page. Click `Run` on the top left and follow the prompts to connect your Flow Wallet and sign the transaction. +Before you run the tool, ensure that the network section - bottom right corner - displays testnet. If not, click and select `Testnet` as your network and refresh. After you've confirmed your Flow Runner targets testnet, copy these addresses and paste them into the respective fields on the Flow Runner page. Click `Run` on the top left and follow the prompts to connect your Flow Wallet and sign the transaction. :::warning -Although we are running a manual transaction for the purposes of this walkthrough, always be careful to review the transaction details before you sign and submit. +Although we ran a manual transaction for the purposes of this walkthrough, always be careful to review the transaction details before you sign and submit. ::: -Again, since the ERC721 has a 50% chance of failing, you may need to run the transaction multiple times until it succeeds. However, note that if the mint fails, the entire transaction will revert, unwinding the wrapped FLOW and approval. +Again, since the ERC721 has a 50% chance of failure, you may need to run the transaction multiple times until it succeeds. However, note that if the mint fails, the entire transaction will revert, unwinding the wrapped FLOW and approval. -Again, since the ERC721 has a 50% chance of failure and the success of the transaction is conditioned on successfully minting, your transaction may fail. If it does fail, importantly the entire transaction reverts, unwinding the wrapped -FLOW deposit and approval - the wrapping and approval transactions **do not execute** in the event of mint failure! This -is the main takeaway of this guide, that you embed a whole sequence of EVM transactions into one atomic operation using Cadence and if the primary intent (or intents) does not execute, everything else is reverted as well. +Again, since the ERC721 has a 50% chance of failure and the success of the transaction is conditioned on a successful mint, your transaction may fail. If it does fail, importantly the entire transaction reverts, which unwinds the wrapped FLOW deposit and approval - the wrap and approval transactions **do not execute** in the event of mint failure! This is the main takeaway of this guide, that you embed a whole sequence of EVM transactions into one atomic operation with Cadence and if the primary intent (or intents) does not execute, everything else is reverted as well. In our case, you'll want to submit a transaction until one succeeds. After you submit a successful transaction, you'll see a transaction ID with event logs in the Flow Runner output. Let's take a closer look at the transaction and its results in the Flowscan block explorer. @@ -359,21 +353,21 @@ Now that we can relate to the pain of manually executing these transactions and To recap, our Cadence transaction does the following, reverting if any step fails: -1. Wraps FLOW as WFLOW -2. Approves the `MaybeMintERC721` contract to move WFLOW -3. Attempts to mint a `MaybeMintERC721` token +1. Wraps FLOW as WFLOW. +2. Approves the `MaybeMintERC721` contract to move WFLOW. +3. Attempts to mint a `MaybeMintERC721` token. But how does our Flow account interact with EVM from the Cadence runtime? As you'll recall from the [Interacting with COA](./interacting-with-coa.md) guide, we use a Cadence-owned account (COA) to interact with EVM contracts from Cadence. -A COA is a [resource] providing an interface through which Cadence can interact with the EVM runtime. This is **_in addition to_** to the traditional routes you'd normally access normal EVMs - such as via the JSON-RPC API. And with this interface, we can take advantage of all of the benefits of Cadence - namely here scripted transactions and conditional execution. +A COA is a [resource] that provides an interface through which Cadence can interact with the EVM runtime. This is **_in addition to_** to the traditional routes you'd normally access normal EVMs - such as via the JSON-RPC API. And with this interface, we can take advantage of all of the benefits of Cadence - namely here scripted transactions and conditional execution. -So, in addition to the above steps, our transaction first configures a COA in the signer's account if one doesn't already exist. It then funds the COA with enough FLOW to cover the mint cost, sourcing funds from the signing Flow account's Cadence Vault. Finally, it wraps FLOW as WFLOW, approves the ERC721 contract to move the mint amount, and attempts to mint the ERC721 token. +So, in addition to the above steps, our transaction first configures a COA in the signer's account if one doesn't already exist. It then funds the COA with enough FLOW to cover the mint cost, and sources the funds from the signing Flow account's Cadence Vault. Finally, it wraps FLOW as WFLOW, approves the ERC721 contract to move the mint amount, and attempts to mint the ERC721 token. Let's see what each step looks like in the transaction code. ### COA Configuration -The first step in our transaction is to configure a COA in the signer's account if one doesn't already exist. To do this, create a new COA resource and save it to the signer account's storage. A public Capability on the COA is then issued and published on the signer's account, allowing anyone to deposit FLOW into the COA, affecting its EVM balance. +The first step in our transaction is to configure a COA in the signer's account if one doesn't already exist. To do this, create a new COA resource and save it to the signer account's storage. A public Capability on the COA is then issued and published on the signer's account, which allows anyone to deposit FLOW into the COA and affects its EVM balance. ```cadence /* COA configuration & assignment */ @@ -427,8 +421,8 @@ let fundingVault <- sourceVault.withdraw(amount: self.mintCost) as! @FlowToken.V self.coa.deposit(from: <-fundingVault) ``` -Taking a look at the full transaction, we can see an explicit check that the COA has enough FLOW to cover the mint cost -before proceeding into the transaction's `execute` block. +When we take a look at the full transaction, we can see an explicit check that the COA has enough FLOW to cover the mint cost +before it proceedes into the transaction's `execute` block. ```cadence pre { @@ -448,8 +442,7 @@ After you run the linked transaction, you can check your COA's FLOW balance with ### Setting our EVM contract argets -The last step in our transaction's `prepare` block is to deserialize the provided WFLOW and ERC721 contract addresses -from hex strings to EVM addresses. +The last step in our transaction's `prepare` block is to deserialize the provided WFLOW and ERC721 contract addresses from hex strings to EVM addresses. ```cadence /* Set the WFLOW contract address */ @@ -464,9 +457,9 @@ self.wflowAddress = EVM.addressFromString(wflowAddressHex) self.erc721Address = EVM.addressFromString(maybeMintERC721AddressHex) ``` -### Wrapping FLOW as WFLOW +### Wrap FLOW as WFLOW -Next, we're on to the first EVM interaction - wrapping FLOW as WFLOW. To do this, encode the `deposit()` function call and sett the call value to the mint cost. The COA then calls the WFLOW contract with the encoded calldata, gas limit, and value. +Next, we're on to the first EVM interaction - to wrap FLOW as WFLOW. To do this, encode the `deposit()` function call and set the call value to the mint cost. The COA then calls the WFLOW contract with the encoded calldata, gas limit, and value. ```cadence /* Wrap FLOW in EVM as WFLOW */ @@ -494,9 +487,9 @@ When you set the value of the call, it transmits FLOW along with the call to the You'll notice a general pattern among all EVM calls in this transaction: -1. Encoding the calldata -2. Calling the contract -3. Asserting the call was successful +1. Encodes the calldata. +2. Calls the contract. +3. Asserts the call was successful. Here we're just interested in a successful call, but we could access return data if it were expected and relevant for our Cadence transaction. This returned data is accessible from the `data` field on the `EVM.Result` object returned from `coa.call(...)`. This data would then be decoded with `EVM.decodeABI(...)`. More on this in later guides. @@ -541,17 +534,17 @@ assert( ) ``` -You can run this approval with the transaction. Passing the WFLOW address of `0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e` and MaybeMintERC721 address of `0x2E2Ed0Cfd3AD2f1d34481277b3204d807Ca2F8c2` +You can run this approval with the transaction. Pass the WFLOW address of `0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e` and MaybeMintERC721 address of `0x2E2Ed0Cfd3AD2f1d34481277b3204d807Ca2F8c2` : [`approve_maybe_mint_erc721.cdc`] -The linked transaction will perform the approval step, which authorizes the ERC721 to transfer WFLOW to cover the mint cost when `mint()` is called. Confirm the contract allowance by running the script below. Pass your Flow address, WFLOW +The linked transaction will perform the approval step, which authorizes the ERC721 to transfer WFLOW to cover the mint cost when `mint()` is called. To confirm the contract allowance, run the script below. Pass your Flow address, WFLOW address, ERC721 address, and your COA's EVM address. The result is the amount of your WFLOW balance the ERC721 is allowed to transfer, which after the transaction should be `1` WFLOW, or `1000000000000000000` as returned. -### Mint the ERC721 Token +### Mint the ERC721 token Finally, we attempt to mint the ERC721 token. To do this, encode the `mint()` calldata and call the ERC721 contract with the encoded calldata. If the mint fails, the entire transaction is reverted. @@ -577,35 +570,35 @@ assert( You can run the minting transaction here. Pass the ERC721 address of `0x2E2Ed0Cfd3AD2f1d34481277b3204d807Ca2F8c2`: [`mint.cdc`] -Again, this transaction may fail. But if you executed all the prior stepwise transactions according to the walkthrough, you can try again until the mint succeeds. Recall that you can view your transaction details using Cadence [Flowscan] which will also let you view the embedded EVM transactions in the `EVM` tab. Try it out, and see if you can figure out how to get your minted NFT's URI with the script below. +Again, this transaction may fail. But if you executed all the prior stepwise transactions according to the walkthrough, you can try again until the mint succeeds. Recall that you can view your transaction details with Cadence [Flowscan] which will also let you view the embedded EVM transactions in the `EVM` tab. Try it out, and see if you can figure out how to get your minted NFT's URI with the script below. ### Recap -All of the stepwise transactions you just executed are compiled in the first Cadence transaction we ran. Hopefully, going through the process step by step illuminates the power and flexibility of Cadence, allowing you to write transactions as simple or as complex as you want. +All of the stepwise transactions you just executed are compiled in the first Cadence transaction we ran. Hopefully, going through the process step by step illuminates the power and flexibility of Cadence and allows you to write transactions as simple or as complex as you want. -While lengthy transactions can be intimidating and even a bit verbose at times, the flexibility afforded by the language means you are only limited by your imagination. Cadence transactions allow you to support the most streamlined of experiences, incorporating as many contracts as needed to support your use case. +While lengthy transactions can be intimidating and even a bit verbose at times, the flexibility afforded by the language means you are only limited by your imagination. Cadence transactions allow you to support the most streamlined of experiences and incorporate as many contracts as needed to support your use case. ## Conclusion -In this guide, we've demonstrated how to batch EVM transactions using Cadence, allowing you to conditionally execute multiple EVM transactions in a single Cadence transaction. While this guide focused on relatively simple EVM operations, the principles can be applied to much more complex and interesting applications. +In this guide, we've demonstrated how to batch EVM transactions using Cadence, which allows you to conditionally execute multiple EVM transactions in a single Cadence transaction. While this guide focused on relatively simple EVM operations, the principles can be applied to much more complex and interesting applications. In the process, you learned how to: - Read and write from smart contract functions on EVM Flowscan. -- Run a Cadence transaction from the browser using [Flow Runner]. +- Run a Cadence transaction from the browser with [Flow Runner]. - Execute batched EVM transactions via a COA in a Cadence transaction. - Condition final transaction execution on success of all EVM transactions. - Inspect multiple EVM transactions embedded in a Cadence transaction with [Flowscan] block explorer. The biggest takeaway here isn't the specific actions taken in this walkthrough, but the overarching concept that you can use **Cadence as an orchestration layer** to **extend existing EVM contracts**, which allows you to create unique user experiences with the power **to differentiate your Web3 application**. -With these basics in hand, you're ready to start building more complex applications that leverage the power of Cadence and the Flow blockchain. How will you use these features to build Web3's next killer app? +With these basics in hand, you're ready to build more complex applications that leverage the power of Cadence and the Flow blockchain. How will you use these features to build Web3's next killer app? -## Further Reading +## Further reading -Now that you've experienced the power of Cadence and EVM interactions firsthand, we recommend checking out the following guides to deepen your understanding: +Now that you've experienced the power of Cadence and EVM interactions firsthand, we recommend you check out the following guides to deepen your understanding: - [How Flow EVM Works] - Learn more about the Flow EVM and how it differs from traditional EVM platforms. - [Interacting with COAs] - Get a fuller picture of how Cadence interacts with EVM contracts via Cadence-owned accounts. diff --git a/docs/blockchain-development-tutorials/cross-vm-apps/interacting-with-coa.md b/docs/blockchain-development-tutorials/cross-vm-apps/interacting-with-coa.md index 4d11c89e63..75e91af29e 100644 --- a/docs/blockchain-development-tutorials/cross-vm-apps/interacting-with-coa.md +++ b/docs/blockchain-development-tutorials/cross-vm-apps/interacting-with-coa.md @@ -6,7 +6,7 @@ sidebar_position: 5 # Interacting with COAs from Cadence -[Cadence Owned Accounts (COAs)](../../build/evm/accounts.md#cadence-owned-accounts) are EVM accounts that a Cadence resouce owns, and are used to interact with Flow EVM from Cadence. +[Cadence Owned Accounts (COAs)] are EVM accounts that a Cadence resouce owns, and are used to interact with Flow EVM from Cadence. COAs expose two interfaces for interaction: one on the Cadence side and one on the EVM side. In this guide, we focuses on how to interact with COAs with Cadence. @@ -16,7 +16,7 @@ In this guide, we will walk through some basic examples that create and and inte To begin, we can take a look at a simplified version of the `EVM` contract, and highlight parts specific to COAs. -You can learn more about the `EVM` contract [here](../../build/cadence/core-contracts/13-evm.md) and find the full contract code on [GitHub](https://github.com/onflow/flow-go/tree/master/fvm/evm/stdlib/contract.cdc). +You can learn more about the `EVM` contract [here] and find the full contract code on [GitHub]. ```cadence EVM.cdc access(all) @@ -81,7 +81,7 @@ contract EVM { The `CadenceOwnedAccount` resource is a part of the `EVM` system contract, so to use any of these functions, you will need to import the `EVM` contract into your Cadence code. -To import the `EVM` contract into your Cadence code using the simple import syntax, you can use the following format (learn more about configuring contracts in `flow.json` [here](../../build/tools/flow-cli/flow.json/configuration.md#contracts)): +To import the `EVM` contract into your Cadence code with the simple import syntax, you can use the following format (learn more about how to configure contracts in `flow.json` [here]): ```cadence // This assumes you are working in the in the Flow CLI, FCL, or another tool that supports this syntax @@ -98,7 +98,7 @@ import EVM from 0x1234 // ... ``` -To find the deployment addresses of the `EVM` contract, you can refer to the [EVM contract documentation](../../build/cadence/core-contracts/13-evm.md). +To find the deployment addresses of the `EVM` contract, you can refer to the [EVM contract documentation]. ## Create a COA @@ -137,7 +137,7 @@ During the singular transaction in which an account is created, the `AuthAccount ::: -First, you'll need to use the CLI to [generate keys](../../build/tools/flow-cli/keys/generate-keys.md) for the new account. Then, run the following transaction to create the Cadence Account and COA at one time. +First, you'll need to use the CLI to [generate keys] for the new account. Then, run the following transaction to create the Cadence Account and COA at one time. :::warning @@ -168,7 +168,7 @@ transaction(publicKeys: [Crypto.KeyListEntry]) { ## Retrieve the EVM Address of a COA -To get the EVM address of a COA, you can use the `address` function from the `EVM` contract. This function returns the EVM address of the COA as an `EVM.Address` struct. This struct is used to represent addresses within Flow EVM and you cna also use it to query the balance, code, nonce, and so on of an account. +To get the EVM address of a COA, you can use the `address` function from the `EVM` contract. This function returns the EVM address of the COA as an `EVM.Address` struct. This struct is used to represent addresses within Flow EVM and you can also use it to query the balance, code, nonce, and so on of an account. For our example, we could query the address of the COA we just created with the following script: @@ -282,7 +282,7 @@ transaction(amount: UFix64) { This is a basic example which only transfers tokens between a single user's COA & Flow account. You can easily modify it to transfer these tokens between any arbitrary accounts. -You can also deposit tokens directly into other types of EVM accounts with the `EVM.EVMAddress.deposit` function. See the [EVM contract documentation](../../build/cadence/core-contracts/13-evm.md) for more information. +You can also deposit tokens directly into other types of EVM accounts with the `EVM.EVMAddress.deposit` function. See the [EVM contract documentation] for more information. ::: @@ -329,20 +329,20 @@ transaction(amount: UFix64) { :::info -This is a basic example which only transfers tokens between a single user's COA & Flow account. It can be easily +This is a basic example which only transfers tokens between a single user's COA and Flow account. It can be easily modified to transfer these tokens between any arbitrary accounts. ::: ## Direct Calls to Flow EVM -To interact with smart contracts on the EVM, you can use the `call` function provided by the COA resource. This function +To interact with smart contracts on the EVM, you can use the `call` function the COA resource provides. This function takes the EVM address of the contract you want to call, the data you want to send, the gas limit, and the value you want to send. It will return a `EVM.Result` struct with the result of the call - you will need to handle this result in your Cadence code. This transaction will use the signer's COA to call a contract method with the defined signature and args at a given EVM -address, executing with the provided gas limit and value: +address, and executes with the provided gas limit and value: ```cadence call.cdc import "EVM" @@ -397,7 +397,7 @@ transaction(evmContractHex: String, signature: String, args: [AnyStruct], gasLim :::info Notice that the calldata is encoded in the scope of the transaction. While developers can encode the calldata -outside the scope of the transaction and pass the encoded data as an argument, doing so compromises the +outside the scope of the transaction and pass the encoded data as an argument, this compromises the human-readability of Cadence transactions. It's encouraged to either define transactions for each COA call and encoded the hardcoded EVM signature and arguments, @@ -457,7 +457,7 @@ transaction(to: String, amount: UInt) { ### Transfer ERC20 -Below is an example transaction demonstrating the common ERC20 transfer. You can use a similar pattern for other arbitrary EVM calls. +Below is an example transaction that demonstrates the common ERC20 transfer. You can use a similar pattern for other arbitrary EVM calls. ```cadence erc20_transfer_from.cdc import "EVM" @@ -506,7 +506,7 @@ transaction(erc20AddressHex: String, to: String, amount: UInt256) { ### Transfer ERC721 -Following on from above, the example transaction below demonstrates a common ERC721 transfer. +The example transaction below demonstrates a common ERC721 transfer. ```cadence erc721_transfer.cdc import "EVM" @@ -554,7 +554,7 @@ transaction(erc721AddressHex: String, to: String, id: UInt256) { #### Bulk transfer ERC721 -As covered in the [Batched EVM transactions walkthrough](./batched-evm-transactions.md), you can script multiple EVM calls in a single Cadence transaction. Compared to the single ERC721 transfer, to bulk send multiple tokens isn't much more code and allows for greater utility out of a single transaction. Below is an example of a bulk ERC721 token transfer. +As covered in the [Batched EVM transactions walkthrough], you can script multiple EVM calls in a single Cadence transaction. Compared to the single ERC721 transfer, to bulk send multiple tokens isn't much more code and allows for greater utility out of a single transaction. Below is an example of a bulk ERC721 token transfer. ```cadence erc721_bulk_transfer.cdc import "EVM" @@ -640,8 +640,18 @@ transaction(bytecode: String) { ## More information -For more information about Cadence-owned Accounts, see [Flow EVM Accounts](../../build/evm/accounts.md). +For more information about Cadence-owned Accounts, see [Flow EVM Accounts]. -Other useful snippets to use when you interact with COAs can be found [here](https://fw-internal-doc.gitbook.io/evm). +Other useful snippets to use when you interact with COAs can be found [here]. -Check out the [Batched EVM Transactions walkthrough](./batched-evm-transactions.md) for details on transaction batching with Cadence. +Check out the [Batched EVM Transactions walkthrough] for details on transaction batching with Cadence. + + + +[Flow EVM Accounts]: ../../build/evm/accounts.md +[here]: https://fw-internal-doc.gitbook.io/evm +[Batched EVM Transactions walkthrough]: ./batched-evm-transactions.md +[EVM contract documentation]: ../../build/cadence/core-contracts/13-evm.md +[generate keys]: ../../build/tools/flow-cli/keys/generate-keys.md +[GitHub]: https://github.com/onflow/flow-go/tree/master/fvm/evm/stdlib/contract.cdc +[Cadence Owned Accounts (COAs)]: ../../build/evm/accounts.md#cadence-owned-accounts \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/cross-vm-apps/introduction.md b/docs/blockchain-development-tutorials/cross-vm-apps/introduction.md index 796b073cb3..5ab862449b 100644 --- a/docs/blockchain-development-tutorials/cross-vm-apps/introduction.md +++ b/docs/blockchain-development-tutorials/cross-vm-apps/introduction.md @@ -64,7 +64,7 @@ We assume you're familiar with [wagmi], [viem], and [RainbowKit]. If you come fr ## Get started -For this tutorial, we'll start from a fork of the [FCL + RainbowKit + Wagmi Integration Demo] built by the team. +For this tutorial, we'll start from a fork of the [FCL + RainbowKit + Wagmi Integration Demo] that the team built. Fork the repo so you can push your work freely to your own copy, then follow the setup instructions. @@ -110,7 +110,7 @@ Currently, the Flow wallet sponsors all gas for all transactions signed with the The first line is the transaction ID of the Flow Cadence transaction that calls **both** of the EVM transactions. Search for it in [Testnet Cadence Flowscan]. -Cadence transactions are more complicated than those in Solidity contracts. Rather than being restricted to run functions present on the contract, they can run arbitrary code as long as the caller has access to all of the resources required by the transaction. +Cadence transactions are more complicated than those in Solidity contracts. Rather than being restricted to run functions present on the contract, they can run arbitrary code as long as the caller has access to all of the resources the transaction requires. You can see the code of the transaction in the `Script` tab, but we've included it here for convenience: @@ -234,7 +234,7 @@ return block.height; Returns the current Cadence VM block number. -## Calling Your own contract +## Call your own contract Next, we'll update the starter to connect to and call functions in our own contract. For this, we'll use a simple [Button Clicker Contract]. You can deploy your own copy, or use the one deployed at [`0xA7Cf2260e501952c71189D04FAd17c704DFB36e6`]. @@ -543,7 +543,7 @@ const calls: EVMBatchCall[] = [ ]; ``` -Click the `Send Batch Transaction Example` button again. You'll have to **manually refresh** the page when the EVM transaction hash appears to see the score update. We haven't wired in the query invalidation yet. +Click `Send Batch Transaction Example` again. You'll have to **manually refresh** the page when the EVM transaction hash appears to see the score update. We haven't wired in the query invalidation yet. Next, use some JavaScript to put 10 copies of the transaction call into the array: @@ -568,7 +568,7 @@ While the batched transactions feature works, we've got a few flaws in the user :::warning -We initially tried getting an AI friend to install this for us and it got very confused. `Next.js` and Tailwind have both had a lot of change recently. As a result, the LLMs don't seem to have caught up just yet. +We initially tried to get an AI friend to install this for us and it got very confused. `Next.js` and Tailwind have both had a lot of change recently. As a result, the LLMs don't seem to have caught up just yet. Do this part the old-fashioned way. @@ -772,7 +772,7 @@ return ( ); ``` -### Testing +### Tests Run the app and make sure it works as expected, even if in a rather ugly fashion. @@ -791,13 +791,13 @@ It's up to you do design a comprehensive strategy for your app, but here, we can ``` -### Styling +### Style It's up to you to make the app pretty. If you need inspiration, you can always check the [reference repo]. ## Conclusion -In this tutorial, you reviewed the demo starter for building hybrid applications that use a common EVM stack and integrate with Flow Cadence. You then added functionality to interface with another contract that mints ERC-20 tokens. Finally, you supercharged your app by using the power of Cadence for EVM multi-call contract writes. +In this tutorial, you reviewed the demo starter to build hybrid applications that use a common EVM stack and integrate with Flow Cadence. You then added functionality to interface with another contract that mints ERC-20 tokens. Finally, you supercharged your app with the power of Cadence for EVM multi-call contract writes. Now that you have completed the tutorial, you will be able to: diff --git a/docs/blockchain-development-tutorials/cross-vm-apps/vm-bridge.md b/docs/blockchain-development-tutorials/cross-vm-apps/vm-bridge.md index 0e8bb1b700..d2e842f602 100644 --- a/docs/blockchain-development-tutorials/cross-vm-apps/vm-bridge.md +++ b/docs/blockchain-development-tutorials/cross-vm-apps/vm-bridge.md @@ -6,7 +6,7 @@ sidebar_position: 6 # Cross-VM Bridge -Flow provides the [Cross-VM Bridge](https://www.github.com/onflow/flow-evm-bridge) which allows the movement of fungible and non-fungible tokens between Flow-Cadence & Flow-EVM. The Cross-VM Bridge is a contract-based protocol which allows the automated and atomic bridging of tokens from Cadence into EVM with their corresponding ERC-20 and ERC-721 token types. +Flow provides the [Cross-VM Bridge] which allows the movement of fungible and non-fungible tokens between Flow-Cadence & Flow-EVM. The Cross-VM Bridge is a contract-based protocol which allows the automated and atomic bridging of tokens from Cadence into EVM with their corresponding ERC-20 and ERC-721 token types. In the opposite direction, it supports bridging of arbitrary ERC-20 and ERC-721 tokens from EVM to Cadence as their corresponding FT or NFT token types. @@ -16,11 +16,9 @@ If a developer wants to define and connect the NFT contracts on both sides of th The Cross-VM Bridge internalizes the capabilities to deploy new token contracts in either VM state as needed, resolves access to and maintains links between associated contracts. It also automates account and contract calls to enforce source VM asset burn or lock, and target VM token mint or unlock. -Developers who want to use the Cross-VM Bridge must use a Cadence transaction. Cross-VM bridging functionality is not currently available natively in Flow EVM. By extension, this means that the EVM account bridging -from EVM to Cadence must be a [`CadenceOwnedAccount` (COA)](interacting-with-coa.md) as this is the only EVM account type that can be controlled from the Cadence runtime. +Developers who want to use the Cross-VM Bridge must use a Cadence transaction. Cross-VM bridging functionality is not currently available natively in Flow EVM. By extension, this means that the EVM account bridging from EVM to Cadence must be a [`CadenceOwnedAccount` (COA)] as this is the only EVM account type that can be controlled from the Cadence runtime. -This [FLIP-233](https://github.com/onflow/flips/pull/233) outlines the architecture and implementation of the VM bridge. An additional [FLIP-318](https://github.com/onflow/flips/blob/main/application/20250131-cross-vm-nft-support.md) describes how developers can create custom associations -between NFTs they define and control in each VM. +This [FLIP-233] outlines the architecture and implementation of the VM bridge. An additional [FLIP-318] describes how developers can create custom associations between NFTs they define and control in each VM. This document will focus on how to use the Cross-VM Bridge and considerations for fungible and non-fungible token projects that deploy to either Cadence or EVM. @@ -30,36 +28,33 @@ You can find the core bridge contracts at the following addresses: | Contracts | Testnet | Mainnet | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| All Cadence Bridge contracts | [`0xdfc20aee650fcbdf`](https://contractbrowser.com/account/0xdfc20aee650fcbdf/contracts) | [`0x1e4aa0b87d10b141`](https://contractbrowser.com/account/0x1e4aa0b87d10b141/contracts) | -| `FlowEVMBridgeFactory.sol` | [`0xf8146b4aef631853f0eb98dbe28706d029e52c52`](https://evm-testnet.flowscan.io/address/0xF8146B4aEF631853F0eB98DBE28706d029e52c52) | [`0x1c6dea788ee774cf15bcd3d7a07ede892ef0be40`](https://evm.flowscan.io/address/0x1C6dEa788Ee774CF15bCd3d7A07ede892ef0bE40) | -| `FlowEVMBridgeDeploymentRegistry.sol` | [`0x8781d15904d7e161f421400571dea24cc0db6938`](https://evm-testnet.flowscan.io/address/0x8781d15904d7e161f421400571dea24cc0db6938) | [`0x8fdec2058535a2cb25c2f8cec65e8e0d0691f7b0`](https://evm.flowscan.io/address/0x8FDEc2058535A2Cb25C2f8ceC65e8e0D0691f7B0) | -| `FlowEVMBridgedERC20Deployer.sol` | [`0x4d45CaD104A71D19991DE3489ddC5C7B284cf263`](https://evm-testnet.flowscan.io/address/0x4d45CaD104A71D19991DE3489ddC5C7B284cf263) | [`0x49631Eac7e67c417D036a4d114AD9359c93491e7`](https://evm.flowscan.io/address/0x49631Eac7e67c417D036a4d114AD9359c93491e7) | -| `FlowEVMBridgedERC721Deployer.sol` | [`0x1B852d242F9c4C4E9Bb91115276f659D1D1f7c56`](https://evm-testnet.flowscan.io/address/0x1B852d242F9c4C4E9Bb91115276f659D1D1f7c56) | [`0xe7c2B80a9de81340AE375B3a53940E9aeEAd79Df`](https://evm.flowscan.io/address/0xe7c2B80a9de81340AE375B3a53940E9aeEAd79Df) | +| All Cadence Bridge contracts | [`0xdfc20aee650fcbdf`] | [`0x1e4aa0b87d10b141`] | +| `FlowEVMBridgeFactory.sol` | [`0xf8146b4aef631853f0eb98dbe28706d029e52c52`] | [`0x1c6dea788ee774cf15bcd3d7a07ede892ef0be40`] | +| `FlowEVMBridgeDeploymentRegistry.sol` | [`0x8781d15904d7e161f421400571dea24cc0db6938`] | [`0x8fdec2058535a2cb25c2f8cec65e8e0d0691f7b0`] | +| `FlowEVMBridgedERC20Deployer.sol` | [`0x4d45CaD104A71D19991DE3489ddC5C7B284cf263`] | [`0x49631Eac7e67c417D036a4d114AD9359c93491e7`] | +| `FlowEVMBridgedERC721Deployer.sol` | [`0x1B852d242F9c4C4E9Bb91115276f659D1D1f7c56`] | [`0xe7c2B80a9de81340AE375B3a53940E9aeEAd79Df`] | And below are the bridge escrow's EVM addresses. These addresses are COAs and are stored stored in the same Flow account as you'll find the Cadence contracts (see above). | Network | Address | | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| Testnet | [`0x0000000000000000000000023f946ffbc8829bfd`](https://evm-testnet.flowscan.io/address/0x0000000000000000000000023f946FFbc8829BFD) | -| Mainnet | [`0x00000000000000000000000249250a5c27ecab3b`](https://evm.flowscan.io/address/0x00000000000000000000000249250a5C27Ecab3B) | +| Testnet | [`0x0000000000000000000000023f946ffbc8829bfd`] | +| Mainnet | [`0x00000000000000000000000249250a5c27ecab3b`] | -## Interacting With the Bridge +## Interact With the Bridge :::info -All bridging activity in either direction is orchestrated via Cadence on COA EVM accounts. This means that all bridging activity must be initiated via a Cadence transaction, not an EVM transaction regardless of the directionality of the bridge request. For more information on the interplay between Cadence and EVM, see [How Flow EVM -Works](../../build/evm/how-it-works.md). +All bridging activity in either direction is orchestrated via Cadence on COA EVM accounts. This means that all bridging activity must be initiated via a Cadence transaction, not an EVM transaction, regardless of the directionality of the bridge request. For more information on the interplay between Cadence and EVM, see [How Flow EVM Works]. ::: ## Overview -The Flow EVM bridge allows both fungible and non-fungible tokens to move atomically between Cadence and EVM. In EVM, fungible tokens are defined as ERC20 tokens, and non-fungible tokens as ERC721 tokens. In Cadence, fungible tokens are defined by contracts that implement [the `FungibleToken` interface](https://github.com/onflow/flow-ft/blob/master/contracts/FungibleToken.cdc) -and non-fungible tokens implement [the `NonFungibleToken` interface](https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc). -You can find full guides to create these projects [here](../tokens/nft-cadence.md). +The Flow EVM bridge allows both fungible and non-fungible tokens to move atomically between Cadence and EVM. In EVM, fungible tokens are defined as ERC20 tokens, and non-fungible tokens as ERC721 tokens. In Cadence, fungible tokens are defined by contracts that implement [the `FungibleToken` interface] and non-fungible tokens implement [the `NonFungibleToken` interface]. You can find full guides to create these projects [here]. -Like all operations on Flow, there are native fees associated with both computation and storage. To prevent spam and sustain the bridge account's storage consumption, fees are charged for both onboarding assets and bridging assets. In the case where storage consumption is expected, fees are charged based on the storage consumed at the current network storage rate. +Like all operations on Flow, there are native fees associated with both computation and storage. To prevent spam and sustain the bridge account's storage consumption, fees are charged to both onboard assets and bridge assets. In the case where storage consumption is expected, fees are charged based on the storage consumed at the current network storage rate. ## Onboard your token to the bridge @@ -73,17 +68,17 @@ To create this association, the asset must be "onboarded" to the bridge before b Any user registers the native token contract with the bridge and the bridge deploys a basic templated version of the contract in the target VM. This basic contract is automatically associated with the native contract and is used for bridging. The developer has no direct control over this bridge-deployed contract because the bridge controls it. -This method is covered in the [Automatic Onboarding Section](#automatic-onboarding) +This method is covered in the [Automatic Onboarding Section]. ### Option 2: custom association onboarding With this option (available for only for NFTs), developers can deploy their own contract to the target VM and declare a custom association between it and the native contract. This allows them to have more control over both contracts, which lets them to include more sophisticated features and mechanisms in their bridged token contracts such as ERC-721C, unique metadata views, and more that aren't included in the default bridged template versions. -This method is covered in the [Custom Association Section](#custom-association-onboarding) +This method is covered in the [Custom Association Section]. :::info -Before you continue to onboard your token, review the [Prep Your Assets for Bridging](#prep-your-assets-for-bridging) section of this document. This describes some steps you should follow to make sure that your native asset or bridged asset are properly set up for you to register them with the bridge. +Before you continue to onboard your token, review the [Prep Your Assets for Bridging] section of this document. This describes some steps you should follow to make sure that your native asset or bridged asset are properly set up for you to register them with the bridge. ::: @@ -119,15 +114,13 @@ Below are transactions relevant to automatically onboarding assets native to eit ## Custom association onboarding -With [Custom Associations](https://github.com/onflow/flips/blob/main/application/20250131-cross-vm-nft-support.md), -developers can deploy NFT contracts in both VMs and associate them with each other, which allows them to retain control of the contracts in both VMs as well as implement custom use-case specific functionality. +With [Custom Associations], developers can deploy NFT contracts in both VMs and associate them with each other, which allows them to retain control of the contracts in both VMs as well as implement custom use-case specific functionality. To do this, each contract must implement a special interface that tells the bridge what the associated contract is in the other VM. The fact that both point to each other validates the intended association, which prevents spoofing. If the contracts do not point to each other this way, you can't register them as a custom association. -Review the [Preparing Custom Associations](#preparing-custom-associations) section to learn how to set up each of your contracts for a custom association. +Review the [Preparing Custom Associations] section to learn how to set up each of your contracts for a custom association. -Below is the transaction for onboarding NFTs for a custom association. Remember that both the Cadence and the Solidity contract need to be deployed -and include the special interface conformances to point to each other before registration! +Below is the transaction for onboarding NFTs for a custom association. Remember that both the Cadence and the Solidity contract need to be deployed and include the special interface conformances to point to each other before registration! **Onboard an NFT Custom Association:** @@ -180,7 +173,7 @@ Alternatively, given some onboarded Cadence type, you can retrieve the associate #### NFTs -Any Cadence NFTs taht bridge to EVM are escrowed in the bridge account and either minted in a bridge-deployed ERC721 contract or transferred from escrow to the calling COA in EVM. On the return trip, NFTs are escrowed in EVM - owned by the bridge's COA - and either unlocked from escrow if locked or minted from a bridge-owned NFT contract. +Any Cadence NFTs that bridge to EVM are escrowed in the bridge account and either minted in a bridge-deployed ERC721 contract or transferred from escrow to the calling COA in EVM. On the return trip, NFTs are escrowed in EVM - owned by the bridge's COA - and either unlocked from escrow if locked or minted from a bridge-owned NFT contract. Below are transactions relevant to bridging NFTs: @@ -206,9 +199,9 @@ Below are transactions relevant to bridging NFTs: #### Fungible tokens -Any Cadence fungible tokens bridging to EVM are escrowed in the bridge account only if they are Cadence-native. If the bridge defines the tokens, they are burned. On the return trip the pattern is similar, as the bridge burns bridge-defined tokens or escrows them if they are EVM-native. In all cases, if the bridge has authority to mint on one side, it must escrow on the other as the native VM contract is owned by an external party. +Any Cadence fungible tokens that bridge to EVM are escrowed in the bridge account only if they are Cadence-native. If the bridge defines the tokens, they are burned. On the return trip the pattern is similar, as the bridge burns bridge-defined tokens or escrows them if they are EVM-native. In all cases, if the bridge has authority to mint on one side, it must escrow on the other as the native VM contract is owned by an external party. -With fungible tokens in particular, there may be some cases where the Cadence contract is not deployed to the bridge account, but the bridge still follows a mint/burn pattern in Cadence. These cases are handled via [`TokenHandler`](https://github.com/onflow/flow-evm-bridge/blob/main/cadence/contracts/bridge/interfaces/FlowEVMBridgeHandlerInterfaces.cdc) implementations. Also know that moving $FLOW to EVM is built into the `EVMAddress` object so any requests to bridge $FLOW to EVM will simply leverage this interface; however, moving $FLOW from EVM to Cadence must be done through the COA resource. +With fungible tokens in particular, there may be some cases where the Cadence contract is not deployed to the bridge account, but the bridge still follows a mint/burn pattern in Cadence. These cases are handled via [`TokenHandler`] implementations. Also know that moving $FLOW to EVM is built into the `EVMAddress` object so any requests to bridge $FLOW to EVM will simply leverage this interface; however, you must move $FLOW from EVM to Cadence through the COA resource. Below are transactions relevant to bridging fungible tokens: @@ -240,7 +233,7 @@ To maximize utility to the ecosystem, this bridge is permissionless and open to ### EVMBridgedMetadata -Proposed in [@onflow/flow-nft/pull/203](https://github.com/onflow/flow-nft/pull/203), the `EVMBridgedMetadata` view presents a mechanism to both represent metadata from bridged EVM assets as well as allow Cadence-native projects to specify the representation of their assets in EVM. It isn'trequired to implement this view to bridge asets, but the bridge does default to it when available as a way to provide projects greater control over their EVM asset definitions within the scope of ERC20 and ERC721 standards. +Proposed in [@onflow/flow-nft/pull/203], the `EVMBridgedMetadata` view presents a mechanism to both represent metadata from bridged EVM assets as well as allow Cadence-native projects to specify the representation of their assets in EVM. It isn't required to implement this view to bridge asets, but the bridge does default to it when available as a way to provide projects greater control over their EVM asset definitions within the scope of ERC20 and ERC721 standards. The interface for this view is as follows: @@ -273,10 +266,9 @@ This uri value could be a pointer to some offchain metadata if you expect your m The key consideration with respect to metadata is the distinct metadata storage patterns between ecosystem. It's critical for NFT utility that the metadata be bridged in addition to the representation of the NFTs ownership. However, it's commonplace for Cadence NFTs to store metadata onchain while EVM NFTs often store an onchain pointer to metadata stored offchain. -For Cadence NFTs to be properly represented in EVM platforms, the metadata must be bridged in -a format expected by those platforms and be done in a manner that also preserves the atomicity of bridge requests. The path forward on this was decided to be a commitment of serialized Cadence NFT metadata into formats popular in the EVM ecosystem. +For Cadence NFTs to be properly represented in EVM platforms, the metadata must be bridged in a format expected by those platforms and be done in a manner that also preserves the atomicity of bridge requests. The path forward on this was decided to be a commitment of serialized Cadence NFT metadata into formats popular in the EVM ecosystem. -For assets that do not implement `EVMBridgedMetadata`, the bridge will attempt to serialize the metadata of the asset as a JSON data URL string. This is done via the [`SerializeMetadata` contract](https://github.com/onflow/flow-evm-bridge/blob/main/cadence/contracts/utils/SerializeMetadata.cdc) which serializes metadata values into a JSON blob compatible with the OpenSea metadata standard. The serialized metadata is then committed as the ERC721 `tokenURI` upon bridging Cadence-native NFTs to EVM. Since Cadence NFTs can easily update onchain metadata either by field or by the ownership of sub-NFTs, this serialization pattern enables token URI updates on subsequent bridge requests. +For assets that do not implement `EVMBridgedMetadata`, the bridge will attempt to serialize the metadata of the asset as a JSON data URL string. This is done via the [`SerializeMetadata` contract] which serializes metadata values into a JSON blob compatible with the OpenSea metadata standard. The serialized metadata is then committed as the ERC721 `tokenURI` upon bridging Cadence-native NFTs to EVM. Since Cadence NFTs can easily update onchain metadata either by field or by the ownership of sub-NFTs, this serialization pattern allows token URI updates on subsequent bridge requests. ### Prepar custom associations @@ -294,7 +286,7 @@ The bridge only supports a single custom association declaration. This means tha #### Cadence -All Cadence NFT contracts implement [Metadata Views](../../build/cadence/advanced-concepts/metadata-views.md) that return metadata about their NFTs in standard ways via the `{Contract}.resolveContractView()` and `{NFT}.resolveView()` methods. +All Cadence NFT contracts implement [Metadata Views] that return metadata about their NFTs in standard ways via the `{Contract}.resolveContractView()` and `{NFT}.resolveView()` methods. The following new view (`CrossVMMetadataViews.EVMPointer`) **must** be resolved at the contract level (`ViewResolver.resolveContractView()`) for a given Type **and** at the NFT level (`ViewResolver.Resolver.resolveView()`) @@ -314,7 +306,7 @@ access(all) struct EVMPointer { This view allows a Cadence contract to specify which Solidity contract it is associated with. -You can see an example of how this view is implemented in [the `ExampleNFT` contract](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc#L173-L195) in the Flow Non-Fungible Token repo. +You can see an example of how this view is implemented in [the `ExampleNFT` contract] in the Flow Non-Fungible Token repo. If your EVM contract expects metadata to be passed from Cadence at the time of bridging, you must implement the `CrossVMMetadataViews.EVMBytesMetadata` view. You'll find this useful for Cadence-native NFTs with dynamic metadata. This view will be resolved by the bridge and passed to your EVM contract when the `fulfillToEVM` method is called. @@ -356,7 +348,7 @@ If the NFT being onboarded to the bridge is native to Flow-EVM, then the associa } ``` -You can see an example of an implementation of this interface in the [Flow EVM bridge repo ExampleNFT contract](https://github.com/onflow/flow-evm-bridge/blob/flip-318/cadence/contracts/example-assets/cross-vm-nfts/ExampleEVMNativeNFT.cdc#L352-L377). +You can see an example of an implementation of this interface in the [Flow EVM bridge repo ExampleNFT contract]. A Capability with the `FulfillFromEVM` entitlement is required at the time of registration so the bridge can fulfill NFTs bridged from EVM for the first time. @@ -379,13 +371,13 @@ interface ICrossVM { } ``` -As an example, [`ICrossVM` is already implemented](https://github.com/onflow/flow-evm-bridge/blob/main/solidity/src/interfaces/ICrossVM.sol) and in use in the bridged [ERC721](https://github.com/onflow/flow-evm-bridge/blob/flip-318/solidity/src/templates/FlowEVMBridgedERC721.sol#L37-L43) and [ERC20](https://github.com/onflow/flow-evm-bridge/blob/flip-318/solidity/src/templates/FlowEVMBridgedERC20.sol#L13-L40) templates. +As an example, [`ICrossVM` is already implemented] and in use in the bridged [ERC721] and [ERC20] templates. If you want to register a custom association for an NFT that is native to Cadence, which means that your project distributes NFTs to users on the Cadence side, then your ERC721 contract must implement the `CrossVMBridgeERC721Fulfillment` contract. This is a required conformance that does three primary things: -1. Implements the mint/escrow pattern expected by the VM bridge -2. Allows for the passing of arbitrary abi-encodable metadata from the Cadence NFT at the time of bridging -3. Exposes two optional hooks enabling you to update the fulfilled token's URI with the provided metadata at the time of bridging +1. Implements the mint/escrow pattern expected by the VM bridge. +2. Allows for the passing of arbitrary abi-encodable metadata from the Cadence NFT at the time of bridging. +3. Exposes two optional hooks, which allows you to update the fulfilled token's URI with the provided metadata at the time of bridging. Here is the Solidity contract to implement: @@ -500,21 +492,64 @@ It's also recognized that the logic of some use cases may actually be compromise For instance, an ERC721 implementation may reclaim a user's assets after a month of inactivity. In such a case, bridging that ERC721 to Cadence would decouple the representation of ownership of the bridged NFT from the actual ownership in the defining ERC721 contract after the token had been reclaimed - there would be no NFT in escrow for the bridge to transfer on fulfillment of the NFT back to EVM. In such cases, projects may choose to opt-out of bridging, but **importantly must do so before the asset has been onboarded to the bridge**. -For Solidity contracts, opting out is as simple as extending the [`BridgePermissions.sol` abstract contract](https://github.com/onflow/flow-evm-bridge/blob/main/solidity/src/interfaces/BridgePermissions.sol) which defaults `allowsBridging()` to `false`. The bridge explicitly checks for the implementation of `IBridgePermissions` and the value of `allowsBridging()` to validate that the contract has not opted out of bridging. +For Solidity contracts, opting out is as simple as extending the [`BridgePermissions.sol` abstract contract] which defaults `allowsBridging()` to `false`. The bridge explicitly checks for the implementation of `IBridgePermissions` and the value of `allowsBridging()` to validate that the contract has not opted out of bridging. -Similarly, Cadence contracts can implement the [`IBridgePermissions.cdc` contract interface](https://github.com/onflow/flow-evm-bridge/blob/main/cadence/contracts/bridge/interfaces/IBridgePermissions.cdc). This contract has a single method `allowsBridging()` with a default implementation returning `false`. Again, the bridge explicitly checks for the implementation of `IBridgePermissions` and the value of `allowsBridging()` to validate that the contract has not opted out of bridging. Should you later choose to turn on bridging, you can simply override the default implementation and return `true`. +Similarly, Cadence contracts can implement the [`IBridgePermissions.cdc` contract interface]. This contract has a single method `allowsBridging()` with a default implementation returning `false`. Again, the bridge explicitly checks for the implementation of `IBridgePermissions` and the value of `allowsBridging()` to validate that the contract has not opted out of bridging. Should you later choose to turn on bridging, you can simply override the default implementation and return `true`. In both cases, `allowsBridging()` gates onboarding to the bridge. After the onboard occurs - **a permissionless operation anyone can execute** - the value of `allowsBridging()` is irrelevant and assets can move between VMs permissionlessly. ## Under the hood -For an in-depth look at the high-level architecture of the bridge, see [FLIP -#237](https://github.com/onflow/flips/blob/main/application/20231222-evm-vm-bridge.md) +For an in-depth look at the high-level architecture of the bridge, see [FLIP #237] ### Additional resources For the current state of Flow EVM across various task paths, see the following resources: -- [Flow EVM Equivalence forum post](https://forum.flow.com/t/evm-equivalence-on-flow-proposal-and-path-forward/5478) -- [EVM Integration FLIP #223](https://github.com/onflow/flips/pull/225/files) -- [Gateway & JSON RPC FLIP #235](https://github.com/onflow/flips/pull/235) +- [Flow EVM Equivalence forum post] +- [EVM Integration FLIP #223] +- [Gateway & JSON RPC FLIP #235] + + + + +[Flow EVM Equivalence forum post]: https://forum.flow.com/t/evm-equivalence-on-flow-proposal-and-path-forward/5478 +[EVM Integration FLIP #223]: https://github.com/onflow/flips/pull/225/files +[Gateway & JSON RPC FLIP #235]: https://github.com/onflow/flips/pull/235) +[FLIP #237]: https://github.com/onflow/flips/blob/main/application/20231222-evm-vm-bridge.md +[`IBridgePermissions.cdc` contract interface]: https://github.com/onflow/flow-evm-bridge/blob/main/cadence/contracts/bridge/interfaces/IBridgePermissions.cdc +[`BridgePermissions.sol` abstract contract]: https://github.com/onflow/flow-evm-bridge/blob/main/solidity/src/interfaces/BridgePermissions.sol +[`ICrossVM` is already implemented]: https://github.com/onflow/flow-evm-bridge/blob/main/solidity/src/interfaces/ICrossVM.sol +[ERC721]: https://github.com/onflow/flow-evm-bridge/blob/flip-318/solidity/src/templates/FlowEVMBridgedERC721.sol#L37-L43 +[ERC20]: https://github.com/onflow/flow-evm-bridge/blob/flip-318/solidity/src/templates/FlowEVMBridgedERC20.sol#L13-L40 +[Flow EVM bridge repo ExampleNFT contract]: https://github.com/onflow/flow-evm-bridge/blob/flip-318/cadence/contracts/example-assets/cross-vm-nfts/ExampleEVMNativeNFT.cdc#L352-L377 +[the `ExampleNFT` contract]: https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc#L173-L195 +[Metadata Views]: ../../build/cadence/advanced-concepts/metadata-views.md +[`SerializeMetadata` contract]: https://github.com/onflow/flow-evm-bridge/blob/main/cadence/contracts/utils/SerializeMetadata.cdc +[@onflow/flow-nft/pull/203]: https://github.com/onflow/flow-nft/pull/203 +[`TokenHandler`]: https://github.com/onflow/flow-evm-bridge/blob/main/cadence/contracts/bridge/interfaces/FlowEVMBridgeHandlerInterfaces.cdc +[Preparing Custom Associations]: #preparing-custom-associations +[Custom Associations]: https://github.com/onflow/flips/blob/main/application/20250131-cross-vm-nft-support.md +[Automatic Onboarding Section]: #automatic-onboarding +[Custom Association Section]: #custom-association-onboarding +[Prep Your Assets for Bridging]: #prep-your-assets-for-bridging +[How Flow EVM Works]: ../../build/evm/how-it-works.md +[the `FungibleToken` interface]: https://github.com/onflow/flow-ft/blob/master/contracts/FungibleToken.cdc +[the `NonFungibleToken` interface]: https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc) +[here]: ../tokens/nft-cadence.md) +[`0xdfc20aee650fcbdf`]: https://contractbrowser.com/account/0xdfc20aee650fcbdf/contracts +[`0x1e4aa0b87d10b141`]: https://contractbrowser.com/account/0x1e4aa0b87d10b141/contracts) +[`0xf8146b4aef631853f0eb98dbe28706d029e52c52`]: https://evm-testnet.flowscan.io/address/0xF8146B4aEF631853F0eB98DBE28706d029e52c52) +[`0x1c6dea788ee774cf15bcd3d7a07ede892ef0be40`]: https://evm.flowscan.io/address/0x1C6dEa788Ee774CF15bCd3d7A07ede892ef0bE40) +[`0x8781d15904d7e161f421400571dea24cc0db6938`]: https://evm-testnet.flowscan.io/address0x8781d15904d7e161f421400571dea24cc0db6938 +[`0x8fdec2058535a2cb25c2f8cec65e8e0d0691f7b0`]: https://evm.flowscan.io/address/0x8FDEc2058535A2Cb25C2f8ceC65e8e0D0691f7B0) +[`0x4d45CaD104A71D19991DE3489ddC5C7B284cf263`]: https://evm-testnet.flowscan.io/address/0x4d45CaD104A71D19991DE3489ddC5C7B284cf263 +[`0x49631Eac7e67c417D036a4d114AD9359c93491e7`]: https://evm.flowscan.io/address/0x49631Eac7e67c417D036a4d114AD9359c93491e7 +[`0x1B852d242F9c4C4E9Bb91115276f659D1D1f7c56`]: https://evm-testnet.flowscan.io/address/0x1B852d242F9c4C4E9Bb91115276f659D1D1f7c56 +[`0xe7c2B80a9de81340AE375B3a53940E9aeEAd79Df`]: https://evm.flowscan.io/address/0xe7c2B80a9de81340AE375B3a53940E9aeEAd79Df +[`0x0000000000000000000000023f946ffbc8829bfd`]: https://evm-testnet.flowscan.io/address/0x0000000000000000000000023f946FFbc8829BFD +[`0x00000000000000000000000249250a5c27ecab3b`]: https://evm.flowscan.io/address/0x00000000000000000000000249250a5C27Ecab3B +[`CadenceOwnedAccount` (COA)]: interacting-with-coa.md +[FLIP-233]: https://github.com/onflow/flips/pull/233 +[FLIP-318]: https://github.com/onflow/flips/blob/main/application/20250131-cross-vm-nft-support.md +[Cross-VM Bridge]: https://www.github.com/onflow/flow-evm-bridge \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/evm/development-tools/foundry.md b/docs/blockchain-development-tutorials/evm/development-tools/foundry.md index 39f088bdf8..42ca041e0d 100644 --- a/docs/blockchain-development-tutorials/evm/development-tools/foundry.md +++ b/docs/blockchain-development-tutorials/evm/development-tools/foundry.md @@ -7,7 +7,7 @@ sidebar_position: 5 # Using Foundry with Flow -Foundry is a suite of development tools that simplifies the process to develop and deploy Solidity contracts to EVM networks. This guide will walk you through thow to deploy a Solidity contract to Flow EVM with the Foundry development toolchain. You can check out the official Foundry docs [here](https://book.getfoundry.sh/). +Foundry is a suite of development tools that simplifies the process to develop and deploy Solidity contracts to EVM networks. This guide will walk you through how to deploy a Solidity contract to Flow EVM with the Foundry development toolchain. You can check out the official [Foundry docs]. In this guide, we'll deploy an ERC-20 token contract to Flow EVM using Foundry. We'll cover: @@ -26,13 +26,13 @@ To use Flow across all Foundry tools you need to: --rpc-url https://testnet.evm.nodes.onflow.org ``` -2. Use the `--legacy` flag to turn off [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) style transactions. Flow will support EIP-1559 soon and this flag won't be needed. +2. Use the `--legacy` flag to turn off [EIP-1559] style transactions. Flow will support EIP-1559 soon and this flag won't be needed. As an example, we'll show you how to deploy a fungible token contract to Flow EVM with Foundry. You will see how the above flags are used in practice. -## Example: Deploying an ERC-20 Token Contract to Flow EVM +## Example: Deploy an ERC-20 Token Contract to Flow EVM -ERC-20 tokens are the most common type of tokens on Ethereum. We'll use [OpenZeppelin](https://www.openzeppelin.com/) starter templates with Foundry on Flow Testnet to deploy our own token called `MyToken`. +ERC-20 tokens are the most common type of tokens on Ethereum. We'll use [OpenZeppelin] starter templates with Foundry on Flow Testnet to deploy our own token called `MyToken`. ### Installation @@ -52,17 +52,17 @@ This will install the Foundry tool suite: `forge`, `cast`, `anvil`, and `chisel` You may need to reload your shell after `foundryup` installation. -Check out the official [Installation](https://book.getfoundry.sh/getting-started/installation) guide for more information about different platforms or installing specific versions. +Check out the official [Installation Guide] for more information about different platforms or how to install specific versions. ### Wallet setup -We first need to generate a key pair for our EVM account. We can do this using the `cast` tool: +We first need to generate a key pair for our EVM account. We can do this with the `cast` tool: ```shell cast wallet new ``` -`cast` will print the private key and address of the new account. We can then paste the account address into the [Faucet](https://faucet.flow.com/fund-account) to fund it with some Testnet FLOW tokens. +`cast` will print the private key and address of the new account. We can then paste the account address into the [Faucet] to fund it with some Testnet FLOW tokens. You can verify the balance of the account after funding. Replace `$YOUR_ADDRESS` with the address of the account you funded: @@ -221,7 +221,7 @@ The above will print the deployed contract address. We'll use it in the next sec ### Verify a smart contract -After you deploy the contract, you can verify it so that others can see the source code and interact with it from Flow's block explorer. You can use the [`forge verify-contract`](https://book.getfoundry.sh/reference/forge/forge-verify-contract) command: +After you deploy the contract, you can verify it so that others can see the source code and interact with it from Flow's block explorer. You can use the [`forge verify-contract`] command: ```shell forge verify-contract --rpc-url https://testnet.evm.nodes.onflow.org/ \ @@ -233,7 +233,7 @@ forge verify-contract --rpc-url https://testnet.evm.nodes.onflow.org/ \ :::info -When you verify a Mainnet contract, be sure to use the Mainnet [RPC](../../../build/evm/networks.md) and block explorer URLs. +When you verify a Mainnet contract, be sure to use the Mainnet [RPC] and block explorer URLs. ::: @@ -265,7 +265,7 @@ cast call $DEPLOYED_MYTOKEN_ADDRESS \ "symbol()(string)" ``` -### Sending Transactions +### Send Transactions Let's create a second account and move some tokens with a transaction. You can use `cast wallet new` to create a new test account. You don't need to fund it to receive tokens. Replace `$NEW_ADDRESS` with the address of the new account: @@ -295,3 +295,13 @@ cast balance \ --erc20 $DEPLOYED_MYTOKEN_ADDRESS \ $DEPLOYER_ADDRESS ``` + + + +[Foundry docs]: https://book.getfoundry.sh/) +[EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 +[OpenZeppelin]: https://www.openzeppelin.com/ +[Installation Guide]: https://book.getfoundry.sh/getting-started/installation +[Faucet]: https://faucet.flow.com/fund-account +[`forge verify-contract`]: https://book.getfoundry.sh/reference/forge/forge-verify-contract +[RPC]: ../../../build/evm/networks.md \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/evm/development-tools/hardhat.md b/docs/blockchain-development-tutorials/evm/development-tools/hardhat.md index 37e375163c..f860967f2c 100644 --- a/docs/blockchain-development-tutorials/evm/development-tools/hardhat.md +++ b/docs/blockchain-development-tutorials/evm/development-tools/hardhat.md @@ -13,9 +13,9 @@ Hardhat is an Ethereum development tool designed to facilitate the deployment, t ### Node -Node v18 or higher, available for [download here](https://nodejs.org/en/download). +Node v18 or higher, available for [download here]. -For those new to Hardhat, we recommend that you exploare the [official documentation](https://hardhat.org/tutorial/creating-a-new-hardhat-project) to get acquainted. The following instructions use `npm` to initialize a project and install dependencies: +For those new to Hardhat, we recommend that you exploare the [official Hardhat documentation] to get acquainted. The following instructions use `npm` to initialize a project and install dependencies: ### Wallet @@ -36,7 +36,7 @@ npx hardhat init ### Fund Your wallet -To deploy smart contracts, ensure your wallet has **$FLOW**. To obtain funds, navigate to the Flow [Faucet](https://faucet.flow.com/fund-account) and enter your wallet address. +To deploy smart contracts, ensure your wallet has **$FLOW**. To obtain funds, navigate to the Flow [Faucet] and enter your wallet address. ## Deploy a smart contract with Hardhat @@ -129,7 +129,7 @@ main() 5. Run `npx hardhat run scripts/deploy.ts --network testnet` in the project root. 6. Copy the deployed `HelloWorld` address. This address will be used in other scripts. -Output should look like this (with the exception that your address will be different): +Output will look like this (with the exception that your address will be different): ```shell ❯ npx hardhat run scripts/deploy.ts --network testnet @@ -137,7 +137,7 @@ Deploying contracts with the account: ... HelloWorld address: 0x3Fe94f43Fb5CdB8268A801f274521a07F7b99dfb ``` -You can now search for your deployed contract on the [Flowscan block explorer](https://evm-testnet.flowscan.io/)! +You can now search for your deployed contract on the [Flowscan] block explorer! ### Get HelloWorld contract greeting @@ -244,7 +244,7 @@ The greeting is: Howdy! ### Verify contract -To verify your contract on [Flowscan](https://evm-testnet.flowscan.io/), you can update your Hardhat config file. To do this, include the correct chainID, apiURL and browserURL: +To verify your contract on [Flowscan], you can update your Hardhat config file. To do this, include the correct chainID, apiURL and browserURL: ```javascript import { HardhatUserConfig } from 'hardhat/config'; @@ -286,8 +286,16 @@ const config: HardhatUserConfig = { export default config; ``` -The [verify](https://docs.blockscout.com/developer-support/verifying-a-smart-contract/hardhat-verification-plugin) plugin requires you to include constructor arguments with the verify task and ensures that they correspond to expected ABI signature. However, Blockscout ignores those arguments, so you may specify any values that correspond to the ABI. Execute the following command to verify the contract: +The [verify] plugin requires you to include constructor arguments with the verify task and ensures that they correspond to expected ABI signature. However, Blockscout ignores those arguments, so you may specify any values that correspond to the ABI. Execute the following command to verify the contract: ```shell npx hardhat verify --network testnet DEPLOYED_CONTRACT_ADDRESS "Constructor argument 1" -``` \ No newline at end of file +``` + + + +[download here]: https://nodejs.org/en/download +[official Hardhat documentation]: https://hardhat.org/tutorial/creating-a-new-hardhat-project +[Faucet]: https://faucet.flow.com/fund-account +[Flowscan]: https://evm-testnet.flowscan.io/ +[verify]: https://docs.blockscout.com/developer-support/verifying-a-smart-contract/hardhat-verification-plugin \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/evm/development-tools/index.md b/docs/blockchain-development-tutorials/evm/development-tools/index.md index b3fbaba750..b3e136d02e 100644 --- a/docs/blockchain-development-tutorials/evm/development-tools/index.md +++ b/docs/blockchain-development-tutorials/evm/development-tools/index.md @@ -16,9 +16,9 @@ keywords: # Flow EVM Development Tools -Professional smart contract development requires robust tooling to write, test, deploy, and manage Solidity contracts. This section covers the most popular and powerful development tools in the Ethereum ecosystem, adapted for Flow EVM development. From command-line frameworks to browser-based IDEs, these tools provide everything you need for comprehensive smart contract development workflows. +Professional smart contract development requires robust tools to write, test, deploy, and manage Solidity contracts. This section covers the most popular and powerful development tools in the Ethereum ecosystem, adapted for Flow EVM development. From command-line frameworks to browser-based IDEs, these tools provide everything you need for comprehensive smart contract development workflows. -Each tool offers unique strengths: Foundry excels at testing and gas optimization, Hardhat provides extensive plugin ecosystems and TypeScript support, while Remix allows rapid prototyping without local setup. These tutorials demonstrate how to configure and use each tool effectively with Flow EVM, which allows you to choose the right development environment for your project needs. +Each tool offers unique strengths: Foundry excels at testing and gas optimization, Hardhat provides extensive plugin ecosystems and TypeScript support, while Remix allows you to rapidly prototype without local setup. These tutorials demonstrate how to configure and use each tool effectively with Flow EVM, which allows you to choose the right development environment for your project needs. ## [Foundry] diff --git a/docs/blockchain-development-tutorials/evm/development-tools/remix.md b/docs/blockchain-development-tutorials/evm/development-tools/remix.md index 9e0d71e444..5471060fba 100644 --- a/docs/blockchain-development-tutorials/evm/development-tools/remix.md +++ b/docs/blockchain-development-tutorials/evm/development-tools/remix.md @@ -7,7 +7,7 @@ sidebar_position: 3 # Using Remix -Remix is an open-source, web-based development environment tailored for EVM smart contract development. It offers developers a comprehensive suite of tools to write, deploy, and test smart contracts in Solidity. For more information, visit [Remix](https://remix.ethereum.org/). +Remix is an open-source, web-based development environment tailored for EVM smart contract development. It offers developers a comprehensive suite of tools to write, deploy, and test smart contracts in Solidity. For more information, visit [Remix]. ## Add the Flow network to MetaMask @@ -17,7 +17,7 @@ Navigate to the [Using EVM] page to find the button to add the Flow network info ## Fund Your Flow Account -Navigate to the [Flow Testnet Faucet](https://faucet.flow.com/fund-account) to obtain FLOW tokens necessary to deploy a smart contract. +Navigate to the [Flow Testnet Faucet] to obtain FLOW tokens necessary to deploy a smart contract. ## Deploy a smart contract with Remix @@ -63,11 +63,11 @@ contract HelloWorld { 4. Make sure to select `Injected Provider - Metamask` in Environment dropdown. 5. Deploy the `HelloWorld` smart contract. -## Calling the Deployed Smart Contract +## Call the Deployed Smart Contract ![Call Smart Contract](./imgs/Remix-call-getGreeting.gif) -### Using Ethers.js to Call the HelloWorld Smart Contract +### Use Ethers.js to Call the HelloWorld Smart Contract 1. Create a new `get-greeting.js` file under `scripts`. 2. Paste in the JavaScript code below. @@ -118,4 +118,6 @@ Follow the steps below to change the greeting and retrieve the new greeting. +[Remix]: https://remix.ethereum.org/ +[Flow Testnet Faucet]: https://faucet.flow.com/fund-account [Using EVM]: ../../../build/evm/using.mdx \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/evm/frameworks/ethers.md b/docs/blockchain-development-tutorials/evm/frameworks/ethers.md index e955ceabb2..e4f741ea81 100644 --- a/docs/blockchain-development-tutorials/evm/frameworks/ethers.md +++ b/docs/blockchain-development-tutorials/evm/frameworks/ethers.md @@ -6,7 +6,7 @@ sidebar_position: 1 # Ethers.js -[ethers.js](https://docs.ethers.org/v5/) is a powerful JavaScript library for interacting with Ethereum and other EVM-compatible blockchain networks. +[ethers.js] is a powerful JavaScript library for interacting with Ethereum and other EVM-compatible blockchain networks. In this guide, we'll walk you through how to use `ethers.js` to interact with smart contracts on the Flow Blockchain. @@ -14,7 +14,7 @@ In this guide, we'll walk you through how to use `ethers.js` to interact with sm ## Installation -To begin using `ethers.js` in your project, you'll need to install the package. To do this, run the following command: +To use `ethers.js` in your project, you'll first need to install the package. To do this, run the following command: ```bash bashCopy code @@ -104,3 +104,7 @@ async function getValue() { console.log(value.toString()); } ``` + + + +[ethers.js]: https://docs.ethers.org/v5/ diff --git a/docs/blockchain-development-tutorials/evm/frameworks/rainbowkit.md b/docs/blockchain-development-tutorials/evm/frameworks/rainbowkit.md index b427d01cb0..35f4aa1833 100644 --- a/docs/blockchain-development-tutorials/evm/frameworks/rainbowkit.md +++ b/docs/blockchain-development-tutorials/evm/frameworks/rainbowkit.md @@ -43,9 +43,9 @@ $ cd my-rainbowkit-app $ npm run dev ``` -The [RainbowKit](https://www.rainbowkit.com/) components will be available throughout your application via the provided wrapper components. +The [RainbowKit] components are available throughout your application via the provided wrapper components. -### Creating the Flow Wallet Connector +### Create the Flow Wallet connector The first major step is to define the Flow Wallet connector. Create a new file called `flowWallet.ts` in `src/flowWallet.ts` to house the wallet configuration: @@ -163,19 +163,18 @@ export const config = createConfig({ WalletConnect Project ID -Every dApp that relies on WalletConnect now needs to obtain a projectId from [WalletConnect Cloud (now rebranded as reown)](https://cloud.reown.com/sign-in). This is absolutely free and only takes a few minutes. +Every dApp that relies on WalletConnect now needs to obtain a projectId from [WalletConnect Cloud (now rebranded as reown)]. This is absolutely free and only takes a few minutes. To get a Project ID, sign up at WalletConnect Cloud, create a new project, and copy the generated ID into the `projectId` variable in the `wagmi.ts` file. ::: -## Testing Your Integration +## Test Your Integration After you implement the Flow Wallet connector and configure Wagmi, follow these steps to verify that the integration works correctly in your dApp: 1. **Click "Connect Wallet"** – Open your application and click "Connect Wallet." -2. **Check for Flow Wallet** – Ensure Flow Wallet appears as an option in the RainbowKit wallet selection modal. - - If you haven't installed the browser extension and set up your wallet yet, you can find install it via the [Chrome Web Store][2]. +2. **Check for Flow Wallet** – Ensure Flow Wallet appears as an option in the RainbowKit wallet selection modal. If you haven't installed the browser extension and set up your wallet yet, you can find install it via the [Chrome Web Store][2]. 3. **Connect the Wallet** – Click on Flow Wallet in the selection modal. If you use the browser extension, open it and press "Connect." ![Rainbowkit dAPP UI](./imgs/rainbowkit-1.png) @@ -186,7 +185,7 @@ After you implement the Flow Wallet connector and configure Wagmi, follow these ## Conclusion -In this tutorial, you learned how to integrate Flow Wallet with [RainbowKit](https://www.rainbowkit.com/) and create a seamless wallet connection experience for your users. You should now be able to: +In this tutorial, you learned how to integrate Flow Wallet with [RainbowKit] and create a seamless wallet connection experience for your users. You should now be able to: - Create a custom Flow Wallet connector compatible with RainbowKit's interface. - Configure your Wagmi setup to support Flow Wallet connections. - Implement a complete wallet connection flow for Flow blockchain users. @@ -194,5 +193,9 @@ In this tutorial, you learned how to integrate Flow Wallet with [RainbowKit](htt Now that you've completed this tutorial, you're ready to enhance your dApp with additional Flow blockchain features such as token transfers, NFT minting, and smart contract interactions. + + [1]: https://www.rainbowkit.com/ -[2]: https://chromewebstore.google.com/detail/flow-wallet/hpclkefagolihohboafpheddmmgdffjm?hl=en \ No newline at end of file +[2]: https://chromewebstore.google.com/detail/flow-wallet/hpclkefagolihohboafpheddmmgdffjm?hl=en +[RainbowKit]: https://www.rainbowkit.com/ +[WalletConnect Cloud (now rebranded as reown)]: https://cloud.reown.com/sign-in) \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/evm/frameworks/wagmi.md b/docs/blockchain-development-tutorials/evm/frameworks/wagmi.md index 02a8760460..d79326f7d3 100644 --- a/docs/blockchain-development-tutorials/evm/frameworks/wagmi.md +++ b/docs/blockchain-development-tutorials/evm/frameworks/wagmi.md @@ -11,7 +11,7 @@ Make sure to use `viem` version `2.9.6` or greater. This version contains flow E # Viem & Wagmi -Flow networks have been added to viem chain definitions [viem networks](https://github.com/wevm/viem/tree/main/src/chains/definitions). This allows for convenient flow network configuration when you use viem and wagmi. +Flow networks have been added to viem chain definitions [viem networks]. This allows for convenient flow network configuration when you use viem and wagmi. ## Viem Flow Config @@ -43,7 +43,7 @@ This tutorial will guide you through how to create a simple web application, con ## Step 1: Set up the Next.js project -This tutorial will follow [Wagmi getting-started manual tutorial](https://wagmi.sh/react/getting-started). +This tutorial will follow the [Wagmi getting-started manual tutorial]. First, let's create a Wagmi project named `flow-evm-wagmi`. We will use npm but you are welcome to use yarn or bun. @@ -64,7 +64,8 @@ npm install ## Step 2: Configure Wagmi and connect the Wallet -Make sure you have Metamask installed and Flow network configured. [Metamask and Flow blockchain]. +Make sure you have Metamask installed and Flow network configured. For more information, see [Metamask and Flow blockchain]. + Wagmi needs to know what networks to be aware of. Let's configure to use Flow Testnet and update the `config.ts` file with the following: ```javascript @@ -136,7 +137,7 @@ export default App; ![Connect Metamask](./imgs/Connect-Metamask.gif) -This step relies on an already deployed HelloWorld contract. See [Using Remix](../development-tools/remix.md) to deploy a smart contract on flow evm blockchain. Create or edit the simple `page.tsx` file in the app directory to have better styles, that's beyond this tutorial. We will modify `page.txs` to add a new `HelloWorld.tsx`. Replace `YOUR_CONTRACT_ADDRESS` with your deployed address. +This step relies on an already deployed HelloWorld contract. See [Using Remix] to deploy a smart contract on flow evm blockchain. Create or edit the simple `page.tsx` file in the app directory to have better styles, that's beyond this tutorial. We will modify `page.txs` to add a new `HelloWorld.tsx`. Replace `YOUR_CONTRACT_ADDRESS` with your deployed address. ## Step 3: Create the interface for HelloWorld contract @@ -195,7 +196,7 @@ const HelloWorld = () => { export default HelloWorld; ``` -Reminder: Replace YOUR_CONTRACT_ADDRESS with the actual address of your deployed HelloWorld contract. +Replace YOUR_CONTRACT_ADDRESS with the actual address of your deployed HelloWorld contract. Also notice you need the HelloWorld contract ABI, save this to a new file called `HelloWorld.json` in the app directory. @@ -250,7 +251,7 @@ Also notice you need the HelloWorld contract ABI, save this to a new file called } ``` -## Step 4: Integrate the HelloWorld Component +## Step 4: Integrate the HelloWorld component Finally, import and use the HelloWorld component in your `pages.tsx`, throw it at the bottom of the render section. @@ -282,10 +283,14 @@ import HelloWorld from './helloWorld' Now, you have a functional App that can connect to Metamask, display the current greeting from the "HelloWorld" smart contract, and update the greeting. -To test it, update the greeting, sign a transaction in your Metamask, wait a minute, then refresh the website. Handling transactions are outside of this tutorial. We'll leave that as a future task. [Checkout Wagmi documentation](https://wagmi.sh/react/getting-started) +To test it, update the greeting, sign a transaction in your Metamask, wait a minute, then refresh the website. Handling transactions are outside of this tutorial. We'll leave that as a future task. [Checkout Wagmi documentation] ![Update HelloWorld Greeting](./imgs/Update-HelloWorld-Greeting.gif) -[Metamask and Flow blockchain]: ../../../build/evm/using.mdx \ No newline at end of file +[viem networks]: https://github.com/wevm/viem/tree/main/src/chains/definitions +[Wagmi getting-started manual tutorial]: https://wagmi.sh/react/getting-started +[Metamask and Flow blockchain]: ../../../build/evm/using.mdx +[Checkout Wagmi documentation]: https://wagmi.sh/react/getting-started +[Using Remix]: ../development-tools/remix.md \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/evm/frameworks/web3-js.md b/docs/blockchain-development-tutorials/evm/frameworks/web3-js.md index 6260d6b7b0..4bdbe959c6 100644 --- a/docs/blockchain-development-tutorials/evm/frameworks/web3-js.md +++ b/docs/blockchain-development-tutorials/evm/frameworks/web3-js.md @@ -6,14 +6,14 @@ sidebar_position: 2 # Web3.js -[Web3.js](https://web3js.org/) is a Javascript library for building on EVM-compatible networks. +[Web3.js] is a Javascript library for building on EVM-compatible networks. It allows developers to interact with smart contracts, send transactions, and retrieve data from the network. ## Prerequisites :::info -This guide assumes you have the latest version of [Node.js](https://nodejs.org/en) installed. +This guide assumes you have the latest version of [Node.js] installed. ::: To install `web3` in your project, run the following command: @@ -57,7 +57,7 @@ const gasPrice = await web3.eth.getGasPrice(); console.log(gasPrice); // Gas price in attoFlow ``` -For more information about other queries you can make `web3`, see the [official documentation](https://docs.web3js.org/). +For more information about other queries you can make `web3`, see the [Web3.js] official documentation. ## Interact with smart contracts @@ -65,7 +65,7 @@ The `web3` library allows developers to interact with smart contracts via the `w For this example we will use the following `Storage` contract. -We recommend that you deploy your own contract, which you can do with [Hardhat](../development-tools/hardhat.md) or [Remix](../development-tools/remix.md). +We recommend that you deploy your own contract, which you can do with [Hardhat] or [Remix]. ```solidity // SPDX-License-Identifier: MIT @@ -84,7 +84,7 @@ contract Storage { } ``` -You can generate the ABI for this contract with the [`solc` compiler](https://docs.soliditylang.org/en/latest/installing-solidity.html), or another tool such as [Hardhat](../development-tools/hardhat.md) or [Remix](../development-tools/remix.md). +You can generate the ABI for this contract with the [`solc` compiler], or another tool such as [Hardhat]or [Remix]. Now that we have both the ABI and address of the contract, we can create a new `Contract` object for use in our application. @@ -133,7 +133,7 @@ const contract = new web3.eth.Contract(abi, contractAddress); We can now interact with the contract on the network ith the `contract` object. -### Reading state +### Read state State can be read from the contract via the `call` function with one of the contract's methods. This will not change the state and will not send a transaction. @@ -161,7 +161,7 @@ node -e "console.log(require('web3').eth.accounts.create())" This is not a secure way to generate an account, and you should use a more secure method in a production environment. -You can fund your account with the [Flow Faucet](https://faucet.flow.com/fund-account). +You can fund your account with the [Flow Faucet]. ::: We can use the `privateKeyToAccount` function to create an `Web3Account` object from our account's private key. @@ -194,11 +194,21 @@ const result = await web3.eth.sendSignedTransaction(signed.rawTransaction); console.log(result); ``` -Now that the transaction has been sent, the contract's state will have been updated. To verify this, we can query the contract's state again: +Now that the transaction was sent, the contract's state was updated. To verify this, we can query the contract's state again: ```js const result = await contract.methods.retrieve().call(); console.log(result); // New value stored in the contract ``` -For more information about using smart contracts in web3.js, see the [official documentation](https://docs.web3js.org/libdocs/Contract). +For more information about how to use smart contracts in web3.js, see the [official documentation]. + + + +[Web3.js]: https://web3js.org/ +[Node.js]: https://nodejs.org/en +[Flow Faucet]: https://faucet.flow.com/fund-account +[`solc` compiler]: https://docs.soliditylang.org/en/latest/installing-solidity.html +[Hardhat]: ../development-tools/hardhat.md) +[Remix]: ../development-tools/remix.md). +[official documentation]: https://docs.web3js.org/libdocs/Contract \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/evm/image-gallery.md b/docs/blockchain-development-tutorials/evm/image-gallery.md index ad0985d1a8..7901c889af 100644 --- a/docs/blockchain-development-tutorials/evm/image-gallery.md +++ b/docs/blockchain-development-tutorials/evm/image-gallery.md @@ -26,7 +26,7 @@ keywords: :::info -The [FlowtoBooth] tutorial series teaches you how to build a **fun benchmark app** and provides inspiration for the greater scope of possibilities building on Flow thanks to gas being so much less expensive. +The [FlowtoBooth] tutorial series teaches you how to build a **fun benchmark app** and provides inspiration for the greater scope of possibilities to build on Flow since gas is so much less expensive. It is **not a production best-practice**. While everything in these tutorials works, you'll run into the following problems at production scale: @@ -38,13 +38,13 @@ It is **not a production best-practice**. While everything in these tutorials wo If you search for resources on how to store images of any significant size onchain, you'll be told it's either prohibitively expensive or even completely impossible. The reason for this is two-fold. First, the size limit for data on transactions is about 40kb. Second, to save 40kb takes almost all of the 30 million gas limit on most blockchains. -The former constraint is immutable (though many chains are slowly increasing this limit), which limits the app to images about 256\*256 pixels in size. The latter heavily depends on which chain you choose. +The former constraint is immutable (though many chains have started to slowly increase this limit), which limits the app to images about 256\*256 pixels in size. The latter heavily depends on which chain you choose. -At current gas prices on most chains, to use all 30 million gas in a block costs **several dollars** - or potentially **thousands** on ETH mainnet. At current prices on Flow, spending 30 million gas costs **less than a penny**, usually one or two tenths of a cent. +At current gas prices on most chains, to use all 30 million gas in a block costs **several dollars** - or potentially **thousands** on ETH mainnet. At current prices on Flow, to spend 30 million gas costs **less than a penny**, usually one or two tenths of a cent. Much more computation is available at prices you or your users will want to pay for regular interactions. This includes, but isn't limited to: -- Airdropping hundreds of NFTs with one transaction, for pennies. +- Airdrop hundreds of NFTs with one transaction, for pennies. - Generation of large mazes. - Generation of large amounts of random numbers (with free [native VRF]). - Extensive string manipulation onchain. @@ -247,7 +247,7 @@ contract ImageGalleryFactory { Some app designs may need multiple galleries for each user. For example, you might want to give users the ability to collect images in separate galleries for separate topics, dates, or events, similar to how many photo apps work on smartphones. -To facilitate this feature, update your contract to keep track of which galleries have been created by which users. You'll end up with: +To facilitate this feature, update your contract to keep track of which users created which galleries . You'll end up with: ```solidity // SPDX-License-Identifier: UNLICENSED @@ -355,7 +355,7 @@ Next, install [rainbowkit], [wagmi], and their related dependencies: npm install @rainbow-me/rainbowkit wagmi viem@2.x @tanstack/react-query ``` -### Provider Setup +### Provider setup Add a file called `providers` inside the `app` folder. In it, add your config and providers for [wagmi] and [rainbowkit]. You'll need to [add the Flow Wallet] as a custom wallet. It's not included by default because it has special features that aren't compatible with other blockchains. @@ -939,7 +939,7 @@ The last thing to do for this initial implementation is to add functionality so For now, we'll just generate an error if the file is too big, but later on we can do that for the user as well. -Add the `ImageUploader` component. This needs to handle uploading the image and displaying any errors. We'll keep the state for the image itself in `Content` so that it's accessible to other components: +Add the `ImageUploader` component. This needs to be able to upload the image and display any errors. We'll keep the state for the image itself in `Content` so that it's accessible to other components: ```tsx import React, { useState } from 'react'; diff --git a/docs/blockchain-development-tutorials/evm/setup/index.md b/docs/blockchain-development-tutorials/evm/setup/index.md index 7b3df2be95..b10cb394f7 100644 --- a/docs/blockchain-development-tutorials/evm/setup/index.md +++ b/docs/blockchain-development-tutorials/evm/setup/index.md @@ -16,7 +16,7 @@ keywords: Before you dive into Flow EVM development, you'll need to configure your development environment and connect the necessary tools. This section covers the essential setup steps required to build on Flow EVM, from wallet configuration to network integration. These foundational setup guides ensure you have the proper connections and configurations needed for seamless Flow EVM development. -Whether you're setting up MetaMask for the first time or integrating Flow network support into your current app, these tutorials provide step-by-step instructions to establish a robust development environment on Flow's EVM-compatible blockchain. +Whether you want to set up MetaMask for the first time or integrate Flow network support into your current app, these tutorials provide step-by-step instructions to establish a robust development environment on Flow's EVM-compatible blockchain. ## [Integrating MetaMask] diff --git a/docs/blockchain-development-tutorials/gasless-transactions/index.md b/docs/blockchain-development-tutorials/gasless-transactions/index.md index b58a5a0223..ac7c730498 100644 --- a/docs/blockchain-development-tutorials/gasless-transactions/index.md +++ b/docs/blockchain-development-tutorials/gasless-transactions/index.md @@ -14,18 +14,18 @@ keywords: # Gasless Transactions on Flow -Flow is one of the easiest platforms for developers to onboard new users. Currently, the Flow Wallet automatically sponsors transactions on **both testnet and mainnet**. This allows developers to build seamless Web3 applications without requiring users to manage gas tokens or pay transaction fees. +Flow is one of the easiest platforms for developers to onboard new users. Currently, the Flow Wallet automatically sponsors transactions on **both testnet and mainnet**. This allows developers to build seamless Web3 applications without the need for users to manage gas tokens or pay transaction fees. In addition to native sponsorship, Flow also supports multiple methods for gas sponsorship that you can tailor to your application’s needs. You can learn about these approaches in more detail [here]. The [Flow Wallet] currently sponsors all transactions - on testnet and mainnet! This is possible because [sponsored transactions] are a native feature of the Flow Protocol. Additional methods for gas sponsorship are available and are described here. -## What You'll Learn +## What you'll learn In this tutorial series, you’ll discover how to: - Configure and deploy a **gas free EVM endpoint** for your backend. -- Allow **gasless transactions** so that users can interact with your app without ever paying gas fees. +- Allow **gasless transactions** so that users can interact with your app and never gas fees. - Use Flow’s EVM Gateway service account to automatically cover gas fees for transactions, which ensures a smooth experience for your users. diff --git a/docs/blockchain-development-tutorials/integrations/crossmint/index.md b/docs/blockchain-development-tutorials/integrations/crossmint/index.md index e928c99e73..711d2cf542 100644 --- a/docs/blockchain-development-tutorials/integrations/crossmint/index.md +++ b/docs/blockchain-development-tutorials/integrations/crossmint/index.md @@ -96,17 +96,22 @@ Make sure you have: Get started with Crossmint on Flow in under 15 minutes: -1. **[Set up authentication](./authentication.md)** to seamlessly onboard users. -3. **[Enable fiat payments](./payment-checkout.md)** for your Flow assets. -4. **[Minting Platform](./minting-platform.md)** to create and distribute tokens at scale. +1. **[Set up authentication]** to seamlessly onboard users. +2. **[Enable fiat payments]** for your Flow assets. +3. **[Minting Platform]** to create and distribute tokens at scale. If you have trouble during the integrations process, refer to these documentation sites: -- **[Crossmint Documentation](https://docs.crossmint.com/)** - Complete platform docs. -- **[Flow Developer Portal](https://developers.flow.com/)** - Flow-specific resources. +- **[Crossmint Documentation]** - Complete platform docs. +- **[Flow Developer Portal]** - Flow-specific resources. [Crossmint Console]: https://staging.crossmint.com -[Contact Sales]: https://crossmint.com/contact \ No newline at end of file +[Contact Sales]: https://crossmint.com/contact +[Set up authentication]: ./authentication.md +[Enable fiat payments]:./payment-checkout.md +[Minting Platform]:./minting-platform.md +[Crossmint Documentation]: https://docs.crossmint.com/ +[Flow Developer Portal]: https://developers.flow.com/ \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/integrations/crossmint/minting-platform.md b/docs/blockchain-development-tutorials/integrations/crossmint/minting-platform.md index 666f20beb2..502453962b 100644 --- a/docs/blockchain-development-tutorials/integrations/crossmint/minting-platform.md +++ b/docs/blockchain-development-tutorials/integrations/crossmint/minting-platform.md @@ -33,7 +33,7 @@ Crossmint's minting platform provides no-code tools and powerful APIs to create, - Crossmint account with minting activated. - Flow development environment. -- Basic understanding of NFT standards. +- Basic knowledge of NFT standards. ## Step 1: Deploy smart contract diff --git a/docs/blockchain-development-tutorials/integrations/crossmint/payment-checkout.md b/docs/blockchain-development-tutorials/integrations/crossmint/payment-checkout.md index 72a6dc123b..a600a37907 100644 --- a/docs/blockchain-development-tutorials/integrations/crossmint/payment-checkout.md +++ b/docs/blockchain-development-tutorials/integrations/crossmint/payment-checkout.md @@ -17,7 +17,7 @@ keywords: # Payment checkout integration guide -Enable seamless fiat and cryptocurrency payments for your Flow assets. Crossmint's checkout solution supports credit cards, Apple Pay, Google Pay, and cross-chain crypto payments, allowing users to buy Flow NFTs and tokens without holding FLOW tokens. +Enable seamless fiat and cryptocurrency payments for your Flow assets. Crossmint's checkout solution supports credit cards, Apple Pay, Google Pay, and cross-chain crypto payments, which allows users to buy Flow NFTs and tokens without FLOW tokens. ## Overview @@ -50,7 +50,7 @@ You'll integrate checkout functionality that activates: **Option A: create new collection** -1. Go to [Crossmint Console](https://staging.crossmint.com) > **Collections**. +1. Go to [Crossmint Console] > **Collections**. 2. Click **Create Collection**. 3. Choose **Flow** blockchain. 4. Configure collection settings: @@ -186,7 +186,6 @@ export function AdvancedHostedCheckout({ Embed checkout directly in your application with full UI control. - ### Basic embedded checkout ```jsx @@ -316,7 +315,7 @@ export function CustomEmbeddedCheckout({ --- -## Step 4: Headless Checkout Integration +## Step 4: Headless checkout integration For maximum customization, use the headless API to build completely custom checkout flows. @@ -795,3 +794,7 @@ export function UniversalCheckout({ - **Universal Payment Support**: credit cards, mobile payments, and over 40 cryptocurrencies. - **Flow Native**: optimized for both Flow EVM and Cadence ecosystems. - **Global Scale**: support for 197 countries with no buyer KYC. + + + +[Crossmint Console]: https://staging.crossmint.com diff --git a/docs/blockchain-development-tutorials/integrations/crossmint/smart-wallets.md b/docs/blockchain-development-tutorials/integrations/crossmint/smart-wallets.md index a2ae56c49f..3899776b6d 100644 --- a/docs/blockchain-development-tutorials/integrations/crossmint/smart-wallets.md +++ b/docs/blockchain-development-tutorials/integrations/crossmint/smart-wallets.md @@ -23,49 +23,49 @@ import TabItem from '@theme/TabItem'; Traditional blockchain wallets create significant friction for mainstream users. Managing seed phrases, understanding gas fees, and connecting multiple wallets are barriers that prevent widespread Web3 adoption. Crossmint Smart Wallets solves these problems by providing **enterprise-grade wallet infrastructure** that enables Web2-like user experiences without compromising on security or decentralization. With Crossmint Smart Wallets, you can: -- **Eliminate wallet complexity** with email and social login authentication -- **Remove onboarding friction** by automatically creating wallets for users -- **Support multiple authentication methods** including email, Google, passkeys, and external wallets -- **Enable gasless transactions** to improve user experience -- **Build on Flow** with full support for both mainnet and testnet environments -- **Scale with confidence** using infrastructure trusted by Fortune 500 companies +- **Eliminate wallet complexity** with email and social login authentication. +- **Remove onboarding friction** with automatic user wallet creation. +- **Support multiple authentication methods** such as email, Google, passkeys, and external wallets. +- **Enable gasless transactions** to improve user experience. +- **Build on Flow** with full support for both mainnet and testnet environments. +- **Scale with confidence** using infrastructure trusted by Fortune 500 companies. -This tutorial will guide you through integrating Crossmint Smart Wallets into your Flow application. You'll learn how to set up authentication, automatically create wallets, check balances, transfer tokens, and display transaction historyall with a familiar Web2-style developer experience. +This tutorial will guide you through how to integrate Crossmint Smart Wallets into your Flow application. You'll learn how to set up authentication, automatically create wallets, check balances, transfer tokens, and display transaction historyall with a familiar Web2-style developer experience. :::info -Crossmint provides flexible wallet solutions across 50+ blockchains including Flow. This tutorial focuses on the **React implementation** for web applications, but Crossmint also supports Node.js, React Native, Swift (iOS), and Kotlin (Android) platforms. +Crossmint provides flexible wallet solutions across more than 50 blockchains, such as Flow. This tutorial focuses on the **React implementation** for web applications, but Crossmint also supports Node.js, React Native, Swift (iOS), and Kotlin (Android) platforms. ::: ## Objectives -After completing this guide, you'll be able to: +After you complete this guide, you'll be able to: -- Configure a Crossmint account with proper API keys and permissions -- Implement email and social authentication for automatic wallet creation -- Display wallet information including address, balance, and ownership details -- Execute token transfers on Flow using Crossmint's SDK -- Build an activity feed showing transaction history -- Handle authentication states and error scenarios properly -- Deploy your Crossmint-powered application to production +- Configure a Crossmint account with proper API keys and permissions. +- Implement email and social authentication for automatic wallet creation. +- Display wallet information including address, balance, and ownership details. +- Execute token transfers on Flow using Crossmint's SDK. +- Build an activity feed showing transaction history. +- Handle authentication states and error scenarios properly. +- Deploy your Crossmint-powered application to production. ## Prerequisites -Before starting this tutorial, you should have: +Before you start this tutorial, you should have: -- **Development Environment**: Node.js and npm/yarn/pnpm installed -- **React Knowledge**: Familiarity with React hooks and component patterns -- **Next.js or Create-React-App**: A React application ready for integration -- **Basic Blockchain Concepts**: Understanding of wallet addresses and token transfers (helpful but not required) +- **Development Environment**: Node.js and npm/yarn/pnpm installed. +- **React Knowledge**: Familiarity with React hooks and component patterns. +- **Next.js or Create-React-App**: A React application ready for integration. +- **Basic Blockchain Concepts**: Knowledge of wallet addresses and token transfers (helpful but not required). -## Setting Up Your Crossmint Account +## Set up your crossmint account -You need to create a Crossmint account and configure API access before implementing wallet functionality. +You need to create a Crossmint account and configure API access before you implement wallet functionality. -### Step 1. Create Your Crossmint Account +### Step 1. Create your Crossmint account -Sign up on the [Crossmint Console](https://www.crossmint.com/console) to establish an account. For development and testing, use the [Staging Console](https://staging.crossmint.com/console) instead. +Sign up on the [Crossmint Console] to establish an account. For development and testing, use the [Staging Console] instead. :::tip @@ -73,23 +73,23 @@ Always use the staging environment during development. Staging supports testnet ::: -### Step 2. Create a New Project +### Step 2. Create a new project -After logging into the console: +After you log in to the console: -1. Click **Create New Project** -2. Enter a project name (e.g., "Flow DApp") -3. Select your project type (Web Application recommended) -4. Save your project settings +1. Click **Create New Project**. +2. Enter a project name (such as "Flow DApp"). +3. Select your project type (Web Application recommended). +4. Save your project settings. -### Step 3. Generate API Keys +### Step 3. Generate API keys Navigate to your project dashboard to create a client-side API key: 1. Go to the **API Keys** section 2. Click **Create New API Key** 3. Select **Client API Key** (not server key) -4. Enable the following scopes: +4. Activate the following scopes: - `users.create` - Create new users - `users.read` - Read user information - `wallets.read` - Read wallet data @@ -97,7 +97,7 @@ Navigate to your project dashboard to create a client-side API key: - `wallets:transactions.create` - Create transactions - `wallets:transactions.sign` - Sign transactions - `wallets:balance.read` - Read balance information - - `wallets.fund` - Fund wallets (staging/development only) + - `wallets.fund` - Fund wallets (staging and development only) 5. Copy the generated API key to your clipboard @@ -107,7 +107,7 @@ Keep your API keys secure! Never commit them to version control. Use environment ::: -### Step 4. Configure Environment Variables +### Step 4. Configure environment variables Create a `.env` or `.env.local` file in your project root: @@ -123,11 +123,11 @@ NEXT_PUBLIC_CROSSMINT_API_KEY=your_production_api_key NEXT_PUBLIC_CHAIN=flow ``` -## Implementing Crossmint Smart Wallets +## Implement Crossmint Smart Wallets With your Crossmint account configured, you can now integrate wallet functionality into your React application. -### Step 1. Install Dependencies +### Step 1. Install dependencies Install the Crossmint React SDK: @@ -154,7 +154,7 @@ Install the Crossmint React SDK: -### Step 2. Configure Crossmint Providers +### Step 2. Configure Crossmint providers Crossmint requires three providers to be set up in a specific hierarchy. These providers handle API configuration, authentication, and wallet management. @@ -274,16 +274,16 @@ Crossmint requires three providers to be set up in a specific hierarchy. These p -**Provider Configuration Options:** +**Provider configuration cptions:** -- **CrossmintProvider**: Top-level provider requiring only your API key +- **CrossmintProvider**: Top-level provider that requires only your API key. - **CrossmintAuthProvider**: Manages authentication with configurable options: - - `authModalTitle`: Title displayed in the authentication modal - - `loginMethods`: Array of enabled authentication methods (`"email"`, `"google"`, `"apple"`, `"twitter"`, `"farcaster"`) - - `appearance`: Customize UI colors and styling + - `authModalTitle`: Title displayed in the authentication modal. + - `loginMethods`: Array of active authentication methods (`"email"`, `"google"`, `"apple"`, `"twitter"`, `"farcaster"`). + - `appearance`: Customize UI colors and style. - **CrossmintWalletProvider**: Handles wallet creation and management: - - `createOnLogin.chain`: Target blockchain (e.g., `"flow"`, `"flow-testnet"`) - - `createOnLogin.signer.type`: Authentication method for wallet signing (`"email"`, `"passkey"`) + - `createOnLogin.chain`: Target blockchain (such as `"flow"`, `"flow-testnet"`) + - `createOnLogin.signer.type`: Authentication method for wallet signing (`"email"`, `"passkey"`). :::info @@ -291,9 +291,9 @@ The `createOnLogin` configuration enables **automatic wallet creation**. When a ::: -### Step 3. Implement Authentication +### Step 3. Implement authentication -Create login and logout components using Crossmint's `useAuth` hook. +Create login and logout components with Crossmint's `useAuth` hook. **LoginButton.tsx:** @@ -363,9 +363,9 @@ export function Header() { } ``` -### Step 4. Display Wallet Information +### Step 4. Display wallet information -Create a component to show wallet details using the `useWallet` hook. +Create a component to show wallet details with the `useWallet` hook. **WalletInfo.tsx:** @@ -437,9 +437,9 @@ export function WalletInfo() { } ``` -### Step 5. Display Wallet Balance +### Step 5. Display wallet balance -Fetch and display the wallet's token balance using the `wallet.balances()` method. +Fetch and display the wallet's token balance with the `wallet.balances()` method. **WalletBalance.tsx:** @@ -515,9 +515,9 @@ export function WalletBalance() { } ``` -### Step 6. Implement Token Transfers +### Step 6. Implement token transfers -Create a component for transferring tokens using the `wallet.send()` method. +Create a component to transfer tokens with the `wallet.send()` method. **TransferTokens.tsx:** @@ -643,13 +643,13 @@ export function TransferTokens() { :::tip -The `wallet.send()` method throws an `AuthRejectedError` when users cancel the transaction. Handle this separately to avoid showing unnecessary error messages. +The `wallet.send()` method throws an `AuthRejectedError` when users cancel the transaction. Handle this separately to avoid a display of unnecessary error messages. ::: -### Step 7. Build Activity Feed +### Step 7. Build activity feed -Display transaction history using the `wallet.experimental_activity()` method with polling for real-time updates. +Display transaction history with the `wallet.experimental_activity()` method with polling for real-time updates. **ActivityFeed.tsx:** @@ -779,7 +779,7 @@ The `experimental_activity()` method is experimental and may change in future SD ::: -### Step 8. Create Main Dashboard +### Step 8. Create main dashboard Combine all components into a cohesive dashboard with proper state management. @@ -868,25 +868,25 @@ While this tutorial focuses on React for web applications, Crossmint provides SD ### Node.js (Backend) For server-side wallet creation and management, use the Node.js SDK: -- [Node.js Quickstart Documentation](https://docs.crossmint.com/wallets/quickstarts/nodejs) +- [Node.js Quickstart Documentation] ### React Native (Mobile) For iOS and Android mobile applications: -- [React Native Quickstart Documentation](https://docs.crossmint.com/wallets/quickstarts/react-native) +- [React Native Quickstart Documentation] ### Swift (iOS Native) For native iOS development: -- Contact [Crossmint Sales](https://www.crossmint.com/contact/sales) for access +- Contact [Crossmint Sales] for access ### Kotlin (Android Native) For native Android development: -- Contact [Crossmint Sales](https://www.crossmint.com/contact/sales) for access +- Contact [Crossmint Sales] for access --- ## Conclusion -In this tutorial, you successfully integrated Crossmint Smart Wallets to enable seamless blockchain experiences on Flow. You learned how to implement email-based authentication, automatically create wallets for users, display balances, execute token transfers, and show transaction historyall without requiring users to understand complex blockchain concepts like seed phrases or gas fees. +In this tutorial, you successfully integrated Crossmint Smart Wallets to enable seamless blockchain experiences on Flow. You learned how to implement email-based authentication, automatically create wallets for users, display balances, execute token transfers, and show transaction history, all without a requirement that users understand complex blockchain concepts like seed phrases or gas fees. Now that you have completed the tutorial, you should be able to: @@ -901,14 +901,23 @@ Crossmint's wallet infrastructure, combined with Flow's high-performance blockch ## Next Steps -- Explore [Crossmint's NFT Minting Platform](https://docs.crossmint.com/nft-minting/overview) to add NFT functionality -- Learn about [Payment Checkout](https://docs.crossmint.com/payments/overview) for credit card and crypto payments -- Implement [Passkey Authentication](https://docs.crossmint.com/wallets/signers/passkey) for enhanced security -- Review [Flow Smart Contract Development](../../cadence/) to build custom on-chain logic -- Join the [Flow Discord](https://discord.gg/flow) to connect with other developers +- Explore [Crossmint's NFT Minting Platform]to add NFT functionality +- Learn about [Payment Checkout] for credit card and crypto payments +- Implement [Passkey Authentication] for enhanced security +- Review [Flow Smart Contract Development] to build custom on-chain logic +- Join the [Flow Discord] to connect with other developers + + [Crossmint Console]: https://www.crossmint.com/console [Staging Console]: https://staging.crossmint.com/console [Crossmint Documentation]: https://docs.crossmint.com/ [Crossmint Wallets SDK]: https://github.com/Crossmint/crossmint-sdk +[Crossmint Sales]: https://www.crossmint.com/contact/sales [Flow Discord]: https://discord.gg/flow +[Crossmint's NFT Minting Platform]: https://docs.crossmint.com/nft-minting/overview +[Payment Checkout]: https://docs.crossmint.com/payments/overview +[Passkey Authentication]: https://docs.crossmint.com/wallets/signers/passkey +[Flow Smart Contract Development]: ../../cadence/ +[Node.js Quickstart Documentation]: https://docs.crossmint.com/wallets/quickstarts/nodejs +[React Native Quickstart Documentation]: https://docs.crossmint.com/wallets/quickstarts/react-native \ No newline at end of file diff --git a/docs/blockchain-development-tutorials/integrations/gelato-sw.md b/docs/blockchain-development-tutorials/integrations/gelato-sw.md index 40aa47298c..68136f4f21 100644 --- a/docs/blockchain-development-tutorials/integrations/gelato-sw.md +++ b/docs/blockchain-development-tutorials/integrations/gelato-sw.md @@ -35,7 +35,7 @@ This tutorial will guide you through how to set up Gelato Smart Wallet to activa :::info -This tutorial focuses on **EIP-7702** implementation with Gelato Smart Wallet on Flow EVM. EIP-7702 provides a streamlined experience for users. It maintains the same address as their EOA and adds smart wallet capabilities, which activates enhanced features like gasless transactions and improved user experience. +This tutorial focuses on **EIP-7702** implementation with Gelato Smart Wallet on Flow EVM. EIP-7702 provides a streamlined experience for users. It maintains the same address as their EOA and adds Smart Wallet capabilities, which activates enhanced features like gasless transactions and improved user experience. ::: @@ -53,11 +53,11 @@ After you complete this guide, you'll be able to: You need to set up the following in the Gelato App to create a Gelato Sponsor API Key: -### Step 1. create your Gelato account +### Step 1. Create your Gelato account Sign up on the [Gelato App] to establish an account. This account is the foundation to set up relay tasks and manage gas sponsorships. -### Step 2. deposit funds into 1Balance +### Step 2. Deposit funds into 1Balance To use Gelato for sponsored transactions, you need to deposit funds into 1Balance as your target environment requires: @@ -79,7 +79,7 @@ If you need to fund your account, you can use one of the following third-party f - [Chainlink Sepolia Faucet] - [Metamask Sepolia Faucet] -### Step 3. create a relay app +### Step 3. Create a relay app Select the `Relay` tab in the Gelato App and switch to the `Testnet` environment. @@ -144,7 +144,7 @@ You can find the examples in the [Gelato Smart Wallet SDK] repository. -### Step 2. set up a Smart Wallet account +### Step 2. Set up a Smart Wallet account Import required dependencies: @@ -162,8 +162,7 @@ const publicClient = createPublicClient({ }); ``` -You can set up a Smart Account as per your needs. -After you create the `gelato` account, the Gelato Smart Account address will be the same as your EOA, which activates EIP-7702 features. +You can set up a Smart Account as per your needs. After you create the `gelato` account, the Gelato Smart Account address will be the same as your EOA, which activates EIP-7702 features. ```ts // Prepare a normal EOA account @@ -200,7 +199,7 @@ const swc = await createGelatoSmartWalletClient(client, { }); ``` -### Step 3. estimate or send a gasless transaction +### Step 3. Estimate or send a gasless transaction Now you can estimate or send a gasless transaction with the Gelato Smart Wallet client. @@ -289,6 +288,8 @@ Now that you have completed the tutorial, you should be able to: The combination of Flow's efficient gas prices and Gelato's sponsored transaction infrastructure opens up new possibilities for you to build user-friendly dApps. When you eliminate the need for users to hold native tokens for gas fees, you can create onboarding experiences that rival traditional Web2 applications and maintain the security and transparency of blockchain technology. + + [Gelato App]: https://app.gelato.cloud/ [Google Cloud Sepolia Faucet]: https://cloud.google.com/application/web3/faucet/ethereum/sepolia [Alchemy Sepolia Faucet]: https://www.alchemy.com/faucets/ethereum-sepolia