Skip to content

Commit

Permalink
Update AN docs for indexing to include setup to use local data in the…
Browse files Browse the repository at this point in the history
… API (#896)

* Added section for local script execution

* Added documentation for local data usage for events and tx results

* Fixed remarks and added flags for script execution
  • Loading branch information
AndriiDiachuk authored Sep 19, 2024
1 parent 2e27326 commit 0bff8de
Showing 1 changed file with 31 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ First, your node needs to download and index the execution data. There are 3 ste
1. Enable Execution Data Sync
2. Download the root checkpoint file
3. Configure the node to run the indexer
4. Use the indexed data in the Access API.

As of **`mainnet24`** / **`devnet49`**, Access nodes can be configured to index execution data to support local script execution, and serving all of the Access API endpoints using local data. There are different setup procedures depending on if you are enabling indexing immediately after a network upgrade, or at some point between upgrades.

Expand Down Expand Up @@ -139,6 +140,7 @@ There are 2 cli flags that you will need to add:
- `--execution-data-indexing-enabled=true` This will enable the indexer.
- `--execution-state-dir` This defines the path where the registers db will be stored. A good default is on the same drive as the protocol db. e.g. `/data/execution-state`


# Start your node

Now that all of the settings to enable indexing are in place, you can start your node.
Expand Down Expand Up @@ -166,6 +168,35 @@ Notes on what to expect:

When you restart the node for the first time with syncing enabled, it will sync execution data for all blocks from the network.

# Use the indexed data in the Access API

### Setup Local Script Execution

Local execution is controlled with the `--script-execution-mode` flag, which can have one of the following values:

- `execution-nodes-only` (default): Requests are executed using an upstream execution node.
- `failover` (recommended): Requests are executed locally first. If the execution fails for any reason besides a script error, it is retried on an upstream execution node. If data for the block is not available yet locally, the script is also retried on the EN.
- `compare`: Requests are executed both locally and on an execution node, and a comparison of the results and errors are logged.
- `local-only`: Requests are executed locally and the result is returned directly.

There are a few other flags available to configure some limits used while executing scripts:

- `--script-execution-computation-limit`: Controls the maximum computation that can be used by a script. The default is `100,000` which is the same as used on ENs.
- `--script-execution-timeout`: Controls the maximum runtime for a script before it times out. Default is `10s`.
- `--script-execution-max-error-length`: Controls the maximum number of characters to include in script error messages. Default is `1000`.
- `--script-execution-log-time-threshold`: Controls the run time after which a log message is emitted about the script. Default is `1s`.
- `--script-execution-min-height`: Controls the lowest block height to allow for script execution. Default: `no limit`.
- `--script-execution-max-height`: Controls the highest block height to allow for script execution. Default: `no limit`.
- `--register-cache-size`: Controls the number of registers to cache for script execution. Default: `0 (no cache)`.

### Setup Using Local Data with Transaction Results and Events

Local data usage for transaction results and events are controlled with the `--tx-result-query-mode` and `--event-query-mode` corresponding flags, which can have one of the following values:

- `execution-nodes-only` (default): Requests are forwarded to an upstream execution node.
- `failover` (recommended): - `failover` (recommended): Requests are handled locally first. If the processing fails for any reason, it is retried on an upstream execution node. If data for the block is not available yet locally, the script is also retried on the EN.
- `local-only`: Requests are handled locally and the result is returned directly.

# Troubleshooting

- If the root checkpoint file is missing or invalid, the node will crash. It must be taken from the same block as the `root-protocol-state-snapshot.json` used to start your node.
Expand Down

0 comments on commit 0bff8de

Please sign in to comment.