Merge branch 'main' into Previewnet-doc-updates

docs/build/basics/scripts.md

@@ -4,14 +4,22 @@ sidebar_position: 4
 
 # Scripts
 
-A script is executable Cadence code that queries the Flow network but does not modify it. Unlike Flow transactions, they don’t need signing and they can return a value. You can think of executing scripts as a read-only operation. 
+A script provides a light-weight method to query chain data.
 
-Scripts are executed on Access Nodes or Execution Nodes. 
+It is executable Cadence code that can query for Flow execution state data but cannot modify it in any way.
 
-Scripts are defined by following the Cadence code and we can only execute one at a time.
+Unlike a Flow transaction, a script is not signed and requires no transaction fees. Also unlike a transaction, a script can return a value back to the caller.
+You can think of executing a script as a read-only operation, very similar to the `eth_call` RPC method on Ethereum.
+
+Scripts are currently executed on either the Access Nodes or the Execution Nodes based on the Access node configuration.
+
+Scripts are defined by the following the Cadence code:
 
 ```cadence
-pub fun main() {}
+// The 'main' function is the entry point function and every script needs to have one.
+pub fun main() {
+ // Cadence statements to be executed go here
+}
 ```
 
 Scripts can return a typed value:
@@ -22,6 +30,14 @@ pub fun main(): Int {
 }
 ```
 
+Scripts can also accept arguments:
+
+```cadence
+pub fun main(arg: String): String {
+	return "Hello ".concat(arg)
+}
+```
+
 Scripts can call contract functions and query the state of a contract. To call a function on another contract, import it from its address and invoke the function:
 
 ```cadence
@@ -32,19 +48,22 @@ pub fun main(): String {
 }
 ```
 
-## Executing Scripts
+Scripts can also be run against previous blocks, allowing you to query historic data from the Flow network. This is particularly useful for retrieving historical states of contracts or tracking changes over time.
 
-You can execute a script by using the Flow CLI:
+## When to use a script?
 
-```sh
-flow scripts execute ./helloWorld.cdc
-```
+Scripts can be used for the following:
 
-A user can define their own scripts or can use already defined scripts by the contract authors that can be found by using the FLIX service.
+1. Validating a transaction before submitting it e.g. checking if the payer has sufficient balance, the receiver account is setup correctly to receive a token or NFT etc.
+2. Collecting chain data over time.
+3. Continuously verifying accounts through a background job e.g. a Discord bot that verifies users by their Flow account.
+4. Querying core contracts e.g. see [staking scripts and events](../../networks/staking/07-staking-scripts-events.md) for querying staking and epoch related information, see the scripts directory under each of the [core contract transactions](https://github.com/onflow/flow-core-contracts/tree/master/transactions) for other core contracts related scripts.
 
-Scripts can be run against previous blocks, allowing you to query historic data from the Flow network. This is particularly useful for retrieving historical states of contracts or tracking changes over time.
+## Executing Scripts
+
+### Access API
 
-Scripts are executed by being submitted to the Access Node APIs. Currently, there’s support for two APIs:
+A script can be executed by submitting it to the Access API provided by access nodes. Currently, there are three API endpoints that allow a user to execute scripts at the latest sealed block, a previous block height, or a previous block ID.
 
 [**gRPC Script API**](../../networks/node-ops/access-onchain-data/access-nodes/accessing-data/access-api.md#scripts)
 
@@ -57,3 +76,27 @@ There are multiple SDKs implementing the above APIs for different languages:
 [**Go SDK**](../../tools/clients/flow-go-sdk/index.mdx)
 
 Find a list of all SDKs [here](../../tools/clients/index.md)
+
+### Flow CLI
+
+You can also execute a script by using the [Flow CLI](../../tools/flow-cli/scripts/execute-scripts):
+
+```sh
+flow scripts execute ./helloWorld.cdc
+```
+
+A user can define their own scripts or can use already defined scripts by the contract authors that can be found by using the [FLIX](../../tools/flow-cli/flix) service.
+
+## Limitations
+
+1. **Rate limit** - Script execution is subjected to API rate-limits imposed by the Access nodes and the Execution nodes. The rate limits for the Public Access nodes hosted by QuickNode are outlined [here](https://www.quicknode.com/docs/flow#endpoint-rate-limits).
+
+
+2. **Computation limit** - Similar to a transaction, each script is also subjected to a computation limit. The specific value can be configured by individual Access and Execution node operators. Currently, the default compute (gas) limit for a script is 100,000.
+
+
+3. **Historic block data limit**
+   1. Script execution on execution nodes is restricted to approximately the last 100 blocks. Any request for script execution on an execution node on a past block (specified by block ID or block height) will fail if that block is more than 100 blocks in the past.
+   2. Script execution on an access node can go much beyond the last 100 blocks but is restricted to the height when the [last](https://developers.flow.com/networks/node-ops/node-operation/past-sporks) network upgrade ([HCU](https://developers.flow.com/networks/node-ops/node-operation/hcu) or spork) occurred. 
+
+

docs/build/core-contracts/flow-nft/index.md

@@ -118,7 +118,7 @@ the format to query and return them, so projects can still be flexible with how
 This example shows how to read basic information about an NFT
 including the name, description, image and owner.
 
-**Source: [get_nft_metadata.cdc](https://github.com/onflow/flow-nft/blob/standard-v2/scripts/get_nft_metadata.cdc)**
+**Source: [get_nft_metadata.cdc](https://github.com/onflow/flow-nft/blob/standard-v2/transactions/scripts/get_nft_metadata.cdc)**
 
 ### How to implement metadata
 

docs/ecosystem/block-explorers.md

@@ -18,13 +18,16 @@ Block explorers are user-friendly online tools that visually present blockchain
 - Blocks
 - Transactions
 - Contracts
-
-It also offers analytics for the mainnet:
-
 - Network activity (transaction count)
 - Transaction cost (gas fee)
 - Validators information
 
+### Supported networks:
+
+- [Mainnet](https://www.flowdiver.io/)
+- [Testnet](https://testnet.flowdiver.io/)
+- [Previewnet](https://previewnet.flowdiver.io/)
+
 ## Flow View
 
 [Flow View](https://www.flowview.app/) offers comprehensive tools to view accounts' information, including:
@@ -35,11 +38,11 @@ It also offers analytics for the mainnet:
 - Tokens, collections, and listings
 - Deployed smart contracts
 
-Supported networks:
+### Supported networks:
 
-- Mainnet: [https://www.flowview.app/](https://www.flowview.app/)
-- Testnet: [https://testnet.flowview.app/](https://testnet.flowview.app/)
-- Emulator (local): [https://emulator.flowview.app/](https://emulator.flowview.app/)
+- [Mainnet](https://www.flowview.app/)
+- [Testnet](https://testnet.flowview.app/)
+- [Emulator (local)](https://emulator.flowview.app/)
 
 ## Contract Browser
 

docs/ecosystem/bridges.md

@@ -7,6 +7,14 @@ sidebar_custom_props:
 
 # Bridges
 
+:::info
+## Coming Soon
+
+Details on bridges connecting Flow with other networks are currently in the works and will be shared soon. These bridges will facilitate seamless asset transfers and interoperability between Flow and various blockchains, enhancing the utility and reach of Flow's ecosystem.
+
+For real-time updates and discussions, please join the [Flow Discord](https://discord.gg/flow) and check the #evm channel.
+:::
+
 Bridges are mechanisms that connect different blockchain networks, enabling secure and decentralized transfers of assets and data across various platforms.
 
 <div id="cards" className="cards">

docs/evm/about.md

@@ -1,60 +1,47 @@
 ---
-title: About EVM On Flow
-sidebar_label: About
+title: Why EVM on Flow 
+sidebar_label: Why EVM on Flow 
 sidebar_position: 1
 ---
 
-# About EVM On Flow
+# Why EVM on Flow 
 
-Flow is a secure, performant, highly scalable EVM-equivalent L1. With EVM on Flow all of Flow's native protocol benefits of fast transactions, low costs, and mainstream scalability are available without any code changes.
-It inherits Flow's [multi-node distributed consensus](https://flow.com/decentralization) and transaction model. Specifically, EVM on Flow benefits from Flow's [horizontally scaled transaction linearization](https://flow.com/core-protocol-vision#scaling-transactions) design which has solved proposer builder separation, separation of compute, and settlement – all without sharding.
+Flow is an L1 that now supports EVM-equivalency. This means that all of Flow's protocol benefits, such as fast transactions, low costs, and mainstream scalability, are natively available without any additional code changes to solidity contracts. With EVM, solidity devs and builders can now easily tap into Flow's user base and unique IPs without any implementation risk. 
 
 ## Seamless Integration for Ethereum Developers
 
-EVM on Flow is designed to work out-of-the-box with the Ethereum toolchain or other clients, and will run existing Solidity contracts as-is without any code changes. Developers can get their existing applications up and running on day one! With your core application running you can begin to explore how to leverage Flow's powerful feature set for your application.
-To achieve this will require implementing a minimal transaction script in Cadence, Flow's smart contract language, to integrate Flow features with EVM. This is made possible because EVM transactions are composed and executed within Cadence transactions, enabling novel use-cases and patterns for integration.
+EVM on Flow is designed to work out-of-the-box with the Ethereum toolchain or other clients..   Native EVM transactions also continue to be supported when using Metamask and other EVM-compatible clients.
+EVM-equivalency on Flow works behind-the-scenes by  implementing a minimal transaction script in Cadence, Flow's smart contract language, to integrate Flow features with EVM. This is made possible because EVM transactions are composed and executed within Cadence transactions, enabling novel use-cases and patterns for integration.
 
-Native EVM transactions continue to be supported when using Metamask and other EVM-compatible clients.
 
 ## Best-In-Class UX
 
-Account Linking is built on Flow's account abstraction model and enables users to immediately use an app without
-wallet authentication. On-chain accounts can be created as needed by the application which custodies their use for an anonymous user. At some later point these users may choose to link the custodied account to their self-custodial wallet taking full ownership of the account. EVM apps on Flow can also leverage Account Linking to handle creation of accounts and achieve a similarly smooth onboarding user experience.
+Flow allows for the creation of app on-boarding experiences that meet every type of user exactly where they are at, from web3 beginners to ecosystem veterans. This is possible through Account Linking, which utilizes the account abstraction model on Flow and enables users to immediately use an app without wallet authentication. On-chain accounts can be created as needed by the application which custodies their use for an anonymous user. At some later point these users may choose to link the custodied account to their self-custodial wallet taking full ownership of the account. EVM apps on Flow can also leverage Account Linking to handle creation of accounts and achieve a similarly smooth onboarding user experience.
+
+With Flow, builders can choose to expand EVM capabilities and transcend limitations using Cadence, which offers a powerful new account model, programmable resources, and hybrid ownership.
 
 ## Instant Cross-VM Token Transfers
 
-EVM and Cadence environments both use FLOW token as the gas currency for transactions, sharing a singular token
-supply across both environments. A few lines Cadence can transfer FLOW tokens in the Cadence environment to EVM, or vice versa. Other fungible and non-fungible tokens can also be seamlessly transferred between environments using the native cross-VM token bridge, taking place instantly in a single atomic transaction
+EVM and Cadence environments both use FLOW as gas for transactions, sharing a singular token supply across both environments. Fungible and non-fungible tokens can also be seamlessly transferred between environments using the native VM token bridge, taking place instantly in a single atomic transaction.
 
 ## Scalability, Performance and Low Gas Fees
 
-Flow’s state space is extensible to the petabyte scale and is the reason why Cadence contracts have standardized on storing application data on-chain. This benefit translates directly to EVM on Flow allowing contracts to maintain a full working dataset - including metadata - together with contract logic, all at low gas rates. Flow's state scalability sets the foundations for significant throughput optimization yet to come.
+For sustainable user adoption, apps require the network they build on to be secure, efficient, affordable and fast. Gas fees are ultra-low cost on the network, but Flow goes a step further allowing for gasless experiences through sponsored transactions. Scalable performance is ensured with an innovative multi-node distributed consensus, flexible transaction model and horizontally scaled transaction linearization which solves proposer-builder separation, separation of compute, and settlement – all without sharding.
 
-Flow's transaction throughput peaked to 2M daily transactions during 2023 sustaining a similar average transaction volume as Ethereum. Unlike Ethereum, Flow has always operated well under its maximum throughput ceiling which is presently scalable to 5x more transactions with further performance optimizations to come when parallel execution is released.
+Flow’s state space is extensible to the petabyte scale  making it easy to store application data on-chain. This means contracts can  maintain a full working dataset - including metadata - together with contract logic.
 
-## MEV Resilience
+Flow's transaction throughput peaked to 2M daily transactions during 2023 sustaining a similar average transaction volume as Ethereum. Unlike Ethereum, Flow has always operated well under its maximum throughput ceiling which is presently scalable to 5x more transactions with further performance optimizations to come when parallel execution is released. State scalability on Flow sets the foundations for further significant throughput optimization. 
 
-Since EVM on Flow transactions are composed and executed within a Cadence transaction block production is handled by Flow’s multi-role architecture. The heterogeneity between node roles ensures that visibility into block proposal, assembly, asserting block validity and other correctness checks during the block processing cycle expose only the limited information that a given node type requires to perform its function. These differences in node and consensus design results in strong economic disincentives for collusion because no individual node has full visibility into the state of block processing for the chain. This robust MEV resilience is a significant difference from other EVMs and will help to ensure gas fees are reasonably priced at all times. The impracticality of frontrunning or other attacks improves the user experience by eliminating failed transactions and invisible fees.
 
-## Key Advantages
+## MEV Resilience
 
-- **Access New Markets**: Easily tap into Flow's user base and unique IPs without any implementation risk
-- **Simplified Multi-Chain Experience**: Ideal for applications without a multi-chain approach or those wanting to ensure cross-chain compatibility
-- **Leverage Flow’s Protocol**: Expand EVM capabilities and transcend EVM limitations using Cadence, which offers a powerful new account model, programmable resources, and hybrid ownership
-- **No Miner Extractable Value (MEV)**: Leading to a more fair and secure environment for all participants and minimizing the risk of front running transactions
-- **Enhanced Functionality**:
-  - Compose assets and functionality using a shared world state and [Cadence contracts](https://cadence-lang.org/).
-  - Conduct multiple contract interactions atomically.
-  - Tap in to [Capabilities](https://cadence-lang.org/docs/tutorial/capabilities) for zero-transfer access ([Account Linking](../build/guides/account-linking/index.md)).
-  - **Gas Fees**: Transactions are extremely low-cost and denominated in FLOW. see [Fees](./build/fees)
+The MEV Resilient design on Flow offers DeFi builders improved market efficiency, fairness, trust and long-term viability for their apps. Since EVM on Flow transactions are composed and executed within a Cadence transaction,block production is handled by Flow’s multi-role architecture. The heterogeneity between node roles ensures that visibility into block proposal, assembly, asserting block validity and other correctness checks during the block processing cycle expose only the limited information that a given node type requires to perform its function. These differences in node and consensus design results in strong economic disincentives for collusion because no individual node has full visibility into the state of block processing for the chain. This robust MEV resilience is a significant difference from other EVMs and will help to ensure gas fees are reasonably priced at all times. The impracticality of frontrunning or other attacks improves the user experience by eliminating failed transactions and invisible fees.
 
-## Learn More and Join the Conversation
 
-Users and developers are welcome to chat with us in the Flow [Discord](https://discord.com/channels/613813861610684416/1167476806333513800).
+## Join the Community
 
-## Interested in Partnering or Co-marketing?
+Are you interested in launching an EVM project on Flow or partnering with us? Visit our weekly Flow [office hours](https://calendar.google.com/calendar/ical/c_47978f5cd9da636cadc6b8473102b5092c1a865dd010558393ecb7f9fd0c9ad0%40group.calendar.google.com/public/basic.ics) for discussions on project development and other opportunities for collaboration. You can also chat with us in the Flow [Discord](https://discord.com/channels/613813861610684416/1167476806333513800).
 
-Are you interested in launching an EVM project on Flow or partnering with us? Visit our weekly Flow office hours for discussions on project development and other opportunities for collaboration.
 
 ## Further Reading and Discussions