0.4 docs cleanup (WIP) (#199)

* Update blockchain-interactions.mdx

* cleanup

* Update commands.mdx

* Update README.md

* Update component.mdx

* Update how-it-works.mdx

* Update 1-overview.mdx

* Update 2-setup.mdx

* Update 3-project.mdx

* Update 4-component.mdx

* Update 5-build.mdx

* Update 6-run-service.mdx

* Update 7-prediction.mdx

* Update overview.mdx

* Update triggers.mdx

* Update workflows.mdx

Author: evanorti

README.md

@@ -19,7 +19,7 @@ A template for developing WebAssembly AVS applications using Rust and Solidity,
 
 ### Docker
 
-If prompted, remove containerd with `sudo apt remove containerd.io`.
+If prompted, remove container with `sudo apt remove containerd.io`.
 
 - **MacOS**: `brew install --cask docker`
 - **Linux**: `sudo apt -y install docker.io`
@@ -289,7 +289,7 @@ SERVICE_FILE=.docker/service.json source ./script/ipfs-upload.sh
 
 ## Start Aggregator
 
-**TESTNET** You can move the aggregator it to its own machine for testnet deployments, it's easiest to run this on the deployer machine first. If moved, ensure you set the env variables correctly (copy pasted from the previous steps on the other machine).
+**TESTNET** You can move the aggregator it to its own machine for testnet deployments, it's easiest to run this on the deployer machine first. If moved, ensure you set the env variables correctly (copied and pasted from the previous steps on the other machine).
 
 ```bash
 bash ./script/create-aggregator.sh 1

docs/handbook/commands.mdx

@@ -9,30 +9,34 @@ docsignore-->
 
 ## Commands
 
+Use `make help` to see all the commands:
+
 ```bash
 make help
 ```
 
+Here are the available makefile commands and their descriptions:
+
 ```bash
-build                     building the project
-wasi-build                building WAVS wasi components | WASI_BUILD_DIR
-wasi-exec                 executing the WAVS wasi component(s) | COMPONENT_FILENAME, COIN_MARKET_CAP_ID
-clean                     cleaning the project files
-clean-docker              remove unused docker containers
-fmt                       formatting solidity and rust code
-test                      running tests
-setup                     install initial dependencies
-start-all-local           starting anvil and core services (like IPFS for example)
-get-trigger-from-deploy   getting the trigger address from the script deploy
-get-submit-from-deploy    getting the submit address from the script deploy
-wavs-cli                  running wavs-cli in docker
-upload-component          uploading the WAVS component | COMPONENT_FILENAME, WAVS_ENDPOINT
-deploy-service            deploying the WAVS component service json | SERVICE_URL, CREDENTIAL, WAVS_ENDPOINT
-get-trigger               get the trigger id | SERVICE_TRIGGER_ADDR, RPC_URL
-show-result               showing the result | SERVICE_SUBMISSION_ADDR, TRIGGER_ID, RPC_URL
-upload-to-ipfs            uploading the a service config to IPFS | SERVICE_FILE, [PINATA_API_KEY]
-operator-list             listing the AVS operators | ENV_FILE
-operator-register         listing the AVS operators | ENV_FILE, AVS_PRIVATE_KEY
-update-submodules         update the git submodules
-check-requirements        verify system requirements are installed
+make build                     building the project
+make wasi-build                building WAVS wasi components | WASI_BUILD_DIR
+make wasi-exec                 executing the WAVS wasi component(s) | COMPONENT_FILENAME, COIN_MARKET_CAP_ID
+make clean                     cleaning the project files
+make clean-docker              remove unused docker containers
+make fmt                       formatting solidity and rust code
+make test                      running tests
+make setup                     install initial dependencies
+make start-all-local           starting anvil and core services (like IPFS for example)
+make get-trigger-from-deploy   getting the trigger address from the script deploy
+make get-submit-from-deploy    getting the submit address from the script deploy
+make wavs-cli                  running wavs-cli in docker
+make upload-component          uploading the WAVS component | COMPONENT_FILENAME, WAVS_ENDPOINT
+make deploy-service            deploying the WAVS component service json | SERVICE_URL, CREDENTIAL, WAVS_ENDPOINT
+make get-trigger               get the trigger id | SERVICE_TRIGGER_ADDR, RPC_URL
+make show-result               showing the result | SERVICE_SUBMISSION_ADDR, TRIGGER_ID, RPC_URL
+make upload-to-ipfs            uploading the a service config to IPFS | SERVICE_FILE, [PINATA_API_KEY]
+make update-submodules         update the git submodules
+make check-requirements        verify system requirements are installed
 ```
+
+For more information on commands when using the template, visit the [WAVS tutorial](/tutorial/1-overview).

docs/handbook/components/blockchain-interactions.mdx

@@ -7,7 +7,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
 import { DocsPage } from 'fumadocs-ui/page';
 docsignore-->
 
-Components can interact with blockchains and smart contracts by using crates like [`wavs-wasi-utils`](https://docs.rs/wavs-wasi-utils/latest/wavs_wasi_utils/). This page provides an overview of the dependencies and configuration needed to interact with Ethereum and other EVM-compatible chains. For more information on other helpful crates, see the [Utilities and crates](./utilities) page.
+Components can interact with blockchains and smart contracts by using crates like [`wavs-wasi-utils`](https://docs.rs/wavs-wasi-utils/latest/wavs_wasi_utils/). This page provides an overview of the dependencies and configuration needed to interact with Ethereum and other EVM-compatible chains.
 
 ### `wavs-wasi-utils` crate
 
@@ -198,7 +198,7 @@ pub fn query_nft_ownership(address: Address, nft_contract: Address) -> Result<bo
 }
 ```
 
-For another approach using the `alloy-contract` crate, visit the example in the [Utilities and crates](./utilities#alloy-contract-crate) page.
+You can also use the `alloy-contract` crate to interact with smart contracts. See the [alloy-contract docs](https://crates.io/crates/alloy-contract) page for more information.
 
 See the [wavs-wasi-utils documentation](https://docs.rs/wavs-wasi-utils/latest/wavs_wasi_utils/) and the [Alloy documentation](https://docs.rs/alloy/latest/alloy/) for more detailed information.
 
@@ -211,6 +211,7 @@ The Alloy ecosystem provides a comprehensive set of crates for Ethereum developm
 - [`alloy-provider`](https://docs.rs/alloy-provider/latest/alloy_provider/): Ethereum node interaction (RPC, WebSocket, batching)
 - [`alloy-network`](https://docs.rs/alloy-network/latest/alloy_network/): Network types and chain-specific functionality
 - [`alloy-sol-types`](https://docs.rs/alloy-sol-types/latest/alloy_sol_types/): ABI handling and type generation
+- [`alloy-contract`](https://docs.rs/alloy-contract/latest/alloy_contract/): Contract interaction utilities
 
 ### Utility crates
 

docs/handbook/components/component.mdx

@@ -70,7 +70,7 @@ mod solidity { // Define the Solidity types for the incoming trigger event using
 
 The component decodes the incoming event trigger data using the `decode_event_log_data!` macro from the [`wavs-wasi-utils` crate](https://docs.rs/wavs-wasi-utils/latest/wavs_wasi_utils/macro.decode_event_log_data.html).
 
-The `sol!` macro from `alloy-sol-macro` is usedto define Solidity types in Rust. This macro reads a Solidity interface file and generates corresponding Rust types and encoding/decoding functions. For more information, visit the [Utilities and crates page](./utilities#sol-macro).
+The `sol!` macro from `alloy-sol-macro` is usedto define Solidity types in Rust. This macro reads a Solidity interface file and generates corresponding Rust types and encoding/decoding functions. For more information, visit the [Blockchain interactions page](./blockchain-interactions#sol-macro).
 
 ### Component logic
 
@@ -190,3 +190,14 @@ A component is defined in the [workflow](../workflows) object of the [service.js
 ```
 
 For more information on component configuration variables and keys, visit the [variables](./variables) page.
+
+## Registry
+
+WAVS uses a registry to store the WASM components. A service like [wa.dev](https://wa.dev) is recommended for proper distribution in production. A similar registry environment is emulated locally in docker compose for rapid development without an API key:
+
+- Build your component
+- Compile the component
+- Upload the component to the registry
+- Set the registry in your service using the wavs-cli command in the `build_service.sh` script:
+
+`wavs-cli workflow component --id ${WORKFLOW_ID} set-source-registry --domain ${REGISTRY} --package ${PKG_NAMESPACE}:${PKG_NAME} --version ${PKG_VERSION}`

docs/handbook/components/variables.mdx

@@ -7,11 +7,9 @@ import { Callout } from 'fumadocs-ui/components/callout';
 import { DocsPage } from 'fumadocs-ui/page';
 docsignore-->
 
-## Environment variables
-
 Components can be configured with two types of variables:
 
-### Public variables
+## Public variables
 
 These variables can be used for non-sensitive information that can be viewed publicly. These variables are set in the `config` field of a service manifest. All config values are stored as strings, even for numbers.
 
@@ -34,7 +32,7 @@ To add public variables:
 let value = host::config_var("api_endpoint");
 ```
 
-### Environment keys
+## Environment keys
 
 Environment keys are private and can be used for sensitive data like API keys. These variables are set by operators in their environment and are not viewable by anyone. These variables must be prefixed with `WAVS_ENV_`. Each operator must set these variables in their environment before deploying the service. WAVS validates that all environment variables are set before allowing the service to run.
 
@@ -56,7 +54,13 @@ Variables can also be set in your `~/.bashrc`, `~/.zshrc`, or `~/.profile` files
 WAVS_ENV_MY_API_KEY=your_secret_key_here
 ```
 
-3. Add the environment key to the `env_keys` array in the service manifest:
+3. Access the environment key from a component:
+
+```rust
+let api_key = std::env::var("WAVS_ENV_MY_API_KEY")?;
+```
+
+4. Before deploying a service, add the environment key to the `env_keys` array in the service manifest:
 
 ```json
 "component": {
@@ -66,12 +70,6 @@ WAVS_ENV_MY_API_KEY=your_secret_key_here
 }
 ```
 
-4. Access the environment key from a component:
-
-```rust
-let api_key = std::env::var("WAVS_ENV_MY_API_KEY")?;
-```
-
 ## Local Execution
 
 When running components locally (raw), use the `--config` flag to set values in a KEY=VALUE format, comma-separated: `--config a=1,b=2`.

docs/handbook/overview.mdx

@@ -33,15 +33,14 @@ This handbook provides an overview of the different parts that make up a WAVS AV
 - [Submission and Aggregator](./submission) - Discover how results are submitted to the blockchain through the aggregator service and submission contracts.
 
 ## Components
-- [Component Overview](./components/component) - Learn about the structure and lifecycle of WAVS components, including how to handle triggers and process data.
+- [Component overview](./components/component) - Learn about the structure and lifecycle of WAVS components, including how to handle triggers and process data.
 - [Variables](./components/variables) - Understand how to configure components with public and private variables.
-- [Utilities and Crates](./components/utilities) - Explore the available utilities and crates for building WAVS components.
-- [Blockchain Interactions](./components/blockchain-interactions) - Discover how to interact with blockchains and smart contracts from your components.
-- [Network Requests](./components/network-requests) - Learn how to make HTTP requests to external APIs from your components.
+- [Blockchain interactions](./components/blockchain-interactions) - Discover how to interact with blockchains and smart contracts from your components.
+- [Network requests](./components/network-requests) - Learn how to make HTTP requests to external APIs from your components.
 
 
 ## Development
 - [Template](./template) - Get started with the WAVS template, including its structure, configuration files, and how to customize it for your service.
-- [Makefile Commands](./commands) - Reference for the available makefile commands to build, deploy, and manage your service.
+- [Makefile commands](./commands) - Reference for the available makefile commands to build, deploy, and manage your service.
 
 Each section provides detailed information and examples to help you understand and build your WAVS service. Start with the Service section to understand the basic concepts, then explore the other sections based on your needs.

docs/handbook/service.mdx

@@ -9,11 +9,11 @@ docsignore-->
 
 A service is a collection of smart contracts, operators, and offchain components that make up a WAVS AVS. The different parts of a service are defined in a service manifest or `service.json` file. This file can be stored on IPFS or an HTTP/HTTPS server, and its URL is set on the service manager contract during deployment, allowing the system to fetch the service definition when needed.
 
-The service manifest defines the configuration and different parts of a WAVS service, including information about the service, workflows, components, submission, service manager contract, and more.
+The service manifest defines the configuration and different parts of a WAVS service, including information about the service, [workflows](/handbook/workflows), [components](/handbook/components/component), [submission](/handbook/submission), [service manager contract](#service-manager), and more.
 
 ## Generate Manifest
 
-Easily create this JSON file using the `wavs-cli service` command. The template provides a script to generate a 1 component service with ease, [build_service.sh](https://github.com/Lay3rLabs/wavs-foundry-template/blob/main/script/build_service.sh).
+You can create the service.json file using the `wavs-cli service` command. The template provides a script to generate a single-component service with ease, [build_service.sh](https://github.com/Lay3rLabs/wavs-foundry-template/blob/main/script/build_service.sh).
 
 ## Example Manifest
 

docs/handbook/submission.mdx

@@ -89,8 +89,7 @@ contract SimpleSubmit is ITypes, IWavsServiceHandler {
 
 ## Aggregator
 
-{/* todo: link to design page. */}
-The aggregator is used to collect and validate responses from multiple operators before submitting them to the blockchain. It acts as an intermediary that receives signed responses from operators, validates each operator's signature, aggregates signatures when enough operators have responded, and submits the aggregated data to the submission contract. The aggregator supports exact match aggregation, meaning that consensus is reached if a threshold amount of submitted responses from operators are identical.
+The aggregator is used to collect and validate responses from multiple operators before submitting them to the blockchain. It acts as an intermediary that receives signed responses from operators, validates each operator's signature, aggregates signatures when enough operators have responded, and submits the aggregated data to the submission contract. The aggregator supports exact match aggregation, meaning that consensus is reached if a threshold amount of submitted responses from operators are identical. Visit the [design considerations page](/design) for more information on aggregation and service design.
 
 WAVS currently uses ECDSA signatures for aggregation, but will also support BLS signatures in the future.
 

docs/handbook/triggers.mdx

@@ -14,7 +14,7 @@ A trigger prompts a WAVS service to run. Operators listen for the trigger event
 
 ### Trigger lifecycle
 
-1. A service is deployed with a service.json manifest which contains information on the service and workflow logic (components, triggers, submission logic).
+1. A service is deployed with a service.json manifest which contains information on the service and [workflow](/handbook/workflows) logic (components, triggers, [submission](/handbook/submission) logic).
 
 2. Operators maintain lookup maps to track and verify triggers. For EVM and Cosmos events, they map chain names, contract addresses, and event identifiers to trigger IDs. Block interval triggers are tracked by chain name with countdown timers, while cron triggers are managed in a priority queue ordered by execution time.
 
@@ -62,7 +62,7 @@ pub enum TriggerData {
 
 ## Trigger configuration
 
-Triggers define when and how the component should be executed. Each workflow needs a trigger to be set. They are set in the `trigger` field of the `service.json` file.
+Triggers define when and how the component should be executed. Each workflow needs a trigger to be set. They are set in the `trigger` field of the [`service.json` file](/handbook/service).
 
 ### EVM event trigger
 
@@ -73,7 +73,7 @@ This trigger listens for specific events emitted by contracts on EVM-compatible
 "trigger": {
   "evm_contract_event": {
     "address": "0x00000000219ab540356cbb839cbe05303d7705fa", // Contract address to monitor
-    "chain_name": "ethereum-mainnet", // Chain to monitor
+    "chain_name": "ethereum", // Chain to monitor
     "event_hash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" // Event hash (32 bytes)
   }
 }
@@ -83,18 +83,17 @@ This trigger listens for specific events emitted by contracts on EVM-compatible
 Your evm chain information must be set in `wavs.toml` under the `[default.chains.evm.<chain_name>]` section:
 
 ```toml wavs.toml
-# Local / Testnet
-[default.chains.evm.local]
-chain_id = "31337"
-ws_endpoint = "ws://localhost:8545"
-http_endpoint = "http://localhost:8545"
-poll_interval_ms = 7000
+# Mainnet
+[default.chains.evm.ethereum]
+chain_id = "1"
+ws_endpoint = "wss://eth.drpc.org"
+http_endpoint = "https://eth.drpc.org"
 ```
 
 You'll need to set your EVM chain credential in your `.env` file to establish a connection for monitoring the EVM chain:
 
 ```env .env
-WAVS_CLI_EVM_CREDENTIAL="0x5ce146f435835b1762ed602088740d201b68fd94bf808f97fd04588f1a63c9ab"
+WAVS_CLI_EVM_CREDENTIAL="0x5ze146f435835b1762ed602088740d201b68fd94bf808f97fd04588f1a63c9ab"
 ```
 
 ### Cosmos event trigger

docs/handbook/workflows.mdx

@@ -12,7 +12,7 @@ A WAVS service is a collection of one or more workflows that define the differen
 Each workflow consists of three parts:
 
 - [**Trigger**](./triggers): Defines what event initiates the workflow
-- [**Component**](./component): The WASM component that processes the event
+- [**Component**](./components/component): The WASM component that processes the event
 - [**Submit**](./submission): Specifies where to send the results
 
 ## Workflow Structure