WAVS Dashboard

.claude/skills/wavs/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: wavs
+description: >
+  Develops, deploys, and manages WAVS (WebAssembly-based Actively Validated Services)
+  components and services using the wavs MCP server. Use when the user wants to build a
+  WASM component, deploy a new service, update an existing service, or manage service
+  lifecycle. Triggers on: wavs, wasm component, AVS, service manager,
+  deploy service, scaffold component.
+---
+
+# WAVS Developer Guide
+
+WAVS runs off-chain computation as sandboxed WebAssembly (WASI) components triggered by on-chain events (EVM/Cosmos contract events, cron, block intervals, or manual inputs); execution results are submitted back on-chain through a ServiceManager contract.
+
+---
+
+## MCP Setup
+
+The `wavs:` MCP tools below require `wavs-mcp` to be running and registered with Claude Code.
+
+**One-command setup (recommended)**
+```bash
+npx @wavs/mcp@latest
+```
+Interactive wizard: installs the binary, prompts for URL + token + credentials,
+writes `~/.claude.json` and `~/.wavs/wavs.toml`, installs skill files.
+
+**Using the WAVS desktop app**
+The app auto-starts `wavs-mcp`. Use the "Register with Claude Code" button in
+Settings → MCP Server to register for any project path without leaving the app.
+
+**WAVS repo users**
+```bash
+just setup-claude-mcp [/path/to/project]
+```
+
+**CLI / manual setup**
+```bash
+# 1. Start a WAVS node
+just start-wavs-dev
+
+# 2. Run wavs-mcp (in a separate terminal)
+./target/release/wavs-mcp --wavs-url http://localhost:8000 --token <token>
+
+# 3. Register with Claude Code
+npx @wavs/mcp@latest
+```
+
+> **Local tools** (`scaffold_component`, `build_component`, `get_wit_interface`) work without MCP — useful for component development without a running node.
+
+---
+
+## Choose Your Flow
+
+| User Intent | Follow |
+|-------------|--------|
+| Build a new component from scratch | [`flows/component-dev.md`](flows/component-dev.md) |
+| Deploy a new service with an on-chain contract | [`flows/deployment.md`](flows/deployment.md) |
+| Update a deployed service with a new component | [`flows/update-service.md`](flows/update-service.md) |
+
+When in doubt, start with **component-dev** — it ends with a deployment step.
+
+---
+
+## MCP Tool Categories
+
+| Category | Tools | Auth Required |
+|----------|-------|---------------|
+| **Read** | `get_node_info`, `get_health`, `list_services`, `get_service` | None |
+| **Write** | `deploy_service`, `delete_service` | `--token` |
+| **Dev** | `upload_component`, `save_service`, `simulate_trigger`, `deploy_dev_service`, `query_kv` | Dev endpoints enabled |
+| **Chain-write** | `set_service_uri`, `deploy_service_manager`, `deploy_poa_service_manager`, `register_operator` | `WAVS_MCP_CHAIN_CREDENTIAL` env var |
+| **Local** | `get_wit_interface`, `scaffold_component`, `build_component` | None |
+
+Full tool reference: [`reference/mcp-tools.md`](reference/mcp-tools.md)
+
+---
+
+## Key Configuration
+
+For on-chain operations, credentials are read from `~/.wavs/wavs.toml` (the WAVS home config):
+
+```toml
+[wavs]
+mcp_chain_credential = "0x<private-key>"
+signing_mnemonic = "word1 word2 ... word12"
+```
+
+The WAVS app "Register with Claude" button and `just setup-claude-mcp` write this file automatically.
+
+Dev endpoints must be enabled in `wavs.toml` under `[wavs]`:
+```toml
+dev_endpoints_enabled = true   # Required for upload, save, simulate, deploy_dev
+```
+
+---
+
+## Reference
+
+- [`reference/mcp-tools.md`](reference/mcp-tools.md) — All 20 tools with auth requirements and parameter notes
+- [`reference/service-json.md`](reference/service-json.md) — Service/trigger JSON formats + simulate examples

.claude/skills/wavs/flows/component-dev.md

@@ -0,0 +1,200 @@
+# Component Development Flow
+
+Build, test, and deploy a new WAVS WASM component from scratch.
+
+---
+
+## Checklist
+
+- [ ] **Step 1** — `wavs:wavs_get_wit_interface` — Read WIT definitions to understand available APIs before writing code.
+- [ ] **Step 2** — `wavs:wavs_scaffold_component` — Generate project skeleton (`Cargo.toml` + `src/lib.rs`).
+- [ ] **Step 3** — Implement logic in `src/lib.rs` using the patterns below.
+- [ ] **Step 4** — `wavs:wavs_build_component` — Compile; read stderr and fix errors; repeat until exit code 0.
+- [ ] **Step 5** — `wavs:wavs_upload_component` — Upload `.wasm`; save the returned digest (raw 64-char hex, no `sha256:` prefix).
+- [ ] **Step 6** — `wavs:wavs_deploy_dev_service` (no on-chain contract) **or** follow [`deployment.md`](deployment.md) for a real deployment.
+- [ ] **Step 7** — `wavs:wavs_simulate_trigger` — Verify output.
+
+---
+
+## Scaffold Parameters
+
+```
+name:         lowercase-with-hyphens  (e.g. "price-feed")
+trigger_type: evm_contract_event | cosmos_contract_event | block_interval | cron | manual
+description:  optional one-line description
+```
+
+Place the generated component at `examples/components/{name}/` to use workspace deps automatically.
+
+---
+
+## Component Anatomy
+
+Minimal working component using the prelude:
+
+```rust
+// Brief description of what this component does.
+use example_helpers::prelude::*;
+
+struct Component;
+
+impl Guest for Component {
+    fn run(action: TriggerAction) -> Result<Vec<WasmResponse>, String> {
+        let (trigger_id, data) = decode_trigger_event(action.data)?;
+
+        // Process `data` bytes and compute output.
+        let output = data; // echo the raw input for now
+
+        Ok(vec![encode_trigger_output(
+            trigger_id,
+            &output,
+            action.config.service_id,
+        )])
+    }
+}
+
+export_layer_trigger_world!(Component);
+```
+
+The prelude re-exports: `Guest`, `TriggerAction`, `WasmResponse`, `decode_trigger_event`, `encode_trigger_output`, `export_layer_trigger_world`, and the `host` module.
+
+Full explicit imports (when you need specific types):
+
+```rust
+use example_helpers::bindings::world::{
+    host,
+    wavs::operator::{
+        input::{TriggerAction, TriggerData},
+        output::WasmResponse,
+    },
+    Guest,
+};
+use example_helpers::export_layer_trigger_world;
+use example_helpers::trigger::{decode_trigger_event, encode_trigger_output};
+```
+
+---
+
+## Host APIs
+
+```rust
+host::config_var("my-key")               // → Option<String>; reads service config
+host::log(host::LogLevel::Info, "msg");  // levels: Debug, Info, Warn, Error
+host::get_service()                      // → ServiceInfo (manager address, config, etc.)
+host::get_event_id(None)                 // deterministic event ID (default salt)
+host::get_event_id(Some(salt))           // custom salt (Vec<u8>)
+```
+
+---
+
+## Trigger Type Patterns
+
+```rust
+match action.data {
+    TriggerData::EvmContractEvent(_) | TriggerData::CosmosContractEvent(_) => {
+        let (trigger_id, data) = decode_trigger_event(action.data)?;
+    }
+    TriggerData::Raw(bytes) => {
+        // Plain bytes — trigger_id is 0 for raw/manual triggers.
+        let data = bytes;
+    }
+    TriggerData::Cron { trigger_time } => {
+        // trigger_time: unix timestamp (u64)
+    }
+    TriggerData::BlockInterval { block_height } => {
+        // block_height: u64
+    }
+    _ => return Err("unsupported trigger type".to_string()),
+}
+```
+
+---
+
+## WASI APIs
+
+### Key-Value Store
+
+```rust
+use example_helpers::bindings::world::wasi::keyvalue::{store, atomics};
+
+let bucket = store::open("my-bucket").map_err(|e| e.to_string())?;
+let value: Option<Vec<u8>> = bucket.get("key").map_err(|e| e.to_string())?;
+bucket.set("key", &bytes).map_err(|e| e.to_string())?;
+let new_val = atomics::increment(&bucket, "counter", 1).map_err(|e| e.to_string())?;
+```
+
+### Outbound HTTP
+
+```rust
+use wstd::runtime::block_on;
+
+let bytes = block_on(async {
+    let resp = wstd::http::Client::new()
+        .get("https://api.example.com/data")
+        .send()
+        .await?;
+    resp.bytes().await
+})?;
+```
+
+---
+
+## Cargo.toml Template
+
+Place at `examples/components/{name}/Cargo.toml`:
+
+```toml
+[package]
+name = "{name}"
+edition.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[package.metadata.component]
+package = "wavs-user:{name}"
+
+[dependencies]
+example-helpers = { path = "../../_helpers" }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+# Add for KV store or outbound HTTP:
+# wstd = { workspace = true }
+```
+
+---
+
+## Build Output Paths
+
+After `wavs_build_component` (release mode):
+```
+target/wasm32-wasip1/release/{package_name_with_underscores}.wasm
+```
+
+After `just wasi-build-native {component-name}` (from repo root):
+```
+examples/build/components/{component-name}.wasm
+```
+
+Use the **absolute path** when calling `wavs_upload_component`.
+
+---
+
+## Debugging
+
+**Build errors** (read `stderr` from `wavs_build_component`):
+- `cannot find type` / `unresolved import` — check `example-helpers` path; try `use example_helpers::prelude::*`
+- `the trait bound is not satisfied` — `encode_trigger_output` needs `&[u8]` or `AsRef<[u8]>`
+- `does not implement Guest` — ensure `export_layer_trigger_world!(Component)` is present
+
+**Runtime errors** (from `wavs_simulate_trigger`):
+- Error message comes directly from your `?` or `return Err(...)` calls
+- Add `host::log(host::LogLevel::Debug, &format!("data: {:?}", data))` and re-simulate
+
+**Missing config vars** — component returns `"config var X not found"`:
+- Service definition must include the key in its `config` map
+- Verify with `wavs_get_service`
+
+**Wrong trigger type** — `"unsupported trigger data type"`:
+- The `match` must cover the trigger type configured in the service definition
+- Use `TriggerData::Raw` for manual/simulation testing