wayfinder-paths 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

wayfinder_paths/CONFIG_GUIDE.md

@@ -6,7 +6,9 @@ This guide explains how to configure your vault strategies for local testing.
 
 ```bash
 # 1. Generate test wallets (required!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# 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
@@ -25,11 +27,11 @@ cp wayfinder_paths/config.example.json config.json
     "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
+    "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)
+    "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": {
@@ -48,11 +50,13 @@ cp wayfinder_paths/config.example.json config.json
 **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)
+- `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
@@ -93,24 +97,24 @@ Individual strategies may have their own configuration parameters. Check the str
 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
+# 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 --default --vault -n 3
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 3
 
-# Replace existing wallets
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --override
+# 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 --default --vault --keystore-password "your-password"
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1 --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
+- **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.
+**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
 
@@ -147,7 +151,7 @@ Wallets in `wallets.json` are stored with labels that match strategy directory n
   {
     "address": "0x...",
     "private_key_hex": "...",
-    "label": "default"
+    "label": "main"
   },
   {
     "address": "0x...",
@@ -235,7 +239,7 @@ No code changes are required - existing strategies continue to work.
 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 adapters.evm_transaction_adapter.adapter import EvmTransactionAdapter
 from my_privy_integration import PrivyWalletProvider
 
 # Create your custom wallet provider
@@ -270,7 +274,7 @@ API keys provide service account authentication and are automatically discovered
 
 #### Option A: Strategy Constructor (Programmatic)
 ```python
-from wayfinder_paths.vaults.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
+from wayfinder_paths.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
 
 strategy = StablecoinYieldStrategy(
     config={...},
@@ -301,10 +305,11 @@ export WAYFINDER_API_KEY="sk_live_abc123..."
 - 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()`)
+  - `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)
 

wayfinder_paths/abis/generic/erc20.json

@@ -0,0 +1,383 @@
+[
+    {
+        "constant": true,
+        "inputs": [
+            {
+                "name": "owner",
+                "type": "address"
+            },
+            {
+                "name": "spender",
+                "type": "address"
+            }
+        ],
+        "name": "allowance",
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [
+            {
+                "name": "account",
+                "type": "address"
+            }
+        ],
+        "name": "balanceOf",
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [],
+        "name": "decimals",
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint8"
+            }
+        ],
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [],
+        "name": "name",
+        "outputs": [
+            {
+                "name": "",
+                "type": "string"
+            }
+        ],
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [],
+        "name": "symbol",
+        "outputs": [
+            {
+                "name": "",
+                "type": "string"
+            }
+        ],
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "recipient",
+                "type": "address"
+            },
+            {
+                "name": "amount",
+                "type": "uint256"
+            }
+        ],
+        "name": "transfer",
+        "outputs": [
+            {
+                "name": "",
+                "type": "bool"
+            }
+        ],
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "spender",
+                "type": "address"
+            },
+            {
+                "name": "amount",
+                "type": "uint256"
+            }
+        ],
+        "name": "approve",
+        "outputs": [
+            {
+                "name": "",
+                "type": "bool"
+            }
+        ],
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "tokenA",
+                "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "tokenB",
+                "type": "address"
+            },
+            {
+                "internalType": "bool",
+                "name": "stable",
+                "type": "bool"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountADesired",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountBDesired",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountAMin",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountBMin",
+                "type": "uint256"
+            },
+            {
+                "internalType": "address",
+                "name": "to",
+                "type": "address"
+            },
+            {
+                "internalType": "uint256",
+                "name": "deadline",
+                "type": "uint256"
+            }
+        ],
+        "name": "addLiquidity",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "amountA",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountB",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "liquidity",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "tokenA",
+                "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "tokenB",
+                "type": "address"
+            },
+            {
+                "internalType": "bool",
+                "name": "stable",
+                "type": "bool"
+            },
+            {
+                "internalType": "address",
+                "name": "_factory",
+                "type": "address"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountADesired",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountBDesired",
+                "type": "uint256"
+            }
+        ],
+        "name": "quoteAddLiquidity",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "amountA",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountB",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "liquidity",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "defaultFactory",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "tokenA",
+                "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "tokenB",
+                "type": "address"
+            },
+            {
+                "internalType": "bool",
+                "name": "stable",
+                "type": "bool"
+            },
+            {
+                "internalType": "address",
+                "name": "_factory",
+                "type": "address"
+            },
+            {
+                "internalType": "uint256",
+                "name": "liquidity",
+                "type": "uint256"
+            }
+        ],
+        "name": "quoteRemoveLiquidity",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "amountA",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountB",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "tokenA",
+                "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "tokenB",
+                "type": "address"
+            },
+            {
+                "internalType": "bool",
+                "name": "stable",
+                "type": "bool"
+            },
+            {
+                "internalType": "uint256",
+                "name": "liquidity",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountAMin",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountBMin",
+                "type": "uint256"
+            },
+            {
+                "internalType": "address",
+                "name": "to",
+                "type": "address"
+            },
+            {
+                "internalType": "uint256",
+                "name": "deadline",
+                "type": "uint256"
+            }
+        ],
+        "name": "removeLiquidity",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "amountA",
+                "type": "uint256"
+            },
+            {
+                "internalType": "uint256",
+                "name": "amountB",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "uint256",
+                "name": "_amount",
+                "type": "uint256"
+            }
+        ],
+        "name": "deposit",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "uint256",
+                "name": "_shares",
+                "type": "uint256"
+            }
+        ],
+        "name": "withdraw",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    }
+]

wayfinder_paths/{vaults/adapters → adapters}/balance_adapter/README.md

@@ -2,7 +2,7 @@
 
 Adapter that exposes wallet, token, and pool balances backed by `WalletClient`/`TokenClient` and now orchestrates transfers between the configured main/vault wallets (with ledger bookkeeping).
 
-- Entrypoint: `vaults.adapters.balance_adapter.adapter.BalanceAdapter`
+- Entrypoint: `adapters.balance_adapter.adapter.BalanceAdapter`
 - Manifest: `manifest.yaml`
 - Tests: `test_adapter.py`
 
@@ -14,7 +14,7 @@ The adapter declares both `wallet_read` and `wallet_transfer` capabilities in it
 
 ```python
 from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
-from wayfinder_paths.vaults.adapters.balance_adapter.adapter import BalanceAdapter
+from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
 web3_service = DefaultWeb3Service(config)
 balance = BalanceAdapter(config, web3_service=web3_service)

wayfinder_paths/{vaults/adapters → adapters}/balance_adapter/adapter.py

@@ -1,13 +1,13 @@
 from typing import Any
 
+from wayfinder_paths.adapters.ledger_adapter.adapter import LedgerAdapter
+from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
 from wayfinder_paths.core.clients.TokenClient import TokenClient
 from wayfinder_paths.core.clients.WalletClient import WalletClient
 from wayfinder_paths.core.services.base import Web3Service
 from wayfinder_paths.core.settings import settings
 from wayfinder_paths.core.utils.evm_helpers import resolve_chain_id
-from wayfinder_paths.vaults.adapters.ledger_adapter.adapter import LedgerAdapter
-from wayfinder_paths.vaults.adapters.token_adapter.adapter import TokenAdapter
 
 
 class BalanceAdapter(BaseAdapter):

wayfinder_paths/{vaults/adapters → adapters}/balance_adapter/manifest.yaml

@@ -1,5 +1,5 @@
 schema_version: "0.1"
-entrypoint: "vaults.adapters.balance_adapter.adapter.BalanceAdapter"
+entrypoint: "adapters.balance_adapter.adapter.BalanceAdapter"
 capabilities:
   - "wallet_read"
   - "wallet_transfer"

wayfinder_paths/{vaults/adapters → adapters}/balance_adapter/test_adapter.py

@@ -2,7 +2,7 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from wayfinder_paths.vaults.adapters.balance_adapter.adapter import BalanceAdapter
+from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
 
 class TestBalanceAdapter:
@@ -21,19 +21,25 @@ class TestBalanceAdapter:
         return mock_client
 
     @pytest.fixture
-    def adapter(self, mock_wallet_client, mock_token_client):
+    def mock_web3_service(self):
+        """Mock TokenClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def adapter(self, mock_wallet_client, mock_token_client, mock_web3_service):
         """Create a BalanceAdapter instance with mocked clients for testing"""
         with (
             patch(
-                "wayfinder_paths.vaults.adapters.balance_adapter.adapter.WalletClient",
+                "wayfinder_paths.adapters.balance_adapter.adapter.WalletClient",
                 return_value=mock_wallet_client,
             ),
             patch(
-                "wayfinder_paths.vaults.adapters.balance_adapter.adapter.TokenClient",
+                "wayfinder_paths.adapters.balance_adapter.adapter.TokenClient",
                 return_value=mock_token_client,
             ),
         ):
-            return BalanceAdapter(config={})
+            return BalanceAdapter(config={}, web3_service=mock_web3_service)
 
     @pytest.mark.asyncio
     async def test_health_check(self, adapter):
@@ -68,7 +74,7 @@ class TestBalanceAdapter:
             return_value=(True, mock_response)
         )
 
-        success, data = await adapter.get_all_enriched_token_balances_for_wallet(
+        success, data = await adapter.get_all_balances(
             wallet_address="0x1234567890123456789012345678901234567890",
             enrich=True,
         )

wayfinder_paths/{vaults/adapters → adapters}/brap_adapter/README.md

@@ -26,7 +26,7 @@ The BRAPClient will automatically:
 
 ```python
 from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
-from wayfinder_paths.vaults.adapters.brap_adapter.adapter import BRAPAdapter
+from wayfinder_paths.adapters.brap_adapter.adapter import BRAPAdapter
 
 web3_service = DefaultWeb3Service(config)
 adapter = BRAPAdapter(web3_service=web3_service)

wayfinder_paths/{vaults/adapters → adapters}/brap_adapter/adapter.py

@@ -2,6 +2,8 @@ from typing import Any
 
 from eth_utils import to_checksum_address
 
+from wayfinder_paths.adapters.ledger_adapter.adapter import LedgerAdapter
+from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
 from wayfinder_paths.core.clients.BRAPClient import BRAPClient
 from wayfinder_paths.core.clients.SimulationClient import SimulationClient
@@ -9,8 +11,6 @@ from wayfinder_paths.core.clients.TokenClient import TokenClient
 from wayfinder_paths.core.constants import DEFAULT_SLIPPAGE
 from wayfinder_paths.core.services.base import Web3Service
 from wayfinder_paths.core.settings import settings
-from wayfinder_paths.vaults.adapters.ledger_adapter.adapter import LedgerAdapter
-from wayfinder_paths.vaults.adapters.token_adapter.adapter import TokenAdapter
 
 _NEEDS_CLEAR_APPROVAL = {
     (1, "0xdac17f958d2ee523a2206206994597c13d831ec7"),

wayfinder_paths/{vaults/adapters → adapters}/brap_adapter/manifest.yaml

@@ -1,5 +1,5 @@
 schema_version: "0.1"
-entrypoint: "vaults.adapters.brap_adapter.adapter.BRAPAdapter"
+entrypoint: "adapters.brap_adapter.adapter.BRAPAdapter"
 capabilities:
   - "swap.quote"
   - "swap.execute"

wayfinder_paths/{vaults/adapters → adapters}/brap_adapter/test_adapter.py

@@ -3,7 +3,7 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from wayfinder_paths.vaults.adapters.brap_adapter.adapter import BRAPAdapter
+from wayfinder_paths.adapters.brap_adapter.adapter import BRAPAdapter
 
 
 class TestBRAPAdapter:
@@ -34,7 +34,7 @@ class TestBRAPAdapter:
     def adapter(self, mock_brap_client, mock_web3_service):
         """Create a BRAPAdapter instance with mocked client for testing"""
         with patch(
-            "vaults.adapters.brap_adapter.adapter.BRAPClient",
+            "adapters.brap_adapter.adapter.BRAPClient",
             return_value=mock_brap_client,
         ):
             return BRAPAdapter(web3_service=mock_web3_service)

wayfinder_paths/adapters/hyperlend_adapter/__init__.py

@@ -0,0 +1,7 @@
+"""
+Hyperlend Adapter
+"""
+
+from wayfinder_paths.adapters.hyperlend_adapter.adapter import HyperlendAdapter
+
+__all__ = ["HyperlendAdapter"]

wayfinder_paths/{vaults/adapters → adapters}/hyperlend_adapter/manifest.yaml

@@ -1,5 +1,5 @@
 schema_version: "0.1"
-entrypoint: "vaults.adapters.hyperlend_adapter.adapter.HyperlendAdapter"
+entrypoint: "adapters.hyperlend_adapter.adapter.HyperlendAdapter"
 capabilities:
   - "hyperlend.stable_markets.read"
   - "hyperlend.markets.query"

wayfinder_paths/{vaults/adapters → adapters}/hyperlend_adapter/test_adapter.py

@@ -2,7 +2,7 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from wayfinder_paths.vaults.adapters.hyperlend_adapter.adapter import HyperlendAdapter
+from wayfinder_paths.adapters.hyperlend_adapter.adapter import HyperlendAdapter
 
 
 class TestHyperlendAdapter:
@@ -18,7 +18,7 @@ class TestHyperlendAdapter:
     def adapter(self, mock_hyperlend_client):
         """Create a HyperlendAdapter instance with mocked client for testing"""
         with patch(
-            "wayfinder_paths.vaults.adapters.hyperlend_adapter.adapter.HyperlendClient",
+            "wayfinder_paths.adapters.hyperlend_adapter.adapter.HyperlendClient",
             return_value=mock_hyperlend_client,
         ):
             return HyperlendAdapter()