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

wayfinder_paths/core/clients/SimulationClient.py

@@ -3,14 +3,26 @@ Simulation Client
 Handles blockchain transaction simulations via Gorlami/Tenderly
 """
 
+from __future__ import annotations
+
 import time
-from typing import Any
+from typing import NotRequired, Required, TypedDict
 
 from loguru import logger
 
 from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 
 
+class SimulationResult(TypedDict):
+    """Simulation result structure"""
+
+    success: Required[bool]
+    gas_used: NotRequired[str | None]
+    gas_price: NotRequired[str | None]
+    balances: NotRequired[dict[str, str]]
+    error: NotRequired[str | None]
+
+
 class SimulationClient(WayfinderClient):
     """Client for blockchain transaction simulations"""
 
@@ -25,7 +37,7 @@ class SimulationClient(WayfinderClient):
         amount: str,
         chain_id: int,
         initial_balances: dict[str, str],
-    ) -> dict[str, Any]:
+    ) -> SimulationResult:
         """
         Simulate sending native ETH or ERC20 tokens.
 
@@ -77,7 +89,7 @@ class SimulationClient(WayfinderClient):
         chain_id: int,
         initial_balances: dict[str, str],
         clear_approval_first: bool = False,
-    ) -> dict[str, Any]:
+    ) -> SimulationResult:
         """
         Simulate ERC20 token approval.
 
@@ -132,7 +144,7 @@ class SimulationClient(WayfinderClient):
         from_address: str,
         slippage: float,
         initial_balances: dict[str, str],
-    ) -> dict[str, Any]:
+    ) -> SimulationResult:
         """
         Simulate token swap operation.
 

wayfinder_paths/core/clients/TokenClient.py

@@ -3,13 +3,44 @@ Token Adapter
 Handles token information, prices, and parsing
 """
 
-from typing import Any
+from __future__ import annotations
+
+from typing import NotRequired, Required, TypedDict
 
 from wayfinder_paths.core.clients.AuthClient import AuthClient
 from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 from wayfinder_paths.core.settings import settings
 
 
+class TokenDetails(TypedDict):
+    """Token details response structure"""
+
+    id: Required[str]
+    address: Required[str]
+    symbol: Required[str]
+    name: Required[str]
+    decimals: Required[int]
+    chain_id: Required[int]
+    chain_code: Required[str]
+    price_usd: NotRequired[float]
+    price: NotRequired[float]
+    image_url: NotRequired[str | None]
+    coingecko_id: NotRequired[str | None]
+
+
+class GasToken(TypedDict):
+    """Gas token response structure"""
+
+    id: Required[str]
+    address: Required[str]
+    symbol: Required[str]
+    name: Required[str]
+    decimals: Required[int]
+    chain_id: Required[int]
+    chain_code: Required[str]
+    price_usd: NotRequired[float]
+
+
 class TokenClient(WayfinderClient):
     """Adapter for token-related operations"""
 
@@ -22,7 +53,7 @@ class TokenClient(WayfinderClient):
 
     async def get_token_details(
         self, token_id: str, force_refresh: bool = False
-    ) -> dict[str, Any]:
+    ) -> TokenDetails:
         """
         Get token data including price from the token-details endpoint
 
@@ -44,7 +75,7 @@ class TokenClient(WayfinderClient):
         data = response.json()
         return data.get("data", data)
 
-    async def get_gas_token(self, chain_code: str) -> dict[str, Any]:
+    async def get_gas_token(self, chain_code: str) -> GasToken:
         """
         Fetch the native gas token for a given chain code via public endpoint.
         Example: GET /api/v1/public/tokens/gas/?chain_code=base
@@ -56,18 +87,3 @@ class TokenClient(WayfinderClient):
         response.raise_for_status()
         data = response.json()
         return data.get("data", data)
-
-    async def is_native_token(
-        self, token_address: str, chain_id: int
-    ) -> dict[str, Any]:
-        """
-        Determine if a token address corresponds to the native gas token on a chain.
-        Returns the API payload (usually includes an `is_native` boolean).
-        """
-        url = f"{settings.WAYFINDER_API_URL}/public/tokens/is-native/"
-        params = {"token_address": token_address, "chain_id": str(chain_id)}
-        # Public endpoint: do not pass auth headers
-        response = await self._request("GET", url, params=params, headers={})
-        response.raise_for_status()
-        data = response.json()
-        return data.get("data", data)

wayfinder_paths/core/clients/TransactionClient.py

@@ -3,13 +3,29 @@ Transaction Client
 Handles transaction building, gas estimation, and monitoring
 """
 
-from typing import Any
+from __future__ import annotations
+
+from typing import NotRequired, Required, TypedDict
 
 from wayfinder_paths.core.clients.AuthClient import AuthClient
 from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 from wayfinder_paths.core.settings import settings
 
 
+class TransactionPayload(TypedDict):
+    """Transaction payload structure"""
+
+    from_address: Required[str]
+    to_address: Required[str]
+    token_address: Required[str]
+    amount: Required[str]
+    chain_id: Required[int]
+    data: NotRequired[str | None]
+    value: NotRequired[str | None]
+    gas_limit: NotRequired[str | None]
+    gas_price: NotRequired[str | None]
+
+
 class TransactionClient(WayfinderClient):
     """Client for transaction operations"""
 
@@ -27,7 +43,7 @@ class TransactionClient(WayfinderClient):
         token_address: str,
         amount: float,
         chain_id: int,
-    ) -> dict[str, Any]:
+    ) -> TransactionPayload:
         """
         Build a send transaction payload for EVM tokens/native transfers.
 

wayfinder_paths/core/clients/WalletClient.py

@@ -3,13 +3,44 @@ Wallet Client
 Fetches wallet-related data such as aggregated balances for the authenticated user.
 """
 
-from typing import Any
+from __future__ import annotations
+
+from typing import NotRequired, Required, TypedDict
 
 from wayfinder_paths.core.clients.AuthClient import AuthClient
 from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 from wayfinder_paths.core.settings import settings
 
 
+class TokenBalance(TypedDict):
+    """Token balance response structure"""
+
+    token_id: Required[str]
+    wallet_address: Required[str]
+    balance: Required[str]
+    balance_human: NotRequired[float | None]
+    usd_value: NotRequired[float | None]
+
+
+class PoolBalance(TypedDict):
+    """Pool balance response structure"""
+
+    pool_address: Required[str]
+    chain_id: Required[int]
+    user_address: Required[str]
+    balance: Required[str]
+    balance_human: NotRequired[float | None]
+    usd_value: NotRequired[float | None]
+
+
+class EnrichedBalances(TypedDict):
+    """Enriched token balances response structure"""
+
+    wallet_address: Required[str]
+    balances: Required[list[TokenBalance]]
+    total_usd_value: NotRequired[float | None]
+
+
 class WalletClient(WayfinderClient):
     def __init__(self, api_key: str | None = None):
         super().__init__(api_key=api_key)
@@ -22,7 +53,7 @@ class WalletClient(WayfinderClient):
         token_id: str,
         wallet_address: str,
         human_readable: bool = True,
-    ) -> dict[str, Any]:
+    ) -> TokenBalance:
         """
         Fetch a single token balance for an explicit wallet address.
 
@@ -45,7 +76,7 @@ class WalletClient(WayfinderClient):
         chain_id: int,
         user_address: str,
         human_readable: bool = True,
-    ) -> dict[str, Any]:
+    ) -> PoolBalance:
         """
         Fetch a wallet's LP/share balance for a given pool address and chain.
 
@@ -69,7 +100,7 @@ class WalletClient(WayfinderClient):
         enrich: bool = True,
         from_cache: bool = False,
         add_llama: bool = True,
-    ) -> dict[str, Any]:
+    ) -> EnrichedBalances:
         """
         Fetch all token balances for a wallet with enrichment via the enriched endpoint.
 

wayfinder_paths/core/clients/WayfinderClient.py

@@ -6,6 +6,7 @@ from typing import Any
 import httpx
 from loguru import logger
 
+from wayfinder_paths.core.constants.base import DEFAULT_HTTP_TIMEOUT
 from wayfinder_paths.core.settings import settings
 
 
@@ -19,7 +20,7 @@ class WayfinderClient:
                     If provided, uses API key auth. Otherwise falls back to config.json.
         """
         self.api_base_url = f"{settings.WAYFINDER_API_URL}/"
-        timeout = httpx.Timeout(30.0)
+        timeout = httpx.Timeout(DEFAULT_HTTP_TIMEOUT)
         self.client = httpx.AsyncClient(timeout=timeout)
 
         self.headers = {
@@ -101,7 +102,16 @@ class WayfinderClient:
                 "refresh_token": user.get("refresh_token"),
                 "api_key": user.get("api_key") or system.get("api_key"),
             }
-        except Exception:
+        except (FileNotFoundError, json.JSONDecodeError, OSError) as e:
+            logger.debug(f"Could not load config file at {path}: {e}")
+            return {
+                "username": None,
+                "password": None,
+                "refresh_token": None,
+                "api_key": None,
+            }
+        except Exception as e:
+            logger.warning(f"Unexpected error loading config file at {path}: {e}")
             return {
                 "username": None,
                 "password": None,
@@ -161,9 +171,10 @@ class WayfinderClient:
                     data = response.json()
                     access = data.get("access") or data.get("access_token")
                     refresh = data.get("refresh") or data.get("refresh_token")
-                    self.set_tokens(access, refresh)
-                    return bool(access)
-            except Exception:
+                self.set_tokens(access, refresh)
+                return bool(access)
+            except Exception as e:
+                logger.debug(f"Failed to authenticate with username/password: {e}")
                 pass
 
         raise PermissionError(

wayfinder_paths/core/clients/protocols.py

@@ -7,7 +7,39 @@ When used as an SDK, users can provide custom implementations that match these p
 Note: AuthClient is excluded as SDK users handle their own authentication.
 """
 
-from typing import Any, Protocol
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from wayfinder_paths.core.clients.BRAPClient import BRAPQuote
+    from wayfinder_paths.core.clients.HyperlendClient import (
+        AssetsView,
+        LendRateHistory,
+        MarketEntry,
+        StableMarket,
+    )
+    from wayfinder_paths.core.clients.LedgerClient import (
+        NetDeposit,
+        StrategyTransactionList,
+        TransactionRecord,
+    )
+    from wayfinder_paths.core.clients.PoolClient import (
+        LlamaMatch,
+        LlamaReport,
+        PoolList,
+    )
+    from wayfinder_paths.core.clients.SimulationClient import SimulationResult
+    from wayfinder_paths.core.clients.TokenClient import (
+        GasToken,
+        TokenDetails,
+    )
+    from wayfinder_paths.core.clients.TransactionClient import TransactionPayload
+    from wayfinder_paths.core.clients.WalletClient import (
+        EnrichedBalances,
+        PoolBalance,
+        TokenBalance,
+    )
 
 
 class TokenClientProtocol(Protocol):
@@ -15,20 +47,14 @@ class TokenClientProtocol(Protocol):
 
     async def get_token_details(
         self, token_id: str, force_refresh: bool = False
-    ) -> dict[str, Any]:
+    ) -> TokenDetails:
         """Get token data including price from the token-details endpoint"""
         ...
 
-    async def get_gas_token(self, chain_code: str) -> dict[str, Any]:
+    async def get_gas_token(self, chain_code: str) -> GasToken:
         """Fetch the native gas token for a given chain code"""
         ...
 
-    async def is_native_token(
-        self, token_address: str, chain_id: int
-    ) -> dict[str, Any]:
-        """Determine if a token address corresponds to the native gas token on a chain"""
-        ...
-
 
 class HyperlendClientProtocol(Protocol):
     """Protocol for Hyperlend-related operations"""
@@ -41,7 +67,7 @@ class HyperlendClientProtocol(Protocol):
         buffer_bps: int | None = None,
         min_buffer_tokens: float | None = None,
         is_stable_symbol: bool | None = None,
-    ) -> dict[str, Any]:
+    ) -> list[StableMarket]:
         """Fetch stable markets from Hyperlend"""
         ...
 
@@ -50,7 +76,7 @@ class HyperlendClientProtocol(Protocol):
         *,
         chain_id: int,
         user_address: str,
-    ) -> dict[str, Any]:
+    ) -> AssetsView:
         """Fetch assets view for a user address from Hyperlend"""
         ...
 
@@ -59,7 +85,7 @@ class HyperlendClientProtocol(Protocol):
         *,
         chain_id: int,
         token_address: str,
-    ) -> dict[str, Any]:
+    ) -> MarketEntry:
         """Fetch market entry from Hyperlend"""
         ...
 
@@ -69,35 +95,35 @@ class HyperlendClientProtocol(Protocol):
         chain_id: int,
         token_address: str,
         lookback_hours: int,
-    ) -> dict[str, Any]:
+    ) -> LendRateHistory:
         """Fetch lend rate history from Hyperlend"""
         ...
 
 
 class LedgerClientProtocol(Protocol):
-    """Protocol for vault transaction history and bookkeeping operations"""
+    """Protocol for strategy transaction history and bookkeeping operations"""
 
-    async def get_vault_transactions(
+    async def get_strategy_transactions(
         self,
         *,
         wallet_address: str,
         limit: int = 50,
         offset: int = 0,
-    ) -> dict[str, Any]:
-        """Fetch a paginated list of transactions for a given vault wallet"""
+    ) -> StrategyTransactionList:
+        """Fetch a paginated list of transactions for a given strategy wallet"""
         ...
 
-    async def get_vault_net_deposit(self, *, wallet_address: str) -> dict[str, Any]:
-        """Fetch the net deposit (deposits - withdrawals) for a vault"""
+    async def get_strategy_net_deposit(self, *, wallet_address: str) -> NetDeposit:
+        """Fetch the net deposit (deposits - withdrawals) for a strategy"""
         ...
 
-    async def get_vault_latest_transactions(
+    async def get_strategy_latest_transactions(
         self, *, wallet_address: str
-    ) -> dict[str, Any]:
-        """Fetch the latest transactions for a vault"""
+    ) -> StrategyTransactionList:
+        """Fetch the latest transactions for a strategy"""
         ...
 
-    async def add_vault_deposit(
+    async def add_strategy_deposit(
         self,
         *,
         wallet_address: str,
@@ -107,11 +133,11 @@ class LedgerClientProtocol(Protocol):
         usd_value: str | float,
         data: dict[str, Any] | None = None,
         strategy_name: str | None = None,
-    ) -> dict[str, Any]:
-        """Record a deposit for a vault"""
+    ) -> TransactionRecord:
+        """Record a deposit for a strategy"""
         ...
 
-    async def add_vault_withdraw(
+    async def add_strategy_withdraw(
         self,
         *,
         wallet_address: str,
@@ -121,32 +147,19 @@ class LedgerClientProtocol(Protocol):
         usd_value: str | float,
         data: dict[str, Any] | None = None,
         strategy_name: str | None = None,
-    ) -> dict[str, Any]:
-        """Record a withdrawal for a vault"""
+    ) -> TransactionRecord:
+        """Record a withdrawal for a strategy"""
         ...
 
-    async def add_vault_operation(
+    async def add_strategy_operation(
         self,
         *,
         wallet_address: str,
         operation_data: dict[str, Any],
         usd_value: str | float,
         strategy_name: str | None = None,
-    ) -> dict[str, Any]:
-        """Record a vault operation (e.g., swaps, rebalances)"""
-        ...
-
-    async def add_vault_cashflow(
-        self,
-        *,
-        wallet_address: str,
-        block_timestamp: int,
-        token_addr: str,
-        amount: str | int | float,
-        description: str,
-        strategy_name: str | None = None,
-    ) -> dict[str, Any]:
-        """Record a cashflow for a vault (interest, funding, reward, or fee)"""
+    ) -> TransactionRecord:
+        """Record a strategy operation (e.g., swaps, rebalances)"""
         ...
 
 
@@ -159,7 +172,7 @@ class WalletClientProtocol(Protocol):
         token_id: str,
         wallet_address: str,
         human_readable: bool = True,
-    ) -> dict[str, Any]:
+    ) -> TokenBalance:
         """Fetch a single token balance for an explicit wallet address"""
         ...
 
@@ -170,7 +183,7 @@ class WalletClientProtocol(Protocol):
         chain_id: int,
         user_address: str,
         human_readable: bool = True,
-    ) -> dict[str, Any]:
+    ) -> PoolBalance:
         """Fetch a wallet's LP/share balance for a given pool address and chain"""
         ...
 
@@ -181,7 +194,7 @@ class WalletClientProtocol(Protocol):
         enrich: bool = True,
         from_cache: bool = False,
         add_llama: bool = True,
-    ) -> dict[str, Any]:
+    ) -> EnrichedBalances:
         """Fetch all token balances for a wallet with enrichment"""
         ...
 
@@ -196,7 +209,7 @@ class TransactionClientProtocol(Protocol):
         token_address: str,
         amount: float,
         chain_id: int,
-    ) -> dict[str, Any]:
+    ) -> TransactionPayload:
         """Build a send transaction payload for EVM tokens/native transfers"""
         ...
 
@@ -209,25 +222,19 @@ class PoolClientProtocol(Protocol):
         *,
         pool_ids: str,
         merge_external: bool | None = None,
-    ) -> dict[str, Any]:
+    ) -> PoolList:
         """Fetch pools by comma-separated pool ids"""
         ...
 
-    async def get_all_pools(
-        self, *, merge_external: bool | None = None
-    ) -> dict[str, Any]:
+    async def get_all_pools(self, *, merge_external: bool | None = None) -> PoolList:
         """Fetch all pools"""
         ...
 
-    async def get_combined_pool_reports(self) -> dict[str, Any]:
-        """Fetch combined pool reports"""
-        ...
-
-    async def get_llama_matches(self) -> dict[str, Any]:
+    async def get_llama_matches(self) -> dict[str, LlamaMatch]:
         """Fetch Llama matches for pools"""
         ...
 
-    async def get_llama_reports(self, *, identifiers: str) -> dict[str, Any]:
+    async def get_llama_reports(self, *, identifiers: str) -> dict[str, LlamaReport]:
         """Fetch Llama reports using identifiers"""
         ...
 
@@ -247,7 +254,7 @@ class BRAPClientProtocol(Protocol):
         amount1: str,
         slippage: float | None = None,
         wayfinder_fee: float | None = None,
-    ) -> dict[str, Any]:
+    ) -> BRAPQuote:
         """Get a quote for a bridge/swap operation"""
         ...
 
@@ -263,7 +270,7 @@ class SimulationClientProtocol(Protocol):
         amount: str,
         chain_id: int,
         initial_balances: dict[str, str],
-    ) -> dict[str, Any]:
+    ) -> SimulationResult:
         """Simulate sending native ETH or ERC20 tokens"""
         ...
 
@@ -276,7 +283,7 @@ class SimulationClientProtocol(Protocol):
         chain_id: int,
         initial_balances: dict[str, str],
         clear_approval_first: bool = False,
-    ) -> dict[str, Any]:
+    ) -> SimulationResult:
         """Simulate ERC20 token approval"""
         ...
 
@@ -290,6 +297,6 @@ class SimulationClientProtocol(Protocol):
         from_address: str,
         slippage: float,
         initial_balances: dict[str, str],
-    ) -> dict[str, Any]:
+    ) -> SimulationResult:
         """Simulate token swap operation"""
         ...

wayfinder_paths/core/clients/sdk_example.py

@@ -31,11 +31,6 @@ class CachedTokenClient:
     async def get_gas_token(self, chain_code: str) -> dict[str, Any]:
         return await self._default_client.get_gas_token(chain_code)
 
-    async def is_native_token(
-        self, token_address: str, chain_id: int
-    ) -> dict[str, Any]:
-        return await self._default_client.is_native_token(token_address, chain_id)
-
 
 class MockHyperlendClient:
     """Mock client for testing"""