Merge pull request #953 from onflow/brian-doyle/update-why-flow

Reorg of early content

CONTRIBUTING.md

@@ -108,7 +108,7 @@ Examples:
 
 ## Go SDK
 
-[Flow Go SDK](./flow-go-sdk/index.mdx) provides a set of packages for Go developers to build applications that interact with the Flow network.
+[Flow Go SDK](./flow-go-sdk/index.md) provides a set of packages for Go developers to build applications that interact with the Flow network.
 
 ## JavaScript (FCL)
 
@@ -119,7 +119,7 @@ Examples:
 ```
 
 
-```markdown index.mdx
+```markdown index.md
 ---
 sidebar_position: 1
 title: Tools

docs/build/advanced-concepts/_category_.yml

@@ -1,2 +1,2 @@
 label: Advanced Concepts
-position: 5
+position: 7

docs/build/getting-started/app-architecture/index.md → docs/build/app-architecture/index.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 5
 title: App Architecture
 description: Describes building self-custody and app custody applications on Flow Blockchain.
 sidebar_custom_props:
@@ -12,7 +12,7 @@ The Flow blockchain, with its focus on scalability and user-centric design, offe
 
 While the Flow blockchain offers various architectural patterns, the recommended approaches for developers are **Self-Custody** and **App Custody**. These choices align with Flow's ethos of user-centric design and flexibility.
 
-### **Self-Custody Architecture**
+### Self-Custody Architecture
 
 In a self-custody architecture, users retain direct control over their private keys and assets. This model emphasizes user sovereignty and decentralization, placing the responsibility of asset management squarely on the user's shoulders. While it offers the highest degree of control, it also demands a certain level of technical knowledge and awareness from the user, which can sometimes lead to a more complex user experience.
 
@@ -39,9 +39,9 @@ In a self-custody architecture, users retain direct control over their private k
 - **Decentralized Finance (DeFi)**: Users interacting with financial protocols while maintaining full control.
 - **Web3 Native Users**: Those familiar with blockchain technology and key management.
 
-### **App Custody Architecture**
+### 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](../../guides/account-linking/index.md)** and **[walletless onboarding](../../guides/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](../guides/account-linking/index.md)** and **[walletless onboarding](../guides/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)
 

docs/build/basics/_category_.yml

@@ -1,2 +1,2 @@
-label: Basic Concepts
+label: Flow Protocol
 position: 4

docs/build/basics/accounts.md

@@ -221,6 +221,6 @@ There are multiple SDKs implementing the above APIs for different languages:
 
 **Javascript SDK** [tools/clients/fcl-js](../../tools/clients/fcl-js/index.md)
 
-**Go SDK** [tools/clients/flow-go-sdk](../../tools/clients/flow-go-sdk/index.mdx)
+**Go SDK** [tools/clients/flow-go-sdk](../../tools/clients/flow-go-sdk/index.md)
 
 Find a list of all SDKs here: [tools/clients](../../tools/clients/index.md)

docs/build/basics/blocks.md

@@ -71,6 +71,6 @@ There are multiple SDKs implementing the above APIs for different languages:
 
 [**Javascript SDK**](../../tools/clients/fcl-js/index.md)
 
-[**Go SDK**](../../tools/clients/flow-go-sdk/index.mdx)
+[**Go SDK**](../../tools/clients/flow-go-sdk/index.md)
 
 Find a list of all SDKs [here](../../tools/clients/index.md)

docs/build/basics/collections.md

@@ -28,6 +28,6 @@ There are multiple SDKs implementing the above APIs for different languages:
 
 [**Javascript SDK**](../../tools/clients/fcl-js/index.md)
 
-[**Go SDK**](../../tools/clients/flow-go-sdk/index.mdx)
+[**Go SDK**](../../tools/clients/flow-go-sdk/index.md)
 
 Find a list of all SDKs [here](../../tools/clients/index.md)

docs/build/basics/scripts.md

@@ -73,7 +73,7 @@ There are multiple SDKs implementing the above APIs for different languages:
 
 [**Javascript SDK**](../../tools/clients/fcl-js/index.md)
 
-[**Go SDK**](../../tools/clients/flow-go-sdk/index.mdx)
+[**Go SDK**](../../tools/clients/flow-go-sdk/index.md)
 
 Find a list of all SDKs [here](../../tools/clients/index.md)
 

docs/build/basics/transactions.md

@@ -442,6 +442,6 @@ There are multiple SDKs implementing the above APIs for different languages:
 
 [**Javascript SDK**](../../tools/clients/fcl-js/index.md)
 
-[**Go SDK**](../../tools/clients/flow-go-sdk/index.mdx)
+[**Go SDK**](../../tools/clients/flow-go-sdk/index.md)
 
 Find a list of all SDKs [here](../../tools/clients/index.md)

docs/build/differences-vs-evm/index.md

@@ -1,48 +1,60 @@
 ---
-sidebar_position: 1
-title: Differences vs EVM
+sidebar_position: 2
+title: Differences vs. EVM
 sidebar_custom_props:
   icon: ↔️
 ---
 
-This document summarizes the differences you might encounter between building on Flow vs. other blockchains, especially Ethereum. This will be most useful to developers who are already familiar with building on a blockchain system. Check out [Why Flow](../flow.md) for a more beginner-friendly overview of the Flow blockchain.
+Flow [Cadence] is designed with many improvements over prior blockchain networks.  As a result, you'll notice many differences between Flow vs. other blockchains, especially Ethereum. This document will be most useful to developers who are already familiar with building on the EVM, but contains details useful to all developers. Check out [Why Flow] for a more general overview of the Flow blockchain.
 
-## The Flow Account Model
+:::tip
 
-Key pairs establish ownership on blockchains. In other blockchains (e.g. Bitcoin), the user’s address is also calculated based on their public key, making a unique one-to-one relationship between accounts (addresses) and public keys. This also means there is no concrete “account creation” process other than generating a valid key pair. With the advent of smart contracts, Ethereum introduced a new account type for deploying contracts that can use storage space (i.e., to store contract bytecode). You can learn more about the distinction between EOA and Contract accounts on Ethereum [here](https://ethereum.org/en/developers/docs/accounts/).
+Remember, Flow also supports full [EVM] equivalence!  You can start by moving over your existing contracts, then start building new features that take advantage of the power of Cadence.
 
-Flow combines the concepts of EOAs and Contract Accounts into a single account model and decouples accounts and public keys. Flow accounts are associated with one or more public keys of varying weights that specify interested parties that need to produce valid cryptographic signatures for each transaction authorized by that account.
+:::
+
+## The Flow Cadence Account Model
+
+Key pairs establish ownership on blockchains. In other blockchains (e.g. Bitcoin and Ethereum), the user's address is also calculated based on their public key, making a unique one-to-one relationship between accounts (addresses) and public keys. This also means there is no concrete "account creation" process other than generating a valid key pair. 
+
+With the advent of smart contracts, Ethereum introduced a new account type for deploying contracts that can use storage space (i.e., to store contract bytecode). You can learn more about the distinction between EOA and Contract [accounts on Ethereum].
+
+The [Flow account model] combines the concepts of EOAs and Contract Accounts into a single account model and decouples accounts and public keys. Flow accounts are associated with one or more public keys of varying weights that specify interested parties that need to produce valid cryptographic signatures for each transaction authorized by that account.
 
 ![Screenshot 2023-08-16 at 16.43.07.png](../basics/_accounts_images/Screenshot_2023-08-16_at_16.43.07.png)
 
 This natively enables interesting use cases, like key revocation, rotation, and multi-signature transactions. All Flow accounts can use network storage (e.g., for deploying contracts and storing resources like NFTs) based on the number of FLOW tokens they hold.
 
-<Callout type="info">
+:::warning
 
-You must run an explicit account creation transaction on Flow to create a new account. [Flow CLI](../../tools/flow-cli/accounts/create-accounts.md) can create an account on any network with a given public key.
+You must run an explicit account creation transaction on Flow to create a new account. [Flow CLI] can create an account on any network with a given public key.  Doing so requires a [very small fee] to be paid in FLOW.
 
-</Callout>
+:::
 
-Check out the [Accounts](../basics/accounts.md) concept document to learn more about Flow accounts.
+Another key difference is that [storage] for data and assets related to an account are stored in the account, **not** in the contract as with the EVM.
+
+Check out the [Accounts] concept document to learn more about Flow accounts.
 
 ## Smart Contracts
 
-On Flow, smart contracts are written in Cadence. Cadence syntax is user-friendly and inspired by modern languages like Swift. Notable features of Cadence that make it unique and the key power of the Flow blockchain are:
+On Flow, smart contracts can be written in [Cadence], or Solidity. Cadence syntax is user-friendly and inspired by modern languages like Swift. Notable features of Cadence that make it unique and the key power of the Flow blockchain are:
+
+- **Resource-oriented**: Cadence introduces a new type called Resources. Resources enable onchain representation of digital assets natively and securely. Resources can only exist in one location at a time and are strictly controlled by the execution environment to avoid common mishandling mistakes. Each resource has a unique `uuid` associated with it on the blockchain. Examples of usage are fungible tokens, NFTs, or any custom data structure representing a real-world asset. Check out [Resources] to learn more.
+- **Capability-based**: Cadence offers a [Capability-based Security] model. This also enables the use of Resources as structures to build access control. Capabilities and [Entitlements] can provide fine-grained access to the underlying objects for better security. For example, when users list an NFT on a Flow marketplace, they create a new Capability to the stored NFT in their account so the buyer can withdraw the asset when they provide the tokens. Check out [Capability-based Access Control] to learn more about Capabilities on Cadence.
 
-- **Resource-oriented**: Cadence introduces a new type called Resources. Resources enable onchain representation of digital assets natively and securely. Resources can only exist in one location at a time and are strictly controlled by the execution environment to avoid common mishandling mistakes. Each resource has a unique `uuid` associated with it on the blockchain. Examples of usage are fungible tokens, NFTs, or any custom data structure representing a real-world asset. Check out [Resources](https://cadence-lang.org/docs/language/resources) to learn more.
-- **Capability-based**: Cadence offers a [Capability-based Security](https://en.wikipedia.org/wiki/Capability-based_security) model. This also enables the use of Resources as structures to build access control. Capabilities and [Entitlements](https://cadence-lang.org/docs/1.0/language/access-control#entitlements) can provide fine-grained access to the underlying objects for better security. For example, when users list an NFT on a Flow marketplace, they create a new Capability to the stored NFT in their account so the buyer can withdraw the asset when they provide the tokens. Check out [Capability-based Access Control](https://cadence-lang.org/docs/language/capabilities) to learn more about Capabilities on Cadence.
+:::warning
 
-<Callout type="info">
+Cadence is not compiled. All contracts are public and unobfuscated on Flow. This isn't that different from the EVM, where it's trivial to decompile a contract back into Solidity. 
 
-Cadence is not compiled. All contracts are open source on Flow.
+:::
 
-</Callout>
+Check out the [Cadence] website to learn the details of the Cadence programming language.
 
-Check out the [Cadence website](https://cadence-lang.org/) to learn more about Cadence.
+If you are a Solidity developer, we recommend you start with Cadence's [Guide for Solidity Developers] to dive deeper into the differences between the two languages.
 
-If you are a Solidity developer, it's recommended to read Cadence's [Guide for Solidity Developers](https://cadence-lang.org/docs/solidity-to-cadence) to dive deeper into the differences between the two languages. Here are some additional resources that can help you get started with Cadence:
+Here are some additional resources that can help you get started with Cadence:
 
-- [The Cadence tutorial](https://cadence-lang.org/docs/tutorial/first-steps)
+- [The Cadence tutorial]
 - ERC-20 equivalent on Flow is the Flow Fungible Token Standard
   - [Repository](https://github.com/onflow/flow-ft)
   - [Tutorial](https://cadence-lang.org/docs/tutorial/fungible-tokens)
@@ -53,9 +65,9 @@ If you are a Solidity developer, it's recommended to read Cadence's [Guide for S
   - [Tutorial](https://cadence-lang.org/docs/tutorial/marketplace-setup)
   - [NFT Storefront](https://github.com/onflow/nft-storefront/) is an example marketplace standard
 
-### Transactions and Scripts
+## Transactions and Scripts
 
-You can interact with the state on most other blockchains by cryptographically authorizing smart contract function calls. On Flow, transactions are more complex and are pieces of Cadence code. This means that any number of contracts and function calls can be composed together atomically to mutate the blockchain state.
+You can interact with the state on most other blockchains by cryptographically authorizing smart contract function calls. On Flow, transactions offer rich functionality through Cadence code. This allows you to seamlessly combine multiple contracts and function calls into a single transaction that updates the blockchain state - all executing together as one unified operation.
 
 Here is a sample transaction that mints an NFT from `ExampleNFT` contract on Testnet:
 
@@ -109,12 +121,14 @@ transaction(recipient: Address) {
 }
 ```
 
-Authorizing transactions is also more complex on Flow involving multiple roles:
+### Authorizing Transactions
 
-- Accounts can have multiple keys with varying weights
+The process to authorize a transaction on Flow Cadence is more complex, but also much more powerful than an EVM transaction:
+
+- [Accounts] can have multiple keys with varying weights
 - Multiple accounts can sign a single transaction (`prepare` takes any number of arguments)
 - Transaction computation fees can be paid by a different account, called the `Payer` account.
-- The transaction [nonce](https://ethereum.org/en/developers/docs/accounts/#an-account-examined) is provided by the `Proposer` account. This enables rate control and order to be dictated by a different party if needed.
+- The [transaction nonce] is provided by the `Proposer` account. This enables rate control and order to be dictated by a different party if needed.
 - All of the above roles can be the same account.
 
 The same powerful concept also exists for querying the blockchain state using Scripts. Here is a sample script that fetches the `ExampleNFT` IDs owned by a given account on Testnet:
@@ -143,17 +157,17 @@ access(all) fun main(address: Address, collectionPublicPath: PublicPath): [UInt6
 }
 ```
 
-Check out [Transactions](../basics/transactions.md) and [Scripts](../basics/scripts.md) to learn more about the concepts. You can also read the Cadence language reference on [Transactions](https://cadence-lang.org/docs/language/transactions) to dive deeper.
+Check out [Transactions] and [Scripts] to learn more about the concepts. You can also read the Cadence language reference on [Transactions] to dive deeper.
 
 ## Flow Nodes
 
-Developers need a blockchain node to send transactions and fetch state. Flow is based on a multi-node architecture that separates roles like consensus and computation. You can learn more about the Flow architecture [here](https://flow.com/primer#primer-how-flow-works).
+Developers need a blockchain node to send transactions and fetch state. Flow is based on a multi-node architecture that separates tasks like consensus and computation into separate nodes. You can learn more about the Flow architecture in the [Flow Primer].
 
-Access Nodes are the node type that are most useful for developers, as they provide access to the Flow network [via an API](../../networks/flow-networks/index.md).
+Access Nodes are the node type that are most useful for developers, as they provide access to the Flow network [via an API].
 
 ## SDKs and Tools
 
-If you’re already familiar with blockchain development, here's a comparison between popular software packages and Flow's tooling:
+If you're already familiar with blockchain development, here's a comparison between popular software packages and Flow's tooling:
 
 - [hardhat](https://hardhat.org/) / [Truffle](https://trufflesuite.com/) / [Foundry](https://github.com/foundry-rs/foundry)
   - [Flow CLI](https://github.com/onflow/flow-cli/) provides local development tools and the [Flow Emulator](https://github.com/onflow/flow-emulator)
@@ -172,3 +186,27 @@ If you’re already familiar with blockchain development, here's a comparison be
   - [Cadence testing framework](https://cadence-lang.org/docs/testing-framework) enables native tests in Cadence.
   - [overflow](https://github.com/bjartek/overflow) for testing in Go.
   - [js-testing](https://github.com/onflow/flow-js-testing) for testing in JS.
+
+<!-- Relative-style links.  Does not render on the page -->
+
+[Why Flow]: ../flow.md
+[EVM]: ../../evm/about.md
+[accounts on Ethereum]: https://ethereum.org/en/developers/docs/accounts
+[Flow CLI]: ../../tools/flow-cli/accounts/create-accounts.md
+[very small fee]: ../basics/fees.md#fee-structure
+[Flow account model]: ../basics/accounts.md
+[Accounts]: ../basics/accounts.md
+[storage]: ../basics/accounts.md#storage
+[Cadence]: https://cadence-lang.org/
+[Resources]: https://cadence-lang.org/docs/language/resources
+[Capability-based Security]: https://en.wikipedia.org/wiki/Capability-based_security
+[Entitlements]: https://cadence-lang.org/docs/1.0/language/access-control#entitlements
+[Capability-based Access Control]: https://cadence-lang.org/docs/language/capabilities
+[Guide for Solidity Developers]: https://cadence-lang.org/docs/solidity-to-cadence
+[The Cadence tutorial]: https://cadence-lang.org/docs/tutorial/first-steps
+[transaction nonce]: https://ethereum.org/en/developers/docs/accounts/#an-account-examined
+[Transactions]: ../basics/transactions.md
+[Scripts]: ../basics/scripts.md
+[Transactions]: https://cadence-lang.org/docs/language/transactions
+[Flow Primer]: https://flow.com/primer#primer-how-flow-works
+[via an API]: ../../networks/flow-networks/index.md