diff --git a/docs/build/flow.md b/docs/build/flow.md index 243a6fe537..435cc1f694 100644 --- a/docs/build/flow.md +++ b/docs/build/flow.md @@ -36,13 +36,13 @@ keywords: # Why Flow: The Consumer DeFi Layer-One Network -Flow is powering the future of Consumer DeFi. Flow is the home of Consumer DeFi. +Flow powers the future of Consumer DeFi. Flow is the home of Consumer DeFi. -Flow is a purpose-built L1 blockchain designed for large-scale consumer finance applications. It is the leading consumer layer-one network, boasting over 1 million monthly active users across ecosystem applications built in collaboration with top global brands like NBA, Disney, PayPal, NFL, and Ticketmaster. +Flow is a purpose-built L1 blockchain designed for large-scale consumer finance applications. It is the leading consumer layer-one network, boasting over one million monthly active users across ecosystem applications built in collaboration with top global brands like NBA, Disney, PayPal, NFL, and Ticketmaster. -## The Consumer DeFi Movement +## The Consumer DeFi movement -Today's fintech is a digital facade on analog rails, subject to the same outdated limitations of your brick-and-mortar bank. These platforms gave us the appearance of digital money without the benefits of digital-native assets. Your accounts there are mere pointers to the underlying legacy system. But that is about to change with the Consumer DeFi movement: turning decentralized finance into personal finance. +Today's fintech is a digital facade on analog rails, subject to the same outdated limitations of your brick-and-mortar bank. These platforms gave us the appearance of digital money without the benefits of digital-native assets. Your accounts there are mere pointers to the underlying legacy system. But that is about to change with the Consumer DeFi movement: to turn decentralized finance into personal finance. The new chapter for Flow in leading Consumer DeFi is not a sudden shift, but rather the culmination of many years of focused dedication in providing the best consumer experience. Within the past 12 months, Flow network achieved remarkable feats: nearly 10x throughput increase for consumer-scale ambitions, 600% year-over-year increase in total value locked (TVL) to over $100M, and the pivotal Forte upgrade that drastically reduced the development time for consumer finance applications from months to mere days. @@ -53,11 +53,11 @@ The next generation of consumer finance is not just facilitated by the internet; - **Real-Time**: Settling transactions in seconds, not days. - **Open**: Programmable and composable across apps. -The foundation for the future of consumer finance is already being laid. After years of development, DeFi technology is ready to transition from a niche market to the mainstream. However, a significant hurdle remains: current DeFi platforms are designed for crypto-savvy users, demanding steep learning curves and willingness to take on unlimited risk. We must move beyond this crypto native phase to the new consumer DeFi era with better-than-fintech user experiences, safer and sustainable yields, and most importantly delivering a tangible impact on users' daily lives. +The foundation for the future of consumer finance is already being laid. After years of development, DeFi technology is ready to transition from a niche market to the mainstream. However, a significant hurdle remains: current DeFi platforms are designed for crypto-savvy users, which demands steep learning curves and willingness to take on unlimited risk. We must move beyond this crypto native phase to the new consumer DeFi era with better-than-fintech user experiences, safer and sustainable yields, and most importantly delivering a tangible impact on users' daily lives. **What is Consumer DeFi?** Consumer DeFi is any app or experience that provides the benefits powered by DeFi rails to audiences with zero crypto knowledge. Apps powered by Flow win consumer mindshare because they offer features and benefits that are extremely hard to replicate with just web2 rails while ensuring users do not require crypto-specific knowledge to understand and use them. -Flow has demonstrated its capability to attract global brands and institutions, offering an innovative and safe platform for their millions of users. With the DeFi sector now ready to transition from a niche market to the mainstream, Flow is uniquely positioned to lead the Consumer DeFi charge. +Flow has demonstrated its capability to attract global brands and institutions, and offers an innovative and safe platform for their millions of users. With the DeFi sector now ready to transition from a niche market to the mainstream, Flow is uniquely positioned to lead the Consumer DeFi charge. Dieter Shirley, Chief Architect of Flow and co-author of the [ERC-721 NFT standard], calls Flow: @@ -75,88 +75,88 @@ Dieter Shirley, Chief Architect of Flow and co-author of the [ERC-721 NFT standa > -## Flow: Automated DeFi and Consumer Applications +## Flow: automated DeFi and consumer applications -Flow is a high-performance layer-one blockchain designed for automated DeFi and large-scale consumer applications. Its multi-role architecture isolates heavy computation to Execution Nodes while keeping validation lightweight, so developers gain incredible performance and users benefit from low-cost transactions, even at scale. +Flow is a high-performance, layer-one blockchain designed for automated DeFi and large-scale consumer applications. Its multi-role architecture isolates heavy computation to Execution Nodes while keeping validation lightweight, so developers gain incredible performance and users benefit from low-cost transactions, even at scale. The Forte upgrade expands the core protocol with Flow Actions for atomic multi-step DeFi operations and Scheduled Transactions for fully onchain automation. Developers can compose swaps, staking, or yield workflows that self-execute without off-chain keepers, scripts, or relayers required. Flow delivers a unified environment for automation-heavy, composable applications that demand reliability and precision at scale. It's where DeFi, fintech, and consumer-grade performance converge in a single L1. -## Forte Network Upgrade: Autonomous DeFi Execution +## Forte network upgrade: autonomous DeFi execution -The Forte network upgrade marks a turning point for builders creating DeFi systems on Flow. Until now, blockchains have largely been reactive, responding only when a user or off-chain keeper sends a transaction. Forte changes that model by giving developers a native framework for composable, autonomous execution. +The Forte network upgrade marks a turning point for builders who create DeFi systems on Flow. Until now, blockchains have largely been reactive, and respond only when a user or off-chain keeper sends a transaction. Forte changes that model by giving developers a native framework for composable, autonomous execution. > **_ERC-20 and ERC-721 unlocked nouns. Actions and scheduled transactions unlock verbs._** -Forte transforms Flow from a reactive blockchain into an autonomous, intelligent network capable of executing complex workflows without external dependencies. The upgrade introduces native time scheduling, protocol-level composability, and AI-optimized development tools that enable entirely new categories of applications. +Forte transforms Flow from a reactive blockchain into an autonomous, intelligent network that executes complex workflows without external dependencies. The upgrade introduces native time scheduling, protocol-level composability, and AI-optimized development tools that enable entirely new categories of applications. Together, these systems turn Flow into a self-governing financial runtime that is precise with 128-bit fixed-point math for lossless calculations, secure through resource-based execution, and fully composable across protocols. In this environment, DeFi logic can schedule itself, chain together across protocols, and operate autonomously—a blockchain that finally does more than react. -### Flow Actions: Protocol-native composability +### Flow Actions: protocol-native composability [**Flow Actions**] are protocol-native, composable operations that enable developers to create multi-step workflows across protocols in a single atomic transaction. With Flow Actions, builders can link together standardized DeFi primitives such as sources, sinks, swappers, price oracles, and flashers into atomic, protocol-agnostic workflows. -A single transaction can claim rewards, swap assets, add liquidity, and restake LP tokens without any off-chain orchestration. These building blocks eliminate custom integrations and ensure every operation either fully succeeds or safely reverts, unlocking complex strategies like automated yield farming, arbitrage, and rebalancing through simple, auditable Cadence code. +A single transaction can claim rewards, swap assets, add liquidity, and restake LP tokens without any off-chain orchestration. These building blocks eliminate custom integrations and ensure every operation either fully succeeds or safely reverts, and unlock complex strategies like automated yield farming, arbitrage, and rebalancing through simple, auditable Cadence code. This means developers can: -- **Compose complex operations**: Build sophisticated DeFi strategies by combining multiple Actions in one transaction -- **Eliminate integration complexity**: Use standardized interfaces instead of custom contract integrations -- **Ensure atomicity**: All operations succeed together or fail together, eliminating partial execution risks -- **Reduce gas costs**: Execute multiple protocol interactions more efficiently than separate transactions +- **Compose complex operations**: Combine multiple actions in one transaction to build sophisticated DeFi strategies. +- **Eliminate integration complexity**: Use standardized interfaces instead of custom contract integrations. +- **Ensure atomicity**: All operations succeed together or fail together, which eliminates partial execution risks. +- **Reduce gas costs**: Execute multiple protocol interactions more efficiently than separate transactions. -### Scheduled Transactions: Autonomous onchain execution +### Scheduled Transactions: autonomous onchain execution -[**Scheduled Transactions**] introduce the first truly onchain time scheduler. Developers can schedule or trigger transactions directly within Flow accounts, enabling recurring actions, deferred settlements, and autonomous portfolio management without external cron jobs or trusted servers. +[**Scheduled Transactions**] introduce the first truly onchain time scheduler. Developers can schedule or trigger transactions directly within Flow accounts, which allows recurring actions, deferred settlements, and autonomous portfolio management without external cron jobs or trusted servers. -Scheduled Transactions are onchain resources that run entirely within a Flow account, enabling fully autonomous, secure transaction execution. They can self-trigger based on conditions and operate without external keepers. +Scheduled Transactions are onchain resources that run entirely within a Flow account, which allows fully autonomous, secure transaction execution. They can self-trigger based on conditions and operate without external keepers. Key capabilities: -- **Autonomous operation**: Execute transactions automatically based on programmed logic -- **Self-contained**: Run entirely onchain without external dependencies -- **Trigger-based**: React to onchain events, time schedules, or custom conditions +- **Autonomous operation**: Execute transactions automatically based on programmed logic. +- **Self-contained**: Run entirely onchain without external dependencies. +- **Trigger-based**: React to onchain events, time schedules, or custom conditions. -Combined, Actions and Scheduling allow DeFi protocols to become self-maintaining: positions can compound automatically, vaults can adjust exposure based on time or events, and protocols can enforce predictable behavior entirely onchain. +Combined, Actions and Scheduling allow DeFi protocols to become self-maintaining. Positions can compound automatically, vaults can adjust exposure based on time or events, and protocols can enforce predictable behavior entirely onchain. Scheduled Transactions are the first native time scheduler that lets onchain apps run tasks automatically, like cron jobs for blockchains. Applications are no longer restricted to being reactive only to user transactions. They can be used for: -- **DeFi protocols** that automatically rebalance portfolios on schedule -- **AI-driven agents** that proactively settle, sweep, or optimize positions -- **Subscription services** with automatic recurring payments -- **Gaming mechanics** with time-based events and rewards +- **DeFi protocols** that automatically rebalance portfolios on schedule. +- **AI-driven agents** that proactively settle, sweep, or optimize positions. +- **Subscription services** with automatic recurring payments. +- **Gaming mechanics** with time-based events and rewards. -Scheduled Transactions run natively on the network, simplifying operations, reducing off-chain dependencies, and making behavior auditable and predictable in code. This implements [FLIP 330: Scheduled Transaction]. +Scheduled Transactions run natively on the network, which simplifies operations, reduces off-chain dependencies, and makes behavior auditable and predictable in code. This implements [FLIP 330: Scheduled Transaction]. ### High-precision DeFi with 128-bit fixed-point types -Cadence now supports **Fix128** and **UFix128** - 128-bit fixed-point types enabling precision up to **24 decimal places** for advanced DeFi, risk engines, and interest accrual workloads. +Cadence now supports **Fix128** and **UFix128** - 128-bit fixed-point types that allow precision up to **24 decimal places** for advanced DeFi, risk engines, and interest accrual workloads. -The native precision in Forte with built-in 128-bit fixed-point support eliminates the need for bespoke arithmetic scaffolding while minimizing rounding-related errors common in integer-based math. This ensures lossless conversion where all existing Fix64 and UFix64 values convert seamlessly, providing financial-grade accuracy that supports sophisticated financial calculations requiring extreme precision. +The native precision in Forte with built-in 128-bit fixed-point support eliminates the need for bespoke arithmetic scaffolding and minimizes rounding-related errors common in integer-based math. This ensures lossless conversion where all existing Fix64 and UFix64 values convert seamlessly, which provides financial-grade accuracy that supports sophisticated financial calculations that require extreme precision. This implements [FLIP 341: Add 128-bit Fixed-point Types to Cadence]. ### WebAuthn and passkey support -Forte adds **native WebAuthn support** including passkeys, enabling wallets to use device-backed credentials on iOS, Android, and popular password managers to sign transactions. +Forte adds **native WebAuthn support** such as passkeys, which allows wallets to use device-backed credentials on iOS, Android, and popular password managers to sign transactions. -Native WebAuthn support on Flow eliminates seed phrases by enabling biometric authentication while preserving self-custody, with cross-device portability that securely syncs credentials across devices. The native integration requires no additional smart contract layers like ERC-4337, providing a seamless UX where users can sign transactions with Touch ID, Face ID, or hardware keys. +Native WebAuthn support on Flow eliminates seed phrases by turning on biometric authentication while preserving self-custody, with cross-device portability that securely syncs credentials across devices. The native integration requires no additional smart contract layers like ERC-4337, providing a seamless UX where users can sign transactions with Touch ID, Face ID, or hardware keys. Combined with native account abstraction on Flow, developers can build [smart wallets without relying on complex contract architectures]. This implements [FLIP 264: WebAuthn Credential Support]. ### AI-friendly Cadence errors -Cadence compiler and linter errors are now **designed for AI assistance**, making it easier for agents and IDE copilots to fix issues automatically. Error messages: +Cadence compiler and linter errors are now **designed for AI assistance**, which makes it easier for agents and IDE copilots to fix issues automatically. Error messages: -- **Explain the cause** with context-aware descriptions -- **Suggest concrete fixes** with actionable recommendations -- **Link directly** to reference docs and migration notes -- **Surface through language server** for AI-powered editors like Cursor +- **Explain the cause** with context-aware descriptions. +- **Suggest concrete fixes** with actionable recommendations. +- **Link directly** to reference docs and migration notes. +- **Surface through language server** for AI-powered editors like Cursor. This enables faster feedback, fewer documentation round trips, and smoother AI agent workflows for code refactoring and migration. -### Boosting Efficiency and Scalability +### Boost efficiency and scalability #### Enhanced node performance with PebbleDB @@ -164,17 +164,17 @@ Forte upgrades node storage from BadgerDB to **PebbleDB**, delivering up to 80% #### Optimized state storage with account key de-duplication -Public key de-duplication eliminates redundancy while preserving multi-key account flexibility, consolidating 53% of all keys that were duplicates. This optimization delivers a 6% reduction in the Flow execution state (saving 21 GB from 349 GB), removes 0.29 billion entries from the storage trie, and provides a 6-18% reduction in Execution Node memory usage, resulting in faster state access through leaner data structures. +Public key de-duplication eliminates redundancy while preserving multi-key account flexibility, which consolidates 53% of all keys that were duplicates. This optimization delivers a 6% reduction in the Flow execution state (saving 21 GB from 349 GB), removes 0.29 billion entries from the storage trie, and provides a 6-18% reduction in Execution Node memory usage, which results in faster state access through leaner data structures. #### Adaptive collection rate limiting for overload resilience -The [assembly line architecture] on Flow gains intelligent rate limiting to prevent pipeline bottlenecks through automatic throttling when execution or sealing lags behind collection. The system maintains steady pipeline flow even at several hundred TPS while providing priority handling for governance and protocol transactions, creating a self-regulating system that disengages once the backlog clears. +The [assembly line architecture] on Flow gains intelligent rate limiting to prevent pipeline bottlenecks through automatic throttling when execution or sealing lags behind collection. The system maintains steady pipeline flow even at several hundred TPS while providing priority handling for governance and protocol transactions, which creates a self-regulating system that disengages after the backlog clears. #### Near real-time transaction results -Building on the [data availability vision] for Flow, Access Nodes ingest account data and transaction results **before finalization**, enabling soft finality access for high-frequency DeFi applications with early state reads that include graceful rollback handling. This approach provides reduced latency for real-time applications and direct data serving without third-party dependencies. +Building on the [data availability vision] for Flow, Access Nodes ingest account data and transaction results **before finalization**, which allows soft finality access for high-frequency DeFi applications with early state reads that include graceful rollback handling. This approach provides reduced latency for real-time applications and direct data serving without third-party dependencies. -### Protocol Autonomy +### Protocol autonomy #### Hardened data integrity across the network @@ -188,7 +188,7 @@ Flow is a fast, decentralized, and developer-friendly blockchain designed to be Much of the protocol design is based on lessons learned from building Web3 applications while working at [Dapper Labs], particularly [CryptoKitties] — the first onchain game to reach [widespread popularity]. The game went viral, then [struggled under its own success] when it caused so much traffic that the Ethereum network itself was overwhelmed by the load. -The design of Flow was guided by the need to alleviate this burden while creating the best experience possible for both developers and users. Flow Foundation (the core team) and Dapper Labs (the leading ecosystem builder) work together as two integral parts of a unified effort, combining their strengths to position Flow as the leader in Consumer DeFi. This synergy brings together deep protocol and infrastructure expertise hardened by over 10 years of production experience with the highest security standards, alongside deep consumer audience expertise honed by operating multiple production apps that generated over $1 billion in revenue combined. +The design of Flow was guided by the need to alleviate this burden and create the best experience possible for both developers and users. Flow Foundation (the core team) and Dapper Labs (the leading ecosystem builder) work together as two integral parts of a unified effort, combining their strengths to position Flow as the leader in Consumer DeFi. This synergy brings together deep protocol and infrastructure expertise hardened by over 10 years of production experience with the highest security standards, alongside deep consumer audience expertise honed by operating multiple production apps that generated over $1 billion in revenue combined. The blockchain network of the future must be able to handle millions of users while upholding the key pillars of decentralization: @@ -199,16 +199,16 @@ The blockchain network of the future must be able to handle millions of users wh 1. Interoperability 1. Security -Flow solves the [blockchain trilemma] and represents the next generation of blockchain technology. It's built to enable seamless consumer-scale apps without compromising decentralization or user experience, and is the chosen blockchain network for [NBA Top Shot], [NFL All Day], [Mattel Creations], and [Disney Pinnacle]. +Flow solves the [blockchain trilemma] and represents the next generation of blockchain technology. It's built to allow seamless consumer-scale apps without compromising decentralization or user experience, and is the chosen blockchain network for [NBA Top Shot], [NFL All Day], [Mattel Creations], and [Disney Pinnacle]. ### Dual language architecture -Flow is unique in supporting two powerful programming languages for smart contract development: +Flow is unique in that it supports two powerful programming languages for smart contract development: - **Cadence**: A modern programming language developed by smart contract application builders. - **Solidity**: The industry-standard language for EVM development, fully supported on Flow with full EVM equivalence. -EVM and Cadence environments both use FLOW as gas for transactions and are connected by a native bridge that allows seamless and cheap communication between them. Fungible and non-fungible tokens can also be seamlessly transferred between environments using the native VM token bridge, taking place instantly in a single atomic transaction. +EVM and Cadence environments both use FLOW as gas for transactions and are connected by a native bridge that allows seamless and cheap communication between them. Fungible and non-fungible tokens can also be seamlessly transferred between environments with the native VM token bridge, taking place instantly in a single atomic transaction. This means developers can choose the language that best fits their needs while maintaining full interoperability between both environments. @@ -230,21 +230,21 @@ Key Cadence features: ### Solidity development on Flow EVM -[Solidity] allows developers to deploy existing contracts on a fast and efficient, fully EVM-equivalent network while benefitting from access to native VRF, batched transactions, and all the benefits of the Flow protocol. A native bridge allows seamless transfers of assets between these two networks. +[Solidity] allows developers to deploy current contracts on a fast and efficient, fully EVM-equivalent network and benefit from access to native VRF, batched transactions, and all the benefits of the Flow protocol. A native bridge allows seamless transfers of assets between these two networks. Flow EVM provides the best EVM experience available anywhere: - **Speed, cost, and compatibility**: Flow EVM can already run all of your audited Solidity contracts at an average of less than 1 cent per transaction ([usually way less!]). Unlike L2 solutions, Flow EVM reaches true finality in seconds — not in [a week]. - **Bridge from Other EVM networks**: You can [bridge] hundreds of assets from dozens of chains to Flow. - **VM token bridge**: Assets can be bridged between Flow Cadence and Flow EVM easily and atomically with the VM token bridge. Assets can even be bridged **and used** in a **single** transaction, allowing full composability between the EVM and Cadence environments. -- **Access to Cadence features**: Access Cadence features and contracts from Flow EVM to take advantage of native [VRF], higher computation for lower cost, and any asset on Cadence Flow. You can also build [cross-vm apps] on top of the _wagmi/viem/RainbowKit_ stack, enabling batched transactions and more. +- **Access to Cadence features**: Access Cadence features and contracts from Flow EVM to take advantage of native [VRF], higher computation for lower cost, and any asset on Cadence Flow. You can also build [cross-vm apps] on top of the _wagmi/viem/RainbowKit_ stack, which allows batched transactions and more. - **EVM equivalence:** Flow EVM is truly _EVM Equivalent_, not just _EVM Compatible_. It runs exactly the same as EVM mainnet, which means builders do not run into _minor_ variances or endless 'quirks' when they try to integrate. If it works on Ethereum Mainnet, it works with Flow EVM. ### Seamless integration for Ethereum developers Flow EVM is designed to work out-of-the-box with the Ethereum toolchain or other clients. Native EVM transactions continue to be supported when using Metamask and other EVM-compatible clients. -EVM-equivalency on Flow works behind-the-scenes by implementing a minimal transaction script in Cadence to integrate Flow features with EVM. This is made possible because EVM transactions are composed and executed within Cadence transactions, enabling novel use-cases and patterns for integration. +EVM-equivalency on Flow works behind-the-scenes by implementing a minimal transaction script in Cadence to integrate Flow features with EVM. This is made possible because EVM transactions are composed and executed within Cadence transactions, which allows novel use-cases and patterns for integration. ### Flow blockchain core features @@ -267,43 +267,43 @@ Flow leadership in Consumer DeFi is built on a foundation of proven expertise an **Consumer expertise:** -- The leading consumer chain that onboarded millions of net new users onchain and still boasts over 1 million monthly active users +- The leading consumer chain that onboarded millions of net new users onchain and still boasts over one million monthly active users - Deep consumer audience expertise honed by operating multiple production apps that generated over $1 billion in revenue combined - Vast network of global consumer brands and platforms like NBA, Disney, PayPal, Ticketmaster **DeFi and fintech expertise:** -- Deep protocol and infrastructure expertise hardened by over 10 years of production experience with the highest security standards (since CryptoKitties days) -- Built the first smart contract wallet (Dapper Wallet plugin) on Ethereum back in 2018, ahead of the account abstraction movement -- Managed the end-to-end infrastructure for on/off-ramp, KYC, and risk monitoring platform that handles hundreds of millions of dollars in volume (Dapper Wallet) -- Flow ALP provides the best risk-adjusted yield opportunities in DeFi for consumers and institutional capital -- The best infrastructure layer that offers the fastest time to market for consumer DeFi apps +- Deep protocol and infrastructure expertise hardened by over 10 years of production experience with the highest security standards (since CryptoKitties days). +- Built the first smart contract wallet (Dapper Wallet plugin) on Ethereum back in 2018, ahead of the account abstraction movement. +- Managed the end-to-end infrastructure for on/off-ramp, KYC, and risk monitoring platform that handles hundreds of millions of dollars in volume (Dapper Wallet). +- Flow ALP provides the best risk-adjusted yield opportunities in DeFi for consumers and institutional capital. +- The best infrastructure layer that offers the fastest time to market for consumer DeFi apps. Flow is where consumers deposit their funds and access the best risk-adjusted yields, making it the ideal platform for Consumer DeFi applications that prioritize safety and sustainable returns. ### Scalability, performance, and low gas fees -For sustainable user adoption, apps require the network they build on to be secure, efficient, affordable, and fast. Gas fees are ultra-low cost on the network, but Flow goes a step further allowing for gasless experiences through sponsored transactions. +For sustainable user adoption, apps require the network they build on to be secure, efficient, affordable, and fast. Gas fees are ultra-low cost on the network, but Flow goes a step further, as it allows for gasless experiences through sponsored transactions. The state space on Flow is extensible to the petabyte scale, making it easy to store application data onchain. This means contracts can maintain a full working dataset — including metadata — together with contract logic. Transaction throughput on the Flow network has reached as many as 2 million daily transactions, a similar average transaction volume as Ethereum. Unlike Ethereum, Flow has always operated well under its maximum throughput ceiling, and that ceiling is scalable to even greater performance when it becomes necessary. -## Getting started +## Get started Whether you're ready to dive into the advantages of building with [Cadence], or are starting with Flow [EVM], we've got paths to get you up and running as quickly as possible. -### Getting started with Cadence app development +### Get started with Cadence app development The [Getting Started] tutorial covers everything you need to know to build a Flow Cadence application: -- Setting up your local development environment (it's fast and easy!). -- Deploying and interacting with Flow Cadence contracts. -- Building a frontend that can interact with smart contracts written by you or other developers. +- Set up your local development environment (it's fast and easy!). +- Deploy and interact with Flow Cadence contracts. +- Build a frontend that can interact with smart contracts written by you or other developers. ### Learn Cadence -[Cadence] is a modern smart contract programming language designed to work with Flow. Learning a new language is an investment, but you'll find that Cadence is safer, more explicit, and less dangerous than other blockchain languages. Plus, it unlocks the full power of the Flow protocol! +[Cadence] is a modern smart contract programming language designed to work with Flow. To learn a new language is an investment, but you'll find that Cadence is safer, more explicit, and less dangerous than other blockchain languages. Plus, it unlocks the full power of the Flow protocol! :::tip @@ -313,7 +313,7 @@ If you're already comfortable with Solidity, be sure to check out how [Cadence] ### Build with Solidity on Flow EVM -Not ready to take the plunge and learn [Cadence]? Try out **EVM++** by deploying existing [EVM] contracts to see that Flow EVM is faster and cheaper than nearly every other EVM solution without compromising on security. +Not ready to take the plunge and learn [Cadence]? Try out **EVM++** by deploying current [EVM] contracts to see that Flow EVM is faster and cheaper than nearly every other EVM solution without compromising on security. Deploying on Flow EVM also gives your Solidity contracts access to many Flow Cadence features, such as native [VRF]. @@ -331,7 +331,7 @@ The [FLOW] (or $FLOW) token is the native currency for the Flow network. Develop ## Flow Improvement Proposals (FLIPs) -Those wishing to understand the technical specifics of how Flow EVM works, we recommend reviewing the following improvement proposals: +Those wishing to understand the technical specifics of how Flow EVM works, we recommend that you review the following improvement proposals: - Understanding [EVM Support on Flow] - Exploring the [Flow VM Bridge] @@ -340,11 +340,11 @@ Those wishing to understand the technical specifics of how Flow EVM works, we re ## Build with Flow -Whether you're building with Cadence or Solidity, porting an existing Solidity dApp or building from scratch, Flow offers a **fast, scalable blockchain with low fees** and the tooling you already know. As a **purpose-built L1 for consumer finance applications**, Flow combines familiar development workflows with performance and UX enhancements you can't get elsewhere. Build the next generation of Consumer DeFi applications that deliver better-than-fintech user experiences, safer and sustainable yields, and tangible impact on users' daily lives. +Whether you build with Cadence or Solidity, portiwant to port a current Solidity dApp or build one from scratch, Flow offers a **fast, scalable blockchain with low fees** and the tooling you already know. As a **purpose-built L1 for consumer finance applications**, Flow combines familiar development workflows with performance and UX enhancements you can't get elsewhere. Build the next generation of Consumer DeFi applications that deliver better-than-fintech user experiences, safer and sustainable yields, and tangible impact on users' daily lives. ## Join the community -Are you interested in launching a project on Flow or partnering with us? Visit our weekly Flow [office hours] for discussions on project development and other opportunities for collaboration. You can also connect with us in our developers-chat in the Flow [Discord]. +Want to launch a project on Flow or partner with us? Visit our weekly Flow [office hours] for discussions on project development and other opportunities for collaboration. You can also connect with us in our developers-chat in the Flow [Discord]. diff --git a/docs/build/tools/error-codes.md b/docs/build/tools/error-codes.md index 52776f36bc..789deb6b8d 100644 --- a/docs/build/tools/error-codes.md +++ b/docs/build/tools/error-codes.md @@ -5,8 +5,8 @@ sidebar_position: 7 # Error Codes -List of error codes returned from failing transactions and scripts. The error code has an accompanied error message that usually gives more clarification. This list is meant to give more information and helpful hints. -[Code file](https://github.com/onflow/flow-go/blob/master/fvm/errors/codes.go) +List of error codes returned from transactions and scripts that fail. The error code has an accompanied error message that usually gives more clarification. This list is meant to give more information and helpful hints. +[Code file] ### 1006 @@ -99,7 +99,7 @@ Example: Example: `[Error Code: 1103] The account with address (xxx) uses 96559611 bytes of storage which is over its capacity (96554500 bytes). Capacity can be increased by adding FLOW tokens to the account.` -For more information refer to [Fees](../cadence/basics/fees.md#maximum-available-balance) +For more information refer to [Fees] ### 1105 @@ -282,3 +282,8 @@ Example: Example: `...` + + + +[Code file]: https://github.com/onflow/flow-go/blob/master/fvm/errors/codes.go +[Fees]: ../cadence/basics/fees.md#maximum-available-balance \ No newline at end of file diff --git a/docs/build/tools/flow-dev-wallet/index.md b/docs/build/tools/flow-dev-wallet/index.md index bac494585b..82137e6645 100644 --- a/docs/build/tools/flow-dev-wallet/index.md +++ b/docs/build/tools/flow-dev-wallet/index.md @@ -4,35 +4,29 @@ sidebar_label: Flow Dev Wallet sidebar_position: 5 --- -The Flow Dev Wallet is a mock Flow wallet that simulates the protocols used by [FCL](../clients/fcl-js/index.md) to interact with the Flow blockchain on behalf of simulated user accounts. +The Flow Dev Wallet is a mock Flow wallet that simulates the protocols the Flow Client Library ([FCL]) uses to interact with the Flow blockchain on behalf of simulated user accounts. -:::warning[IMPORTANT] +:::warning -This project implements an FCL compatible -interface, but should **not** be used as a reference for -building a production grade wallet. +This project implements an FCL compatible interface, but should **not** be used as a reference to build a production grade wallet. -This project should only be used in aid of local -development against a locally run instance of the Flow -blockchain like the Flow emulator, and should never be used in -conjunction with Flow Mainnet, Testnet, or any -other instances of Flow. +This project should only be used in aid of local development against a locally run instance of the Flow blockchain like the Flow emulator, and should never be used in conjunction with Flow Mainnet, Testnet, or any other instances of Flow. ::: :::info -To see a full list of Flow compatible wallets visit [Wallets page](../../../ecosystem/wallets.md) +To see a full list of Flow compatible wallets, visit the [Wallets page] ::: -## Getting Started +## Get started -Before using the dev wallet, you'll need to start the Flow emulator. +Before you use the dev wallet, you'll need to start the Flow emulator. ### Install the `flow-cli` -The Flow emulator is bundled with the Flow CLI. Instructions for installing the CLI can be found here: [flow-cli/install/](../flow-cli/install.md) +The Flow emulator is bundled with the Flow CLI. Instructions for how to install the CLI can be found here: [flow-cli/install/] ### Create a `flow.json` file @@ -44,14 +38,14 @@ flow init --config-only ### Start the Emulator -Start the Emulator and deploy the contracts by running the following command from the directory containing `flow.json` in your project: +To start the Emulator and deploy the contracts, run the following command from the directory that contains `flow.json` in your project: ```sh flow emulator start flow project deploy --network emulator ``` -### Start the Dev Wallet +### Start the dev wallet In a separate terminal session, start the dev wallet service. @@ -59,11 +53,11 @@ In a separate terminal session, start the dev wallet service. flow dev-wallet ``` -### Configuring Your JavaScript Application +### Configure your JavaScript application -The Flow Dev Wallet is designed to be used with [`@onflow/fcl`](https://github.com/onflow/fcl-js) version `1.0.0` or higher. The FCL package can be installed with: `npm install @onflow/fcl` or `yarn add @onflow/fcl`. +The Flow Dev Wallet is designed to be used with [`@onflow/fcl`] version `1.0.0` or higher. The FCL package can be installed with: `npm install @onflow/fcl` or `yarn add @onflow/fcl`. -To use the dev wallet, configure FCL to point to the address of a locally running [Flow emulator](#start-the-emulator) and the dev wallet endpoint. +To use the dev wallet, configure FCL to point to the address of a locally running [Flow emulator] and the dev wallet endpoint. ```javascript import * as fcl from '@onflow/fcl'; @@ -78,22 +72,21 @@ fcl :::info -For a full example refer to [Authenticate using FCL snippet](https://academy.ecdao.org/en/snippets/fcl-authenticate) +For a full example refer to [Authenticate using FCL snippet] ::: ### Test harness -It's easy to use this FCL harness app as a barebones -app to interact with the dev-wallet during development: +It's easy to use this FCL harness app as a barebones app to interact with the dev-wallet during development: Navigate to http://localhost:8701/harness ### Wallet Discovery -[Wallet Discovery](../clients/fcl-js/discovery.md) offers a convenient modal and mechanism to authenticate users and connects to all wallets available in the Flow ecosystem. +[Wallet Discovery]offers a convenient modal and mechanism to authenticate users and connects to all wallets available in the Flow ecosystem. -The following code from [Emerald Academy](https://academy.ecdao.org/en/snippets/fcl-authenticate) can be added to your React app to enable Wallet Discovery: +The following code from [Emerald Academy] can be added to your React app to turn on Wallet Discovery: ```javascript import { config, authenticate, unauthenticate, currentUser } from '@onflow/fcl'; @@ -158,9 +151,9 @@ export default function App() { } ``` -### Account/Address creation +### Account or Address creation -You can [create a new account](https://cadence-lang.org/docs/language/accounts#account-creation) by using the `&Account` constructor. When you do this, make sure to specify which account will pay for the creation fees by setting it as the payer. +You can [create a new account] with the `&Account` constructor. When you do this, make sure to specify which account will pay for the creation fees. TO do this, set it as the payer. The account you choose to pay these fees must have enough money to cover the cost. If it doesn't, the process will stop and the account won't be created. @@ -183,12 +176,12 @@ transaction(publicKey: String) { To create a new Flow account refer to these resources -- [Create an Account with FCL snippet](https://academy.ecdao.org/en/snippets/fcl-create-account) -- [Create an Account in Cadence snippet](https://academy.ecdao.org/en/snippets/cadence-create-account) +- [Create an Account with FCL snippet] +- [Create an Account in Cadence snippet] -### Get Flow Balance +### Get Flow balance -Retrieving the token balance of a specific account involves writing a script to pull data from onchain. The user may have both locked tokens as well as unlocked so to retrieve the total balance we would aggregate them together. +To retrieve the token balance of a specific account, you must write involves write a script that pulls data from onchain. The user may have both locked tokens as well as unlocked so to retrieve the total balance we would aggregate them together. ```javascript import * as fcl from '@onflow/fcl'; @@ -227,14 +220,32 @@ export const getTotalFlowBalance = async (address) => { }; ``` -## Contributing +## Contribute -Releasing a new version of Dev Wallet is as simple as tagging and creating a release, a Github Action will then build a bundle of the Dev Wallet that can be used in other tools (such as CLI). If the update of the Dev Wallet is required in the CLI, a seperate update PR on the CLI should be created. For more information, please visit the [fcl-dev-wallet GitHub repository](https://github.com/onflow/fcl-dev-wallet). +To release a new version of Dev Wallet is as simple as tagging and creating a release, a Github Action will then build a bundle of the Dev Wallet that can be used in other tools (such as CLI). If the update of the Dev Wallet is required in the CLI, create a seperate update PR on the CLI. For more information, visit the [fcl-dev-wallet GitHub repository]. ## More -Additionally, consider exploring these resources: - -- [Guide to Creating a Fungible Token on Flow](../../../blockchain-development-tutorials/tokens/fungible-token-cadence.md) -- [Tutorial on Fungible Tokens](https://cadence-lang.org/docs/tutorial/fungible-tokens) -- [Faucets](../../../ecosystem/faucets.md) +Additionally, you can explore these resources: + +- [Guide to Creating a Fungible Token on Flow] +- [Tutorial on Fungible Tokens] +- [Faucets] + + + +[FCL]: ../clients/fcl-js/index.md +[Wallets page]: ../../../ecosystem/wallets.md +[flow-cli/install/]: ../flow-cli/install.md +[`@onflow/fcl`]: https://github.com/onflow/fcl-js +[Flow emulator]: #start-the-emulator +[Authenticate using FCL snippet]: https://academy.ecdao.org/en/snippets/fcl-authenticate +[Wallet Discovery]: ../clients/fcl-js/discovery.md +[Emerald Academy]: https://academy.ecdao.org/en/snippets/fcl-authenticate +[create a new account]: https://cadence-lang.org/docs/language/accounts#account-creation +[Create an Account with FCL snippet]: https://academy.ecdao.org/en/snippets/fcl-create-account +[Create an Account in Cadence snippet]: https://academy.ecdao.org/en/snippets/cadence-create-account +[fcl-dev-wallet GitHub repository]: https://github.com/onflow/fcl-dev-wallet +[Guide to Creating a Fungible Token on Flow]: ../../../blockchain-development-tutorials/tokens/fungible-token-cadence.md +[Tutorial on Fungible Tokens]: https://cadence-lang.org/docs/tutorial/fungible-tokens +[Faucets]: ../../../ecosystem/faucets.md \ No newline at end of file diff --git a/docs/build/tools/react-sdk/components.md b/docs/build/tools/react-sdk/components.md index 354870e084..e8ffd6b0c7 100644 --- a/docs/build/tools/react-sdk/components.md +++ b/docs/build/tools/react-sdk/components.md @@ -22,25 +22,25 @@ A drop-in wallet connection component with UI for copy address, logout, and bala **Props:** -- `variant?: ButtonProps["variant"]` – Optional button style variant (default: `"primary"`) -- `onConnect?: () => void` – Callback triggered after successful authentication -- `onDisconnect?: () => void` – Callback triggered after logout +- `variant?: ButtonProps["variant"]` – Optional button style variant (default: `"primary"`). +- `onConnect?: () => void` – Callback triggered after successful authentication. +- `onDisconnect?: () => void` – Callback triggered after logout. - `balanceType?: "cadence" | "evm" | "combined"` – Specifies which balance to display (default: `"cadence"`). Options: - - `"cadence"`: Shows the token balance from the Cadence side - - `"evm"`: Shows the token balance from the Flow EVM side - - `"combined"`: Shows the total combined token balance from both sides + - `"cadence"`: Shows the token balance from the Cadence side. + - `"evm"`: Shows the token balance from the Flow EVM side. + - `"combined"`: Shows the total combined token balance from both sides. - `balanceTokens?: TokenConfig[]` – Optional array of token configurations to display in the balance selector. Each `TokenConfig` requires: - - `symbol: string` – Token symbol (e.g. "FLOW", "USDC") - - `name: string` – Full token name - - Either `vaultIdentifier: string` (for Cadence tokens) or `erc20Address: string` (for EVM tokens) + - `symbol: string` – Token symbol (for example, "FLOW", "USDC") + - `name: string` – Full token name. + - Either `vaultIdentifier: string` (for Cadence tokens) or `erc20Address: string` (for EVM tokens). - `modalConfig?: ConnectModalConfig` – Optional configuration for the profile modal: - - `scheduledTransactions.show?: boolean` – Whether to show the scheduled transactions tab (default: `false`) - - `scheduledTransactions.filterHandlerTypes?: string[]` – Optional array of handler type identifiers to filter displayed transactions -- `modalEnabled?: boolean` – Whether to show the profile modal on click when connected (default: `true`). When `false`, clicking the button when connected will disconnect instead + - `scheduledTransactions.show?: boolean` – Whether to show the scheduled transactions tab (default: `false`). + - `scheduledTransactions.filterHandlerTypes?: string[]` – Optional array of handler type identifiers to filter displayed transactions. +- `modalEnabled?: boolean` – Whether to show the profile modal on click when connected (default: `true`). When `false`, click the button when connected to disconnect. :::note WalletConnect Support -To enable WalletConnect as a wallet option, add your registered project ID to the `walletconnectProjectId` field in your `FlowProvider` config. +To turn on WalletConnect as a wallet option, add your registered project ID to the `walletconnectProjectId` field in your `FlowProvider` config. ::: @@ -66,30 +66,30 @@ import { Connect } from "@onflow/react-sdk" ### `Profile` -A standalone component for displaying wallet information including account address, balance and optional scheduled transactions. +A standalone component used to display wallet information, such as account address, balance and optional scheduled transactions.
**Props:** -- `onDisconnect?: () => void` – Callback triggered when the user clicks the disconnect button +- `onDisconnect?: () => void` – Callback triggered when the user disconnects. - `balanceType?: "cadence" | "evm" | "combined"` – Specifies which balance to display (default: `"cadence"`). Options: - - `"cadence"`: Shows the token balance from the Cadence side - - `"evm"`: Shows the token balance from the Flow EVM side - - `"combined"`: Shows the total combined token balance from both sides + - `"cadence"`: Shows the token balance from the Cadence side. + - `"evm"`: Shows the token balance from the Flow EVM side. + - `"combined"`: Shows the total combined token balance from both sides. - `balanceTokens?: TokenConfig[]` – Optional array of token configurations to display in the balance selector. Each `TokenConfig` requires: - - `symbol: string` – Token symbol (e.g. "FLOW", "USDC") - - `name: string` – Full token name - - Either `vaultIdentifier: string` (for Cadence tokens) or `erc20Address: string` (for EVM tokens) + - `symbol: string` – Token symbol (for example, "FLOW", "USDC"). + - `name: string` – Full token name. + - Either `vaultIdentifier: string` (for Cadence tokens) or `erc20Address: string` (for EVM tokens). - `profileConfig?: ProfileConfig` – Optional configuration for the profile display: - - `scheduledTransactions.show?: boolean` – Whether to show the scheduled transactions tab (default: `false`) - - `scheduledTransactions.filterHandlerTypes?: string[]` – Optional array of handler type identifiers to filter displayed transactions -- `className?: string` – Optional custom CSS class -- `style?: React.CSSProperties` – Optional inline styles + - `scheduledTransactions.show?: boolean` – Whether to show the scheduled transactions tab (default: `false`). + - `scheduledTransactions.filterHandlerTypes?: string[]` – Optional array of handler type identifiers to filter displayed transactions. +- `className?: string` – Optional custom CSS class. +- `style?: React.CSSProperties` – Optional inline styles. :::note WalletConnect Support -To enable WalletConnect as a wallet option, add your registered project ID to the `walletconnectProjectId` field in your `FlowProvider` config. +To turn on WalletConnect as a wallet option, add your registered project ID to the `walletconnectProjectId` field in your `FlowProvider` config. ::: @@ -106,16 +106,16 @@ import { Profile } from "@onflow/react-sdk" ### `TransactionButton` -Button component for executing Flow transactions with built-in loading states and global transaction management. +Button component used to execute Flow transactions with built-in loading states and global transaction management.
**Props:** -- `transaction: Parameters[0]` – Flow transaction object to execute when clicked -- `label?: string` – Optional custom button label (default: `"Execute Transaction"`) -- `mutation?: UseMutationOptions[0]>` – Optional TanStack React Query mutation options -- `...buttonProps` – All other `ButtonProps` except `onClick` and `children` (includes `variant`, `disabled`, `className`, etc.) +- `transaction: Parameters[0]` – Flow transaction object to execute when clicked. +- `label?: string` – Optional custom button label (default: `"Execute Transaction"`). +- `mutation?: UseMutationOptions[0]>` – Optional TanStack React Query mutation options. +- `...buttonProps` – All other `ButtonProps` except `onClick` and `children` (includes `variant`, `disabled`, `className`, and so on). ```tsx import { TransactionButton } from "@onflow/react-sdk" @@ -166,15 +166,15 @@ Dialog component for real-time transaction status updates. **Props:** -- `open: boolean` – Whether the dialog is open -- `onOpenChange: (open: boolean) => void` – Callback to open/close dialog -- `txId?: string` – Optional Flow transaction ID or scheduled transaction ID to track -- `onSuccess?: () => void` – Optional callback when transaction is successful -- `pendingTitle?: string` – Optional custom pending state title -- `pendingDescription?: string` – Optional custom pending state description -- `successTitle?: string` – Optional custom success state title -- `successDescription?: string` – Optional custom success state description -- `closeOnSuccess?: boolean` – If `true`, closes the dialog automatically after success +- `open: boolean` – Whether the dialog is open. +- `onOpenChange: (open: boolean) => void` – Callback to open and close dialog +- `txId?: string` – Optional Flow transaction ID or scheduled transaction ID to track. +- `onSuccess?: () => void` – Optional callback when transaction is successful. +- `pendingTitle?: string` – Optional custom pending state title. +- `pendingDescription?: string` – Optional custom pending state description. +- `successTitle?: string` – Optional custom success state title. +- `successDescription?: string` – Optional custom success state description. +- `closeOnSuccess?: boolean` – If `true`, closes the dialog automatically after success. ```tsx import { TransactionDialog } from "@onflow/react-sdk" @@ -204,8 +204,8 @@ Link to the block explorer with the appropriate network scoped to transaction ID **Props:** -- `txId: string` – The transaction ID or scheduled transaction ID to link to -- `variant?: ButtonProps["variant"]` – Optional button variant (defaults to `"link"`) +- `txId: string` – The transaction ID or scheduled transaction ID to link to. +- `variant?: ButtonProps["variant"]` – Optional button variant (defaults to `"link"`). ```tsx import { TransactionLink } from "@onflow/react-sdk" @@ -226,22 +226,22 @@ import { TransactionLink } from "@onflow/react-sdk" ### `NftCard` -A component for rendering a NFT with image, name, description, collection details, traits and external links. Features include loading states, error handling, dark mode support and optional custom actions. +A component used to render a NFT with image, name, description, collection details, traits and external links. Features include loading states, error handling, dark mode support and optional custom actions.
**Props:** -- `accountAddress: string` – The Flow account address that owns the NFT -- `tokenId: string | number` – The ID of the NFT -- `publicPathIdentifier: string` – The public path identifier for the NFT collection (e.g., "A.0b2a3299cc857e29.TopShot.Collection") -- `showTraits?: boolean` – Whether to display NFT traits/attributes (default: `false`). Shows up to 4 traits with a button to view all -- `showExtra?: boolean` – Whether to display additional information like serial number, rarity, and external links (default: `false`) +- `accountAddress: string` – The Flow account address that owns the NFT. +- `tokenId: string | number` – The ID of the NFT. +- `publicPathIdentifier: string` – The public path identifier for the NFT collection (for example, "A.0b2a3299cc857e29.TopShot.Collection"). +- `showTraits?: boolean` – Whether to display NFT traits or attributes (default: `false`). Shows up to four traits with a button to view all. +- `showExtra?: boolean` – Whether to display additional information like serial number, rarity, and external links (default: `false`). - `actions?: NftCardAction[]` – Optional array of custom action buttons displayed in a dropdown menu. Each action requires: - - `title: string` – Display text for the action - - `onClick: () => Promise | void` – Handler function called when action is clicked -- `className?: string` – Optional custom CSS class -- `style?: React.CSSProperties` – Optional inline styles + - `title: string` – Display text for the action. + - `onClick: () => Promise | void` – Handler function called when action is clicked. +- `className?: string` – Optional custom CSS class. +- `style?: React.CSSProperties` – Optional inline styles. ```tsx import { NftCard } from "@onflow/react-sdk" @@ -273,18 +273,18 @@ import { NftCard } from "@onflow/react-sdk" ### `ScheduledTransactionList` -A component for displaying scheduled transactions for a Flow account. Shows transaction metadata including thumbnails, descriptions, priority, scheduled time, execution effort, fees and provides an optional transaction cancellation functionality. +A component used to display scheduled transactions for a Flow account. Shows transaction metadata such as thumbnails, descriptions, priority, scheduled time, execution effort, fees and provides an optional transaction cancellation functionality.
**Props:** -- `address: string` – The Flow account address to fetch scheduled transactions for -- `filterHandlerTypes?: string[]` – Optional array of handler type identifiers to filter which transactions are displayed. Only transactions with matching `handlerTypeIdentifier` will be shown -- `cancelEnabled?: boolean` – Whether to show the cancel button for transactions (default: `true`) -- `className?: string` – Optional custom CSS class -- `style?: React.CSSProperties` – Optional inline styles -- `flowClient?: UseFlowScheduledTransactionListArgs["flowClient"]` – Optional custom Flow client instance +- `address: string` – The Flow account address to fetch scheduled transactions for. +- `filterHandlerTypes?: string[]` – Optional array of handler type identifiers to filter which transactions are displayed. Only transactions with matching `handlerTypeIdentifier` will be shown. +- `cancelEnabled?: boolean` – Whether to show the cancel button for transactions (default: `true`). +- `className?: string` – Optional custom CSS class. +- `style?: React.CSSProperties` – Optional inline styles. +- `flowClient?: UseFlowScheduledTransactionListArgs["flowClient"]` – Optional custom Flow client instance. ```tsx import { ScheduledTransactionList } from "@onflow/react-sdk" @@ -303,11 +303,11 @@ import { ScheduledTransactionList } from "@onflow/react-sdk" ## Theming -### How Theming Works +### How theming works -All UI components in `@onflow/react-sdk` are styled using [Tailwind CSS](https://tailwindcss.com/) utility classes. The kit supports both light and dark themes out of the box, using Tailwind's `dark:` variant for dark mode styling. +All UI components in `@onflow/react-sdk` are styled with [Tailwind CSS] utility classes. The kit supports both light and dark themes out of the box, and uses Tailwind's `dark:` variant for dark mode styling. -You can customize the look and feel of the kit by providing a custom theme to the `FlowProvider` via the `theme` prop. This allows you to override default colors and styles to better match your app's branding. +To customize the look and feel of the kit, you can provide a custom theme to the `FlowProvider` via the `theme` prop. This allows you to override default colors and styles to better match your app's branding. ```tsx import { FlowProvider } from "@onflow/react-sdk" @@ -331,11 +331,11 @@ import { FlowProvider } from "@onflow/react-sdk" --- -## Dark Mode +## Dark mode -### How Dark Mode Works +### How dark mode works -Dark mode is **fully controlled by the parent app** using the `darkMode` prop on `FlowProvider`. The kit does not manage dark mode state internally—this gives you full control and ensures the kit always matches your app's theme. +Dark mode is **fully controlled by the parent app** with the `darkMode` prop on `FlowProvider`. The kit does not manage dark mode state internally—this gives you full control and ensures the kit always matches your app's theme. - `darkMode={false}` (default): Forces all kit components to use light mode styles. - `darkMode={true}`: Forces all kit components to use dark mode styles. @@ -356,7 +356,7 @@ function App() { } ``` -**Accessing Dark Mode State in Components:** +**Access dark mode in components:** You can use the `useDarkMode` hook to check the current mode inside your components: @@ -372,6 +372,10 @@ function MyComponent() { #### Notes -- The kit does **not** automatically follow system preferences or save user choices. You are responsible for managing and passing the correct `darkMode` value. +- The kit does **not** automatically follow system preferences or save user choices. It's your responsibility to manage and pass the correct `darkMode` value. - All kit components will automatically apply the correct Tailwind `dark:` classes based on the `darkMode` prop. - For best results, ensure your app's global theme and the kit's `darkMode` prop are always in sync. + + + +[Tailwind CSS]: https://tailwindcss.com/ \ No newline at end of file diff --git a/docs/build/tools/react-sdk/hooks.md b/docs/build/tools/react-sdk/hooks.md index 870855f9db..9f10421d8f 100644 --- a/docs/build/tools/react-sdk/hooks.md +++ b/docs/build/tools/react-sdk/hooks.md @@ -10,11 +10,11 @@ import PlaygroundButton from '@site/src/components/PlaygroundButton'; :::info -Many of these hooks are built using [`@tanstack/react-query`](https://tanstack.com/query/latest), which provides powerful caching, revalidation, and background refetching features. As a result, you'll see return types like `UseQueryResult` and `UseMutationResult` throughout this section. Other types—such as `Account`, `Block`, and `CurrentUser`—are from the [Flow Client Library (FCL) TypeDefs](https://github.com/onflow/fcl-js/blob/master/packages/typedefs/src/index.ts). Refer to their respective documentation for full type definitions and usage patterns. +Many of these hooks are built with [`@tanstack/react-query`], which provides powerful caching, revalidation, and background refetch features. As a result, you'll see return types like `UseQueryResult` and `UseMutationResult` throughout this section. Other types—such as `Account`, `Block`, and `CurrentUser`—are from the [Flow Client Library (FCL) TypeDefs]. Refer to the hooks' respective documentation for full type definitions and usage patterns. ::: -## Cadence Hooks +## Cadence hooks ### `useFlowCurrentUser` @@ -26,17 +26,17 @@ import { useFlowCurrentUser } from "@onflow/react-sdk" #### Parameters -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: -- `user: CurrentUser` – The current user object from FCL -- `authenticate: () => Promise` – Triggers wallet authentication -- `unauthenticate: () => void` – Logs the user out +- `user: CurrentUser` – The current user object from FCL. +- `authenticate: () => Promise` – Triggers wallet authentication. +- `unauthenticate: () => void` – Logs the user out. :::note WalletConnect Support -To enable WalletConnect as a wallet option, add your registered project ID to the `walletconnectProjectId` field in your `FlowProvider` config. +To turn on WalletConnect as a wallet option, add your registered project ID to the `walletconnectProjectId` field in your `FlowProvider` config. ::: @@ -71,9 +71,9 @@ import { useFlowAccount } from "@onflow/react-sdk" #### Parameters: -- `address?: string` – Flow address (with or without `0x` prefix) -- `query?: UseQueryOptions` – Optional TanStackQuery options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `address?: string` – Flow address (with or without `0x` prefix). +- `query?: UseQueryOptions` – Optional TanStackQuery options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseQueryResult` @@ -111,11 +111,11 @@ import { useFlowBlock } from "@onflow/react-sdk" #### Parameters: -- `sealed?: boolean` – If `true`, fetch latest sealed block -- `id?: string` – Block by ID -- `height?: number` – Block by height -- `query?: UseQueryOptions` – Optional TanStackQuery options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `sealed?: boolean` – If `true`, fetch latest sealed block. +- `id?: string` – Block by ID. +- `height?: number` – Block by height. +- `query?: UseQueryOptions` – Optional TanStackQuery options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. Only one of `sealed`, `id`, or `height` should be provided. @@ -148,7 +148,7 @@ function LatestBlock() { import { useFlowChainId } from "@onflow/react-sdk" ``` -This hook retrieves the Flow chain ID, which is useful for identifying the current network. +This hook retrieves the Flow chain ID, which is useful to help identify the current network. #### Parameters: @@ -157,7 +157,7 @@ This hook retrieves the Flow chain ID, which is useful for identifying the curre #### Returns: `UseQueryResult` -Valid chain IDs include: `testnet` (Flow Testnet), `mainnet` (Flow Mainnet), and `emulator` (Flow Emulator). The `flow-` prefix will be stripped from the chain ID returned by the access node (e.g. `flow-testnet` will return `testnet`). +Valid chain IDs include: `testnet` (Flow Testnet), `mainnet` (Flow Mainnet), and `emulator` (Flow Emulator). The `flow-` prefix will be stripped from the chain ID returned by the access node (for example, `flow-testnet` will return `testnet`). ```tsx function ChainIdExample() { @@ -182,7 +182,7 @@ This hook returns the `FlowClient` for the current `` context. #### Parameters: -- `flowClient?: FlowClient` - Optional `FlowClient` instance to override the result +- `flowClient?: FlowClient` - Optional `FlowClient` instance to override the result. --- @@ -221,15 +221,15 @@ import { useFlowEvents } from "@onflow/react-sdk" #### Parameters: -- `startBlockId?: string` – Optional ID of the block to start listening from -- `startHeight?: number` – Optional block height to start listening from -- `eventTypes?: string[]` – Array of event type strings (e.g., `A.0xDeaDBeef.Contract.EventName`) -- `addresses?: string[]` – Filter by Flow addresses -- `contracts?: string[]` – Filter by contract identifiers -- `opts?: { heartbeatInterval?: number }` – Options for subscription heartbeat -- `onEvent: (event: Event) => void` – Callback for each event received -- `onError?: (error: Error) => void` – Optional error handler -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `startBlockId?: string` – Optional ID of the block to start listening from. +- `startHeight?: number` – Optional block height to start listening from. +- `eventTypes?: string[]` – Array of event type strings (for example, `A.0xDeaDBeef.Contract.EventName`) +- `addresses?: string[]` – Filter by Flow addresses. +- `contracts?: string[]` – Filter by contract identifiers. +- `opts?: { heartbeatInterval?: number }` – Options for subscription heartbeat. +- `onEvent: (event: Event) => void` – Callback for each event received. +- `onError?: (error: Error) => void` – Optional error handler. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Example: @@ -257,10 +257,10 @@ import { useFlowQuery } from "@onflow/react-sdk" #### Parameters: -- `cadence: string` – Cadence script to run -- `args?: (arg, t) => unknown[]` – Function returning FCL arguments -- `query?: UseQueryOptions` – Optional TanStackQuery options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `cadence: string` – Cadence script to run. +- `args?: (arg, t) => unknown[]` – Function that returns FCL arguments. +- `query?: UseQueryOptions` – Optional TanStackQuery options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseQueryResult` @@ -303,10 +303,10 @@ This hook is identical to `useFlowQuery` but returns the raw, non-decoded respon #### Parameters: -- `cadence: string` – Cadence script to run -- `args?: (arg, t) => unknown[]` – Function returning FCL arguments -- `query?: UseQueryOptions` – Optional TanStackQuery options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `cadence: string` – Cadence script to run. +- `args?: (arg, t) => unknown[]` – Function that returns FCL arguments. +- `query?: UseQueryOptions` – Optional TanStackQuery options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseQueryResult` @@ -349,8 +349,8 @@ import { useFlowMutate } from "@onflow/react-sdk" #### Parameters: -- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseMutationResult` @@ -446,15 +446,13 @@ function RandomValues() { #### Notes: -* Randomness is generated using the **onchain `revertibleRandom`** function on Flow, producing pseudorandom values tied to block and script execution. +* Randomness is generated via the **onchain `revertibleRandom`** function on Flow, and produces pseudorandom values tied to block and script execution. * Values are **deterministic**: The values returned for identical calls within the same block will be identical. * If `count ` is larger than one, the returned values are distinct. * This hook is designed for simple use cases that don't require unpredictability, such as randomized UIs. Since the hook uses script executions on existing blocks, the random source is already public and the randoms are predictable. * For **more advanced use cases** that **do** require onchain randomness logic via transactions, Flow provides built-in support using Cadence's `revertibleRandom` and [commit-reveal scheme]. -[commit-reveal scheme]: ../../cadence/advanced-concepts/randomness#commit-reveal-scheme - --- ### `useFlowTransaction` @@ -470,8 +468,8 @@ Fetches a Flow transaction by ID and returns the decoded transaction object. #### Parameters: * `txId?: string` – The Flow transaction ID or scheduled transaction ID to fetch. -* `query?: Omit, "queryKey" | "queryFn">` – Optional TanStack Query options like `staleTime`, `enabled`, etc. -* `flowClient?: FlowClient` - Optional `FlowClient` instance +* `query?: Omit, "queryKey" | "queryFn">` – Optional TanStack Query options like `staleTime`, `enabled`, and so on. +* `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseQueryResult` @@ -509,8 +507,8 @@ import { useFlowTransactionStatus } from "@onflow/react-sdk" #### Parameters: -- `id: string` – Transaction ID or scheduled transaction ID to subscribe to -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `id: string` – Transaction ID or scheduled transaction ID to subscribe to. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: @@ -538,11 +536,11 @@ function TransactionStatusComponent() { import { useDarkMode } from "@onflow/react-sdk" ``` -This hook provides access to the current dark mode state from the `FlowProvider`. It's useful for conditionally rendering content or applying custom styling based on the current theme. +This hook provides access to the current dark mode state from the `FlowProvider`. It's useful if you want to conditionally render content or apply custom styling based on the current theme. #### Returns: -- `isDark: boolean` – Whether dark mode is currently enabled +- `isDark: boolean` – Whether dark mode is currently turned on. ```tsx function ThemeAwareComponent() { @@ -571,11 +569,11 @@ This hook fetches NFT metadata including display information, traits, rarity, an #### Parameters: -- `accountAddress?: string` – Flow address of the account holding the NFT -- `tokenId?: string | number` – The NFT token ID -- `publicPathIdentifier?: string` – Public path identifier for the collection -- `query?: UseQueryOptions` – Optional TanStack Query options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `accountAddress?: string` – Flow address of the account which holds the NFT. +- `tokenId?: string | number` – The NFT token ID. +- `publicPathIdentifier?: string` – Public path identifier for the collection. +- `query?: UseQueryOptions` – Optional TanStack Query options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseQueryResult` @@ -643,8 +641,8 @@ A React hook that returns an authorization function for Flow transactions. If no #### Parameters: -- `authz?: AuthorizationFunction` – Optional custom authorization function -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `authz?: AuthorizationFunction` – Optional custom authorization function. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. Where `AuthorizationFunction` is defined as: @@ -729,10 +727,10 @@ Fetches a scheduled transaction by ID. #### Parameters: -- `txId?: string` – Scheduled transaction ID +- `txId?: string` – Scheduled transaction ID. - `includeHandlerData?: boolean` – Include handler data (default: false) -- `query?: UseQueryOptions` – Optional TanStack Query options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `query?: UseQueryOptions` – Optional TanStack Query options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseQueryResult` @@ -793,10 +791,10 @@ Lists all scheduled transactions for an account. #### Parameters: -- `account?: string` – Flow address to query -- `includeHandlerData?: boolean` – Include handler data (default: false) -- `query?: UseQueryOptions` – Optional TanStack Query options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `account?: string` – Flow address to query. +- `includeHandlerData?: boolean` – Include handler data (default: false). +- `query?: UseQueryOptions` – Optional TanStack Query options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseQueryResult` @@ -841,8 +839,8 @@ Cancels a scheduled transaction and refunds fees. #### Parameters: -- `mutation?: UseMutationOptions` – Optional TanStack Query mutation options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `mutation?: UseMutationOptions` – Optional TanStack Query mutation options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseFlowScheduledTransactionCancelResult` @@ -961,12 +959,12 @@ function SchedulerSetup() { import { useCrossVmBatchTransaction } from "@onflow/react-sdk" ``` -This hook allows you to execute multiple EVM transactions in a single atomic Cadence transaction. It is useful for batch processing EVM calls while ensuring they are executed together, either all succeeding or allowing for some to fail without affecting the others. +This hook allows you to execute multiple EVM transactions in a single atomic Cadence transaction. It is useful for batch processing EVM calls and ensure they are executed together, either all succeeding or allowing for some to fail without affecting the others. #### Parameters: -- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseCrossVmBatchTransactionResult` @@ -1063,7 +1061,7 @@ Fetch the balance of a token balance for a given user across both Cadence and EV #### Parameters: - `owner: string` – Cadence address of the account whose token balances you want. -- `vaultIdentifier?: string` – Optional Cadence resource identifier (e.g. "0x1cf0e2f2f715450.FlowToken.Vault") for onchain balance +- `vaultIdentifier?: string` – Optional Cadence resource identifier (efor example, "0x1cf0e2f2f715450.FlowToken.Vault") for onchain balance - `erc20AddressHexArg?: string` – Optional bridged ERC-20 contract address (hex) for EVM/COA balance - `query?: Omit, "queryKey" | "queryFn">` – Optional TanStack Query config (e.g. staleTime, enabled) - `flowClient?: FlowClient` - Optional `FlowClient` instance @@ -1197,8 +1195,8 @@ This hook bridges NFTs from Flow EVM to Cadence. It withdraws an NFT from the si #### Parameters: -- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseCrossVmBridgeNftFromEvmTxResult` @@ -1265,8 +1263,8 @@ This hook bridges NFTs from Cadence to Flow EVM and executes arbitrary EVM trans #### Parameters: -- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseCrossVmBridgeNftToEvmTxResult` @@ -1343,8 +1341,8 @@ This hook bridges fungible tokens from Flow EVM to Cadence. It withdraws tokens #### Parameters: -- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseCrossVmBridgeTokenFromEvmResult` @@ -1411,8 +1409,8 @@ This hook bridges fungible tokens from Cadence to Flow EVM and executes arbitrar #### Parameters: -- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options -- `flowClient?: FlowClient` - Optional `FlowClient` instance +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options. +- `flowClient?: FlowClient` - Optional `FlowClient` instance. #### Returns: `UseCrossVmBridgeTokenToEvmResult` @@ -1474,3 +1472,9 @@ function BridgeTokenToEvmExample() { ) } ``` + + + +[`@tanstack/react-query`]: https://tanstack.com/query/latest +[Flow Client Library (FCL) TypeDefs]: https://github.com/onflow/fcl-js/blob/master/packages/typedefs/src/index.ts +[commit-reveal scheme]: ../../cadence/advanced-concepts/randomness#commit-reveal-scheme \ No newline at end of file diff --git a/docs/build/tools/vscode-extension/index.md b/docs/build/tools/vscode-extension/index.md index 6a3fe36d7e..7020809ac0 100644 --- a/docs/build/tools/vscode-extension/index.md +++ b/docs/build/tools/vscode-extension/index.md @@ -3,10 +3,10 @@ title: Cadence VS Code Extension sidebar_position: 4 --- -This extension integrates [Cadence](https://cadence-lang.org/docs), the resource-oriented smart contract programming language of [Flow](https://www.onflow.org/), into [Visual Studio Code](https://code.visualstudio.com/). +This extension integrates [Cadence], the resource-oriented smart contract programming language of [Flow], into [Visual Studio Code]. It provides features like syntax highlighting, type checking, code completion, etc. -Note that most editing features (type checking, code completion, etc.) are implemented in the [Cadence Language Server](https://github.com/onflow/cadence-tools/tree/master/languageserver). +Note that most editing features (type checking, code completion, etc.) are implemented in the [Cadence Language Server]. ## Features @@ -15,22 +15,22 @@ Note that most editing features (type checking, code completion, etc.) are imple ## Installation -To install the extension, ensure you have the [VS Code IDE installed](https://code.visualstudio.com/docs/setup/mac). -Then, you can install the Cadence extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=onflow.cadence). +To install the extension, ensure you have the [VS Code IDE installed]. +Then, you can install the Cadence extension from the [VS Code Marketplace]. -## Developing the Extension +## Develop the extension ### Prerequisites - Must have Typescript installed globally: `npm i -g typescript` -### Getting Started +### Get started - Run the Typescript watcher: `tsc -watch -p ./` -- Launch the extension by pressing `F5` in VSCode -- Manually reload the extension host when you make changes to TypeScript code +- Press `F5` in VSCode to launch the extension. +- Manually reload the extension host when you make changes to TypeScript code. -### Configuration for Extension Host if Missing (`launch.json`): +### Configuration for extension host if missing (`launch.json`): ``` { @@ -49,12 +49,9 @@ Then, you can install the Cadence extension from the [VS Code Marketplace](https ``` -### Building +### Build -If you are building the extension from source, you need to build both the -extension itself and the Flow CLI (if you don't already have a version installed). -Unless you're developing the extension or need access to unreleased features, -you should use the Flow CLI install option (above). It's much easier! +If you build the extension from source, you need to build both the extension itself and the Flow CLI (if you don't already have a version installed). Unless you're developing the extension or need access to unreleased features, use the Flow CLI install option (above). It's much easier! If you haven't already, install dependencies. @@ -68,7 +65,7 @@ Next, build and package the extension. npm run package ``` -This will result in a `.vsix` file containing the packaged extension. +This will result in a `.vsix` file that contains the packaged extension. Install the packaged extension. @@ -76,4 +73,12 @@ Install the packaged extension. code --install-extension cadence-*.vsix ``` -Restart VS Code and the extension should be installed! +Restart VS Code and the extension is installed! + + + +[Flow]: https://www.onflow.org/ +[Visual Studio Code]: https://code.visualstudio.com/ +[Cadence Language Server]: https://github.com/onflow/cadence-tools/tree/master/languageserver +[VS Code IDE installed]: https://code.visualstudio.com/docs/setup/mac +[VS Code Marketplace]: https://marketplace.visualstudio.com/items?itemName=onflow.cadence \ No newline at end of file