Template overview

Use the info in this guide to customize the template to create your own custom service. Check out the WAVS design considerations page to learn which use-cases WAVS is best suited for.

Foundry Template structure

The WAVS template is made up of the following main files:

wavs-foundry-template/
├── README.md
├── makefile               # Commands, variables, and configs
├── components/            # WASI components
│   └── evm-price-oracle/
│       ├── src/
│       │   ├── lib.rs         # Main Component logic
│       │   ├── trigger.rs     # Trigger handling
│       │   └── bindings.rs    # Bindings generated by `make build`
│       └── Cargo.toml     # Component dependencies
├── compiled/              # WASM files compiled by `make build`
├── src/
│   ├── contracts/        # Trigger and submission contracts
│   └── interfaces/       # Solidity interfaces
├── script/               # Deployment & interaction scripts
├── wavs.toml             # WAVS service configuration
├── docs/                 # Documentation
├── .cursor/rules/        # Cursor AI rulefiles
├── claude.md             # Claude AI rulefile
└── .env                  # Private environment variables

• The README file contains the tutorial commands.
• The makefile contains commands for building and deploying the service. It also contains configurable variables for the service and deployment.
• The components directory contains the component logic for your service. Running make wasi-build will automatically generate bindings and compile components into the compiled directory.
• The src directory contains the Solidity contracts and interfaces for trigger and submission contracts.
• The script directory contains the scripts used in the makefile commands to deploy, trigger, and test the service.
• The .env file contains private environment variables and keys. Use cp .env.example .env to copy the example .env file.
• The .cursor/rules directory and claude.md file contain rulefiles for building components with Cursor AI and Claude AI agents.

Toml files

There are several toml files in the template that are used to configure the service:

• wavs.toml is used to configure the WAVS service itself, including chains (local, testnets, mainnet) and configurations.
• Cargo.toml in the root directory is used to configure the workspace and includes dependencies, build settings, and component metadata.
• components/*/Cargo.toml in each component directory is used to configure the Rust component and includes dependencies, build settings, and component metadata. It can inherit dependencies from the root Cargo.toml file using workspace = true.

These files can be customized to suit your specific needs, and many settings can be overridden using environment variables.

The following is an example of a component's Cargo.toml file structure:

[package]
name = "evm-price-oracle"
edition.workspace = true
version.workspace = true
authors.workspace = true
rust-version.workspace = true
repository.workspace = true

[dependencies]
wit-bindgen-rt ={ workspace = true }
wavs-wasi-utils = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
alloy-sol-macro = { workspace = true }
wstd = { workspace = true }
alloy-sol-types = { workspace = true }
anyhow = { workspace = true }

[lib]
crate-type = ["cdylib"]

[profile.release]
codegen-units = 1
opt-level = "s"
debug = false
strip = true
lto = true

[package.metadata.component]
package = "component:evm-price-oracle"
target = "wavs:worker/[email protected]"

wavs.toml config

The wavs.toml file contains configuration settings for all WAVS components:

• Default general settings (shared across all processes)
• WAVS server-specific settings
• CLI-specific settings
• Aggregator-specific settings

Environment Variable Overrides

Environment variables can override configuration values using these patterns:

• WAVS server settings: WAVS_<UPPERCASE_KEY>
• CLI settings: WAVS_CLI_<UPPERCASE_KEY>
• Aggregator settings: WAVS_AGGREGATOR_<UPPERCASE_KEY>

Edit on GitHub