Updating the page that describes Scripts (#719)

* updating the scripts documentation * adding usecases for scripts * fixing link * fixing link * update * update * update * update * update * replace full-stops with semicolon as per comment on PR * Update docs/build/basics/scripts.md Co-authored-by: Peter Argue <[email protected]> * Update docs/build/basics/scripts.md Co-authored-by: Peter Argue <[email protected]> * Update docs/build/basics/scripts.md Co-authored-by: Peter Argue <[email protected]> * Update docs/build/basics/scripts.md Co-authored-by: Peter Argue <[email protected]> * Update docs/build/basics/scripts.md Co-authored-by: Peter Argue <[email protected]> * Update docs/build/basics/scripts.md Co-authored-by: Peter Argue <[email protected]> --------- Co-authored-by: Peter Argue <[email protected]>
onflow · Apr 16, 2024 · 12a932f · 12a932f
1 parent cecd7c5
commit 12a932f
Showing 1 changed file with 55 additions and 12 deletions.
diff --git a/docs/build/basics/scripts.md b/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. 
+
+