wayfinder-paths 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

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

@@ -2,7 +2,7 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from wayfinder_paths.vaults.adapters.ledger_adapter.adapter import LedgerAdapter
+from wayfinder_paths.adapters.ledger_adapter.adapter import LedgerAdapter
 
 
 class TestLedgerAdapter:
@@ -18,14 +18,14 @@ class TestLedgerAdapter:
     def adapter(self, mock_ledger_client):
         """Create a LedgerAdapter instance with mocked client for testing"""
         with patch(
-            "vaults.adapters.ledger_adapter.adapter.LedgerClient",
+            "adapters.ledger_adapter.adapter.LedgerClient",
             return_value=mock_ledger_client,
         ):
             return LedgerAdapter()
 
     @pytest.mark.asyncio
-    async def test_get_vault_transactions_success(self, adapter, mock_ledger_client):
-        """Test successful vault transaction retrieval"""
+    async def test_get_strategy_transactions_success(self, adapter, mock_ledger_client):
+        """Test successful strategy transaction retrieval"""
         mock_response = {
             "transactions": [
                 {
@@ -37,11 +37,11 @@ class TestLedgerAdapter:
             ],
             "total": 1,
         }
-        mock_ledger_client.get_vault_transactions = AsyncMock(
+        mock_ledger_client.get_strategy_transactions = AsyncMock(
             return_value=mock_response
         )
 
-        success, data = await adapter.get_vault_transactions(
+        success, data = await adapter.get_strategy_transactions(
             wallet_address="0x1234567890123456789012345678901234567890",
             limit=10,
             offset=0,
@@ -49,20 +49,20 @@ class TestLedgerAdapter:
 
         assert success is True
         assert data == mock_response
-        mock_ledger_client.get_vault_transactions.assert_called_once_with(
+        mock_ledger_client.get_strategy_transactions.assert_called_once_with(
             wallet_address="0x1234567890123456789012345678901234567890",
             limit=10,
             offset=0,
         )
 
     @pytest.mark.asyncio
-    async def test_get_vault_transactions_failure(self, adapter, mock_ledger_client):
-        """Test vault transaction retrieval failure"""
-        mock_ledger_client.get_vault_transactions = AsyncMock(
+    async def test_get_strategy_transactions_failure(self, adapter, mock_ledger_client):
+        """Test strategy transaction retrieval failure"""
+        mock_ledger_client.get_strategy_transactions = AsyncMock(
             side_effect=Exception("API Error")
         )
 
-        success, data = await adapter.get_vault_transactions(
+        success, data = await adapter.get_strategy_transactions(
             wallet_address="0x1234567890123456789012345678901234567890"
         )
 
@@ -70,23 +70,25 @@ class TestLedgerAdapter:
         assert "API Error" in data
 
     @pytest.mark.asyncio
-    async def test_get_vault_net_deposit_success(self, adapter, mock_ledger_client):
-        """Test successful vault net deposit retrieval"""
+    async def test_get_strategy_net_deposit_success(self, adapter, mock_ledger_client):
+        """Test successful strategy net deposit retrieval"""
         mock_response = {
             "net_deposit": "1000.00",
             "total_deposits": "1500.00",
             "total_withdrawals": "500.00",
         }
-        mock_ledger_client.get_vault_net_deposit = AsyncMock(return_value=mock_response)
+        mock_ledger_client.get_strategy_net_deposit = AsyncMock(
+            return_value=mock_response
+        )
 
         # Test
-        success, data = await adapter.get_vault_net_deposit(
+        success, data = await adapter.get_strategy_net_deposit(
             wallet_address="0x1234567890123456789012345678901234567890"
         )
 
         assert success is True
         assert data == mock_response
-        mock_ledger_client.get_vault_net_deposit.assert_called_once_with(
+        mock_ledger_client.get_strategy_net_deposit.assert_called_once_with(
             wallet_address="0x1234567890123456789012345678901234567890"
         )
 
@@ -98,7 +100,7 @@ class TestLedgerAdapter:
             "status": "recorded",
             "timestamp": "2024-01-15T10:30:00Z",
         }
-        mock_ledger_client.add_vault_deposit.return_value = mock_response
+        mock_ledger_client.add_strategy_deposit.return_value = mock_response
 
         # Test
         success, data = await adapter.record_deposit(
@@ -112,7 +114,7 @@ class TestLedgerAdapter:
 
         assert success is True
         assert data == mock_response
-        mock_ledger_client.add_vault_deposit.assert_called_once_with(
+        mock_ledger_client.add_strategy_deposit.assert_called_once_with(
             wallet_address="0x1234567890123456789012345678901234567890",
             chain_id=8453,
             token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
@@ -130,7 +132,7 @@ class TestLedgerAdapter:
             "status": "recorded",
             "timestamp": "2024-01-15T11:00:00Z",
         }
-        mock_ledger_client.add_vault_withdraw.return_value = mock_response
+        mock_ledger_client.add_strategy_withdraw.return_value = mock_response
 
         # Test
         success, data = await adapter.record_withdrawal(
@@ -148,21 +150,24 @@ class TestLedgerAdapter:
     @pytest.mark.asyncio
     async def test_record_operation_success(self, adapter, mock_ledger_client):
         """Test successful operation recording"""
+        from wayfinder_paths.core.adapters.models import SWAP
+
         mock_response = {
             "operation_id": "op_123",
             "status": "recorded",
             "timestamp": "2024-01-15T10:45:00Z",
         }
-        mock_ledger_client.add_vault_operation.return_value = mock_response
+        mock_ledger_client.add_strategy_operation.return_value = mock_response
 
         # Test
-        operation_data = {
-            "type": "SWAP",
-            "from_token": "0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-            "to_token": "0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
-            "amount_in": "1000000000000000000",
-            "amount_out": "995000000000000000",
-        }
+        operation_data = SWAP(
+            from_token_id="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+            to_token_id="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+            from_amount="1000000000000000000",
+            to_amount="995000000000000000",
+            from_amount_usd=1000.0,
+            to_amount_usd=995.0,
+        )
 
         success, data = await adapter.record_operation(
             wallet_address="0x1234567890123456789012345678901234567890",
@@ -184,7 +189,7 @@ class TestLedgerAdapter:
                 {"operation": "SWAP", "amount": "200000000000000000"},
             ]
         }
-        mock_ledger_client.get_vault_transactions.return_value = mock_transactions
+        mock_ledger_client.get_strategy_transactions.return_value = mock_transactions
 
         # Test
         success, data = await adapter.get_transaction_summary(

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

@@ -24,7 +24,7 @@ The PoolClient will automatically:
 ### Initialize the Adapter
 
 ```python
-from wayfinder_paths.vaults.adapters.pool_adapter.adapter import PoolAdapter
+from wayfinder_paths.adapters.pool_adapter.adapter import PoolAdapter
 
 # No configuration needed - uses PoolClient with automatic settings
 adapter = PoolAdapter()
@@ -55,17 +55,6 @@ else:
     print(f"Error: {data}")
 ```
 
-### Get Combined Pool Reports
-
-```python
-success, data = await adapter.get_combined_pool_reports()
-if success:
-    reports = data.get("reports", [])
-    print(f"Received {len(reports)} combined reports")
-else:
-    print(f"Error: {data}")
-```
-
 ### Find High Yield Pools
 
 ```python
@@ -194,7 +183,6 @@ The adapter uses the following Wayfinder API endpoints:
 
 - `GET /api/v1/public/pools/?pool_ids=X` - Get pools by IDs
 - `GET /api/v1/public/pools/` - Get all pools
-- `GET /api/v1/public/pools/combined/` - Get combined pool reports
 - `GET /api/v1/public/pools/llama/matches/` - Get Llama matches
 - `GET /api/v1/public/pools/llama/reports/` - Get Llama reports
 
@@ -209,7 +197,7 @@ All methods return a tuple of `(success: bool, data: Any)` where:
 Run the adapter tests:
 
 ```bash
-pytest wayfinder_paths/vaults/adapters/pool_adapter/test_adapter.py -v
+pytest wayfinder_paths/adapters/pool_adapter/test_adapter.py -v
 ```
 
 ## Dependencies

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

@@ -1,7 +1,12 @@
 from typing import Any
 
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.clients.PoolClient import PoolClient
+from wayfinder_paths.core.clients.PoolClient import (
+    LlamaMatch,
+    LlamaReport,
+    PoolClient,
+    PoolList,
+)
 
 
 class PoolAdapter(BaseAdapter):
@@ -27,7 +32,7 @@ class PoolAdapter(BaseAdapter):
 
     async def get_pools_by_ids(
         self, pool_ids: list[str], merge_external: bool | None = None
-    ) -> tuple[bool, Any]:
+    ) -> tuple[bool, PoolList | str]:
         """
         Get pool information by pool IDs.
 
@@ -50,7 +55,7 @@ class PoolAdapter(BaseAdapter):
 
     async def get_all_pools(
         self, merge_external: bool | None = None
-    ) -> tuple[bool, Any]:
+    ) -> tuple[bool, PoolList | str]:
         """
         Get all available pools.
 
@@ -67,21 +72,7 @@ class PoolAdapter(BaseAdapter):
             self.logger.error(f"Error fetching all pools: {e}")
             return (False, str(e))
 
-    async def get_combined_pool_reports(self) -> tuple[bool, Any]:
-        """
-        Get combined pool reports with analytics.
-
-        Returns:
-            Tuple of (success, data) where data is combined reports or error message
-        """
-        try:
-            data = await self.pool_client.get_combined_pool_reports()
-            return (True, data)
-        except Exception as e:
-            self.logger.error(f"Error fetching combined pool reports: {e}")
-            return (False, str(e))
-
-    async def get_llama_matches(self) -> tuple[bool, Any]:
+    async def get_llama_matches(self) -> tuple[bool, dict[str, LlamaMatch] | str]:
         """
         Get Llama protocol matches for pools.
 
@@ -95,7 +86,9 @@ class PoolAdapter(BaseAdapter):
             self.logger.error(f"Error fetching Llama matches: {e}")
             return (False, str(e))
 
-    async def get_llama_reports(self, identifiers: list[str]) -> tuple[bool, Any]:
+    async def get_llama_reports(
+        self, identifiers: list[str]
+    ) -> tuple[bool, dict[str, LlamaReport] | str]:
         """
         Get Llama reports for specific identifiers.
 

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

@@ -1,5 +1,5 @@
 schema_version: "0.1"
-entrypoint: "vaults.adapters.pool_adapter.adapter.PoolAdapter"
+entrypoint: "adapters.pool_adapter.adapter.PoolAdapter"
 capabilities:
   - "pool.read"
   - "pool.analytics"

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

@@ -2,7 +2,7 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from wayfinder_paths.vaults.adapters.pool_adapter.adapter import PoolAdapter
+from wayfinder_paths.adapters.pool_adapter.adapter import PoolAdapter
 
 
 class TestPoolAdapter:
@@ -18,7 +18,7 @@ class TestPoolAdapter:
     def adapter(self, mock_pool_client):
         """Create a PoolAdapter instance with mocked client for testing"""
         with patch(
-            "vaults.adapters.pool_adapter.adapter.PoolClient",
+            "adapters.pool_adapter.adapter.PoolClient",
             return_value=mock_pool_client,
         ):
             return PoolAdapter()

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

@@ -20,7 +20,7 @@ The TokenClient will automatically:
 ### Initialize the Adapter
 
 ```python
-from wayfinder_paths.vaults.adapters.token_adapter.adapter import TokenAdapter
+from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
 
 # No configuration needed - uses TokenClient with automatic settings
 adapter = TokenAdapter()

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

@@ -1,7 +1,11 @@
 from typing import Any
 
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.clients.TokenClient import TokenClient
+from wayfinder_paths.core.clients.TokenClient import (
+    GasToken,
+    TokenClient,
+    TokenDetails,
+)
 
 
 class TokenAdapter(BaseAdapter):
@@ -20,7 +24,7 @@ class TokenAdapter(BaseAdapter):
         super().__init__("token_adapter", config)
         self.token_client = token_client or TokenClient()
 
-    async def get_token(self, query: str) -> tuple[bool, Any]:
+    async def get_token(self, query: str) -> tuple[bool, TokenDetails | str]:
         """
         Get token data by address using the token-details endpoint.
 
@@ -39,7 +43,7 @@ class TokenAdapter(BaseAdapter):
             self.logger.error(f"Error getting token by query {query}: {e}")
             return (False, str(e))
 
-    async def get_token_price(self, token_id: str) -> tuple[bool, Any]:
+    async def get_token_price(self, token_id: str) -> tuple[bool, dict[str, Any] | str]:
         """
         Get token price by token ID or address using the token-details endpoint.
 
@@ -72,7 +76,7 @@ class TokenAdapter(BaseAdapter):
             self.logger.error(f"Error getting token price for {token_id}: {e}")
             return (False, str(e))
 
-    async def get_gas_token(self, chain_code: str) -> tuple[bool, Any]:
+    async def get_gas_token(self, chain_code: str) -> tuple[bool, GasToken | str]:
         """
         Get gas token for a given chain code.
 

wayfinder_paths/adapters/token_adapter/examples.json

@@ -0,0 +1,26 @@
+{
+  "basic_usage": {
+    "description": "Basic usage of TokenAdapter to get token information",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Get token by address\nsuccess, data = await adapter.get_token_by_address(\"0x1234567890abcdef1234567890abcdef12345678\")\nif success:\n    print(f\"Token symbol: {data.get('symbol')}\")\n    print(f\"Token name: {data.get('name')}\")\n    print(f\"Decimals: {data.get('decimals')}\")\nelse:\n    print(f\"Error: {data}\")"
+  },
+  "get_by_token_id": {
+    "description": "Get token information using token ID",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Get token by ID\nsuccess, data = await adapter.get_token_by_id(\"token-12345\")\nif success:\n    print(f\"Token data: {data}\")\nelse:\n    print(f\"Error: {data}\")"
+  },
+  "flexible_lookup": {
+    "description": "Use flexible get_token method that tries both address and token_id",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Try both address and token_id\nsuccess, data = await adapter.get_token(\n    address=\"0x1234567890abcdef1234567890abcdef12345678\",\n    token_id=\"token-12345\"\n)\nif success:\n    print(f\"Found token: {data}\")\nelse:\n    print(f\"Token not found: {data}\")"
+  },
+  "error_handling": {
+    "description": "Proper error handling for various scenarios",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Handle missing parameters\ntry:\n    success, data = await adapter.get_token()\n    if not success:\n        print(f\"Error: {data}\")\nexcept Exception as e:\n    print(f\"Unexpected error: {e}\")\n\n# Handle API errors\nsuccess, data = await adapter.get_token_by_address(\"invalid-address\")\nif not success:\n    print(f\"API error: {data}\")\nelse:\n    print(f\"Token found: {data}\")"
+  },
+  "health_check": {
+    "description": "Check adapter health and connectivity",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Check health\nhealth = await adapter.health_check()\nprint(f\"Adapter status: {health['status']}\")\nprint(f\"Connected: {health['connected']}\")\nprint(f\"Adapter type: {health['adapter']}\")\n\nif health['status'] == 'healthy':\n    print(\"Adapter is ready to use\")\nelse:\n    print(f\"Adapter has issues: {health.get('error', 'Unknown error')}\")"
+  },
+  "batch_operations": {
+    "description": "Perform multiple token lookups efficiently",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\nimport asyncio\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# List of token addresses to lookup\ntoken_addresses = [\n    \"0x1234567890abcdef1234567890abcdef12345678\",\n    \"0xabcdef1234567890abcdef1234567890abcdef12\",\n    \"0x9876543210fedcba9876543210fedcba98765432\"\n]\n\n# Batch lookup\ntoken_data = {}\nfor address in token_addresses:\n    success, data = await adapter.get_token_by_address(address)\n    if success:\n        token_data[address] = data\n    else:\n        print(f\"Failed to get token for {address}: {data}\")\n\nprint(f\"Successfully retrieved {len(token_data)} tokens\")\nfor address, data in token_data.items():\n    print(f\"{address}: {data.get('symbol', 'Unknown')} - {data.get('name', 'Unknown')}\")"
+  }
+}

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

@@ -1,5 +1,5 @@
 schema_version: "0.1"
-entrypoint: "vaults.adapters.token_adapter.adapter.TokenAdapter"
+entrypoint: "adapters.token_adapter.adapter.TokenAdapter"
 capabilities:
   - "token.read"
 dependencies:

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

@@ -2,7 +2,7 @@ from unittest.mock import patch
 
 import pytest
 
-from wayfinder_paths.vaults.adapters.token_adapter.adapter import TokenAdapter
+from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
 
 
 class TestTokenAdapter:

wayfinder_paths/config.example.json

@@ -2,10 +2,12 @@
     "user": {
       "username": "your_username",
       "password": "your_password",
-      "refresh_token": null
+      "refresh_token": null,
+      "api_key": "sk_live_abc123..."
     },
     "system": {
       "api_base_url": "https://wayfinder.ai/api/v1",
+      "api_key": "sk_live_abc123...",
       "wallets_path": "wallets.json"
     },
     "strategy": {

wayfinder_paths/core/__init__.py

@@ -1,7 +1,7 @@
-"""Wayfinder Vaults Core Engine"""
+"""Wayfinder Paths Core Engine"""
 
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.engine.VaultJob import VaultJob
+from wayfinder_paths.core.engine.StrategyJob import StrategyJob
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
 
 __all__ = [
@@ -9,5 +9,5 @@ __all__ = [
     "StatusDict",
     "StatusTuple",
     "BaseAdapter",
-    "VaultJob",
+    "StrategyJob",
 ]

wayfinder_paths/core/adapters/BaseAdapter.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from abc import ABC
 from typing import Any
 
@@ -7,7 +9,7 @@ from loguru import logger
 class BaseAdapter(ABC):
     """Base adapter class for exchange/protocol integrations"""
 
-    adapter_type: str = None
+    adapter_type: str | None = None
 
     def __init__(self, name: str, config: dict[str, Any] | None = None):
         self.name = name
@@ -19,7 +21,22 @@ class BaseAdapter(ABC):
         return True
 
     async def get_balance(self, asset: str) -> dict[str, Any]:
-        """Optional: provide balance. Default is not implemented."""
+        """
+        Get balance for an asset.
+        Optional method that can be overridden by subclasses.
+
+        Args:
+            asset: Asset identifier (token address, token ID, etc.).
+
+        Returns:
+            Dictionary containing balance information.
+
+        Raises:
+            ValueError: If asset is empty or invalid.
+            NotImplementedError: If this adapter does not support balance queries.
+        """
+        if not asset or not isinstance(asset, str) or not asset.strip():
+            raise ValueError("asset must be a non-empty string")
         raise NotImplementedError(
             f"get_balance not supported by {self.__class__.__name__}"
         )
@@ -43,6 +60,6 @@ class BaseAdapter(ABC):
                 "adapter": self.adapter_type or self.__class__.__name__,
             }
 
-    async def close(self):
+    async def close(self) -> None:
         """Clean up resources"""
         pass

wayfinder_paths/core/adapters/models.py

@@ -0,0 +1,41 @@
+"""Pydantic models for ledger operations."""
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SWAP(BaseModel):
+    """Swap operation."""
+
+    type: Literal["SWAP"] = "SWAP"
+    from_token_id: str
+    to_token_id: str
+    from_amount: str
+    to_amount: str
+    from_amount_usd: float
+    to_amount_usd: float
+    transaction_hash: str | None = None
+    transaction_status: str | None = None
+    transaction_receipt: dict[str, Any] | None = None
+
+
+class LEND(BaseModel):
+    type: Literal["LEND"] = "LEND"
+    contract: str
+    amount: int
+
+
+class UNLEND(BaseModel):
+    type: Literal["UNLEND"] = "UNLEND"
+    contract: str
+    amount: int
+
+
+# Type alias for operation types (currently only SWAP is used)
+# Add more operation types here as needed
+Operation = SWAP | LEND | UNLEND
+
+
+class STRAT_OP(BaseModel):
+    op_data: Annotated[Operation, Field(discriminator="type")]

wayfinder_paths/core/clients/BRAPClient.py

@@ -3,8 +3,10 @@ BRAP (Bridge/Router/Adapter Protocol) Client
 Provides access to quote operations via the public quote endpoint.
 """
 
+from __future__ import annotations
+
 import time
-from typing import Any
+from typing import Any, NotRequired, Required, TypedDict
 
 from loguru import logger
 
@@ -13,6 +15,23 @@ from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 from wayfinder_paths.core.settings import settings
 
 
+class BRAPQuote(TypedDict):
+    """BRAP quote response structure"""
+
+    from_token_address: Required[str]
+    to_token_address: Required[str]
+    from_chain_id: Required[int]
+    to_chain_id: Required[int]
+    from_address: Required[str]
+    to_address: Required[str]
+    amount1: Required[str]
+    amount2: NotRequired[str]
+    routes: NotRequired[list[dict[str, Any]]]
+    fees: NotRequired[dict[str, Any] | None]
+    slippage: NotRequired[float | None]
+    wayfinder_fee: NotRequired[float | None]
+
+
 class BRAPClient(WayfinderClient):
     """Client for BRAP quote operations"""
 
@@ -33,7 +52,7 @@ class BRAPClient(WayfinderClient):
         amount1: str,
         slippage: float | None = None,
         wayfinder_fee: float | None = None,
-    ) -> dict[str, Any]:
+    ) -> BRAPQuote:
         """
         Get a quote for a bridge/swap operation.