wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/CONFIG_GUIDE.md

@@ -0,0 +1,394 @@
+# Configuration Guide
+
+This guide explains how to configure your vault strategies for local testing.
+
+## Quick Setup
+
+```bash
+# 1. Generate test wallets (required!)
+poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+
+# 2. Create your config file
+cp wayfinder_paths/config.example.json config.json
+
+# 3. Edit config.json with your Wayfinder credentials
+# NEVER commit this file - it contains your credentials!
+```
+
+## Configuration Structure
+
+### config.json Structure
+
+```json
+{
+  "user": {
+    "username": "your_username",      // OPTIONAL: For OAuth authentication
+    "password": "your_password",      // OPTIONAL: For OAuth authentication
+    "refresh_token": null,            // OPTIONAL: Alternative to username/password
+    "api_key": "sk_live_abc123..."    // OPTIONAL: For service account authentication
+  },
+  "system": {
+    "api_base_url": "https://wayfinder.ai/api/v1",
+    "api_key": "sk_live_abc123...",   // OPTIONAL: System-level API key (alternative to user.api_key)
+    "wallets_path": "wallets.json"    // Path to your generated wallets.json
+  },
+  "strategy": {
+    "rpc_urls": {                     // RPC endpoints for different chains
+      "1": "https://eth.llamarpc.com",
+      "42161": "https://arb1.arbitrum.io/rpc",
+      "8453": "https://mainnet.base.org",
+      "solana": "https://api.mainnet-beta.solana.com"
+    }
+  }
+}
+```
+
+## User Configuration
+
+**Authentication (choose one method):**
+
+**Option 1: Service Account (API Key) - Recommended for Production**
+- `user.api_key` - Your Wayfinder API key for service account authentication
+- OR `system.api_key` - System-level API key (alternative location)
+- OR set `WAYFINDER_API_KEY` environment variable
+- OR pass `api_key` parameter to strategy constructor
+
+**Option 2: Personal Access (OAuth) - For Development**
+- `user.username` - Your Wayfinder backend username
+- `user.password` - Your Wayfinder backend password
+- OR `user.refresh_token` - Alternative to username/password
+
+**Other Optional fields:**
+- `user.main_wallet_address` - Override auto-loaded main wallet
+- `user.vault_wallet_address` - Override auto-loaded vault wallet
+
+**Security Note:** Never commit `config.json` to version control. Add it to `.gitignore`.
+
+## System Configuration
+
+These are managed automatically by Wayfinder:
+- `api_base_url` - Wayfinder backend API endpoint
+- `wallets_path` - Location of generated wallets.json
+- `job_id` - Auto-generated by Wayfinder
+- `job_type` - Set to "vault"
+
+## Strategy Configuration
+
+### RPC Endpoints
+
+Default RPC URLs are provided for:
+- Ethereum (chain ID: 1)
+- Arbitrum (chain ID: 42161) 
+- Base (chain ID: 8453)
+- Solana
+
+You can override these in `config.json` if needed.
+
+### Strategy-Specific Settings
+
+Individual strategies may have their own configuration parameters. Check the strategy's README for available options.
+
+## Wallet Generation for Testing
+
+Use the built-in script to generate test wallets for local development:
+
+```bash
+# Generate default and vault wallets (recommended)
+poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+
+# Add additional wallets for multi-account testing
+poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault -n 3
+
+# Replace existing wallets
+poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --override
+
+# Generate keystore files (for geth/web3 compatibility)
+poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --keystore-password "your-password"
+```
+
+This creates `wallets.json` in the repository root with:
+- **default** wallet - your main wallet for testing
+- Additional unlabeled wallets if specified
+
+**Note:** Generated wallets are for testing only. Wallet addresses are automatically loaded from `wallets.json` when not explicitly set in config.
+
+## Per-Strategy Wallets
+
+Each strategy should have its own dedicated wallet for isolation and security. The system automatically looks up wallets by strategy directory name.
+
+### How It Works
+
+When you run a strategy:
+1. The system uses the strategy directory name (e.g., `hyperlend_stable_yield_strategy`) to look up a wallet
+2. It searches `wallets.json` for a wallet with a matching `label`
+3. If found, that wallet is used as the strategy's `vault_wallet`
+4. Falls back to `vault_wallet_address` from config if explicitly provided
+
+### Creating a Strategy with Wallet
+
+The easiest way to create a new strategy with its own wallet:
+
+```bash
+# Create a new strategy with dedicated wallet
+just create-strategy "My Strategy Name"
+
+# This automatically:
+# - Creates the strategy directory
+# - Generates a wallet with label matching the directory name
+# - Updates the manifest with the correct name and entrypoint
+```
+
+### Wallet Structure
+
+Wallets in `wallets.json` are stored with labels that match strategy directory names:
+
+```json
+[
+  {
+    "address": "0x...",
+    "private_key_hex": "...",
+    "label": "default"
+  },
+  {
+    "address": "0x...",
+    "private_key_hex": "...",
+    "label": "hyperlend_stable_yield_strategy"
+  },
+  {
+    "address": "0x...",
+    "private_key_hex": "...",
+    "label": "my_awesome_strategy"
+  }
+]
+```
+
+### Manual Wallet Creation
+
+If you need to manually create a wallet for an existing strategy:
+
+```bash
+# Generate a wallet
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
+
+# Then edit wallets.json to add a label matching your strategy directory name:
+# {
+#   "address": "0x...",
+#   "private_key_hex": "...",
+#   "label": "your_strategy_directory_name"
+# }
+```
+
+### Strategy Access
+
+Strategies access wallets the same way as before:
+
+```python
+# In strategy code
+vault_address = self.config.get("vault_wallet").get("address")
+main_address = self.config.get("main_wallet").get("address")
+```
+
+The `vault_wallet` is automatically populated from the wallet with label matching the strategy directory name.
+
+## Loading Configuration
+
+The configuration is loaded automatically when running strategies via `run_strategy.py`:
+
+```bash
+poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --config config.json
+```
+
+For programmatic use:
+
+```python
+from pathlib import Path
+from core.config import VaultConfig
+import json
+
+# Load from file
+with open("config.json") as f:
+    config_data = json.load(f)
+
+config = VaultConfig.from_dict(config_data)
+
+# Configuration now has:
+# - config.user.username & password (for Wayfinder backend)
+# - config.system.api_base_url & wallets_path
+# - config.strategy_config (strategy-specific settings)
+```
+
+## Wallet Abstraction
+
+The vault system supports multiple wallet types through a wallet abstraction layer. By default, adapters use local private keys (self-custodial wallets), but you can inject custom wallet providers for custodial wallets like Privy or Turnkey.
+
+### Default Behavior (Local Wallets)
+
+By default, adapters use `LocalWalletProvider` which resolves private keys from:
+- `wallets.json` (matched by address)
+- Environment variables (`PRIVATE_KEY`, `PRIVATE_KEY_VAULT`)
+- Wallet config in `config.json`
+
+No code changes are required - existing strategies continue to work.
+
+### Using Custom Wallet Providers
+
+To use a custodial wallet provider (e.g., Privy, Turnkey), inject it directly into adapters:
+
+```python
+from vaults.adapters.evm_transaction_adapter.adapter import EvmTransactionAdapter
+from my_privy_integration import PrivyWalletProvider
+
+# Create your custom wallet provider
+privy_provider = PrivyWalletProvider(privy_api_key, privy_wallet_id)
+
+# Inject it into adapters
+adapter = EvmTransactionAdapter(config, wallet_provider=privy_provider)
+```
+
+See `core/wallets/README.md` for details on implementing custom wallet providers.
+
+## Security Best Practices
+
+1. **Never commit `config.json`** - add it to `.gitignore`
+2. **Never commit `wallets.json`** - contains private keys
+3. **Use test wallets** - the script generates throwaway wallets for testing
+4. **Keep credentials secure** - Wayfinder username/password grant access to backend resources
+5. **Set conservative parameters** for initial testing:
+   - Lower leverage ratios
+   - Higher slippage tolerance
+   - Lower position sizes
+
+## Authentication with Wayfinder Backend
+
+Wayfinder Vaults supports **dual authentication** for different use cases:
+
+### 1. Service Account Authentication (API Key)
+
+**Best for:** Backend services, automated systems, and production deployments with higher rate limits.
+
+API keys provide service account authentication and are automatically discovered by all clients. You can provide an API key in three ways:
+
+#### Option A: Strategy Constructor (Programmatic)
+```python
+from wayfinder_paths.vaults.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
+
+strategy = StablecoinYieldStrategy(
+    config={...},
+    api_key="sk_live_abc123..."  # Sets WAYFINDER_API_KEY env var automatically
+)
+```
+
+#### Option B: Environment Variable
+```bash
+export WAYFINDER_API_KEY="sk_live_abc123..."
+```
+
+#### Option C: config.json
+```json
+{
+  "user": {
+    "api_key": "sk_live_abc123..."
+  },
+  "system": {
+    "api_key": "sk_live_abc123..."  // Alternative: system-level API key
+  }
+}
+```
+
+**Priority Order:** Constructor parameter > `config.json` (user.api_key or system.api_key) > `WAYFINDER_API_KEY` environment variable
+
+**How It Works:**
+- When a strategy receives an `api_key`, it sets `os.environ["WAYFINDER_API_KEY"]`
+- All clients created by adapters automatically discover the API key from:
+  - Constructor parameter (if passed)
+  - `config.json` (via `_load_config_credentials()`)
+  - `WAYFINDER_API_KEY` environment variable
+- API keys are included in **all** API requests (including public endpoints) for rate limiting
+- No need to pass API keys explicitly to adapters or clients—they auto-discover it
+
+### 2. Personal Access Authentication (OAuth)
+
+**Best for:** Standalone SDK users and local development.
+
+The `username` and `password` in your config authenticate with the Wayfinder backend to access:
+- Wallet management
+- Transaction signing services
+- Vault execution services
+
+```json
+{
+  "user": {
+    "username": "your_username",
+    "password": "your_password",
+    "refresh_token": null  // Optional: use refresh token instead of username/password
+  }
+}
+```
+
+**Fallback Behavior:**
+- If an API key is not found or authentication fails, the system automatically falls back to OAuth
+- OAuth tokens are automatically refreshed when they expire
+
+### Security Best Practices
+
+- **Never commit credentials** to version control - add `config.json` to `.gitignore`
+- **Use API keys for production** - they provide better rate limits and don't require token refresh
+- **Use OAuth for development** - simpler setup for local testing
+- **Rotate credentials regularly** - especially if exposed or compromised
+
+## Configuration in Strategies
+
+Strategies receive configuration automatically through VaultJob:
+
+```python
+from core.strategies.Strategy import Strategy
+
+class MyStrategy(Strategy):
+    async def setup(self):
+        # Access strategy-specific config
+        target_leverage = self.config.get("target_leverage", 1.0)
+        
+        # Access RPC URLs
+        eth_rpc = self.config.get("rpc_urls", {}).get("1")
+        
+        # Configuration is already loaded from config.json
+```
+
+## Advanced: Custom RPC Endpoints
+
+To use custom RPC endpoints, update the `strategy.rpc_urls` section in `config.json`:
+
+```json
+{
+  "strategy": {
+    "rpc_urls": {
+      "1": "https://your-custom-ethereum-rpc.com",
+      "8453": "https://your-custom-base-rpc.com"
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+**Issue:** "Authentication failed"
+- **If using API key:**
+  - Verify API key is correct and not expired
+  - Check that API key is set in one of: constructor parameter, `config.json` (user.api_key or system.api_key), or `WAYFINDER_API_KEY` env var
+  - Ensure API key has proper permissions for the operations you're performing
+- **If using OAuth:**
+  - Check that `username` and `password` are correct in `config.json`
+  - Verify your Wayfinder account credentials
+  - Try using `refresh_token` instead if you have one
+- **General:**
+  - The system automatically falls back from API key to OAuth if API key authentication fails
+  - Check logs for specific authentication error messages
+
+**Issue:** "Wallet not found"
+- Run the wallet generation script first
+- Check that `wallets.json` exists in repository root
+- Verify `system.wallets_path` in config points to the correct location
+
+**Issue:** "Invalid config"
+- Ensure `config.json` follows the correct structure
+- Check that all required fields are present

wayfinder_paths/__init__.py

@@ -0,0 +1,21 @@
+"""Wayfinder Path - Trading strategies and adapters for automated vault management"""
+
+__version__ = "0.1.0"
+
+# Re-export commonly used items for convenience
+from wayfinder_paths.core import (
+    BaseAdapter,
+    StatusDict,
+    StatusTuple,
+    Strategy,
+    VaultJob,
+)
+
+__all__ = [
+    "__version__",
+    "BaseAdapter",
+    "Strategy",
+    "StatusDict",
+    "StatusTuple",
+    "VaultJob",
+]

wayfinder_paths/config.example.json

@@ -0,0 +1,20 @@
+{
+    "user": {
+      "username": "your_username",
+      "password": "your_password",
+      "refresh_token": null
+    },
+    "system": {
+      "api_base_url": "https://wayfinder.ai/api/v1",
+      "wallets_path": "wallets.json"
+    },
+    "strategy": {
+      "rpc_urls": {
+        "1": "https://eth.llamarpc.com",
+        "42161": "https://arb1.arbitrum.io/rpc",
+        "8453": "https://mainnet.base.org",
+        "solana": "https://api.mainnet-beta.solana.com",
+        "999": "https://rpc.hyperliquid.xyz/evm"
+      }
+    }
+  }

wayfinder_paths/conftest.py

@@ -0,0 +1,31 @@
+"""
+Conftest for wayfinder-paths package tests.
+Adds wayfinder-paths directory to Python path for imports.
+This must run early, so imports like 'from tests.test_utils' work.
+"""
+
+import sys
+from pathlib import Path
+
+# Add wayfinder-paths directory to Python path for imports (for tests.test_utils)
+# This needs to be at index 0 to take precedence over repo root 'tests/' directory
+_wayfinder_path_dir = Path(__file__).parent
+_wayfinder_path_str = str(_wayfinder_path_dir)
+
+
+def pytest_configure(config):
+    """Configure pytest - runs early to set up imports."""
+    if _wayfinder_path_str not in sys.path:
+        sys.path.insert(0, _wayfinder_path_str)
+    elif sys.path.index(_wayfinder_path_str) > 0:
+        # Move to front if it exists but isn't first
+        sys.path.remove(_wayfinder_path_str)
+        sys.path.insert(0, _wayfinder_path_str)
+
+
+# Also set it immediately (in case pytest_configure hasn't run yet)
+if _wayfinder_path_str not in sys.path:
+    sys.path.insert(0, _wayfinder_path_str)
+elif sys.path.index(_wayfinder_path_str) > 0:
+    sys.path.remove(_wayfinder_path_str)
+    sys.path.insert(0, _wayfinder_path_str)

wayfinder_paths/core/__init__.py

@@ -0,0 +1,13 @@
+"""Wayfinder Vaults Core Engine"""
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.engine.VaultJob import VaultJob
+from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
+
+__all__ = [
+    "Strategy",
+    "StatusDict",
+    "StatusTuple",
+    "BaseAdapter",
+    "VaultJob",
+]

wayfinder_paths/core/adapters/BaseAdapter.py

@@ -0,0 +1,48 @@
+from abc import ABC
+from typing import Any
+
+from loguru import logger
+
+
+class BaseAdapter(ABC):
+    """Base adapter class for exchange/protocol integrations"""
+
+    adapter_type: str = None
+
+    def __init__(self, name: str, config: dict[str, Any] | None = None):
+        self.name = name
+        self.config = config or {}
+        self.logger = logger.bind(adapter=self.__class__.__name__)
+
+    async def connect(self) -> bool:
+        """Optional: establish connectivity. Defaults to True."""
+        return True
+
+    async def get_balance(self, asset: str) -> dict[str, Any]:
+        """Optional: provide balance. Default is not implemented."""
+        raise NotImplementedError(
+            f"get_balance not supported by {self.__class__.__name__}"
+        )
+
+    async def health_check(self) -> dict[str, Any]:
+        """
+        Check adapter health and connectivity
+        Returns: Health status dictionary
+        """
+        try:
+            connected = await self.connect()
+            return {
+                "status": "healthy" if connected else "unhealthy",
+                "connected": connected,
+                "adapter": self.adapter_type or self.__class__.__name__,
+            }
+        except Exception as e:
+            return {
+                "status": "error",
+                "error": str(e),
+                "adapter": self.adapter_type or self.__class__.__name__,
+            }
+
+    async def close(self):
+        """Clean up resources"""
+        pass

wayfinder_paths/core/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Core Adapter Module - SDK surface re-export"""
+
+from .base import BaseAdapter
+
+__all__ = ["BaseAdapter"]

wayfinder_paths/core/adapters/base.py

@@ -0,0 +1,5 @@
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+
+__all__ = [
+    "BaseAdapter",
+]

wayfinder_paths/core/clients/AuthClient.py

@@ -0,0 +1,83 @@
+import os
+from typing import Any
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class AuthClient(WayfinderClient):
+    def __init__(self, api_key: str | None = None):
+        """
+        Initialize AuthClient.
+
+        Args:
+            api_key: Optional API key for service account authentication.
+                    If provided, uses API key auth. Otherwise falls back to config.json.
+        """
+        super().__init__(api_key=api_key)
+
+        self.api_base_url = f"{settings.WAYFINDER_API_URL}"
+        self.logger = logger.bind(client="AuthClient")
+
+    def _is_using_api_key(self) -> bool:
+        """Check if API key authentication is being used."""
+        if self._api_key:
+            return True
+
+        try:
+            creds = self._load_config_credentials()
+            if creds.get("api_key"):
+                return True
+            if os.getenv("WAYFINDER_API_KEY"):
+                return True
+        except Exception:
+            pass
+
+        return False
+
+    async def authenticate(
+        self,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        refresh_token: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Obtain an access token via username/password or refresh token.
+
+        Expected endpoints:
+        - POST {api_base_url}/token/ (username, password) -> { access, refresh }
+        - POST {api_base_url}/token/refresh/ (refresh) -> { access }
+        """
+        if refresh_token:
+            self.logger.debug(
+                "AuthClient.authenticate -> POST /token/refresh (refresh provided)"
+            )
+            url = f"{self.api_base_url}/auth/token/refresh/"
+            payload = {"refresh": refresh_token}
+        elif username and password:
+            self.logger.debug(
+                f"AuthClient.authenticate -> POST /token (username provided={bool(username)})"
+            )
+            url = f"{self.api_base_url}/auth/token/"
+            payload = {"username": username, "password": password}
+        else:
+            raise ValueError(
+                "Credentials required: provide username+password or refresh_token"
+            )
+
+        response = await self._request("POST", url, json=payload)
+        response.raise_for_status()
+        data = response.json()
+
+        access = data.get("access") or data.get("access_token")
+        refresh = data.get("refresh") or data.get("refresh_token")
+        if access or refresh:
+            self.set_tokens(access, refresh)
+            self.logger.debug(
+                f"AuthClient.authenticate <- success (access={'yes' if access else 'no'}, refresh={'yes' if refresh else 'no'})"
+            )
+
+        return data