How it works
WAVS is a decentralized execution framework for AVSs (Autonomous Verifiable Services), enabling the results of off-chain computation to be brought verifiably on-chain. It provides a runtime for executing WASI-based service components, allowing developers to define event-driven off-chain workflows while inheriting Ethereum's security via EigenLayer restaking.
The flow
Before diving into each part of a WAVS service individually, it's important to understand the basic execution flow of WAVS.
-
A service is a collection of on-chain contracts and off-chain logic run by a set of registered operators, bringing the results of off-chain computation on-chain verifiably. A service's operator set is defined in a service manager contract. A service manifest (service.json) defines the configuration and different parts of a WAVS service, including information about the service, workflows, components, submission, watch trigger, aggregator, and more. The service contracts and manifest are deployed and operators register to run the service.
-
Services contain one or more workflows, which define the different execution paths in your service. Each workflow contains a trigger, a service component, and submission logic. Triggers are defined events that activate a workflow. Registered operators running WAVS nodes maintain lookup maps to track and detect triggers. Triggers can be:
- Any on-chain EVM or Cosmos event from a specified contract address and event signature
- Cron jobs that activate at specified intervals
- Blockheight triggers that activate at a specified block height on EVM or Cosmos chains
-
When a trigger is detected, operators run the workflow's corresponding service component off-chain in the WAVS runtime.
-
Each operator signs the result of their off-chain computation and submits it to the aggregator.
-
The aggregator accepts results from the operators and verifies that the result payloads match and that the signatures are valid. Once enough verified submissions are received (the threshold is defined in the service manager), the aggregator submits the bundled signatures and result payloads as a single transaction to the submission contract specified in the service's manifest.
-
The
handleSignedEnvelope()function on the submission contract validates the data and signatures via the service manager contract. The workflow is complete, bringing the result of the off-chain computation verifiably on-chain. Services and workflows can be chained together by setting the submission event of one workflow to be the trigger of another.
WAVS parts
Service manager
The service manager is a contract that defines a service's operator set. It is used to register operators and define their weights, set the threshold for aggregator submissions, and maintain the URI of the service manifest. For more information, see the Service page.
Service manifest
The service manifest is a JSON file that defines the configuration and different parts of a WAVS service, including information about the service, workflows, components, submission, service manager contract, aggregator configuration, and more. For more information, see the Service page.
Workflows
Workflows are the building blocks of a WAVS service flow. They define the different execution paths of a service, including the trigger, component, and submission logic. For more information, see the Workflows page.
Triggers
A trigger is the event that activates a WAVS service. Triggers can be EVM or Cosmos events, cron, or blockheight triggers. When a specified event is triggered, WAVS operators detect it and execute the corresponding service component off-chain. The results are then verified and submitted back on-chain, completing the execution cycle. For more information, see the Triggers page.
Service components
Service components are the heart of the WAVS platform, encapsulating the core logic that powers a service. They contain the off-chain business logic for a service, written in Rust, Go, or JavaScript (with other languages coming soon). These service components are compiled to WASM and are uploaded to the WAVS platform where they can be run by operators. In the WAVS runtime, service components are sandboxed from each other and from the node's operating system. This way, operators and AVS services maintain a clean separation, with AVS builders defining service components and operators having to opt in to each service.
Service components are lightweight and built for adaptability. Building a service used to take thousands of lines of code and the configuration of dozens of files to execute even the simplest logic. With WAVS, service components can consist of a few lines of code that can be dynamically deployed to the WAVS platform.
Service components are also designed for composability: an AVS can chain multiple components together, creating decentralized flows of off-chain and on-chain executions. These intelligent protocols merge the performance of off-chain computation with on-chain verifiability, creating a complex mesh of decentralized transaction flows.
To learn more, visit the Components page. For a hands-on example of a service component, visit the tutorial.
WAVS runtime
The WAVS (WASI-AVS) runtime serves as the off-chain execution environment for all services running on the WAVS platform. Powered by operators running the WAVS node software, it provides a structured framework for deploying and managing service components that run within a WASI (WebAssembly System Interface) environment. You can think of WASI as a lightweight OS-like interface, offering a standard set of APIs that allow service components to perform system-level operations such as file handling and environment interactions. WAVS enables service components to execute securely within this WASI-powered sandbox, ensuring isolation from both the host system and other components.
WASM and WASI
WASM (Web Assembly) is a high-performance, low-level binary format that can be compiled from multiple programming languages. WASM can even run in web browsers at near-native speed. By leveraging WASM, AVSs built with WAVS are lightning-fast, lightweight, and easy to develop.
WASI (WebAssembly System Interface) is a standardized API that enables WASM (WebAssembly) modules to interact with a host system in a secure and platform-independent way. It provides WASM modules with a standardized set of APIs to access system resources. For more information, visit the WASI documentation.
There are significant advantages in leveraging a WASM/WASI-based platform for AVSs:
- Lightweight execution: Service components are lightweight WASM binaries ideal for high-frequency, low-latency AVS tasks.
- Speed: Components can run in the WASI environment at near-native speeds, providing a significant advantage over Dockerized AVSs.
- Low overhead: Instead of each service needing its own dedicated Docker container, the WAVS runtime provides a computational layer that can be used by many components, saving storage and startup time.
- Dynamic deployment: To upgrade a service, simply upload a new component and update your service metadata to point to the new component. No more downtime or coordination of new binaries among operators.
- Security and separation: The WAVS WASI runtime enforces security by sandboxing service components, allowing them to interact with the host (WAVS) only through explicitly permitted WASI APIs.
Registry
WAVS uses a registry to store the WASM components. A service like wa.dev is recommended for proper distribution in production. For more information, visit the Component page.
Signing and aggregation
When a service is triggered, each operator registered to the service will run the service component on their machine and generate the result. These results are signed by the operator before being submitted to an aggregator.
For services that submit results on Ethereum, an off-chain aggregator can be used to conserve gas fees. Instead of each individual operator submitting results of a service directly on-chain, operators sign the results and submit them off-chain to an aggregator, which aggregates the results and submits a result to be posted to the chain in a single transaction. Results are signed using an operator's individual private key to produce an signature, which is used to prove that the result is associated with an operator's specific private and public key pair. The aggregator accepts the result submissions from operators, verifies their validity, and compares the responses. If there is a consensus among valid operator results, the results and verified signatures are submitted on-chain as a single transaction. Support for BLS signatures and a decentralized aggregator are currently under development.
To learn more about the aggregator, visit the Submission and aggregator page. For more discussion on aggregation considerations, visit the Design considerations page.
Submission
A submission contract is the final destination of the results of a service component. Known as a Service Handler, this logic can be any contract as long as it implements the handleSignedEnvelope() function using the IWavsServiceHandler interface to validate data and signatures using the service manager.
After the execution of a service component in the WAVS runtime, the results are aggregated in the aggregator and passed to the submission contract. Developers can use this contract to define their own logic for results and implement different rules depending on the specific needs of their service.
To learn more about the submission contract, visit the Submission page.
Updating a service
Because of the lightweight and portable nature of WebAssembly, WAVS operators only need to run a single Docker image. WAVS provides a runtime for all registered services to run, each sandboxed from the other and from the node's operating system due to the nature of WASI. Operators will need to opt in to running different services by registering to an AVS.
Updates to service logic do not require node upgrades. Instead, developers can dynamically deploy a new service component and update their service manifest. Instead of needing to run a new Docker image every time a service is updated, operators only need to upgrade if there is a breaking change to the WAVS node software itself.