wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/CONFIG_GUIDE.md

@@ -0,0 +1,399 @@
+# Configuration Guide
+
+This guide explains how to configure your strategies for local testing.
+
+## Quick Setup
+
+```bash
+# 1. Generate test wallets (required!)
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
+
+# 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 (loaded directly by clients, not stored in UserConfig)
+  },
+  "system": {
+    "api_base_url": "https://wayfinder.ai/api/v1",
+    "api_key": "sk_live_abc123...",   // OPTIONAL: System-level API key (alternative to user.api_key, loaded directly by clients)
+    "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 (loaded directly by clients from config.json)
+- OR `system.api_key` - System-level API key (alternative location, loaded directly by clients)
+- OR set `WAYFINDER_API_KEY` environment variable
+- OR pass `api_key` parameter to strategy constructor
+
+**Note:** API keys in `config.json` are loaded directly by `WayfinderClient` via `_load_config_credentials()`, not through the `UserConfig` or `SystemConfig` dataclasses. This is intentional to allow flexible credential loading.
+
+**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.strategy_wallet_address` - Override auto-loaded strategy 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 "strategy"
+
+## 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 main wallet (recommended for initial setup)
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
+
+# Add additional wallets for multi-account testing
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 3
+
+# Create a wallet with a specific label (e.g., for a strategy)
+poetry run python wayfinder_paths/scripts/make_wallets.py --label "my_strategy_name"
+
+# Generate keystore files (for geth/web3 compatibility)
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1 --keystore-password "your-password"
+```
+
+This creates `wallets.json` in the repository root with:
+- **main** wallet - your main wallet for testing (labeled "main")
+- Additional wallets with labels if specified
+
+**Note:** Generated wallets are for testing only. Wallet addresses are automatically loaded from `wallets.json` when not explicitly set in config. Strategy-specific wallets are automatically created when you use `just create-strategy "Strategy Name"`.
+
+## 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 dedicated wallet
+4. Falls back to `strategy_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": "main"
+  },
+  {
+    "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
+strategy_address = self.config.get("strategy_wallet").get("address")
+main_address = self.config.get("main_wallet").get("address")
+```
+
+The strategy 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 StrategyJobConfig
+import json
+
+# Load from file
+with open("config.json") as f:
+    config_data = json.load(f)
+
+config = StrategyJobConfig.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 strategy 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_STRATEGY`)
+- 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 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 Paths 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.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 `WayfinderClient._load_config_credentials()` which reads `user.api_key` or `system.api_key`)
+  - `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
+- **Note:** API keys in `config.json` are loaded directly by clients, not stored in the `UserConfig` or `SystemConfig` dataclasses
+
+### 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
+- Strategy 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 StrategyJob:
+
+```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,22 @@
+"""Wayfinder Path - Trading strategies and adapters for automated strategy management"""
+
+__version__ = "0.1.0"
+
+# Re-export commonly used items for convenience
+from wayfinder_paths.core import (
+    BaseAdapter,
+    LiquidationResult,
+    StatusDict,
+    StatusTuple,
+    Strategy,
+    StrategyJob,
+)
+
+__all__ = [
+    "__version__",
+    "BaseAdapter",
+    "Strategy",
+    "StatusDict",
+    "StatusTuple",
+    "StrategyJob",
+]