main -> 0.4 (july 2nd)

.cursor/rules/ai.mdc

@@ -0,0 +1,134 @@
+---
+description: 
+
+alwaysApply: true
+---
+# AI-powered Component Creation
+
+Use Claude or Cursor AI agents to generate WAVS components with minimal prompts. Components created by AI require thorough review and testing before production use.
+
+## Setup
+
+1. Clone the WAVS Foundry Template and complete system setup:
+
+```sh
+git clone https://github.com/Lay3rLabs/wavs-foundry-template.git
+cd wavs-foundry-template
+# Follow README system setup instructions
+```
+
+2. Install and configure Claude Code ([Claude docs](mdc:https:/docs.anthropic.com/en/docs/claude-code/getting-started)) or download Cursor ([Cursor downloads](mdc:https:/www.cursor.com/downloads)).
+
+3. Open Claude or Cursor in the template root:
+
+```sh
+claude
+# or
+cursor .
+```
+
+4. For Cursor, always attach the `component-rules.mdc` file to the chat prompt:
+
+```sh Chat
+@component-rules.mdc <your prompt>
+```
+
+## Prompting AI Agents
+
+- Use short, clear instructions.
+- Provide relevant docs or `.md` files.
+- Include API endpoints and response structures if needed.
+- Be specific about the component functionality.
+- Examples:
+
+API component:
+
+```
+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:
+
+```
+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 (requires OpenAI API key in `.env`):
+
+```
+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.
+```
+
+Set your API key in `.env`:
+
+```sh
+cp .env.example .env
+# Add your key prefixed with WAVS_ENV_
+WAVS_ENV_OPENAI_KEY=your_api_key
+```
+
+## Component Creation Workflow
+
+1. Submit prompt to AI agent.
+
+2. Review the agent's plan in `plan.md`.
+
+3. Agent creates component files.
+
+4. Validate component:
+
+```sh
+make validate-component COMPONENT=your-component
+```
+
+5. Build component:
+
+```sh
+WASI_BUILD_DIR=components/my-component make wasi-build
+```
+
+6. Test component logic (replace placeholders):
+
+```sh
+export COMPONENT_FILENAME=openai_response.wasm
+export INPUT_DATA="Only respond with yes or no: Is AI beneficial to the world?"
+make wasi-exec
+```
+
+- Ask the agent to provide the `make wasi-exec` command; it cannot run commands itself.
+
+7. Troubleshoot errors by sharing logs with the agent.
+
+## Tips & Best Practices
+
+- AI agents may be unpredictable; update rulefiles if needed.
+- For complex components, build simple versions first.
+- Ignore minor warnings and errors in `bindings.rs` (auto-generated).
+- Avoid letting the agent edit `bindings.rs`.
+- If stuck, clear history and start fresh with adjusted prompts.
+- Be patient; agents may over-engineer fixes or make mistakes.
+
+## Troubleshooting
+
+- Provide full error context to the agent.
+- Avoid letting the agent run commands; request commands instead.
+- Reformat long commands to avoid line break issues.
+
+For support, join the WAVS DEVS Telegram: https://t.me/layer_xyz/818
+
+For more information:
+- [Claude Code Getting Started](mdc:https:/docs.anthropic.com/en/docs/claude-code/getting-started)
+- [Cursor Downloads](mdc:https:/www.cursor.com/downloads)
+- [WAVS Foundry Template GitHub](mdc:https:/github.com/Lay3rLabs/wavs-foundry-template)
+- [OpenAI Platform](mdc:https:/platform.openai.com/login)

.cursor/rules/blockchain-interactions.mdc

@@ -0,0 +1,158 @@
+---
+description: Guide for interacting with Ethereum and EVM-compatible blockchains from WAVS components using Rust crates and configuration.
+
+alwaysApply: true
+---
+# Blockchain Interactions in WAVS Components
+
+Use the `wavs-wasi-utils` crate and Alloy ecosystem crates to interact with Ethereum and other EVM chains from WAVS components. Define chain configs in `wavs.toml` and generate Rust types from Solidity using the `sol!` macro.
+
+1. **Setup Dependencies**
+
+Add these to your `Cargo.toml`:
+
+```toml
+[dependencies]
+wit-bindgen-rt = { workspace = true, features = ["bitflags"] }
+wavs-wasi-utils = "0.4.0-beta.4"
+wstd = "0.5.3"
+
+alloy-sol-macro = { version = "1.1.0", features = ["json"] }
+alloy-sol-types = "1.1.0"
+alloy-network = "0.15.10"
+alloy-provider = { version = "0.15.10", default-features = false, features = ["rpc-api"] }
+alloy-rpc-types = "0.15.10"
+alloy-contract = "0.15.10"
+
+anyhow = "1.0.98"
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.140"
+```
+
+2. **Configure Chains**
+
+Define RPC endpoints and chain IDs in `wavs.toml`:
+
+```toml wavs.toml
+[default.chains.evm.local]
+chain_id = "31337"
+ws_endpoint = "ws://localhost:8545"
+http_endpoint = "http://localhost:8545"
+poll_interval_ms = 7000
+
+[default.chains.evm.ethereum]
+chain_id = "1"
+ws_endpoint = "wss://eth.drpc.org"
+http_endpoint = "https://eth.drpc.org"
+```
+
+3. **Generate Rust Types from Solidity**
+
+Use the `sol!` macro to parse Solidity interfaces and generate Rust types:
+
+```rust
+mod solidity {
+    use alloy_sol_macro::sol;
+
+    // From file
+    sol!("../../src/interfaces/ITypes.sol");
+
+    // Inline definitions
+    sol! {
+        struct TriggerInfo {
+            uint64 triggerId;
+            bytes data;
+        }
+
+        event NewTrigger(TriggerInfo _triggerInfo);
+    }
+}
+```
+
+Example in `trigger.rs`:
+
+```rust trigger.rs
+pub mod solidity {
+    use alloy_sol_macro::sol;
+    pub use ITypes::*;
+
+    sol!("../../src/interfaces/ITypes.sol");
+
+    sol! {
+        function addTrigger(string data) external;
+    }
+}
+```
+
+4. **Access Chain Config and Create Provider**
+
+Use WAVS host bindings and `new_evm_provider` to create an RPC provider:
+
+```rust lib.rs
+use crate::bindings::host::get_evm_chain_config;
+use alloy_network::Ethereum;
+use alloy_provider::RootProvider;
+use wavs_wasi_utils::evm::new_evm_provider;
+
+let chain_config = get_evm_chain_config("local").unwrap();
+
+let provider: RootProvider<Ethereum> = new_evm_provider::<Ethereum>(
+    chain_config.http_endpoint.unwrap(),
+);
+```
+
+5. **Example: Query ERC721 NFT Balance**
+
+```rust lib.rs
+use crate::bindings::host::get_evm_chain_config;
+use alloy_network::Ethereum;
+use alloy_provider::RootProvider;
+use alloy_sol_types::sol;
+use wavs_wasi_utils::evm::{
+    alloy_primitives::{Address, U256},
+    new_evm_provider,
+};
+use alloy_rpc_types::TransactionInput;
+use wstd::runtime::block_on;
+
+sol! {
+    interface IERC721 {
+        function balanceOf(address owner) external view returns (uint256);
+    }
+}
+
+pub fn query_nft_ownership(address: Address, nft_contract: Address) -> Result<bool, String> {
+    block_on(async move {
+        let chain_config = get_evm_chain_config("local").unwrap();
+        let provider: RootProvider<Ethereum> = new_evm_provider::<Ethereum>(
+            chain_config.http_endpoint.unwrap()
+        );
+
+        let balance_call = IERC721::balanceOf { owner: address };
+
+        let tx = alloy_rpc_types::eth::TransactionRequest {
+            to: Some(TxKind::Call(nft_contract)),
+            input: TransactionInput { input: Some(balance_call.abi_encode().into()), data: None },
+            ..Default::default()
+        };
+
+        let result = provider.call(tx).await.map_err(|e| e.to_string())?;
+
+        let balance: U256 = U256::from_be_slice(&result);
+        Ok(balance > U256::ZERO)
+    })
+}
+```
+
+6. **Additional Notes**
+
+- Use `alloy-contract` crate for higher-level contract interactions.
+- The `decode_event_log_data` macro decodes Ethereum event logs from triggers into Rust types implementing `SolEvent`.
+- Re-run `cargo build` after updating Solidity files used with `sol!`.
+
+For more information:
+- [wavs-wasi-utils crate](https://docs.rs/wavs-wasi-utils/latest/wavs_wasi_utils/)
+- [Alloy crate ecosystem](https://docs.rs/alloy/latest/alloy/)
+- [sol! macro documentation](https://docs.rs/alloy-sol-macro/latest/alloy_sol_macro/macro.sol.html)
+- [alloy-contract crate](https://crates.io/crates/alloy-contract)
+- [Example NFT query](https://github.com/Lay3rLabs/wavs-art/blob/main/components/autonomous-artist/src/evm.rs)

.cursor/rules/commands.mdc

@@ -0,0 +1,45 @@
+---
+description: Overview of Makefile commands for WAVS development CLI
+
+alwaysApply: true
+---
+# Makefile Commands for WAVS Development
+
+Use `make help` to list all available commands for building, testing, deploying, and managing WAVS projects.
+
+1. Run `make help` to see all commands:
+```bash
+make help
+```
+
+2. Common commands and their purposes:
+```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           same as wasi-exec but uses fixed byte input (for 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                       format Solidity and Rust code
+test                      run tests
+setup                     install initial dependencies
+start-all-local           start anvil and core services (e.g., IPFS)
+get-trigger-from-deploy   get trigger address from deployment script
+get-submit-from-deploy    get submit address from deployment script
+wavs-cli                  run wavs-cli in docker
+upload-component          upload WAVS component | COMPONENT_FILENAME, WAVS_ENDPOINT
+deploy-service            deploy WAVS component service JSON | SERVICE_URL, CREDENTIAL, WAVS_ENDPOINT
+get-trigger               get trigger id | SERVICE_TRIGGER_ADDR, RPC_URL
+show-result               show result | SERVICE_SUBMISSION_ADDR, TRIGGER_ID, RPC_URL
+upload-to-ipfs            upload service config to IPFS | SERVICE_FILE, [PINATA_API_KEY]
+update-submodules         update git submodules
+check-requirements        verify system requirements are installed
+```
+
+3. Use the commands with appropriate environment variables or arguments as indicated.
+
+4. Best practice: Use `validate-component` before deployment to ensure compliance with WAVS standards.
+
+For more information:
+- [WAVS tutorial](https://docs.wavs.dev/tutorial/1-overview)