sync

Author: evanorti

content/docs/benefits.mdx

@@ -1,5 +1,6 @@
 ---
 title: WAVS benefits
+description: Key advantages and use cases of WAVS platform
 ---
 import { Callout } from 'fumadocs-ui/components/callout';
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
@@ -23,7 +24,7 @@ WAVS redefines the AVS paradigm, making AVSs easier to build, less expensive to
         - WASI components have instantaneous initialization vs. Docker's redundant OS layers and slower boot times.
 2. Simplified Development
     - Focus on your application logic, not overhead:
-        - With templates, there’s no need to write multiple custom contracts to parse events or aggregate signatures.
+        - With templates, there's no need to write multiple custom contracts to parse events or aggregate signatures.
         - WAVS handles common AVS infrastructure, leaving AVS developers to focus on their core logic.
 3. Multichain Ready
     - WAVS is built to operate across multiple blockchain environments and will be released with support for EVM networks.

content/docs/design.mdx

@@ -1,5 +1,6 @@
 ---
 title: WAVS design considerations
+description: Best practices and design patterns for WAVS services
 ---
 import { Callout } from 'fumadocs-ui/components/callout';
 import { DocsPage } from 'fumadocs-ui/page';
@@ -10,12 +11,13 @@ WAVS works best with the "serverless function" approach, wherein the priority of
 
 ## Aggregation and deterministic queries
 
-WAVS currently supports "exact match" [aggregation](./how-it-works#signing-and-aggregation), meaning that consensus is reached if 2/3 of submitted responses from operators are identical. This approach fits many common use cases, but it means that developers must build their components to receive and process data only from deterministic or immutable sources, such as:
+WAVS currently supports "exact match" [aggregation](./handbook/submission#aggregator), meaning that consensus is reached if a threshold amount of submitted responses from operators are identical. This approach fits many common use cases, but it means that developers must build their components to receive and process data only from deterministic or immutable sources, such as:
 
 - Data from the input event trigger
 - Ethereum queries at a given block height
 - IPFS data or other Content-Addressable Storage
 - Web2 APIs that are trusted to return the same result on every query
+- Seeded application parameters (e.g. Ollama for AI models)
 
 For example, when designing a price oracle, a **blockheight** or **timestamp** should be specified in the query logic. This ensures that the query is deterministic and that the same data point is retrieved by all operators.
 
@@ -25,7 +27,7 @@ Conversely, a component that is designed to fetch "current price" would be non-d
 
 Persistent state introduces additional challenges in AVS design with WAVS: operators may execute triggers at different times or, in some cases, not run them at all if they join an AVS after it has been running for some time. Components that rely on operator-local mutable state risk failing consensus due to inconsistencies in execution. For these reasons, it is best practice to avoid storing operator-local mutable state within your components.
 
-This functionality would require features such as state synchronization, guaranteed execution ordering, and Merkle-proof validation which are not yet supported.
+This functionality would require features such as state synchronization (P2P), guaranteed execution ordering, and Merkle-proof validation which are not yet supported.
 
 ## Caching
 

content/docs/handbook/ai.mdx

@@ -0,0 +1,184 @@
+---
+title: AI-powered component creation
+description: Use Claude or Cursor to create one-shot components with minimal prompting
+---
+import { Callout } from 'fumadocs-ui/components/callout';
+import { DocsPage } from 'fumadocs-ui/page';
+
+
+The WAVS Foundry Template contains built-in AI rulefiles for creating "one-shot" components with minimal prompting in Cursor or Claude Code.
+
+These rulefiles are an experimental feature and may not work as expected every time. Components created with AI should not be used in production without thorough review and testing.
+
+<Callout title="LLM resources" type="info">
+  For more information on AI tools and AI-accessible documentation, visit the [LLM resources page](/resources/llms).
+</Callout>
+
+## Claude Code
+
+- Follow the [Claude Code installation instructions](https://docs.anthropic.com/en/docs/claude-code/getting-started) to install Claude Code and link your account.
+- The Claude rulefile is `claude.md` and contains instructions for Claude on how to create a component.
+- Learn more about Claude rulefiles: https://docs.anthropic.com/en/docs/claude-code/memory
+
+## Cursor
+
+- Download Cursor: https://www.cursor.com/downloads
+- The Cursor rulefiles are located in the `.cursor/rules` directory.
+- When using Cursor, always attach the `component-rules.mdc` file to the chat with your prompt.
+- Learn more about Cursor rulefiles: https://docs.cursor.com/context/rules
+
+## Using AI to create components
+
+1. Clone the [WAVS Foundry Template](https://github.com/Lay3rLabs/wavs-foundry-template) and follow the system setup requirements in the README.
+
+```sh
+git clone https://github.com/Lay3rLabs/wavs-foundry-template.git
+cd wavs-foundry-template
+git checkout main
+# Follow the system setup requirements in the README.
+```
+
+2. Open Claude Code or Cursor in the root of the template.
+
+```sh
+claude
+# or
+cursor .
+```
+
+<Callout title="Sandboxed Claude Code" type="info">
+
+You can run a sandboxed instance of [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) in a Docker container that only has access to this project's files by running the following command from the root of the project:
+
+```bash docci-ignore
+npm run claude-code
+# or with no restrictions (--dangerously-skip-permissions)
+npm run claude-code:unrestricted
+```
+
+</Callout>
+
+3. Enter your prompt in the agent chat. You can use the following examples as a starting point, or you can create your own prompt.
+
+<Callout title="Attaching rulefiles" type="warn">
+If you are using cursor, always attach `component-rules.mdc` file to the chat with your prompt.
+
+```
+@component-rules.mdc <your prompt>
+```
+
+</Callout>
+
+### Prompt examples
+
+These simple examples are provided to get you started.
+
+#### API component
+
+You can make a very simple prompt to create a component that can bring API responses verifiably onchain by including the API endpoint:
+
+```
+Let's make a component that takes the input of a zip code, queries the openbrewerydb, 
+and returns the breweries in the area.
+@https://api.openbrewerydb.org/v1/breweries?by_postal=92101&per_page=3
+```
+
+#### Contract balance component
+
+You can also make components that interact with the blockchain:
+
+```
+I want to build a new component that takes the input of a wallet address,
+queries the usdt contract, and returns the balance of that address.
+```
+
+#### Verifiable AI component
+
+```
+Please make a component that takes a prompt as input, sends an api request to OpenAI,
+and returns the response.
+
+  Use this api structure:
+  {
+    "seed": $SEED,
+    "model": "gpt-4o",
+    "messages": [
+      {"role": "system", "content": "You are a helpful assistant."},
+      {"role": "user", "content": "<PROMPT>"}
+    ]
+  }
+
+My api key is WAVS_ENV_OPENAI_KEY in my .env file.
+```
+
+You'll need an [OPENAI API account and key](https://platform.openai.com/login) to use this prompt. The agent will include your API key in the component as a [private variable](./components/variables).
+
+Make sure to include your API key in a `.env` file:
+
+```sh
+# copy the .env.example file
+cp .env.example .env
+# place your key in .env (must be prefixed with WAVS_ENV_)
+WAVS_ENV_OPENAI_KEY=your_api_key
+```
+
+This example utilizes the OpenAI API with a [seed](https://platform.openai.com/docs/advanced-usage#reproducible-outputs) to make the response more deterministic. Please note that OpenAI models are not guaranteed to be 100% deterministic. This example is for demonstration purposes and should not be used in production.
+
+## Component creation process
+
+4. After receiving the prompt, the agent will start creating your component. Review the agent's work and accept changes carefully. Make sure to double check what the agent is doing and be safe about accepting changes.
+
+5. The agent will start by planning its component and will create a `plan.md` file. The agent will then make a new component and files according to this plan.
+
+6. The agent will test its component for errors by running validation tests using `make validate-component COMPONENT=your-component`.
+
+7. The agent may need to make changes after running the Validation tests. After making changes, the agent will build the component using `WASI_BUILD_DIR=components/my-component make wasi-build`.
+
+8. After successfully building your component, it's time to test it. The following command can be used to test your component logic without deploying WAVS. Make sure to replace the placeholders with the correct inputs.
+
+```sh
+# Run this command to build the component:
+WASI_BUILD_DIR=components/openai-response make wasi-build
+
+# Once built, test it with:
+export COMPONENT_FILENAME=openai_response.wasm
+export INPUT_DATA="Only respond with yes or no: Is AI beneficial to the world?"
+make wasi-exec
+```
+
+The agent may try to run the `make wasi-exec` command themselves. You should prompt the agent to give you the command instead, as it can't run the command without permissions.
+
+
+9. Your component should execute and return a response. If there are any errors, share them with the agent for troubleshooting.
+
+If you have any questions, join the WAVS DEVS Telegram channel: https://t.me/layer_xyz/818
+
+## Tips for working with AI agents
+
+- While this repo contains rulefiles with enough context for creating simple components, coding agents are unpredictable and may inevitably run into problems.
+- Feel free to update the rulefiles for your specific purposes or if you run into regular errors.
+- Coding agents can sometimes try to over-engineer their fixes for errors. If you feel it is not being productive, it may be beneficial to start fresh. You may need to adjust your prompt.
+- If you are building a complex component, it may be helpful to have the agent build a simple component first and then expand upon it.
+- The agent may try to fix warnings unnecessarily. You can tell the agent to ignore minor warnings and any errors found in `bindings.rs` (it is auto-generated).
+
+### Prompting
+
+This repo is designed to be used with short prompts for simple components. However, often, coding agents will do better with more context.
+
+When creating a prompt, consider the following:
+
+- Agents work best with short, clear instructions.
+- Provide relevant documentation (preferably as an `.md` file or other ai-digestible content).
+- Provide endpoints.
+- You may need to provide API response structure if the agent is not understanding responses.
+- Be specific about what you want the agent to build.
+- Agents work systematically to build components. For best results, agent should make a plan before they start building.
+- Be patient. Coding agents are not perfect. They may make mistakes.
+
+## Troubleshooting
+
+- You can ask the agent to fix errors it may not be able to catch when executing components. Make sure to give the agent full context of the error.
+- LLMs can be unpredictable. Minimal prompts provide a lot of room for creativity/error. If the agent is not able to fix an error after trying, sometimes deleting the component, clearing the history, and starting fresh can help.
+- The agent may try to edit the bindings.rs file to "fix" it. The agent never needs to do this, and you should tell the agent to not do this.
+- The agent is supposed to provide you with the `make wasi-exec` command. Sometimes it will try to run this itself and it will fail. Instead, ask it to give you the command.
+- When copying and pasting the full `make wasi-exec` command, be careful with line breaks. You may need to reformat long lines to avoid breaking the command.

content/docs/handbook/commands.mdx

@@ -0,0 +1,42 @@
+---
+title: Makefile commands
+description: CLI commands for WAVS development
+---
+import { Callout } from 'fumadocs-ui/components/callout';
+import { DocsPage } from 'fumadocs-ui/page';
+
+## Commands
+
+Use `make help` to see all the commands:
+
+```bash
+make help
+```
+
+Here are the available `make` 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) with ABI function | COMPONENT_FILENAME, INPUT_DATA
+wasi-exec-fixed           the same as wasi-exec, except uses a fixed input as bytes (used in Go & TS components) | COMPONENT_FILENAME, INPUT_DATA
+clean                     cleaning the project files
+clean-docker              remove unused docker containers
+validate-component        validate a WAVS component against best practices
+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]
+update-submodules         update the git submodules
+check-requirements        verify system requirements are installed
+```
+
+For more information on commands when using the template, visit the [WAVS tutorial](/tutorial/1-overview).