Merge pull request #291 from onflow/gregor/concepts-links

Add links to concepts

docs/build/advanced-concepts/account-linking/index.mdx → docs/build/advanced-concepts/account-linking/index.md

@@ -5,17 +5,17 @@ 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)
 
 ## Accessing AuthAccount
 
 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.
 
-<aside>
+<Callout type="warning">
 ❗ Creating an `AuthAccount` capability and sharing it with third-party account is in concept the same as giving that person your account's private keys.
 
-</aside>
+</Callout>
 
-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)
 

docs/build/advanced-concepts/account-linking/parent-accounts.mdx → 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.
+and ultimately the owners of these child accounts the ability to revoke secondary access on owned accounts.

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.
 
 <Callout type="warning">
 The minimum amount of FLOW an account can have is **0.001**.
-
 </Callout>
 
 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.
 
 <Callout type="warning">
-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.
 </Callout>
 
 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:
 

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. 
 

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)
 

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**