diff --git a/docs/blockchain-development-tutorials/cadence/getting-started/building-a-frontend-app.md b/docs/blockchain-development-tutorials/cadence/getting-started/building-a-frontend-app.md index 8b9e3cf6a4..aad7358b6b 100644 --- a/docs/blockchain-development-tutorials/cadence/getting-started/building-a-frontend-app.md +++ b/docs/blockchain-development-tutorials/cadence/getting-started/building-a-frontend-app.md @@ -22,13 +22,13 @@ keywords: # Building a Frontend App -Building on the `Counter` contract you deployed in [Cadence Environment Setup] and [Smart Contract Interaction], this tutorial shows you how to create a simple Next.js frontend that interacts with the `Counter` smart contract deployed on your local Flow emulator. Instead of using FCL directly, you'll leverage [**@onflow/react-sdk**] to simplify authentication, querying, transactions, and to display real-time transaction status updates using convenient React hooks. +This tutorial builds on the `Counter` contract you deployed in [Cadence Environment Setup] and [Smart Contract Interaction]. It shows you how to create a simple `Next.js` frontend that interacts with the `Counter` smart contract deployed on your local Flow emulator. Instead of using FCL directly, you'll leverage [**@onflow/react-sdk**] to simplify authentication, querying, transactions, and to display real-time transaction status updates using convenient React hooks. ## Objectives -After finishing this guide, you will be able to: +After you complete this tutorial, you will be able to: -- Wrap your Next.js app with a Flow provider using [**@onflow/react-sdk**]. +- Wrap your `Next.js` app with a Flow provider using [**@onflow/react-sdk**]. - Read data from a Cadence smart contract (`Counter`) using kit's query hook. - Send a transaction to update the smart contract's state using kit's mutation hook. - Monitor a transaction's status in real time using kit's transaction hook. @@ -40,7 +40,7 @@ After finishing this guide, you will be able to: - [Flow CLI] installed. - Node.js and npm installed. -## Setting Up the Next.js App +## Set Up the Next.js app Follow these steps to set up your Next.js project and integrate [**@onflow/react-sdk**]. @@ -50,7 +50,7 @@ You can visit this [React-sdk Demo] to see how the hooks and components are used ::: -### Step 1: Create a New Next.js App +### Step 1: Create a new Next.js app Run the following command in your project directory: @@ -66,7 +66,7 @@ During setup, choose the following options: This command creates a new Next.js project named `kit-app-quickstart` inside your current directory. We're generating the frontend in a subdirectory so we can next move it into our existing project structure from the previous steps (you can't create an app in a non-empty directory). -### Step 2: Move the Next.js App Up a Directory +### Step 2: Move the Next.js app Up a directory Move the contents of the `kit-app-quickstart` directory into your project root. You can use the gui in your editor, or the console. @@ -92,7 +92,11 @@ Move-Item -Path .\kit-app-quickstart\.* -Destination . -Force Remove-Item -Recurse -Force .\kit-app-quickstart ``` -**Note:** When moving hidden files (those beginning with a dot) like `.gitignore`, be cautious not to overwrite any important files. +:::tip + +When moving hidden files (those beginning with a dot) like `.gitignore`, be cautious not to overwrite any important files. + +::: ### Step 3: Install @onflow/react-sdk @@ -104,11 +108,11 @@ npm install @onflow/react-sdk This library wraps FCL internally and exposes a set of hooks for authentication, querying, sending transactions, and tracking transaction status. -## Configuring the Local Flow Emulator and Dev Wallet +## Configure the local Flow Emulator and Dev Wallet :::warning -You should already have the Flow emulator running from the local development step. If it's not running, you can start it again — but note that restarting the emulator will clear all blockchain state, including any contracts deployed in [Step 2: Local Development]. +You should already have the Flow emulator running from the local development step. If it's not running, you can start it again — but when you restart the emulator, it will clear all blockchain state, which includes any contracts deployed in [Step 2: Local Development]. ::: @@ -132,9 +136,9 @@ flow dev-wallet This will start the [Dev Wallet] on `http://localhost:8701`, which you'll use for authentication during development. -## Wrapping Your App with FlowProvider +## Wrap Your app with FlowProvider -[**@onflow/react-sdk**] provides a `FlowProvider` component that sets up the Flow Client Library configuration. In Next.js using the App Router, add or update your `src/app/layout.tsx` as follows: +[**@onflow/react-sdk**] provides a `FlowProvider` component that sets up the Flow Client Library configuration. In `Next.js` using the App Router, add or update your `src/app/layout.tsx` as follows: ```tsx 'use client'; @@ -170,11 +174,11 @@ This configuration initializes the kit with your local emulator settings and map For more information on Discovery configurations, refer to the [Wallet Discovery Guide]. -## Interacting With the Chain +## Interact With the chain Now that we've set our provider, lets start interacting with the chain. -### Querying the Chain +### Query the chain First, use the kit's [`useFlowQuery`] hook to read the current counter value from the blockchain. @@ -208,7 +212,7 @@ This script fetches the counter value, formats it via the `NumberFormatter`, and ::: -### Sending a Transaction +### Send a transaction Next, use the kit's [`useFlowMutate`] hook to send a transaction that increments the counter. @@ -244,9 +248,9 @@ const handleIncrement = () => { #### Explanation -This sends a Cadence transaction to the blockchain using the `mutate` function. The transaction imports the `Counter` contract and calls its `increment` function. Authorization is handled automatically by the connected wallet during the `prepare` phase. Once submitted, the returned `txId` can be used to track the transaction's status in real time. +This sends a Cadence transaction to the blockchain using the `mutate` function. The transaction imports the `Counter` contract and calls its `increment` function. The connected wallet handles authorization automatically during the `prepare` phase. After it's submitted, you cna use the returned `txId` to track the transaction's status in real time. -### Subscribing to Transaction Status +### Subscribe to transaction status Use the kit's [`useFlowTransactionStatus`] hook to monitor and display the transaction status in real time. @@ -275,19 +279,19 @@ useEffect(() => { - `2`: **Finalized** – The transaction has been included in a block, but not yet executed. - `3`: **Executed** – The transaction code has run successfully, but the result has not yet been sealed. - `4`: **Sealed** – The transaction is fully complete, included in a block, and now immutable onchain. -- We recommend calling `refetch()` when the status reaches **3 (Executed)** to update your UI more quickly after the transaction runs, rather than waiting for sealing. +- We recommend that you call `refetch()` when the status reaches **3 (Executed)** to update your UI more quickly after the transaction runs, rather than waiting for sealing. - The `statusString` property gives a human-readable version of the current status you can display in the UI. -#### Why `Executed` is Recommended for UI Updates: +#### Why we recommend `Executed` for UI Updates: Waiting for `Sealed` provides full onchain confirmation but can introduce a delay — especially in local or test environments. Since most transactions (like incrementing a counter) don't require strong finality guarantees, you can typically refetch data once the transaction reaches `Executed` for a faster, more responsive user experience. However: -- If you're dealing with critical state changes (e.g., token transfers or contract deployments), prefer waiting for `Sealed`. +- If you're dealing with critical state changes (for example, token transfers or contract deployments), prefer waiting for `Sealed`. - For non-critical UI updates, `Executed` is usually safe and significantly improves perceived performance. -### Integrating Authentication and Building the Complete UI +### Integrate authentication and build the complete UI Finally, integrate the query, mutation, and transaction status hooks with authentication using `useFlowCurrentUser`. Combine all parts to build the complete page. @@ -413,7 +417,7 @@ In this tutorial, we inlined Cadence code for simplicity. For real projects, we ::: -## Running the App +## Run the app Start your development server: @@ -442,9 +446,9 @@ Then visit [http://localhost:3000](http://localhost:3000) in your browser. You s - Once logged in, your account address appears with options to **Log Out** and **Increment Count**. - When you click **Increment Count**, the transaction is sent; its status updates are displayed in real time below the action buttons, and once the transaction is sealed, the updated count is automatically fetched. -## Wrapping Up +## Conclusion -By following these steps, you've built a simple Next.js dApp that interacts with a Flow smart contract using [**@onflow/react-sdk**]. In this guide you learned how to: +By following these steps, you've built a simple `Next.js` dApp that interacts with a Flow smart contract using [**@onflow/react-sdk**]. In this guide you learned how to: - Wrap your application in a `FlowProvider` to configure blockchain connectivity. - Use kit hooks such as `useFlowQuery`, `useFlowMutate`, `useFlowTransactionStatus`, and `useFlowCurrentUser` to manage authentication, query onchain data, submit transactions, and monitor their status. diff --git a/docs/blockchain-development-tutorials/cadence/getting-started/cadence-environment-setup.md b/docs/blockchain-development-tutorials/cadence/getting-started/cadence-environment-setup.md index ff577d513f..d5f07fe9fb 100644 --- a/docs/blockchain-development-tutorials/cadence/getting-started/cadence-environment-setup.md +++ b/docs/blockchain-development-tutorials/cadence/getting-started/cadence-environment-setup.md @@ -17,32 +17,32 @@ keywords: - VSCode extension --- -# Cadence Environment Setup +# Cadence environment eetup -This comprehensive tutorial will guide you through setting up your complete development environment, deploying your first smart contract, and mastering the fundamentals of Flow development. You'll work hands-on with the Flow CLI, local emulator, and a real smart contract to build practical skills from day one. +This comprehensive tutorial will guide you through how to set up your complete development environment, deploy your first smart contract, and learn the fundamentals of Flow development. You'll work hands-on with the Flow CLI, local emulator, and a real smart contract to build practical skills from day one. -Flow is a blockchain built for the next generation of apps, games, and digital assets. With its unique multi-role architecture and resource-oriented programming language Cadence, Flow enables developers to create secure, composable, and scalable applications. This tutorial focuses on getting you productive with Flow's developer tools as quickly as possible. +Flow is a blockchain built for the next generation of apps, games, and digital assets. With its unique multi-role architecture and resource-oriented programming language Cadence, Flow allows developers to create secure, composable, and scalable applications. This tutorial focuses on getting you productive with Flow's developer tools as quickly as possible. -## What You'll Learn +## What you'll learn -After completing this tutorial, you'll be able to: +After you complete this tutorial, you'll be able to: -- **Set up a complete Flow development environment** with CLI tools and VSCode integration -- **Create and manage Flow projects** using the Flow CLI and understand project structure -- **Deploy and interact with smart contracts** on the local Flow emulator -- **Execute scripts and transactions** to read from and modify blockchain state -- **Understand Flow's account model** and how contracts are deployed to account storage -- **Navigate the Flow ecosystem** and know where to find help and resources +- **Set up a complete Flow development environment** with CLI tools and VSCode integration. +- **Create and manage Flow projects** using the Flow CLI and understand project structure. +- **Deploy and interact with smart contracts** on the local Flow emulator. +- **Execute scripts and transactions** to read from and modify blockchain state. +- **Understand Flow's account model** and how contracts are deployed to account storage. +- **Navigate the Flow ecosystem** and know where to find help and resources. -## What You'll Build +## What you'll build -You'll work with a `Counter` contract—a simple but comprehensive example that demonstrates core Flow development patterns. This contract maintains a count value and provides functions to increment, decrement, and read the current count. By the end of this tutorial, you'll have: +You'll work with a `Counter` contract, a simple but comprehensive example that demonstrates core Flow development patterns. This contract maintains a count value and provides functions to increment, decrement, and read the current count. By the end of this tutorial, you'll have: -- A fully functional local Flow development environment -- A deployed Counter contract running on your local emulator -- Scripts to query the contract's state -- Transactions to modify the contract's state -- Understanding of how to extend this foundation for more complex applications +- A fully functional local Flow development environment. +- A deployed Counter contract running on your local emulator. +- Scripts to query the contract's state. +- Transactions to modify the contract's state. +- Understanding of how to extend this foundation for more complex applications. **Time Commitment:** Approximately 30-45 minutes @@ -50,7 +50,7 @@ You'll work with a `Counter` contract—a simple but comprehensive example that - Basic command line familiarity - Code editor (VSCode recommended) -- Node.js installed (for future frontend development) +- `Node.js` installed (for future frontend development) --- @@ -58,13 +58,13 @@ You'll work with a `Counter` contract—a simple but comprehensive example that The [Flow Command Line Interface] (CLI) is a set of tools that developers can use to interact with the Flow blockchain by managing accounts, sending transactions, deploying smart contracts, running the emulator, and more. This quickstart will get you familiar with its main concepts and functionality. -The first thing you'll need to do is install the Flow CLI. If you have [homebrew] installed you can run: +The first thing you'll need to do is install the Flow CLI. If you have [homebrew] installed, run: ```zsh brew install flow-cli ``` -**For other operating systems,** please refer to the [installation guide] for detailed instructions. +**For other operating systems,** refer to the [installation guide] for detailed instructions. **Verify Installation:** @@ -72,18 +72,18 @@ brew install flow-cli flow version ``` -You should see output showing your Flow CLI version. +You will see output showing your Flow CLI version. -### Install VSCode Extension +### Install VSCode extension Install the [Flow Cadence VSCode Extension] from the marketplace. This extension provides: -- Syntax highlighting for Cadence -- Code completion and IntelliSense -- Error checking and diagnostics -- Integrated development tools +- Syntax highlighting for Cadence. +- Code completion and IntelliSense. +- Error checking and diagnostics. +- Integrated development tools. -## Create Your First Project +## Create your first project Navigate to your desired development directory and create a new Flow project: @@ -93,13 +93,13 @@ flow init When prompted: -1. **Project name:** Enter your preferred project name +1. **Project name:** Enter your preferred project name. 2. Select `Basic Cadence project (no dependencies)`. The `flow init` command creates: -- **`flow.json`**: Central configuration file containing accounts, contracts, deployments, and network settings -- **`emulator-account.pkey`**: Private key for the default emulator account +- **`flow.json`**: Central configuration file containing accounts, contracts, deployments, and network settings. +- **`emulator-account.pkey`**: Private key for the default emulator account. - **`cadence/`**: Directory structure for your Cadence code: - `contracts/`: Smart contract files - `scripts/`: Read-only blockchain queries @@ -118,7 +118,7 @@ For additional details on how `flow.json` is configured, review the [configurati ::: -### Start the Flow Emulator +### Start the Flow emulator The emulator is a local version of the Flow blockchain that you can use to test your contracts and scripts. It's a great way to develop and test your contracts locally - before you try them on the `testnet` or `mainnet`. @@ -130,16 +130,16 @@ flow emulator start Keep this terminal running. The emulator provides: -- Local blockchain environment -- Fast transaction processing -- No real-world costs -- Complete Flow feature set +- Local blockchain environment. +- Fast transaction processing. +- No real-world costs. +- Complete Flow feature set. -## Your First Contract +## Your first contract Now let's examine, deploy, and interact with the Counter contract that was created in your project. -### Examine the Counter Contract +### Examine the Counter contract Open `cadence/contracts/Counter.cdc` in your editor. Let's break down this contract: @@ -177,20 +177,20 @@ access(all) contract Counter { } ``` -**Key Components:** +**Key components:** -- **Contract Declaration**: `access(all) contract Counter` creates a public contract named Counter -- **State Variable**: `access(all) var count: Int` stores the counter value, accessible to everyone -- **Events**: `CounterIncremented` and `CounterDecremented` notify listeners when changes occur -- **Initializer**: `init()` sets the initial count to 0 when the contract is deployed +- **Contract Declaration**: `access(all) contract Counter` creates a public contract named Counter. +- **State Variable**: `access(all) var count: Int` stores the counter value, accessible to everyone. +- **Events**: `CounterIncremented` and `CounterDecremented` notify listeners when changes occur. +- **Initializer**: `init()` sets the initial count to 0 when the contract is deployed. - **Public Functions**: - `increment()`: Increases count by 1 and emits an event - `decrement()`: Decreases count by 1 and emits an event - `getCount()`: Returns the current count (read-only, marked with `view`) -### Create and Configure Deployment Account +### Create and configure deployment account -When you created a project you'll see that a `Counter` contract was added to your [`flow.json` configuration file](../../../build/tools/flow-cli/flow.json/configuration.md), but it's not set up for deployment yet. We could deploy it to the automatically created `emulator-account`, but for this example lets also create a new account on the emulator to deploy it to. +When you create a project, you'll see that a `Counter` contract was added to your [`flow.json` configuration file](../../../build/tools/flow-cli/flow.json/configuration.md), but it's not set up for deployment yet. We could deploy it to the automatically created `emulator-account`, but for this example, lets also create a new account on the emulator to deploy it to. :::info @@ -211,7 +211,7 @@ When prompted: This adds the new account to your `flow.json` configuration file.You'll now see this account in your [`flow.json`](../../../build/tools/flow-cli/flow.json/configuration.md). -Once you have created you accounts, then you can view all your accounts on the with the Flow CLI with: +After you've created you accounts, then you can view all your accounts on the with the Flow CLI with: ```zsh 📋 Account Status Across Networks @@ -242,9 +242,9 @@ This shows which networks your configured accounts are accessible on: This is a great tool to visualize your different accounts and balances when you are developing. -### Configure Contract Deployment +### Configure contract deployment -To deploy the `Counter` contract to the emulator, you'll need to add it to your project configuration. You can do this by running: +To deploy the `Counter` contract to the emulator, you'll need to add it to your project configuration. To do this, run: ```zsh flow config add deployment @@ -259,7 +259,7 @@ Follow the prompts: This configures your `flow.json` to deploy the Counter contract to your test account on the emulator. -### Deploy the Contract +### Deploy the contract To deploy the `Counter` contract to the emulator, run: @@ -267,7 +267,7 @@ To deploy the `Counter` contract to the emulator, run: flow project deploy ``` -You should see output similar to: +You'll see output similar to: ```zsh Deploying 1 contracts for accounts: test-account @@ -279,7 +279,7 @@ Counter -> 0x179b6b1cb6755e31 (a98c155fe7afc8eb2af5551748759b08a80a0ae85d1b09f92 That's it! You've just deployed your first contract to the Flow Emulator. -### Verify Deployment with a Script +### Verify deployment with a script Scripts are used to read data from the Flow blockchain. There is no state modification. Let's verify the deployment by reading the counter value. Run the included script: @@ -293,7 +293,7 @@ You should see: Result: 0 ``` -This confirms your contract is deployed and functioning correctly. The counter starts at 0, as defined in the contract's `init()` function. +This confirms your contract is deployed and functional. The counter starts at zero (0), as defined in the contract's `init()` function. If we wanted to generate a new script, we could run: @@ -311,13 +311,13 @@ For more information about generating Cadence files, see the [Generating Cadence :::tip -If you'll like to learn more about writing scripts, please check out the docs for [basic scripts]. +To learn more about writing scripts, check out the docs for [basic scripts]. ::: -### Executing Transactions +### Execute transactions -Now let's increment the counter using a transaction: +Now let's increment the counter with a transaction: ```zsh flow transactions send cadence/transactions/IncrementCounter.cdc @@ -331,9 +331,9 @@ flow transactions send cadence/transactions/IncrementCounter.cdc --signer test-a The transaction output shows detailed information including: -- Transaction ID and block information -- Status confirmation (`✅ SEALED`) -- Events emitted (including `CounterIncremented`) +- Transaction ID and block information. +- Status confirmation (`✅ SEALED`). +- Events emitted (including `CounterIncremented`). ```zsh Transaction ID: 9cc7ac4d3d5239016965aba89b9692d3401a48a090d1ad1a8d9ef9cfca685e6e @@ -383,7 +383,7 @@ Result: 1 :::tip -If you want to learn more about writing transactions, please read the docs for [basic transactions]. +To learn more about writing transactions, read the docs for [basic transactions]. ::: @@ -391,30 +391,30 @@ If you want to learn more about writing transactions, please read the docs for [ You've successfully established a solid foundation for building on Flow. Let's recap what you've accomplished and learned. Through this hands-on tutorial, you've successfully built a complete Flow development foundation: -✅ **Complete Flow Development Environment** +✅ **Complete Flow development environment** -- Flow CLI installed and configured for project management -- Local Flow emulator running and ready for development -- Project creation and management workflow with `flow init` +- Flow CLI installed and configured for project management. +- Local Flow emulator running and ready for development. +- Project creation and management workflow with `flow init`. -✅ **Smart Contract Deployment Skills** +✅ **Smart contract deployment skills** -- Counter contract successfully deployed to your local emulator -- Account creation and contract deployment configuration mastered +- Counter contract successfully deployed to your local emulator. +- Account creation and contract deployment configuration mastered. -✅ **Blockchain Interactions** +✅ **Blockchain interactions** -- Scripts to query contract state (reading blockchain data) -- Transactions to modify contract state (writing to blockchain) -- Real-time interaction with blockchain data through CLI commands +- Scripts to query contract state (reading blockchain data). +- Transactions to modify contract state (writing to blockchain). +- Real-time interaction with blockchain data through CLI commands. -### Resources for Continued Learning +### Resources for continued learning As you continue your Flow development journey: -- **[Flow Discord Community]**: Connect with other developers, get help, and share your projects -- **[Cadence Language Reference]**: Deep dive into Flow's programming language features and best practices -- **[Flow GitHub]**: Explore open source tools, examples, and contribute to the ecosystem +- **[Flow Discord Community]**: Connect with other developers, get help, and share your projects. +- **[Cadence Language Reference]**: Deep dive into Flow's programming language features and best practices. +- **[Flow GitHub]**: Explore open source tools, examples, and contribute to the ecosystem. The foundation you've built today will serve you well as you explore Flow's capabilities and build applications that take advantage of blockchain's unique properties: permanence, transparency, and decentralization. diff --git a/docs/blockchain-development-tutorials/cadence/getting-started/index.md b/docs/blockchain-development-tutorials/cadence/getting-started/index.md index 1db25a51c9..c3247c2b0f 100644 --- a/docs/blockchain-development-tutorials/cadence/getting-started/index.md +++ b/docs/blockchain-development-tutorials/cadence/getting-started/index.md @@ -17,7 +17,7 @@ keywords: - Production deployment --- -# Getting Started with Cadence +# Getting started with Cadence The Cadence is designed for the next generation of apps, games, and digital assets. This comprehensive tutorial series will guide you from setting up your development environment to deploying production-ready applications on Flow's mainnet while a complete Counter application that demonstrates all essential Flow development patterns. @@ -33,56 +33,56 @@ The Cadence is designed for the next generation of apps, games, and digital asse > -## What You'll Learn +## What you'll learn In this tutorial series, you'll discover how to: -- Set up a complete Flow development environment with CLI tools and local emulator -- Build and deploy smart contracts using Cadence -- Integrate external dependencies and work with Flow's composable ecosystem -- Create transactions and implement comprehensive testing strategies -- Build interactive frontend applications using @onflow/react-sdk -- Deploy applications to testnet and mainnet with production best practices -- Implement monitoring, security, and maintenance for live blockchain applications +- Set up a complete Flow development environment with CLI tools and local emulator. +- Build and deploy smart contracts with Cadence. +- Integrate external dependencies and work with Flow's composable ecosystem. +- Create transactions and implement comprehensive testing strategies. +- Build interactive frontend applications with @onflow/react-sdk. +- Deploy applications to testnet and mainnet with production best practices. +- Implement monitoring, security, and maintenance for live blockchain applications. -## What You'll Build +## What you'll build Throughout these tutorials, you'll build a complete **Counter Application** that demonstrates the core aspects of Flow development: -- **Smart Contracts**: Counter contract with increment/decrement functionality -- **External Dependencies**: Integration with NumberFormatter for enhanced display -- **Frontend Interface**: React-based web application with wallet authentication -- **Production Deployment**: Live application accessible on Flow's public networks +- **Smart Contracts**: Counter contract with increment/decrement functionality. +- **External Dependencies**: Integration with NumberFormatter for enhanced display. +- **Frontend Interface**: React-based web application with wallet authentication. +- **Production Deployment**: Live application accessible on Flow's public networks. By the end, you'll have a fully functional blockchain application and the skills to build your own Flow projects. -## Environment Setup +## Environment setup Learn how to set up your Flow development environment and deploy your first smart contract. This foundational tutorial covers CLI installation, project creation, contract deployment, and basic blockchain interaction patterns using the local Flow emulator. Tutorial: [Cadence Environment Setup] -## Smart Contract Interaction +## Smart contract interaction -Master advanced Flow development skills including dependency management, sophisticated transaction patterns, and comprehensive testing strategies. Learn to integrate external contracts, handle complex state changes, and implement test-driven development workflows. +Gain advanced Flow development skills including dependency management, sophisticated transaction patterns, and comprehensive testing strategies. Learn to integrate external contracts, handle complex state changes, and implement test-driven development workflows. Tutorial: [Smart Contract Interaction] -## Building a Frontend App +## Building a frontend app -Create a Next.js frontend application that interacts with your Flow smart contracts using @onflow/react-sdk. Implement wallet authentication, real-time data queries, transaction submission, and status monitoring for a complete user experience. +Create a `Next.js` frontend application that interacts with your Flow smart contracts using `@onflow/react-sdk`. Implement wallet authentication, real-time data queries, transaction submission, and status monitoring for a complete user experience. Tutorial: [Building a Frontend App] -## Production Deployment +## Production deployment -Take your application live by deploying to Flow's testnet and mainnet networks. Learn security best practices, production configuration, monitoring strategies, and maintenance practices for managing live blockchain applications. +To take your application live, deploy to Flow's testnet and mainnet networks. Learn security best practices, production configuration, monitoring strategies, and maintenance practices you can use to manage live blockchain applications. Tutorial: [Production Deployment] -## Next Steps +## Next steps -After completing these tutorials, you'll be equipped with the fundamental skills needed for Flow development. Consider exploring our other tutorial series to expand your blockchain development expertise: +After you complete these tutorials, you'll have the fundamental skills needed for Flow development. Consider exploring our other tutorial series to expand your blockchain development expertise: - [Cross-VM Apps] - Build applications that integrate Flow EVM and Cadence - [Native VRF] - Implement verifiable random functions in your applications diff --git a/docs/blockchain-development-tutorials/cadence/getting-started/production-deployment.md b/docs/blockchain-development-tutorials/cadence/getting-started/production-deployment.md index dc601ca2fb..c0700a6e46 100644 --- a/docs/blockchain-development-tutorials/cadence/getting-started/production-deployment.md +++ b/docs/blockchain-development-tutorials/cadence/getting-started/production-deployment.md @@ -22,45 +22,45 @@ keywords: You've developed locally with the emulator, integrated external dependencies, built sophisticated transactions, implemented comprehensive testing, and created a frontend interface. Now it's time to take your application live and deploy it to Flow's public networks. -This tutorial will guide you through deploying your Counter application to both testnet and mainnet, ensuring your contracts and frontend work seamlessly in production environments. You'll learn the essential practices for managing live blockchain applications, from security considerations to monitoring and maintenance. +This tutorial will guide you through deploying your Counter application to both testnet and mainnet, ensuring your contracts and frontend work seamlessly in production environments. You'll learn the essential practices for how to manage live blockchain applications, from security considerations to monitoring and maintenance. -## What You'll Learn +## What you'll learn -After completing this tutorial, you'll be able to: +After you complete this tutorial, you'll be able to: -- **Deploy contracts to Flow testnet** with proper account setup and funding -- **Configure your application** for different network environments (emulator, testnet, mainnet) -- **Deploy to mainnet** with security best practices and production considerations -- **Update frontend configuration** to work with live networks -- **Implement monitoring and maintenance** practices for production applications -- **Understand the deployment pipeline** from development to production +- **Deploy contracts to Flow testnet** with proper account setup and funding. +- **Configure your application** for different network environments (emulator, testnet, mainnet). +- **Deploy to mainnet** with security best practices and production considerations. +- **Update frontend configuration** to work with live networks. +- **Implement monitoring and maintenance** practices for production applications. +- **Understand the deployment pipeline** from development to production. **Prerequisites:** -- Completed all previous tutorials ([Environment Setup], [Smart Contract Interaction], [Building a Frontend App]) -- Counter contract and frontend app working locally -- Flow CLI installed and configured +- Completed all previous tutorials ([Environment Setup], [Smart Contract Interaction], [Building a Frontend App]). +- Counter contract and frontend app working locally. +- Flow CLI installed and configured. ## Deploy to Testnet -Testnet is Flow's public test network that mirrors mainnet functionality without using real FLOW tokens. It's the perfect environment to test your application in a live blockchain environment before committing to mainnet deployment. +Testnet is Flow's public test network that mirrors mainnet functionality without using real FLOW tokens. It's the perfect environment to test your application in a live blockchain environment before you commit to mainnet deployment. -### Understanding Flow Networks +### Understanding Flow networks Flow has several networks for different purposes: -- **Emulator**: Local development environment (what you've been using) -- **Testnet**: Public test network with free test tokens -- **Mainnet**: Production network with real FLOW tokens +- **Emulator**: Local development environment (what you currently use). +- **Testnet**: Public test network with free test tokens. +- **Mainnet**: Production network with real Flow tokens. Each network has its own: -- Access nodes and APIs -- Account addresses and contract deployments -- Token economics (free on testnet, real value on mainnet) +- Access nodes and APIs. +- Account addresses and contract deployments. +- Token economics (free on testnet, real value on mainnet). -### Create a Testnet Account +### Create a testnet account -First, you'll need a testnet account to deploy your contracts. You can create one using the Flow CLI: +First, you'll need a testnet account to deploy your contracts. You can create one with the Flow CLI: ```zsh flow accounts create --network testnet @@ -72,14 +72,14 @@ When prompted: This creates a new account on testnet and adds it to your `flow.json` configuration. The CLI will show you the account address and save the private key locally. -### Fund Your Testnet Account +### Fund your testnet account -To deploy contracts and send transactions on testnet, you need FLOW tokens. Flow provides a faucet service to get free testnet tokens. +To deploy contracts and send transactions on testnet, you need Flow tokens. Flow provides a faucet service to get free testnet tokens. -1. Visit the [Flow Testnet Faucet](https://faucet.flow.com/) -2. Enter your testnet account address -3. Complete any required verification (captcha, etc.) -4. Request tokens (you'll receive 1000 FLOW tokens) +1. Visit the [Flow Testnet Faucet](https://faucet.flow.com/). +2. Enter your testnet account address. +3. Complete any required verification (captcha, and so on). +4. Request tokens (you'll receive 1000 FLOW tokens). This command automatically requests tokens from the testnet faucet for your account. @@ -87,7 +87,7 @@ This command automatically requests tokens from the testnet faucet for your acco flow accounts fund --network testnet testnet-account ``` -**Verify Funding:** +**Verify funding:** Check your account balance: @@ -95,11 +95,11 @@ Check your account balance: flow accounts list ``` -You should see your account details with a balance of FLOW tokens. +You will see your account details with a balance of Flow tokens. -### Configure Testnet Deployment +### Configure testnet deployment -Update your `flow.json` to include testnet deployment configuration. The NumberFormatter contract already exists on testnet, so you only need to deploy your Counter contract. +Update your `flow.json` to include testnet deployment configuration. The `NumberFormatter` contract already exists on testnet, so you only need to deploy your Counter contract. ```zsh flow config add deployment @@ -112,7 +112,7 @@ Follow the prompts: 4. **Deploy more contracts**: `yes` 5. **Contract**: `NumberFormatter` -Your `flow.json` should now include a testnet deployment section: +Your `flow.json` now includes a testnet deployment section: ```json { @@ -135,7 +135,7 @@ Your `flow.json` should now include a testnet deployment section: } ``` -### Deploy Counter Contract to Testnet +### Deploy Counter contract to testnet Deploy your Counter contract to the public testnet: @@ -143,7 +143,7 @@ Deploy your Counter contract to the public testnet: flow project deploy --network testnet ``` -You should see output similar to: +You will see output similar to: ```zsh Deploying 2 contracts for accounts: testnet-account @@ -154,9 +154,9 @@ NumberFormatter -> 0x9942a81bc6c3c5b7 (9a550aeefa5ede62cb95f0549084b2ab7abf3a493 🎉 All contracts deployed successfully ``` -### Test Your Testnet Deployment +### Test your testnet deployment -Verify your contract works on testnet by running a script: +Verify your contract works on testnet with this script: ```zsh flow scripts execute cadence/scripts/GetCounter.cdc --network testnet @@ -183,11 +183,11 @@ flow scripts execute cadence/scripts/GetCounter.cdc --network testnet Result: "1" ``` -Perfect! Your Counter contract is now live on testnet and working correctly. +Perfect! Your Counter contract is now live on testnet and works correctly. -### Update Frontend for Testnet +### Update frontend for testnet -Now update your Next.js application to connect to testnet instead of the emulator. +Now update your `Next.js` application to connect to testnet instead of the emulator. **Update `src/app/layout.tsx`:** @@ -221,13 +221,13 @@ export default function RootLayout({ } ``` -**Key Changes:** +**Key changes:** -- `accessNodeUrl`: Changed from localhost to Flow's testnet REST API -- `flowNetwork`: Changed from 'emulator' to 'testnet' -- `discoveryWallet`: Updated to use testnet wallet discovery +- `accessNodeUrl`: Changed from localhost to Flow's testnet REST API. +- `flowNetwork`: Changed from 'emulator' to 'testnet'. +- `discoveryWallet`: Updated to use testnet wallet discovery. -### Test Your Testnet Frontend +### Test your testnet frontend Start your frontend application: @@ -235,33 +235,33 @@ Start your frontend application: npm run dev ``` -Visit `http://localhost:3000` and you should see: +Visit `http://localhost:3000` and you will see: -1. **Counter value**: Displays the current count from your testnet contract -2. **Connect Wallet**: You can now connect using various Flow wallets (not just Dev Wallet) -3. **Increment functionality**: Transactions are sent to the live testnet -4. **Real transaction costs**: Small amounts of testnet FLOW are used for gas +1. **Counter value**: Displays the current count from your testnet contract. +2. **Connect Wallet**: You can now connect with various Flow wallets (not just Dev Wallet). +3. **Increment functionality**: Transactions are sent to the live testnet. +4. **Real transaction costs**: Small amounts of testnet Flow are used for gas. -**Important**: When connecting your wallet, make sure to: +**Important**: When you connect your wallet, make sure to: -- Switch your wallet to testnet network -- Use an account that has testnet FLOW tokens -- Confirm you're interacting with the correct contract address +- Switch your wallet to Testnet network. +- Use an account that has testnet Flow tokens. +- Confirm you're interacting with the correct contract address. -## Deploy to Mainnet +## Deploy to mainnet -Mainnet deployment is the final step in your application's journey. Unlike testnet, mainnet uses real FLOW tokens and serves real users, so additional security considerations and best practices are essential. +Mainnet deployment is the final step in your application's journey. Unlike testnet, mainnet uses real Flow tokens and serves real users, so additional security considerations and best practices are essential. -### Create a Mainnet Account +### Create a mainnet account -For mainnet, you'll need to acquire FLOW tokens through exchanges or other means, as there's no faucet. +For mainnet, you'll need to acquire Flow tokens through exchanges or other means, as there's no faucet. **Option 1: Use Flow Wallet** -1. Download and install [Flow Wallet] -2. Create a new wallet and securely store your recovery phrase -3. Purchase FLOW tokens from a supported exchange -4. Transfer tokens to your Flow Wallet +1. Download and install [Flow Wallet]. +2. Create a new wallet and securely store your recovery phrase. +3. Purchase Flow tokens from a supported exchange. +4. Transfer tokens to your Flow Wallet. **Option 2: Use Flow CLI** @@ -273,19 +273,19 @@ When prompted: 1. **Account name**: Enter `mainnet-account` 2. **Select "Mainnet" Network** -### Acquire FLOW Tokens +### Acquire FLOW tokens -You can purchase FLOW tokens from major exchanges like [Coinbase], [Moonpay], and [Binance]. +You can purchase Flow tokens from major exchanges like [Coinbase], [Moonpay], and [Binance]. -You can also obtain FLOW directly from the Flow Wallet by clicking the "Buy" button in your account. +To obtain Flow directly from the Flow Wallet, click "Buy" in your account. ![flow-wallet-icons](./imgs/flow-wallet-icons.png) -Then click on a provider to purchase FLOW. +Then, click on a provider to purchase FLOW. ![provider](./imgs/provider.png) -### Configure Mainnet Deployment +### Configure mainnet deployment Add mainnet deployment configuration to your `flow.json`: @@ -300,7 +300,7 @@ Follow the prompts: 4. **Deploy more contracts**: `yes` 5. **Contract**: `NumberFormatter` -Your `flow.json` should now include mainnet configuration: +Your `flow.json` will now include mainnet configuration: ```json { @@ -338,7 +338,7 @@ Your `flow.json` should now include mainnet configuration: } ``` -### Deploy to Mainnet +### Deploy to mainnet Deploy your Counter contract to mainnet: @@ -346,9 +346,9 @@ Deploy your Counter contract to mainnet: flow project deploy --network mainnet ``` -**⚠️ Important**: This deployment costs real FLOW tokens and cannot be undone. +**⚠️ Important**: This deployment costs real FLOW tokens and you can't undo it. -You should see output similar to: +You will see output similar to: ```zsh Deploying 2 contracts for accounts: mainnet-account @@ -359,7 +359,7 @@ NumberFormatter -> 0x123456789ABC (contract deployed successfully) 🎉 All contracts deployed successfully ``` -### Production Frontend Configuration +### Production frontend configuration Create a production build of your frontend configured for mainnet: diff --git a/docs/blockchain-development-tutorials/cadence/getting-started/smart-contract-interaction.md b/docs/blockchain-development-tutorials/cadence/getting-started/smart-contract-interaction.md index 17fb5215ba..e9b49f8067 100644 --- a/docs/blockchain-development-tutorials/cadence/getting-started/smart-contract-interaction.md +++ b/docs/blockchain-development-tutorials/cadence/getting-started/smart-contract-interaction.md @@ -20,39 +20,39 @@ keywords: # Smart Contract Interaction -Building on your local development setup from the previous tutorial, you'll now master advanced Flow development skills that every professional developer needs. This tutorial focuses on working with external dependencies, building sophisticated transactions, and establishing robust testing practices. +Building on your local development setup from the previous tutorial, you'll now master advanced Flow development skills that every professional developer needs. This tutorial focuses on how to work with external dependencies, build sophisticated transactions, and establish robust testing practices. -Flow's composability is one of its greatest strengths—contracts can easily import and use functionality from other contracts. You'll learn to leverage this power while building reliable, well-tested applications that interact seamlessly with the broader Flow ecosystem. +Flow's composability is one of its greatest strengths, becuase contracts can easily import and use functionality from other contracts. You'll learn to leverage this power while building reliable, well-tested applications that interact seamlessly with the broader Flow ecosystem. -## What You'll Learn +## What you'll learn -After completing this tutorial, you'll be able to: +After you complete this tutorial, you'll be able to: -- **Manage external dependencies** using Flow's dependency manager and integrate third-party contracts -- **Build sophisticated transactions** that interact with multiple contracts and handle complex state changes -- **Master transaction anatomy** and understand how Cadence transactions work under the hood -- **Implement comprehensive testing** strategies including edge cases and error conditions -- **Apply test-driven development** workflows to ensure code quality and reliability -- **Handle transaction monitoring** and error management in production scenarios +- **Manage external dependencies** using Flow's dependency manager and integrate third-party contracts. +- **Build sophisticated transactions** that interact with multiple contracts and handle complex state changes. +- **Master transaction anatomy** and understand how Cadence transactions work under the hood. +- **Implement comprehensive testing** strategies including edge cases and error conditions. +- **Apply test-driven development** workflows to ensure code quality and reliability. +- **Handle transaction monitoring** and error management in production scenarios. -## What You'll Build +## What you'll build Building on your Counter contract, you'll enhance it with external dependencies and create a comprehensive testing suite. By the end of this tutorial, you'll have: -- **Enhanced Counter app** that uses the NumberFormatter contract for better display -- **Complex transactions** that demonstrate advanced interaction patterns -- **Comprehensive test suite** covering normal operations, edge cases, and error conditions -- **Professional workflow** for developing, testing, and deploying contract interactions +- **Enhanced Counter app** that uses the NumberFormatter contract for better display. +- **Complex transactions** that demonstrate advanced interaction patterns. +- **Comprehensive test suite** that covers normal operations, edge cases, and error conditions. +- **Professional workflow** for you to develop, test, and deploy contract interactions. **Prerequisites:** -- Completed Environment Setup tutorial -- Flow CLI, emulator running, and Counter contract deployed -- Basic understanding of Cadence syntax +- Completed Environment Setup tutorial. +- Flow CLI, emulator running, and Counter contract deployed. +- Basic understanding of Cadence syntax. -## Managing Dependencies +## Manage dependencies -In addition to creating your own contracts, you can also install contracts that have already been deployed to the network by using the [Dependency Manager]. This is useful for interacting with contracts that are part of the Flow ecosystem or that have been deployed by other developers. +In addition to creating your own contracts, you can also install contracts that you previously deployed to the network with the [Dependency Manager]. This is useful for interacting with contracts that are part of the Flow ecosystem or that other developers deployed. Flow's dependency manager allows you to: @@ -62,7 +62,7 @@ Flow's dependency manager allows you to: For example, let's say we want to format the result of our `GetCounter` script so that we display the number with commas if it's greater than 999. To do that we can install a contract called [`NumberFormatter`] from `testnet` that has a function to format numbers. -### Install NumberFormatter Contract +### Install NumberFormatter contract The [`NumberFormatter`] contract provides utilities for formatting numbers with commas, making large numbers more readable. Let's install it from testnet: @@ -72,19 +72,19 @@ flow dependencies install testnet://8a4dce54554b225d.NumberFormatter When prompted: -1. **Account to deploy to:** Select `emulator-account` (this will deploy it locally for development) -2. **Alias for mainnet:** You can skip this by pressing Enter +1. **Account to deploy to:** Select `emulator-account` (this will deploy it locally for development). +2. **Alias for mainnet:** To skip this, press Enter. This command: -- Downloads the NumberFormatter contract from testnet and any of its dependencies -- Adds it to your `imports/` directory -- Configures deployment settings in [`flow.json`] -- Sets up automatic address resolution +- Downloads the NumberFormatter contract from testnet and any of its dependencies. +- Adds it to your `imports/` directory. +- Configures deployment settings in [`flow.json`]. +- Sets up automatic address resolution. ### Configure Dependencies in flow.json -Open your `flow.json` file and notice the new sections: +Open your `flow.json` file and view the new sections: ```json { @@ -115,19 +115,19 @@ Open your `flow.json` file and notice the new sections: This configuration: -- Maps the `NumberFormatter` dependency to its testnet source -- Sets up deployment to your emulator account -- Enables automatic address resolution in your code +- Maps the `NumberFormatter` dependency to its testnet source. +- Sets up deployment to your emulator account. +- Enables automatic address resolution in your code. ### Deploy External Dependencies -Now we can deploy the `NumberFormatter` contract to the emulator by running: +Now we can deploy the `NumberFormatter` contract to the emulator: ```zsh flow project deploy ``` -You should see output like: +You will see output like: ```zsh Deploying 1 contracts for accounts: emulator-account @@ -160,9 +160,9 @@ fun main(): String { **Key Points:** -- **Import syntax**: `import "Counter"` and `import "NumberFormatter"` don't require addresses -- **Contract interaction**: We call `NumberFormatter.formatWithCommas()` just like any other function -- **Return type change**: The script now returns a `String` instead of an `Int` +- **Import syntax**: `import "Counter"` and `import "NumberFormatter"` don't require addresses. +- **Contract interaction**: We call `NumberFormatter.formatWithCommas()` just like any other function. +- **Return type change**: The script now returns a `String` instead of an `Int`. ### Test the Integration @@ -172,15 +172,15 @@ Run your updated script: flow scripts execute cadence/scripts/GetCounter.cdc ``` -You should see: +You will see: ```zsh Result: "1" ``` -The number is now formatted as a string. Let's create a more impressive example by adding a transaction that increments by 1000. +The number is now formatted as a string. Let's create a more impressive example and add a transaction that increments by 1000. -### Create a Bulk Increment Transaction +### Create a bulk increment transaction Generate a new transaction to demonstrate the NumberFormatter's power: @@ -239,11 +239,11 @@ Perfect! The NumberFormatter automatically adds commas to make large numbers rea ::: -## Building Transactions +## Build transactions Transactions are the foundation of blockchain state changes. Unlike scripts (which only read data), transactions can modify contract state, transfer tokens, and emit events. Let's master advanced transaction patterns. -### Understanding Transaction Anatomy +### Understanding transaction anatomy Every Cadence transaction has the same basic structure: @@ -271,16 +271,16 @@ transaction { } ``` -### Transaction Phases Explained +### Transaction phases explained -1. **Import Phase**: Declare contract dependencies -2. **Parameter Declaration**: Define inputs the transaction accepts -3. **Variable Declaration**: Declare transaction-scoped variables -4. **Prepare Phase**: Access account storage and capabilities (authorized) -5. **Execute Phase**: Main logic execution (no storage access) -6. **Post Phase**: Verify transaction success conditions +1. **Import Phase**: Declare contract dependencies. +2. **Parameter Declaration**: Define inputs the transaction accepts. +3. **Variable Declaration**: Declare transaction-scoped variables. +4. **Prepare Phase**: Access account storage and capabilities (authorized). +5. **Execute Phase**: Main logic execution (no storage access). +6. **Post Phase**: Verify transaction success conditions. -#### Transaction with Parameters +#### Transaction with parameters Create a transaction that accepts a custom increment value: @@ -338,7 +338,7 @@ Execute with a parameter: flow transactions send cadence/transactions/IncrementByAmount.cdc --network emulator --signer test-account ``` -## Testing Your Code +## Test your code Testing is crucial for smart contract development. Flow provides powerful testing capabilities built into the CLI that enable comprehensive test coverage and test-driven development workflows. @@ -348,7 +348,7 @@ Execute the test suite: flow test ``` -You should see output confirming the tests pass: +You will see output that confirms the tests pass: ```zsh Test results: "Counter_test.cdc" @@ -379,9 +379,9 @@ access(all) fun testContract() { This basic test: -1. **Creates a test account** using `Test.createAccount()` -2. **Deploys the Counter contract** to the test environment -3. **Verifies deployment succeeded** by checking that no error occurred +1. **Creates a test account** using `Test.createAccount()`. +2. **Deploys the Counter contract** to the test environment. +3. **Verifies deployment succeeded** by checking that no error occurred. ### Test Integration with Dependencies @@ -414,7 +414,7 @@ access(all) fun testNumberFormatterLogic() { } ``` -The Formatter_test.cdc test validates that number formatting with commas works correctly by testing two scenarios: numbers under 1,000 (which should have no commas) and numbers over 999 (which should have commas). The test is constructed with two main assertions - first testing that 123 formats as "123" without commas, and second testing that 1234 formats as "1,234" with a comma. +The `Formatter_test.cdc` test validates that number formatting with commas works correctly by testing two scenarios: numbers under 1,000 (which should have no commas) and numbers over 999 (which should have commas). The test is constructed with two main assertions - first testing that 123 formats as "123" without commas, and second testing that 1234 formats as "1,234" with a comma. ### Run Your Enhanced Test Suite @@ -449,45 +449,45 @@ For a more detailed guide on Cadence testing patterns and advanced techniques, c Through this tutorial, you've accomplished: -✅ **Dependency Management** +✅ **Dependency management** -- Successfully integrated the NumberFormatter contract from testnet -- Learned about Flow's dependency management system and automatic address resolution -- Demonstrated contract composability by enhancing functionality without modifying source code -- Configured multi-contract deployments across different environments +- Successfully integrated the NumberFormatter contract from testnet. +- Learned about Flow's dependency management system and automatic address resolution. +- Demonstrated contract composability by enhancing functionality without modifying source code. +- Configured multi-contract deployments across different environments. -✅ **Transaction Development** +✅ **Transaction development** -- Understood transaction anatomy including prepare, execute, and post phases -- Implemented proper input validation and error handling patterns +- Understood transaction anatomy including prepare, execute, and post phases. +- Implemented proper input validation and error handling patterns. ✅ **Testing** - Implemented test coverage for contract functionality - Created integration tests that verify multi-contract interactions -### What You've Learned +### What you've learned You have learned how to use Flow's dependency management system to install and integrate external contracts (like NumberFormatter), understand the structure of Cadence transactions including their prepare, execute, and post phases, and implement basic testing for contract functionality. You can now work with multi-contract applications and understand how contracts can be composed together to extend functionality. -### Next Steps +### Next steps With these skills, you're ready to: -- Build frontend applications that interact with your smart contracts -- Deploy contracts to live networks (testnet and mainnet) -- Explore advanced Flow patterns and ecosystem contracts -- Contribute to the growing Flow developer community +- Build frontend applications that interact with your smart contracts. +- Deploy contracts to live networks (testnet and mainnet). +- Explore advanced Flow patterns and ecosystem contracts. +- Contribute to the growing Flow developer community. You've made significant progress in becoming a proficient Flow developer! -### Resources for Continued Learning +### Resources for continued learning Continue your Flow mastery with these advanced resources: -- **[Flow Discord Community]**: Connect with other developers building sophisticated Flow applications -- **[Cadence Language Reference]**: Master advanced language features including resources, capabilities, and access control -- **[Flow GitHub]**: Explore production contract examples and contribute to the ecosystem +- **[Flow Discord Community]**: Connect with other developers building sophisticated Flow applications. +- **[Cadence Language Reference]**: Master advanced language features including resources, capabilities, and access control. +- **[Flow GitHub]**: Explore production contract examples and contribute to the ecosystem.