diff --git a/docs/build/advanced-concepts/metadata-views.md b/docs/build/advanced-concepts/metadata-views.md index a74b3a9783..a7635e142d 100644 --- a/docs/build/advanced-concepts/metadata-views.md +++ b/docs/build/advanced-concepts/metadata-views.md @@ -19,25 +19,26 @@ sidebar_label: NFT Metadata Views # NFT Metadata Views on Flow -`MetadataViews` on Flow offer a standardized way to represent onchain metadata +`MetadataViews` on Flow offer a standardized way to represent onchain metadata across different NFTs. Through its integration, developers can ensure that different platforms and marketplaces can interpret the NFT metadata in a unified manner. This means that when users visit different websites, -wallets, and marketplaces, +wallets, and marketplaces, the NFT metadata will be presented in a consistent manner, ensuring a uniform experience across various platforms. :::info -It is important to understand this document so you can make meaningful decisions +It is important to understand this document so you can make meaningful decisions about how to manage your project's metadata as support for metadata views does not happen by default. Each project has unique metadata and therefore will have to define how they expose it in unique ways. ::: -A view is a standard Cadence struct that represents a specific type of metadata, +A view is a standard Cadence struct that represents a specific type of metadata, such as a [Royalty specification](https://github.com/onflow/flow-nft?tab=readme-ov-file#royalty-view): + ```cadence access(all) struct Royalty { /// Where royalties should be paid to @@ -52,6 +53,7 @@ access(all) struct Royalty { ``` or a [rarity description](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L614): + ```cadence access(all) struct Rarity { /// The score of the rarity as a number @@ -72,11 +74,11 @@ the content of this document so third party apps can integrate with their smart contracts as easily and effectively as possible. > If you'd like to follow along while we discuss the concepts below, -you can do so by referring to -the [ExampleNFT contract](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc). -Additionally, here is the source code for the -[`ViewResolver` contract](https://github.com/onflow/flow-nft/blob/master/contracts/ViewResolver.cdc) -and the [`MetadataViews` contract](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc). +> you can do so by referring to +> the [ExampleNFT contract](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc). +> Additionally, here is the source code for the +> [`ViewResolver` contract](https://github.com/onflow/flow-nft/blob/master/contracts/ViewResolver.cdc) +> and the [`MetadataViews` contract](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc). Flowty has also provided [a useful guide](https://docs.flowty.io/developer-docs/) for how to manage metadata views properly @@ -89,12 +91,12 @@ regardless of what marketplace it is using. Metadata in Cadence is structured at two distinct levels: 1. **Contract-Level Metadata**: This provides an overarching description -of the entire NFT collection/project. -Any metadata about individual NFTs is not included here. + of the entire NFT collection/project. + Any metadata about individual NFTs is not included here. -2. **NFT-Level Metadata**: Diving deeper, this metadata relates to individual NFTs. -It provides context, describes rarity, and highlights other distinctive attributes -that distinguish one NFT from another within the same collection. +2. **NFT-Level Metadata**: Diving deeper, this metadata relates to individual NFTs. + It provides context, describes rarity, and highlights other distinctive attributes + that distinguish one NFT from another within the same collection. While these distinct levels describe different aspects of a project, they both use the same view system for representing the metadata @@ -105,21 +107,21 @@ just from different places. When considering Flow and how it handles metadata for NFTs, it is crucial to understand two essential interfaces: -`ViewResolver` and `MetadataViews.Resolver`. -[Interfaces](https://cadence-lang.org/docs/language/interfaces) +`ViewResolver` and `MetadataViews.Resolver`. +[Interfaces](https://cadence-lang.org/docs/language/interfaces) serve as blueprints for types that specify the required fields and methods -that your contract or [composite type](https://cadence-lang.org/docs/language/composite-types) must adhere to +that your contract or [composite type](https://cadence-lang.org/docs/language/composite-types) must adhere to to be considered a subtype of that interface. This guarantees that any contract asserting adherence to these interfaces will possess a consistent set of functionalities that other applications or contracts can rely on. 1. **`ViewResolver` for Contract-Level Metadata**: - - This interface ensures that **contracts**, particularly those encapsulating NFT collections, conform to the Metadata Views standard. - - Through the adoption of this interface, contracts can provide dynamic metadata that represents the entirety of the collection. + - This interface ensures that **contracts**, particularly those encapsulating NFT collections, conform to the Metadata Views standard. + - Through the adoption of this interface, contracts can provide dynamic metadata that represents the entirety of the collection. 2. **`MetadataViews.Resolver` (`ViewResolver.Resolver` in Cadence 1.0) for NFT-Level Metadata**: - - Used within **individual NFT resources**, this interface ensures each token adheres to the Metadata standard format. - - It focuses on the distinct attributes of an individual NFT, such as its unique ID, name, description, and other defining characteristics. + - Used within **individual NFT resources**, this interface ensures each token adheres to the Metadata standard format. + - It focuses on the distinct attributes of an individual NFT, such as its unique ID, name, description, and other defining characteristics. ### Core Functions @@ -164,7 +166,6 @@ As you can see, the return values of `getViews()` can be used as arguments for `resolveView()` if you want to just iterate through all the views that an NFT implements. - ## NFT-Level Metadata Implementation NFT-level metadata addresses the unique attributes of individual tokens @@ -200,12 +201,13 @@ access(all) resource NFT: NonFungibleToken.NFT { To make this possible though, it is **vital** that projects all use the standard metadata views in the same way, so third-party -applications can consume them in standard ways. +applications can consume them in standard ways. For example, many metadata views have `String`-typed fields. It is difficult to enforce that these fields are formatted in the correct way, so it is important for projects to be dilligent about how they use them. Take `Traits` for example, a commonly misused metadata view: + ```cadence access(all) struct Trait { // The name of the trait. Like Background, Eyes, Hair, etc. @@ -214,6 +216,7 @@ access(all) struct Trait { ... } ``` + The name of the trait should be formatted in a way so that it is easy to display on a user-facing website. Many projects will use something like CamelCase for the value, so it looks like "HairColor", which is not pretty on a website. @@ -246,13 +249,16 @@ case Type(): ) ) ``` + If the thumbnail is a HTTP resource: -```cadence + +```cadence thumbnail : MetadataViews.HTTPFile(url: *Please put your url here) ``` If the thumbnail is an IPFS resource: -```cadence + +```cadence // thumbnail : MetadataViews.IPFSFile( cid: thumbnail cid, // Type @@ -260,12 +266,13 @@ thumbnail : MetadataViews.IPFSFile( ) ``` -![MetadataViews.Display](display.png "Display") +![MetadataViews.Display](display.png 'Display') :::info Note about SVG files on-chain: SVG field should be sent as `thumbnailURL`, should be base64 encoded, and should have a dataURI prefix, like so: + ``` data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMSIgaGVpZ2h0PSIxIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxyZWN0IHdpZHRoPSIxMDAlIiBoZWlnaHQ9IjEwMCUiIGZpbGw9InJlZCIvPjwvc3ZnPg== ``` @@ -323,6 +330,7 @@ including the percentage of sales revenue that will go to the original creator or other stakeholders on secondary sales. Each royalty view contains a fungible token receiver capability where royalties should be paid: + ```cadence access(all) struct Royalty { @@ -333,6 +341,7 @@ access(all) struct Royalty { ``` here is an example of how an NFT might return a `Royalties` view: + ```cadence case Type(): // Assuming each 'Royalty' in the 'royalties' array has 'cut' and 'description' fields @@ -342,7 +351,7 @@ case Type(): receiver: ExampleNFT.account.capabilities.get<&AnyResource{FungibleToken.Receiver}>(/public/GenericFTReceiver), // The percentage cut of each sale cut: 0.05, - // A description of the royalty terms + // A description of the royalty terms description: "Royalty payment to the original creator" ) } @@ -354,10 +363,11 @@ the marketplace can check to see if the royalty receiver accepts the seller's desired fungible token by calling the `receiver.getSupportedVaultTypes(): {Type: Bool}` function via the `receiver` reference: + ```cadence let royaltyReceiverRef = royalty.receiver.borrow() ?? panic("Could not borrow a reference to the receiver") -let supportedTypes = receiverRef.getSupportedVaultTypes() +let supportedTypes = receiverRef.getSupportedVaultTypes() if supportedTypes[**royalty.getType()**] { // The type is supported, so you can deposit recieverRef.deposit(<-royalty) @@ -382,10 +392,10 @@ to the correct vault in the receiving account. #### Important instructions for royalty receivers If you plan to set your account as a receiver of royalties, -you'll likely want to be able to accept as many token types as possible. +you'll likely want to be able to accept as many token types as possible. This is possible with the `FungibleTokenSwitchboard`. If you initialize a switchboard in your account, it can accept any generic fungible token -and route it to the correct vault in your account. +and route it to the correct vault in your account. Therefore, if you want to receive royalties, you should set up your account with the [`setup_royalty_account_by_paths.cdc`](https://github.com/onflow/flow-ft/blob/master/transactions/switchboard/setup_royalty_account_by_paths.cdc) transaction. @@ -403,13 +413,14 @@ that uses a URL. ```cadence case Type(): - return MetadataViews.ExternalURL("".concat(self.id.toString())) + return MetadataViews.ExternalURL("".concat(self.id.toString())) ``` ### Traits Metadata The [`Trait`](https://github.com/onflow/flow-nft/blob/master/contracts/MetadataViews.cdc#L655) view type encapsulates the unique attributes of an NFT, like any visual aspects or category-defining properties. These can be essential for marketplaces that need to sort or filter NFTs based on these characteristics. By returning trait views as recommended, you can fit the data in the places you want. + ```cadence access(all) struct Trait { // The name of the trait. Like Background, Eyes, Hair, etc. @@ -440,7 +451,7 @@ how to display the trait properly. Developers should not just default to `String` or `Integer` for all their display types. When applicable, the display types to accurately reflect the data that needs to be displayed. -![MetadataViews.Traits](traits_String.png "traits_String") +![MetadataViews.Traits](traits_String.png 'traits_String') #### Note: Always prefer wrappers over single views @@ -476,6 +487,7 @@ at the collection or series level rather than individual NFTs. These views should still should be queryable via individual NFTs though. One can accomplish this by just forwarding the call from the NFT's `resolveView()` method to the contract's `resolveView()` method, like so: + ```cadence /// this line is in `ExampleNFT.NFT.resolveView()` case Type(): @@ -530,7 +542,7 @@ case Type(): return MetadataViews.NFTCollectionDisplay( name: "The Example Collection", description: "This collection is used as an example to help you develop your next Flow NFT.", - externalURL: MetadataViews.ExternalURL(""), + externalURL: MetadataViews.ExternalURL(""), squareImage: media, bannerImage: media, socials: { @@ -544,11 +556,11 @@ like the collection's name and description but also provides image URLs for visual representations of the collection (`squareImage` and `bannerImage`) and external links, including social media profiles. -![MetadataViews.CollectionDisplay](collectionDisplay.png "CollectionDisplay") +![MetadataViews.CollectionDisplay](collectionDisplay.png 'CollectionDisplay') ### Contract-borrowing Metadata -With the contract borrowing feature, the [ViewResolver](https://github.com/onflow/flow-nft/blob/master/contracts/ViewResolver.cdc) +With the contract borrowing feature, the [ViewResolver](https://github.com/onflow/flow-nft/blob/master/contracts/ViewResolver.cdc) interface on contracts can be borrowed directly without needing to import the contract first. Views can be resolved directly from there. As an example, you might want to allow your contract @@ -575,6 +587,7 @@ access(all) fun main(addr: Address, name: String): StoragePath? { ``` Will Return + ```cadence {"domain":"storage","identifier":"exampleNFTCollection"} ``` @@ -586,10 +599,10 @@ is crucial for developers aiming to deploy NFTs on Flow. With these views and functions, NFTs can maintain a consistent presentation across various platforms and marketplaces and foster interoperability between contracts and applications in the Flow ecosystem. -To gain a deeper understanding of implementing the MetadataView standard, +To gain a deeper understanding of implementing the MetadataView standard, check out our documentation on "How to Create an NFT Project on Flow". It provides an introduction to integrating these standards into your NFT contracts. - See the [API reference for a complete list of Metadata functions](https://developers.flow.com/build/core-contracts/flow-nft/MetdataViews/MetadataViews) - Check out [an Example NFT project](https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc) implementing `MetadataViews` -- Read [the NFT Guide](../guides/nft.md) for an introduction to implementation \ No newline at end of file +- Read [the NFT Guide](../guides/nft.md) for an introduction to implementation diff --git a/docs/build/advanced-concepts/scaling.md b/docs/build/advanced-concepts/scaling.md index e672d7a746..7e13cbf930 100644 --- a/docs/build/advanced-concepts/scaling.md +++ b/docs/build/advanced-concepts/scaling.md @@ -22,24 +22,24 @@ Flow is designed for consumer-scale internet applications and is one of the fast 1. **User Transactions** - These are transactions initiated by users, such as: + These are transactions initiated by users, such as: - * Buying or selling NFTs - * Transferring tokens - * Swapping tokens on decentralized exchanges (DEXs) - * Staking or unstaking tokens + - Buying or selling NFTs + - Transferring tokens + - Swapping tokens on decentralized exchanges (DEXs) + - Staking or unstaking tokens - In this category, each transaction originates from a unique account and is sent to the Flow network from a different machine. Developers don't need to take special measures to scale for this category, beyond ensuring their logic is primarily on-chain and their supporting systems (e.g., frontend, backend) can handle scaling if they become bottlenecks. Flow's protocol inherently manages scaling for user transactions. + In this category, each transaction originates from a unique account and is sent to the Flow network from a different machine. Developers don't need to take special measures to scale for this category, beyond ensuring their logic is primarily on-chain and their supporting systems (e.g., frontend, backend) can handle scaling if they become bottlenecks. Flow's protocol inherently manages scaling for user transactions. 2. **System Transactions** - These are transactions initiated by an app's backend or various tools, such as: + These are transactions initiated by an app's backend or various tools, such as: - * Minting thousands of tokens from a single minter account - * Creating transaction workers for custodians - * Running maintenance jobs and batch operations + - Minting thousands of tokens from a single minter account + - Creating transaction workers for custodians + - Running maintenance jobs and batch operations - In this category, many transactions originate from the same account and are sent to the Flow network from the same machine, which can make scaling tricky. This guide focuses on strategies for scaling transactions from a single account. + In this category, many transactions originate from the same account and are sent to the Flow network from the same machine, which can make scaling tricky. This guide focuses on strategies for scaling transactions from a single account. In the following sections, we'll explore how to execute concurrent transactions from a single account on Flow using multiple proposer keys. @@ -56,24 +56,26 @@ Blockchains use sequence numbers, also known as nonces, for each transaction to This behavior presents a challenge for scaling, as sending multiple transactions does not guarantee that they will be executed in the order they were sent. This is a fundamental aspect of Flow's resistance to MEV (Maximal Extractable Value), as transaction ordering is randomized within each block. If a transaction arrives out of order, the network will reject it and return an error message similar to the following: + ``` * checking sequence number failed: [Error Code: 1007] invalid proposal key: public key X on account 123 has sequence number 7, but given 6 ``` + Our objective is to execute multiple concurrent transactions without encountering the sequence number error described above. While designing a solution, we must consider the following key factors: - **Reliability** - Ideally, we want to avoid local sequence number management, as it is error-prone. In a local sequence number implementation, the sender must determine which error types increment the sequence number and which do not. For instance, network issues do not increment the sequence number, but application errors do. Furthermore, if the sender's sequence number becomes unsynchronized with the network, multiple transactions may fail. + Ideally, we want to avoid local sequence number management, as it is error-prone. In a local sequence number implementation, the sender must determine which error types increment the sequence number and which do not. For instance, network issues do not increment the sequence number, but application errors do. Furthermore, if the sender's sequence number becomes unsynchronized with the network, multiple transactions may fail. - The most reliable approach to managing sequence numbers is to query the network for the latest sequence number before signing and sending each transaction. + The most reliable approach to managing sequence numbers is to query the network for the latest sequence number before signing and sending each transaction. - **Scalability** - Allowing multiple workers to manage the same sequence number can introduce coupling and synchronization challenges. To address this, we aim to decouple workers so that they can operate independently without interfering with one another. + Allowing multiple workers to manage the same sequence number can introduce coupling and synchronization challenges. To address this, we aim to decouple workers so that they can operate independently without interfering with one another. - **Capacity Management** - To ensure reliability, the system must recognize when it has reached capacity. Additional transactions should be queued and executed once there is sufficient throughput. Fire-and-forget strategies are unreliable for handling arbitrary traffic, as they do not account for system capacity. + To ensure reliability, the system must recognize when it has reached capacity. Additional transactions should be queued and executed once there is sufficient throughput. Fire-and-forget strategies are unreliable for handling arbitrary traffic, as they do not account for system capacity. ## Solution @@ -83,25 +85,25 @@ We can leverage this model to design an ideal system transaction architecture as - **Multiple Proposer Keys** - Flow accounts can have multiple keys. By assigning a unique proposer key to each worker, each worker can independently manage its own sequence number without interference from others. + Flow accounts can have multiple keys. By assigning a unique proposer key to each worker, each worker can independently manage its own sequence number without interference from others. - **Sequence Number Management** - Each worker ensures it uses the correct sequence number by fetching the latest sequence number from the network. Since workers operate with different proposer keys, there are no conflicts or synchronization issues. + Each worker ensures it uses the correct sequence number by fetching the latest sequence number from the network. Since workers operate with different proposer keys, there are no conflicts or synchronization issues. - **Queue and Processing Workflow** - * Each worker picks a transaction request from the incoming requests queue, signs it with its assigned proposer key, and submits it to the network. - * The worker remains occupied until the transaction is finalized by the network. - * If all workers are busy, the incoming requests queue holds additional requests until there is enough capacity to process them. + - Each worker picks a transaction request from the incoming requests queue, signs it with its assigned proposer key, and submits it to the network. + - The worker remains occupied until the transaction is finalized by the network. + - If all workers are busy, the incoming requests queue holds additional requests until there is enough capacity to process them. - **Key Reuse for Optimization** - To simplify the system further, we can reuse the same cryptographic key multiple times within the same account by adding it as a new key. These additional keys can have a weight of 0 since they do not need to authorize transactions. + To simplify the system further, we can reuse the same cryptographic key multiple times within the same account by adding it as a new key. These additional keys can have a weight of 0 since they do not need to authorize transactions. Here's a visual example of how such an [account configuration](https://www.flowscan.io/account/18eb4ee6b3c026d2?tab=keys) might look: -![Example.Account](scaling-example-account.png "Example Account") +![Example.Account](scaling-example-account.png 'Example Account') As shown, the account includes additional weightless keys designated for proposals, each with its own independent sequence number. This setup ensures that multiple workers can operate concurrently without conflicts or synchronization issues. @@ -142,7 +144,7 @@ We're using Testnet to demonstrate real network conditions. To run this example, flow keys generate ``` -You can use the generated key with the [faucet](https://testnet-faucet.onflow.org/create-account) to create a testnet account. Update the corresponding variables in the `main.go` file: +You can use the generated key with the [faucet](https://faucet.flow.com/fund-account) to create a testnet account. Update the corresponding variables in the `main.go` file: ```go const PRIVATE_KEY = "123" @@ -299,4 +301,4 @@ Final Counter: 420 ✅ Done! 420 transactions executed in 11.695372059s ``` -It takes roughly the time of 1 transaction to run all 420 without any errors. \ No newline at end of file +It takes roughly the time of 1 transaction to run all 420 without any errors. diff --git a/docs/build/basics/fees.md b/docs/build/basics/fees.md index 165fc8ec87..df67b77127 100644 --- a/docs/build/basics/fees.md +++ b/docs/build/basics/fees.md @@ -42,7 +42,6 @@ Fees will improve the overall security of the network by making malicious action The unique Flow architecture is targeted at high throughput. It makes it easier to have slack in the system, so short spikes can be handled more gracefully. - ### **Fee Structure** Each transaction fee consists of three components: execution fee, inclusion fee, and network surge factor. @@ -76,7 +75,7 @@ The inclusion effort of a transaction represents the work needed for: - Transporting the transaction information from node to node - Verifying transaction signatures -Right now, the inclusion effort is always 1.0 and the inclusion effort cost is fixed to `0.000001`. +Right now, the inclusion effort is always 1.0 and the inclusion effort cost is fixed to `0.000001`. **Surge Factor** @@ -92,7 +91,7 @@ Cost estimation is a two-step process. First, you need to gather the execution e Flow's approach to storage capacity is a bit similar to some banks' pricing models, where maintaining a minimum balance prevents monthly account fees. Here, the amount of data in your account determines your minimum balance. If you fall below the minimum balance, you cannot transact with your account, except for deposits or deleting data. The essence of storage fee model is that it ensures data availability without continuously charging fees for storage, while also preventing abuses that could burden the network's storage resources. This distinction between current state and blockchain history is crucial for understanding storage requirements and limitations. -Each Flow account has associated storage used. The account's storage used is the byte size of all the data stored in the account's storage. Accounts also have a storage capacity, which is directly tied to the amount of Flow tokens an account has. The account can, without any additional cost, use any amount of storage up to its storage capacity. +Each Flow account has associated storage used. The account's storage used is the byte size of all the data stored in the account's storage. Accounts also have a storage capacity, which is directly tied to the amount of Flow tokens an account has. The account can, without any additional cost, use any amount of storage up to its storage capacity. :::warning @@ -102,7 +101,7 @@ If a transaction puts an account over storage capacity, that transaction fails a **Storage Capacity** -The storage capacity of an account is dictated by the amount of FLOW it has. +The storage capacity of an account is dictated by the amount of FLOW it has. :::danger @@ -112,11 +111,11 @@ The **minimum amount of FLOW an account can have is 0.001**. This minimum is pro The minimum account reservation ensures that most accounts won't run out of storage capacity if anyone deposits anything (like an NFT) to the account. -Currently, the amount required to store 100 MB in account storage is 1 Flow. +Currently, the amount required to store 100 MB in account storage is 1 Flow. ![Screenshot 2023-08-17 at 17.27.50.png](_fees_images/Screenshot_2023-08-17_at_17.27.50.png) -Please note that storing data in an account on Flow doesn't charge tokens from the account, it just makes sure you will keep the tokens as a reserve. Once the storage is freed up you can transfer the Flow tokens. +Please note that storing data in an account on Flow doesn't charge tokens from the account, it just makes sure you will keep the tokens as a reserve. Once the storage is freed up you can transfer the Flow tokens. ### Storage Capacity of the Payer @@ -140,7 +139,7 @@ Data stored on the Flow blockchain is stored in a key-value ledger. Each item's ### Maximum available balance -Due to the storage restrictions, there is a maximum available balance that user can withdraw from the wallet. The core contract [`FlowStorageFees`](../core-contracts/05-flow-fees.md#flowstoragefees) provides a function to retrieve that value: +Due to the storage restrictions, there is a maximum available balance that user can withdraw from the wallet. The core contract [`FlowStorageFees`](../core-contracts/05-flow-fees.md#flowstoragefees) provides a function to retrieve that value: ```cadence import "FlowStorageFees" @@ -273,7 +272,7 @@ tx := flow.NewTransaction(). ### Maximum transaction fees of a transaction -The maximum possible fee imposed on the payer for a transaction can be calculated as the **inclusion cost plus the execution cost**. The execution cost is the fee calculated for running the transaction based on the [execution effort limit maximum specified](#configuring-execution-limits). +The maximum possible fee imposed on the payer for a transaction can be calculated as the **inclusion cost plus the execution cost**. The execution cost is the fee calculated for running the transaction based on the [execution effort limit maximum specified](#configuring-execution-limits). The payer will never pay more than this amount for the transaction. @@ -400,13 +399,13 @@ There are several places to learn more about transaction fees: - [FLIP-753](https://github.com/onflow/flow/pull/753) - [Flow Fees Contract](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowFees.cdc) -> **Note**: If you have thoughts on the implementation of transaction fees on Flow, you can [leave feedback on this forum post](https://forum.onflow.org/t/variable-transaction-fees-are-coming-to-flow/2941). +> **Note**: If you have thoughts on the implementation of transaction fees on Flow, you can [leave feedback on this forum post](https://forum.flow.com/t/variable-transaction-fees-are-coming-to-flow/2941). ## FAQs **When will the fee update go into effect?** -The updates were rolled out with the [Spork on April 6, 2022](../../networks/node-ops/node-operation/past-upgrades#mainnet-17), and were enabled on [June 1st](https://forum.onflow.org/t/permissionless-contract-deployment-progress/2981) during the [weekly epoch transition](https://github.com/onflow/service-account/tree/main/transactions/set-execution-effort-weights/2022/jun-1). +The updates were rolled out with the [Spork on April 6, 2022](../../networks/node-ops/node-operation/past-upgrades#mainnet-17), and were enabled on [June 1st](https://forum.flow.com/t/permissionless-contract-deployment-progress/2981) during the [weekly epoch transition](https://github.com/onflow/service-account/tree/main/transactions/set-execution-effort-weights/2022/jun-1). **Why are fees collected even when transactions fail?** diff --git a/docs/build/basics/flow-token.md b/docs/build/basics/flow-token.md index 7a99b71542..2d6bf6f8f9 100644 --- a/docs/build/basics/flow-token.md +++ b/docs/build/basics/flow-token.md @@ -78,7 +78,7 @@ If you have already purchased FLOW and wish to hold it, you have a couple of opt - For larger, long term holdings - you may want to use a custody provider to keep your funds safe. -You can find wallets and custodians supporting Flow in the [Flow Port](https://port.onflow.org/) +You can find wallets and custodians supporting Flow in the [Flow Port](https://port.flow.com/) ### Voting with FLOW diff --git a/docs/build/flow.md b/docs/build/flow.md index a0707f86b5..f9c5779192 100644 --- a/docs/build/flow.md +++ b/docs/build/flow.md @@ -24,17 +24,15 @@ keywords: - maximum extractable value --- - # Why Flow +Flow was built by consumer-facing, onchain app developers to solve the problem of building consumer-facing, onchain apps. Dieter Shirley, Chief Architect of Flow and co-author of the [ERC-721 NFT standard] calls it: -Flow was built by consumer-facing, onchain app developers to solve the problem of building consumer-facing, onchain apps. Dieter Shirley, Chief Architect of Flow and co-author of the [ERC-721 NFT standard] calls it: - ->**A computer that anyone can use, everyone can trust, and no one can shut down.** +> **A computer that anyone can use, everyone can trust, and no one can shut down.** 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 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. The blockchain network of the future must be able to handle millions of users while upholding the key pillars of decentralization: +The design of Flow was guided by the need to alleviate this burden while creating the best experience possible for both developers and users. The blockchain network of the future must be able to handle millions of users while upholding the key pillars of decentralization: 1. Verifiability 1. Predictability/Reliability @@ -47,42 +45,42 @@ Flow solves the [blockchain trilemma] and represents the next generation of bloc ## What Makes Flow Unique -Flow is a fast, decentralized, and developer-friendly blockchain designed to be the foundation for a new generation of games, apps, and the [digital assets] that power them. It is based on a unique [multi-role architecture], and designed to [scale without sharding], allowing for massive improvements in speed and throughput while preserving a developer-friendly, ACID-compliant environment. It natively allows development of smart contracts in the powerful [Cadence] language, and also supports full [Ethereum Virtual Machine (EVM)] equivalence with contracts written in Solidity. +Flow is a fast, decentralized, and developer-friendly blockchain designed to be the foundation for a new generation of games, apps, and the [digital assets] that power them. It is based on a unique [multi-role architecture], and designed to [scale without sharding], allowing for massive improvements in speed and throughput while preserving a developer-friendly, ACID-compliant environment. It natively allows development of smart contracts in the powerful [Cadence] language, and also supports full [Ethereum Virtual Machine (EVM)] equivalence with contracts written in Solidity. ### Flow Blockchain - **Multi-role architecture:** The [multi-role architecture] of Flow allows the network to [scale without sharding] to serve billions of users without reducing the decentralization of consensus and verification. -- **True Fast Finality**: For most other networks, it takes minutes, [a day], or even [a week] to reach hard finality - the point in which a transaction cannot be reversed. On Flow, the median time for finality is [under 10 seconds], without compromising security. -- **Native VRF**: Flow provides [onchain randomness] at the protocol level. Instead of implementing a complex setup and [paying $10+ USD per number], simply call the built-in function. -- **MEV Resistance**: Flow is designed to [ensure equitable access] by resisting MEV. Maximum Extractable Value, also know as Miner-Extractable Value (MEV), is a practice common in other blockchains in which the builder of a block can profit at your expense by manipulating where and how your transaction is included. +- **True Fast Finality**: For most other networks, it takes minutes, [a day], or even [a week] to reach hard finality - the point in which a transaction cannot be reversed. On Flow, the median time for finality is [under 10 seconds], without compromising security. +- **Native VRF**: Flow provides [onchain randomness] at the protocol level. Instead of implementing a complex setup and [paying $10+ USD per number], simply call the built-in function. +- **MEV Resistance**: Flow is designed to [ensure equitable access] by resisting MEV. Maximum Extractable Value, also know as Miner-Extractable Value (MEV), is a practice common in other blockchains in which the builder of a block can profit at your expense by manipulating where and how your transaction is included. - **Consumer Onboarding:** Flow was designed for mainstream consumers, with payment onramps catalyzing a safe and low-friction path from fiat to crypto. -- **EVM Equivalence**: The [Cadence] Virtual Machine (VM) is powerful enough to allow other VMs to run inside of it, almost like a Docker Container. The first one integrated in this way is [EVM] and the EVM RPC API. -- **Efficient Gas Costs**: The Flow blockchain is extremely efficient, allowing apps to do more computation at lower costs. +- **EVM Equivalence**: The [Cadence] Virtual Machine (VM) is powerful enough to allow other VMs to run inside of it, almost like a Docker Container. The first one integrated in this way is [EVM] and the EVM RPC API. +- **Efficient Gas Costs**: The Flow blockchain is extremely efficient, allowing apps to do more computation at lower costs. ### Flow Cadence -- **Native Account Abstraction**: Flow has protocol-native [account abstraction]. All accounts are smart accounts, supporting scripting, multiple keys, multi-signature transactions, and walletless onboarding with social logins. -- **Gasless Transactions**: Flow has multiple [signing roles] for each transaction. Most notably, the payer can be set independently of the authorizer. In other words, having one account sign a transaction and another pay for that transaction is a built-in feature. -- **Security:** Smart contracts on Flow are natively written in [Cadence], an easier, safer, and more secure programming language for crypto assets and apps. It's the first high-level, [resource-oriented] programming language. +- **Native Account Abstraction**: Flow has protocol-native [account abstraction]. All accounts are smart accounts, supporting scripting, multiple keys, multi-signature transactions, and walletless onboarding with social logins. +- **Gasless Transactions**: Flow has multiple [signing roles] for each transaction. Most notably, the payer can be set independently of the authorizer. In other words, having one account sign a transaction and another pay for that transaction is a built-in feature. +- **Security:** Smart contracts on Flow are natively written in [Cadence], an easier, safer, and more secure programming language for crypto assets and apps. It's the first high-level, [resource-oriented] programming language. - **Developer Ergonomics:** The Flow network is designed to maximize developer productivity. Examples range from upgradeable smart contracts to built-in logging support to the Flow Emulator. ### Flow EVM -- **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]. 😳 +- **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**: 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. -- **EVM Equivalence:** Flow EVM is truly _EVM Equivalent_, not just _EVM Compatible_. It runs exactly the same as EVM mainnet, which means builders won't run into "minor" variances or endless "quirks" when they try to integrate. If it works on Ethereum Mainnet, it will work with Flow EVM. +- **Access to Cadence**: 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. +- **EVM Equivalence:** Flow EVM is truly _EVM Equivalent_, not just _EVM Compatible_. It runs exactly the same as EVM mainnet, which means builders won't run into "minor" variances or endless "quirks" when they try to integrate. If it works on Ethereum Mainnet, it will work with Flow EVM. ## Learning Shortcuts -To get a complete picture on how to build on Flow, follow the 👈 sidebar top to bottom. This path will give you the most thorough onboarding experience. +To get a complete picture on how to build on Flow, follow the 👈 sidebar top to bottom. This path will give you the most thorough onboarding experience. If you like to jump right into the deep end of the pool, take a look below for direct links to advanced topics! ### 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. 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! :::tip @@ -115,7 +113,6 @@ The Flow blockchain implements core functionality using its own smart contract l - **Staking Table:** The FlowIDTableStaking contract is the central table that manages staked nodes, delegation, and rewards. - **Epoch Contract:** The FlowEpoch contract is the state machine that manages Epoch phases and emits service events. - ### FLOW Token The [FLOW] (or $FLOW) token is the native currency for the Flow network. Developers and users can use FLOW to transact on the network. Developers can integrate FLOW directly into their apps for peer-to-peer payments, service charges, or consumer rewards. FLOW can be held, transferred, or transacted peer-to-peer. @@ -128,7 +125,6 @@ The [FLOW] (or $FLOW) token is the native currency for the Flow network. Develop - The [Flow Technical Primer] is a great place to start to understand how Flow works. - The [Three technical whitepapers] cover the unique innovation behind the Flow blockchain network in-depth. - [ERC-721 NFT standard]: https://github.com/ethereum/eips/issues/721 @@ -140,13 +136,13 @@ The [FLOW] (or $FLOW) token is the native currency for the Flow network. Develop [NFL All Day]: https://nflallday.com/ [Mattel Creations]: https://creations.mattel.com/pages/virtual [Disney Pinnacle]: https://disneypinnacle.com/ -[digital assets]: https://www.onflow.org/post/flow-blockchain-cadence-programming-language-resources-assets +[digital assets]: https://www.flow.com/post/flow-blockchain-cadence-programming-language-resources-assets [widespread popularity]: https://www.cnn.com/style/article/cryptokitty-blockchain/index.html -[multi-role architecture]: https://www.onflow.org/primer +[multi-role architecture]: https://www.flow.com/primer [onchain randomness]: ./advanced-concepts/randomness.md [paying $10+ USD per number]: https://docs.chain.link/vrf/v2-5/billing [ensure equitable access]: ./basics/mev-resistance.md -[scale without sharding]: https://www.onflow.org/post/flow-blockchain-multi-node-architecture-advantages +[scale without sharding]: https://www.flow.com/post/flow-blockchain-multi-node-architecture-advantages [a day]: https://docs.zksync.io/zk-stack/concepts/finality#finality-on-zksync-era [a week]: https://docs.optimism.io/stack/rollup/overview#fault-proofs [usually way less!]: https://evm.flowscan.io/stats @@ -163,9 +159,7 @@ The [FLOW] (or $FLOW) token is the native currency for the Flow network. Develop [Getting Started]: ./getting-started/contract-interaction.md [core contracts]: ./core-contracts/index.md [FLOW]: ./core-contracts/03-flow-token.md -[Flow Technical Primer]: https://www.onflow.org/primer -[Three technical whitepapers]: https://www.onflow.org/technical-paper -[Flow Token Economics]: https://www.onflow.org/flow-token-economics +[Flow Technical Primer]: https://www.flow.com/primer +[Three technical whitepapers]: https://www.flow.com/technical-paper +[Flow Token Economics]: https://www.flow.com/flow-token-economics [VRF]: ../evm/guides/vrf.md - - diff --git a/docs/build/guides/account-linking/index.md b/docs/build/guides/account-linking/index.md index 7807bdd38a..9493bc1024 100644 --- a/docs/build/guides/account-linking/index.md +++ b/docs/build/guides/account-linking/index.md @@ -82,7 +82,7 @@ A link between two existing accounts on Flow can be created in two steps: These two steps are implemented in Cadence as two transactions: -************************************Create capability************************************ +****************\*\*\*\*****************Create capability****************\*\*\*\***************** The account B creates and publishes the `&Account` Capability to the account A at the address `0x01` @@ -101,7 +101,7 @@ transaction { } ``` -****************************Claim capability**************************** +************\*\*\*\*************Claim capability************\*\*\*\************* The account A claims the Capability published by account B. @@ -131,7 +131,7 @@ transaction { Account linking was specifically designed to enable smooth and seamless custodial onboarding of users to your Flow based application without them first requiring a wallet to do so. This pattern overcomes both the technical hurdle, as well as user's reluctance to install a wallet, opening access to Flow applications to every user. Users can experience an app -without any delay while still offering a path to self-sovreign ownership. +without any delay while still offering a path to self-sovreign ownership. Naturally, users may expect to use their account with another application, or otherwise move assets stored in that account elsewhere - at minimum from their wallet. When an app initially leverages account linking, the app creates the @@ -202,7 +202,7 @@ Learn more about it in the [Hybrid Custody documentation](./parent-accounts.md). ### Resources -- [Forum Post](https://forum.onflow.org/t/hybrid-custody/4016) where core concepts were introduced and discussed. +- [Forum Post](https://forum.flow.com/t/hybrid-custody/4016) where core concepts were introduced and discussed. - [GitHub repository](https://github.com/onflow/hybrid-custody) where `HybridCustody` core contracts and scripts are maintained. Check out the repository for more advanced script or transaction examples. - [Example](https://github.com/jribbink/magic-link-hc-sample/) Account Linking project with diff --git a/docs/build/guides/account-linking/parent-accounts.md b/docs/build/guides/account-linking/parent-accounts.md index 1a9f91c44d..4313493f4a 100644 --- a/docs/build/guides/account-linking/parent-accounts.md +++ b/docs/build/guides/account-linking/parent-accounts.md @@ -47,7 +47,7 @@ The basic idea in the Hybrid Custody model is relatively simple. A parent accoun (albeit restricted) access on another account. The account which has delegated authority over itself to the parent account is the child account. -In the [Hybrid Custody Model](https://forum.onflow.org/t/hybrid-custody/4016), this child account would have shared +In the [Hybrid Custody Model](https://forum.flow.com/t/hybrid-custody/4016), this child account would have shared access between the app - the entity which created and likely custodies the account - and the linked parent account. How does this delegation occur? Typically when we think of shared account access in crypto, we think keys. However, @@ -128,7 +128,6 @@ are simply `OwnedAccount` Capabilities instead of `ChildAccount` Capabilities. ![HybridCustody Total Overview](./resources/hybrid_custody_low_level.png) - ### Considerations Do note that this construction does not prevent an account from having multiple parent accounts or a child account from @@ -215,7 +214,7 @@ import "HybridCustody" /// access(all) fun getViews(_ address: Address, _ resolverCollectionPath: PublicPath): {UInt64: MetadataViews.Display} { - + let account: PublicAccount = getAccount(address) let views: {UInt64: MetadataViews.Display} = {} @@ -243,14 +242,14 @@ fun main(address: Address, resolverCollectionPath: PublicPath): {Address: {UInt6 let allViews: {Address: {UInt64: MetadataViews.Display}} = { address: getViews(address, resolverCollectionPath) } - - /* Iterate over any associated accounts */ + + /* Iterate over any associated accounts */ // let seen: [Address] = [address] if let managerRef = getAuthAccount(address) .storage .borrow<&HybridCustody.Manager>(from: HybridCustody.ManagerStoragePath) { - + for childAccount in managerRef.getChildAddresses() { allViews.insert(key: childAccount, getViews(address, resolverCollectionPath)) seen.append(childAccount) @@ -264,7 +263,7 @@ fun main(address: Address, resolverCollectionPath: PublicPath): {Address: {UInt6 } } - return allViews + return allViews } ``` @@ -332,7 +331,7 @@ fun main(address: Address): {Address: {Type: UFix64}} { if let managerRef = getAuthAccount(address) .storage .borrow<&HybridCustody.Manager>(from: HybridCustody.ManagerStoragePath) { - + for childAccount in managerRef.getChildAddresses() { balances.insert(key: childAccount, getAllBalancesInStorage(address)) seen.append(childAccount) @@ -346,7 +345,7 @@ fun main(address: Address): {Address: {Type: UFix64}} { } } - return balances + return balances } ``` @@ -418,8 +417,8 @@ transaction( // ... } } - - + + ``` diff --git a/docs/build/guides/mobile/react-native-quickstart.md b/docs/build/guides/mobile/react-native-quickstart.md index 5dea632f73..b3334dca51 100644 --- a/docs/build/guides/mobile/react-native-quickstart.md +++ b/docs/build/guides/mobile/react-native-quickstart.md @@ -74,14 +74,16 @@ Now that your app is running, you can configure FCL. Within the main project dir > **Create file:** `./flow/config.js` ```javascript ./flow/config.js -import { config } from "@onflow/fcl"; +import { config } from '@onflow/fcl'; config({ - "accessNode.api": "https://rest-testnet.onflow.org", // Mainnet: "https://rest-mainnet.onflow.org" - "discovery.wallet": "https://fcl-discovery.onflow.org/testnet/authn", // Mainnet: "https://fcl-discovery.onflow.org/authn" - "discovery.authn.endpoint": "https://fcl-discovery.onflow.org/api/testnet/authn", // Mainnet: "https://fcl-discovery.onflow.org/api/authn" -}) + 'accessNode.api': 'https://rest-testnet.onflow.org', // Mainnet: "https://rest-mainnet.onflow.org" + 'discovery.wallet': 'https://fcl-discovery.onflow.org/testnet/authn', // Mainnet: "https://fcl-discovery.onflow.org/authn" + 'discovery.authn.endpoint': + 'https://fcl-discovery.onflow.org/api/testnet/authn', // Mainnet: "https://fcl-discovery.onflow.org/api/authn" +}); ``` + 📣 **Tip**: It's recommend to replace these values with environment variables for easy deployments across different environments like development/production or Testnet/Mainnet. - The `accessNode.api` key specifies the address of a Flow access node. Flow provides these, but in the future access to Flow may be provided by other 3rd parties, through their own access nodes. @@ -111,7 +113,7 @@ The main screen for React Native apps is located in `./App.js` or in `./App.tsx` ```jsx ./App.js import { StatusBar } from 'expo-status-bar'; import { StyleSheet, Text, View } from 'react-native'; -import "./flow/config"; +import './flow/config'; export default function App() { return ( @@ -130,8 +132,6 @@ const styles = StyleSheet.create({ justifyContent: 'center', }, }); - - ``` Now we're ready to start talking to Flow! @@ -140,7 +140,7 @@ Now we're ready to start talking to Flow! To authenticate a user, you'll need to render a `ServiceDiscovery` component provided by `fcl-react-native`. Alternatively you can build your own component using `useServiceDiscovery`. -Unauthenticate is as simple as calling `fcl.unauthenticate()`. Once authenticated, FCL sets an object called `fcl.currentUser` which exposes methods for watching changes in user data, signing transactions, and more. For more information on the `currentUser`, read more [here](../../../tools/clients/fcl-js/api.md#current-user). +Unauthenticate is as simple as calling `fcl.unauthenticate()`. Once authenticated, FCL sets an object called `fcl.currentUser` which exposes methods for watching changes in user data, signing transactions, and more. For more information on the `currentUser`, read more [here](../../../tools/clients/fcl-js/api.md#current-user). Let's add in a few components and buttons buttons for sign up/login and also subscribe to changes on the `currentUser`. When the user is updated (which it will be after authentication), we'll set the user state in our component to reflect this. To demonstrate user authenticated sessions, we'll conditionally render a component based on if the user is or is not logged in. @@ -150,37 +150,36 @@ This is what your file should look like now: ```jsx ./App.js import { Text, View, Button } from 'react-native'; -import "./flow/config"; +import './flow/config'; -import { useState, useEffect } from "react"; -import * as fcl from "@onflow/fcl/dist/fcl-react-native"; +import { useState, useEffect } from 'react'; +import * as fcl from '@onflow/fcl/dist/fcl-react-native'; export default function App() { + const [user, setUser] = useState({ loggedIn: null }); - const [user, setUser] = useState({loggedIn: null}) - - useEffect(() => fcl.currentUser.subscribe(setUser), []) + useEffect(() => fcl.currentUser.subscribe(setUser), []); const AuthedState = () => { return ( - Address: {user?.addr ?? "No Address"} -