diff --git a/docs/build/advanced-concepts/account-linking/index.mdx b/docs/build/advanced-concepts/account-linking/index.md similarity index 90% rename from docs/build/advanced-concepts/account-linking/index.mdx rename to docs/build/advanced-concepts/account-linking/index.md index 8796bdfbe3..6c26e4f857 100644 --- a/docs/build/advanced-concepts/account-linking/index.mdx +++ b/docs/build/advanced-concepts/account-linking/index.md @@ -5,9 +5,9 @@ sidebar_position: 4 # Account Linking -Account linking is a unique Flow concept that enables sharing ownership over accounts. In order to understand how we can achieve that we must first understand how accounts on Flow are accessed. +Account linking is a unique Flow concept that enables sharing ownership over [accounts](../../basics/accounts.md). In order to understand how we can achieve that we must first understand how accounts on Flow are accessed. -Accounts on flow can be accessed in Cadence through two types, `PublicAccount` and `AuthAccount`. As the name implies the `PublicAccount` type gives access to all public account information such as address, balance, storage capacity, etc., but doesn’t allow changes to the account. The `AuthAccount` type allows the same access as `PublicAccount` but also allows changing the account, including adding/revoking account keys, managing the deployed contracts, as well as linking and publishing Capabilities. +Accounts on flow can be accessed in Cadence through two types, `PublicAccount` and `AuthAccount`. As the name implies the `PublicAccount` type gives access to all public account information such as address, balance, storage capacity, etc., but doesn't allow changes to the account. The `AuthAccount` type allows the same access as `PublicAccount` but also allows changing the account, including adding/revoking account keys, managing the deployed contracts, as well as linking and publishing Capabilities. ![Flow account structure](resources/account.png) @@ -15,7 +15,7 @@ Accounts on flow can be accessed in Cadence through two types, `PublicAccount` a Accessing the auth account allows for account modification, so it's essential to safeguard this access by mandating that transactions are signed by the account being accessed. A transaction can list multiple auth accounts it wants to access as part of the `pre` section of the transaction. Read more about transaction signing in the transaction documentation. -Since access to the `AuthAccount` object enables state change, the idea of account ownership actually translates to the ability to access the auth account. Traditionally, you might consider this the same as having key access on an account, but we'll see in just a minute how programmatic, ownership-level access is unlocked with Capabilities on Flow. +Since access to the `AuthAccount` object enables state change, the idea of account ownership actually translates to the ability to access the auth account. Traditionally, you might consider this the same as having key access on an account, but we'll see in just a minute how programmatic, ownership-level access is unlocked with [Capabilities on Flow](../../../cadence/language/capabilities.md). ## AuthAccount Capabilities @@ -72,7 +72,7 @@ transaction { Account linking was specifically designed to enable smooth and seamless 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, and opens access to apps on Flow to every user. Users can experience an app 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. When an app initially leverages account linking it creates the account instead of the user and is where that user's specific state is stored. At a later point, users can take ownership of the app account providing they possess a full Flow account, typically by installing a wallet app. +Naturally, users may expect to use their account with another application, or otherwise move assets stored in that account elsewhere. When an app initially leverages account linking it creates the account instead of the user and is where that user's specific state is stored. At a later point, users can take ownership of the app account providing they possess a full [Flow account](../../basics/accounts.md), typically by installing a wallet app. Account linking enables users to possess multiple linked child accounts from different apps. Complexities associated with accessing those child accounts are eliminated by abstracting access to them through the user's parent account. Simply put, child accounts are accessed and treated as a seamless part of the parent account. @@ -90,12 +90,12 @@ Account linking is a _very_ powerful Cadence feature, and thus it must be treate Creating an `AuthAccount` capability and publishing it to an account we don’t own means we are giving that account full access to our account. This should be seen as an anti-pattern. - + -Because pure account linking can be dangerous, Flow introduces the `HybridCustody` contract that helps custodial applications regulate access and parent account manage their many child accounts. +Because pure account linking can be dangerous, Flow introduces the [`HybridCustody` contract](./parent-accounts.md) that helps custodial applications regulate access and parent account manage their many child accounts. ## Hybrid Custody and Account Linking @@ -104,7 +104,7 @@ Apps need assurances that their own resources are safe from malicious actors, so 1. Share capabilities freely, with a few built-in controls over the types of capabilities that can be retrieved by parent accounts via helper contracts (the `CapabilityFactory`, and `CapabilityFilter`) 2. Share additional capabilities (public or private) with a parent account via a `CapabilityDelegator` resource -Learn more about it in the Hybrid Custody documentation. +Learn more about it in the [Hybrid Custody documentation](./parent-accounts.md). ### Guides[](https://developers.flow.com/concepts/account-linking#guides) diff --git a/docs/build/advanced-concepts/account-linking/parent-accounts.mdx b/docs/build/advanced-concepts/account-linking/parent-accounts.md similarity index 99% rename from docs/build/advanced-concepts/account-linking/parent-accounts.mdx rename to docs/build/advanced-concepts/account-linking/parent-accounts.md index 42d32290e4..2cca27577d 100644 --- a/docs/build/advanced-concepts/account-linking/parent-accounts.mdx +++ b/docs/build/advanced-concepts/account-linking/parent-accounts.md @@ -419,4 +419,4 @@ After removal, the signer no longer has delegated access to the removed account removed as a parent of the removed child. Note also that it's possible for a child account to remove a parent. This is necessary to give application developers -and ultimately the owners of these child accounts the ability to revoke secondary access on owned accounts. \ No newline at end of file +and ultimately the owners of these child accounts the ability to revoke secondary access on owned accounts. diff --git a/docs/build/basics/accounts.md b/docs/build/basics/accounts.md index 2368170ec0..2c7cb68f78 100644 --- a/docs/build/basics/accounts.md +++ b/docs/build/basics/accounts.md @@ -10,7 +10,7 @@ An account on Flow is a record in the chain state that holds the following infor - Code: Cadence contracts deployed to the account - Storage: area of the account used to store resource assets. -Accounts and their keys are needed to sign transactions that change the Flow blockchain state. To execute a transaction, a small amount of Flow, called a “Fee” must be paid by the account or subsidized by a wallet or service. Flow allocates a fixed amount of storage to each account for saving data structures and Resources. Flow allocates a fixed amount of storage to each account for saving data structures and Resources. +Accounts and their keys are needed to sign transactions that change the Flow blockchain state. To execute a transaction, a small amount of Flow, called a [“Fee”](./fees.md) must be paid by the account or subsidized by a wallet or service. Flow allocates a fixed amount of storage to each account for saving data structures and Resources. Flow allocates a [fixed amount of storage](./fees.md#storage) to each account for saving data structures and Resources. An account may also contain contract code which transactions and scripts can interact with to query or mutate the state of the blockchain. A simple representation of an account: @@ -25,22 +25,21 @@ This decoupling is a unique advantage of Flow, allowing for multiple public keys **Balance** -Each Flow account created on Mainnet will by default [hold a Flow vault that holds a balance and is part of the FungibleToken standard](./flow-token). This balance is used to pay for transaction fees and storage fees. More on that in the fees document. +Each Flow account created on Mainnet will by default [hold a Flow vault that holds a balance and is part of the FungibleToken standard](./flow-token). This balance is used to pay for [transaction fees and storage fees](./fees.md). More on that in the fees document. The minimum amount of FLOW an account can have is **0.001**. - This minimum storage fee is provided by the account creator and covers the cost of storing up to 100kB of data in perpetuity. This fee is applied only once and can be "topped up" to add additional storage to an account. 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. **Contracts** -An account can optionally store multiple Cadence contracts. The code is stored as a human-readable UTF-8 encoded string which makes it easy for anyone to inspect the contents. +An account can optionally store multiple [Cadence contracts](../../cadence/language/contracts.mdx). The code is stored as a human-readable UTF-8 encoded string which makes it easy for anyone to inspect the contents. **Storage** -Each Flow account has an associated storage and capacity. The account's storage used is the byte size of all the data stored in the account's storage. An account's storage capacity is directly tied to the balance of Flow tokens an account has. An account can, without any additional cost, use any amount of storage up to its storage capacity. If a transaction puts an account over storage capacity or drops an account's balance below the minimum 0.001 Flow tokens, that transaction fails and is reverted. +Each Flow account has an associated storage and capacity. The account's storage used is the byte size of all the data stored in the account's storage. An account's [storage capacity is directly tied to the balance of Flow tokens](./fees.md#storage) an account has. An account can, without any additional cost, use any amount of storage up to its storage capacity. If a transaction puts an account over storage capacity or drops an account's balance below the minimum 0.001 Flow tokens, that transaction fails and is reverted. ## Account **Keys** @@ -51,15 +50,14 @@ During account creation, public keys can be provided which will be used when int Each account key has a weight that determines the signing power it holds. -A transaction is not authorized to access an account unless it has a total signature weight greater than or equal to **1000**, the weight threshold. - +A transaction is not authorized to access an account unless it has a total signature weight greater than or equal to **1000**, the weight threshold. For example, an account might contain 3 keys, each with 500 weight: ![Screenshot 2023-08-16 at 16.28.58.png](_accounts_images/Screenshot_2023-08-16_at_16.28.58.png) -This represents a 2-of-3 multi-sig quorum, in which a transaction is authorized to access the account if it receives signatures from *at least* 2 out of 3 keys. +This represents a 2-of-3 multi-sig quorum, in which a transaction is authorized to access the account if it receives signatures from *at least* 2 out of 3 keys. An account key contains the following attributes: diff --git a/docs/build/basics/blocks.md b/docs/build/basics/blocks.md index 0ab42e71c7..34a76fad12 100644 --- a/docs/build/basics/blocks.md +++ b/docs/build/basics/blocks.md @@ -6,7 +6,7 @@ sidebar_position: 1 ## Overview -Blocks are entities that make up the Flow blockchain. Each block contains a list of transactions that were executed and as a result, changed the global blockchain state. Each block is identified by a unique ID which is a cryptographic hash of the block contents. Block also includes a link to the parent block ID creating a linked list of blocks called the Flow blockchain. +Blocks are entities that make up the Flow blockchain. Each block contains a list of [transactions](./transactions.md) that were executed and as a result, changed the global blockchain state. Each block is identified by a unique ID which is a cryptographic hash of the block contents. Block also includes a link to the parent block ID creating a linked list of blocks called the Flow blockchain. The unique block ID serves as proof of the block contents which can be independently validated by any observer. Interesting cryptographic properties of the hash that make up the block ID guarantee that if any change is made to the block data it would produce a different hash and because blocks are linked, a different hash would break the link as it would no longer be referenced in the next block. @@ -34,14 +34,14 @@ The Block header contains the following fields: The block payload contains the following fields: -- **Collection Guarantees** is a list of collection IDs with the signatures from the collection nodes that produced the collections. This acts as a guarantee by collection nodes that transaction data in the collection will be available on the collection node if requested by other nodes at a later time. Flow purposely skips including transaction data in a block, making blocks as small as possible, and the production of new blocks by consensus nodes fast, that is because consensus nodes have to sync the proposed block between nodes, and that data should be the smallest possible. The consensus nodes don’t really care what will a transaction do as long as it’s valid, they only need to define an order of those transactions in a block. +- **Collection Guarantees** is a list of collection IDs with the signatures from the collection nodes that produced the collections. This acts as a guarantee by collection nodes that [transaction data](./transactions.md) in the collection will be available on the collection node if requested by other nodes at a later time. Flow purposely skips including transaction data in a block, making blocks as small as possible, and the production of new blocks by consensus nodes fast, that is because consensus nodes have to sync the proposed block between nodes, and that data should be the smallest possible. The consensus nodes don’t really care what will a transaction do as long as it’s valid, they only need to define an order of those transactions in a block. - **Block Seals** is the attestation by verification nodes that the transactions in a previously executed block have been verified. This seals a previous block referenced by the block ID. It also references the result ID and execution root hash. It contains signatures of the verification nodes that produced the seal. ## Lifecycle and Status Block status is not a value stored inside the block itself but it represents the lifecycle of a block. We derive this value based on the block inclusion in the Flow blockchain and present it to the user as it acts as an important indicator of the finality of the changes the block contains. -Here we’ll give an overview of the different phases a block goes through. More details can be found in the whitepaper. Also, a lot of the block states are not necessarily important to the developer but only important to the functioning of the Flow blockchain. +Here we’ll give an overview of the different phases a block goes through. [More details can be found in the whitepaper](https://flow.com/technical-paper). Also, a lot of the block states are not necessarily important to the developer but only important to the functioning of the Flow blockchain. New blocks are constantly being proposed even if no new transactions are submitted to the network. Consensus nodes are in charge of producing blocks. They use a consensus algorithm (an implementation of HotStuff) to agree on what the new block will be. A block contains the ordered list of collections and each collection contains an ordered list of transactions. This is an important fact to reiterate. A block serves as a list of transitions to the Flow state machine. It documents, as an ordered list, all the changes transactions will make to the state. diff --git a/docs/build/basics/collections.md b/docs/build/basics/collections.md index 987a848e91..6d32f09aa0 100644 --- a/docs/build/basics/collections.md +++ b/docs/build/basics/collections.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Collections -Collections link blocks and transactions together. Collection node clusters make these collections (using the HotStuff consensus algorithm), made up of an ordered list of one or more hashes of signed transactions. In order to optimize data, blocks don’t contain transactions (as they do on Ethereum). The benefits are transaction data does not get transferred to consensus nodes on the network which optimizes transfer speed and this architecture allows scaling of ingestion speed by adding collection clusters. Consensus nodes need to only agree on the order of transactions to be executed, they don’t need to know the transaction payload, thus making blocks and collections lightweight. Collection nodes hold transaction payloads for anyone who requests them (e.g. execution nodes). +Collections link blocks and transactions together. Collection node clusters make these collections (using the HotStuff consensus algorithm), made up of an ordered list of one or more hashes of [signed transactions](./transactions.md). In order to optimize data, blocks don’t contain transactions (as they do on Ethereum). The benefits are transaction data does not get transferred to consensus nodes on the network which optimizes transfer speed and this architecture allows scaling of ingestion speed by adding collection clusters. Consensus nodes need to only agree on the order of transactions to be executed, they don’t need to know the transaction payload, thus making blocks and collections lightweight. Collection nodes hold transaction payloads for anyone who requests them (e.g. execution nodes). ![Screenshot 2023-08-17 at 19.50.39.png](_collection_images/Screenshot_2023-08-17_at_19.50.39.png) diff --git a/docs/build/basics/events.md b/docs/build/basics/events.md index b6e8117c93..45ddcdb2d8 100644 --- a/docs/build/basics/events.md +++ b/docs/build/basics/events.md @@ -59,25 +59,25 @@ There is an unlimited amount of events that can be defined on Flow, but you shou ### FLOW Token Events -The FLOW Token contract uses the fungible token standard on Flow and is the contract that issues a core FLOW token. As with any contract, it can emit events when interacted with. When we transfer the FLOW token, events are emitted. You can find a lot of details on the events emitted in the [FLOW Token documentation](../../references/core-contracts/03-flow-token.md). +The FLOW Token contract uses the [fungible token standard on Flow](../../references/core-contracts/03-flow-token.md) and is the contract that issues a core FLOW token. As with any contract, it can emit events when interacted with. When we transfer the FLOW token, events are emitted. You can find a lot of details on the events emitted in the [FLOW Token documentation](../../references/core-contracts/03-flow-token.md). The most common events are when tokens are transferred which is accomplished with two actions: withdrawing tokens from the payer and depositing tokens in the receiver. Each of those action has a corresponding event: **Withdraw Tokens** -Event name: `TokensWithdrawn` +Event name: `TokensWithdrawn` -Mainnet event: `A.1654653399040a61.FlowToken.TokensWithdrawn` +Mainnet event: `A.1654653399040a61.FlowToken.TokensWithdrawn` -Testnet event: `A.7e60df042a9c0868.FlowToken.TokensWithdrawn` +Testnet event: `A.7e60df042a9c0868.FlowToken.TokensWithdrawn` **Deposit Tokens** -Event name: `TokensDeposited` +Event name: `TokensDeposited` -Mainnet event: `A.1654653399040a61.FlowToken.TokensDeposited` +Mainnet event: `A.1654653399040a61.FlowToken.TokensDeposited` -Testnet event: `A.7e60df042a9c0868.FlowToken.TokensDeposited` +Testnet event: `A.7e60df042a9c0868.FlowToken.TokensDeposited` ### **Fee Events** diff --git a/docs/build/basics/fees.md b/docs/build/basics/fees.md index 6cd7f60629..773aa59f86 100644 --- a/docs/build/basics/fees.md +++ b/docs/build/basics/fees.md @@ -8,7 +8,7 @@ sidebar_position: 5 A transaction fee is a cost paid in Flow by the payer account and is required for a transaction to be included in the Flow blockchain. Fees are necessary for protecting the network against spam, and infinite running transactions and to provide monetary incentives for participants that make up the Flow network. -A transaction fee is paid regardless of whether a transaction succeeds or fails. If the payer account doesn’t have sufficient Flow balance to pay for the transaction fee, the transaction will fail. We can limit the transaction fee to some extent by providing the gas limit value when submitting the transaction. +A transaction fee is paid regardless of whether a transaction succeeds or fails. If the payer account doesn't have sufficient Flow balance to pay for the transaction fee, the transaction will fail. We can limit the transaction fee to some extent by providing the gas limit value when submitting the transaction. ### Understanding the need for transaction fees @@ -21,7 +21,7 @@ The unique Flow architecture is targeted at high throughput. It makes it easier ### **Fee Structure** -Each transaction fee consits of three components: execution fee, inclusion fee, and network surge factor. +Each transaction fee consists of three components: execution fee, inclusion fee, and network surge factor. ![Screenshot 2023-08-17 at 17.16.32.png](_fees_images/Screenshot_2023-08-17_at_17.16.32.png) @@ -88,7 +88,7 @@ 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 diff --git a/docs/build/getting-started/app-architecture/index.md b/docs/build/getting-started/app-architecture/index.md index 067e76007b..4008b09be7 100644 --- a/docs/build/getting-started/app-architecture/index.md +++ b/docs/build/getting-started/app-architecture/index.md @@ -41,7 +41,7 @@ In a self-custody architecture, users retain direct control over their private k ### **App Custody Architecture** -App custody on Flow offers a unique approach to key management and user experience. Unlike traditional app custody solutions on other blockchains, Flow's App Custody architecture introduces features like **[account linking](../../advanced-concepts/account-linking/index.mdx)** and **[walletless onboarding](../../advanced-concepts/account-linking/child-accounts.md)**. These features ensure that while users enjoy a seamless experience, they still have the option to link their accounts and move their assets freely around the Flow ecosystem, providing a balanced approach to key management. +App custody on Flow offers a unique approach to key management and user experience. Unlike traditional app custody solutions on other blockchains, Flow's App Custody architecture introduces features like **[account linking](../../advanced-concepts/account-linking/index.md)** and **[walletless onboarding](../../advanced-concepts/account-linking/child-accounts.md)**. These features ensure that while users enjoy a seamless experience, they still have the option to link their accounts and move their assets freely around the Flow ecosystem, providing a balanced approach to key management. ![app-custody.png](app-custody.png)