wayfinder-paths 0.1.19__py3-none-any.whl → 0.1.21__py3-none-any.whl

wayfinder_paths/core/clients/ClientManager.py

@@ -1,8 +1,3 @@
-"""
-Client Manager
-Consolidated client management for all API interactions
-"""
-
 from typing import Any
 
 from wayfinder_paths.core.clients.BRAPClient import BRAPClient
@@ -22,28 +17,11 @@ from wayfinder_paths.core.clients.WalletClient import WalletClient
 
 
 class ClientManager:
-    """
-    Manages all API client instances for a strategy job.
-
-    Args:
-        clients: Optional dict of pre-instantiated clients to inject directly.
-            Keys: 'token', 'hyperlend', 'ledger', 'wallet', 'transaction', 'pool', 'brap'.
-            If not provided, defaults to HTTP-based clients.
-        skip_auth: If True, skips authentication (for SDK usage).
-    """
-
     def __init__(
         self,
         clients: dict[str, Any] | None = None,
         skip_auth: bool = False,
     ):
-        """
-        Initialize ClientManager.
-
-        Args:
-            clients: Optional dict of pre-instantiated clients to inject directly.
-            skip_auth: If True, skips authentication (for SDK usage).
-        """
         self._injected_clients = clients or {}
         self._skip_auth = skip_auth
 
@@ -60,17 +38,6 @@ class ClientManager:
         injected_key: str,
         client_class: type[Any],
     ) -> Any:
-        """
-        Helper method to get or create a client instance.
-
-        Args:
-            client_attr: Name of the private attribute storing the client (e.g., "_token_client").
-            injected_key: Key to look up in _injected_clients dict.
-            client_class: Client class to instantiate if not injected.
-
-        Returns:
-            Client instance.
-        """
         client = getattr(self, client_attr)
         if not client:
             client = self._injected_clients.get(injected_key) or client_class()
@@ -79,44 +46,26 @@ class ClientManager:
 
     @property
     def token(self) -> TokenClientProtocol:
-        """Get or create token client"""
         return self._get_or_create_client("_token_client", "token", TokenClient)
 
     @property
     def ledger(self) -> LedgerClientProtocol:
-        """Get or create ledger client"""
         return self._get_or_create_client("_ledger_client", "ledger", LedgerClient)
 
     @property
     def pool(self) -> PoolClientProtocol:
-        """Get or create pool client"""
         return self._get_or_create_client("_pool_client", "pool", PoolClient)
 
     @property
     def hyperlend(self) -> HyperlendClientProtocol:
-        """Get or create hyperlend client"""
         return self._get_or_create_client(
             "_hyperlend_client", "hyperlend", HyperlendClient
         )
 
     @property
     def wallet(self) -> WalletClientProtocol:
-        """Get or create wallet client"""
         return self._get_or_create_client("_wallet_client", "wallet", WalletClient)
 
     @property
     def brap(self) -> BRAPClientProtocol:
-        """Get or create BRAP client"""
         return self._get_or_create_client("_brap_client", "brap", BRAPClient)
-
-    def get_all_clients(self) -> dict[str, Any]:
-        """Get all initialized clients for direct access"""
-        return {
-            "token": self._token_client,
-            "transaction": self._transaction_client,
-            "ledger": self._ledger_client,
-            "pool": self._pool_client,
-            "wallet": self._wallet_client,
-            "hyperlend": self._hyperlend_client,
-            "brap": self._brap_client,
-        }

wayfinder_paths/core/clients/HyperlendClient.py

@@ -1,8 +1,3 @@
-"""
-Hyperlend Client
-Provides access to Hyperlend stable markets data via blockchain endpoints.
-"""
-
 from __future__ import annotations
 
 from typing import Any, Required, TypedDict
@@ -12,8 +7,6 @@ from wayfinder_paths.core.config import get_api_base_url
 
 
 class AssetsView(TypedDict):
-    """Assets view response structure"""
-
     block_number: Required[int]
     user: Required[str]
     native_balance_wei: Required[int]
@@ -24,8 +17,6 @@ class AssetsView(TypedDict):
 
 
 class MarketEntry(TypedDict):
-    """Market entry data structure"""
-
     symbol: Required[str]
     symbol_canonical: Required[str]
     display_symbol: Required[str]
@@ -33,14 +24,10 @@ class MarketEntry(TypedDict):
 
 
 class LendRateHistory(TypedDict):
-    """Lend rate history response structure"""
-
     history: Required[list[RateHistoryEntry]]
 
 
 class MarketHeadroom(TypedDict):
-    """Market headroom data structure"""
-
     symbol: Required[str]
     symbol_canonical: Required[str]
     display_symbol: Required[str]
@@ -51,15 +38,11 @@ class MarketHeadroom(TypedDict):
 
 
 class StableMarketsHeadroomResponse(TypedDict):
-    """Stable markets headroom response structure"""
-
     markets: Required[dict[str, MarketHeadroom]]
     notes: Required[list[str]]
 
 
 class RateHistoryEntry(TypedDict):
-    """Rate history entry data structure"""
-
     timestamp_ms: Required[int]
     timestamp: Required[float]
     supply_apr: Required[float]
@@ -72,8 +55,6 @@ class RateHistoryEntry(TypedDict):
 
 
 class AssetInfo(TypedDict):
-    """Asset information structure"""
-
     underlying: Required[str]
     symbol: Required[str]
     symbol_canonical: Required[str]
@@ -102,8 +83,6 @@ class AssetInfo(TypedDict):
 
 
 class AccountData(TypedDict):
-    """Account data structure"""
-
     total_collateral_base: Required[int | float]
     total_debt_base: Required[int | float]
     available_borrows_base: Required[int | float]
@@ -114,8 +93,6 @@ class AccountData(TypedDict):
 
 
 class BaseCurrencyInfo(TypedDict):
-    """Base currency information structure"""
-
     marketReferenceCurrencyUnit: Required[int]
     marketReferenceCurrencyPriceInUsd: Required[int]
     networkBaseTokenPriceInUsd: Required[int]
@@ -123,8 +100,6 @@ class BaseCurrencyInfo(TypedDict):
 
 
 class HyperlendClient(WayfinderClient):
-    """Client for Hyperlend-related operations"""
-
     def __init__(self):
         super().__init__()
         self.api_base_url = get_api_base_url()
@@ -136,20 +111,6 @@ class HyperlendClient(WayfinderClient):
         buffer_bps: int | None = None,
         min_buffer_tokens: float | None = None,
     ) -> StableMarketsHeadroomResponse:
-        """
-        Fetch stable markets headroom from Hyperlend.
-
-        Args:
-            required_underlying_tokens: Required underlying tokens amount
-            buffer_bps: Buffer in basis points
-            min_buffer_tokens: Minimum buffer in tokens
-
-        Example:
-            GET /api/v1/blockchain/hyperlend/stable_markets_headroom/?required_underlying_tokens=1000&buffer_bps=50&min_buffer_tokens=100
-
-        Returns:
-            Dictionary containing stable markets headroom data with markets and notes
-        """
         url = f"{self.api_base_url}/v1/blockchain/hyperlend/stable_markets_headroom/"
         params: dict[str, Any] = {}
         if required_underlying_tokens is not None:
@@ -169,18 +130,6 @@ class HyperlendClient(WayfinderClient):
         *,
         user_address: str,
     ) -> AssetsView:
-        """
-        Fetch assets view for a user address from Hyperlend.
-
-        Args:
-            user_address: User wallet address to query assets for
-
-        Example:
-            GET /api/v1/blockchain/hyperlend/assets/?user_address=0x0c737cB5934afCb5B01965141F865F795B324080
-
-        Returns:
-            Dictionary containing assets view data with account information and base currency info
-        """
         url = f"{self.api_base_url}/v1/blockchain/hyperlend/assets/"
         params: dict[str, Any] = {
             "user_address": user_address,
@@ -196,18 +145,6 @@ class HyperlendClient(WayfinderClient):
         *,
         token: str,
     ) -> MarketEntry:
-        """
-        Fetch market entry from Hyperlend.
-
-        Args:
-            token: Token address to query market for
-
-        Example:
-            GET /api/v1/blockchain/hyperlend/market_entry/?token=0x5555555555555555555555555555555555555555
-
-        Returns:
-            Dictionary containing market entry data with symbol and reserve information
-        """
         url = f"{self.api_base_url}/v1/blockchain/hyperlend/market_entry/"
         params: dict[str, Any] = {
             "token": token,
@@ -225,20 +162,6 @@ class HyperlendClient(WayfinderClient):
         lookback_hours: int,
         force_refresh: bool | None = None,
     ) -> LendRateHistory:
-        """
-        Fetch lend rate history from Hyperlend.
-
-        Args:
-            token: Token address to query rate history for
-            lookback_hours: Number of hours to look back for rate history
-            force_refresh: Whether to force refresh the data (optional)
-
-        Example:
-            GET /api/v1/blockchain/hyperlend/lend_rate_history/?token=0x5555555555555555555555555555555555555555&lookback_hours=24&force_refresh=false
-
-        Returns:
-            Dictionary containing lend rate history data with history array
-        """
         url = f"{self.api_base_url}/v1/blockchain/hyperlend/lend_rate_history/"
         params: dict[str, Any] = {
             "token": token,

wayfinder_paths/core/clients/LedgerClient.py

@@ -11,8 +11,6 @@ from wayfinder_paths.core.adapters.models import Operation
 
 
 class StrategyTransaction(TypedDict):
-    """Individual strategy transaction structure"""
-
     id: Required[str]
     operation: Required[str]
     timestamp: Required[str]
@@ -24,8 +22,6 @@ class StrategyTransaction(TypedDict):
 
 
 class StrategyTransactionList(TypedDict):
-    """Vault transaction list response structure"""
-
     transactions: Required[list[StrategyTransaction]]
     total: Required[int]
     limit: Required[int]
@@ -33,8 +29,6 @@ class StrategyTransactionList(TypedDict):
 
 
 class NetDeposit(TypedDict):
-    """Net deposit response structure"""
-
     net_deposit: Required[str]
     total_deposits: Required[str]
     total_withdrawals: Required[str]
@@ -42,34 +36,13 @@ class NetDeposit(TypedDict):
 
 
 class TransactionRecord(TypedDict):
-    """Transaction record response structure"""
-
     transaction_id: Required[str]
     status: Required[str]
     timestamp: Required[str]
 
 
 class LedgerClient:
-    """
-    Client for strategy transaction history and bookkeeping operations using local JSON files.
-
-    Supports:
-    - GET strategy transactions
-    - GET strategy net deposit
-    - GET strategy latest transactions
-    - POST add deposit
-    - POST add withdraw
-    - POST add operation
-    - POST record snapshot
-    """
-
     def __init__(self, ledger_dir: Path | str | None = None) -> None:
-        """
-        Initialize the ledger client.
-
-        Args:
-            ledger_dir: Directory to store ledger JSON files. Defaults to .ledger in project root
-        """
         if ledger_dir is None:
             # Default to .ledger directory in project root
             project_root = Path(__file__).parent.parent.parent.parent
@@ -89,7 +62,6 @@ class LedgerClient:
         self._initialize_files()
 
     def _initialize_files(self) -> None:
-        """Create initial JSON files if they don't exist."""
         if not self.transactions_file.exists():
             self.transactions_file.write_text(
                 json.dumps({"transactions": []}, indent=2)
@@ -99,7 +71,6 @@ class LedgerClient:
             self.snapshots_file.write_text(json.dumps({"snapshots": []}, indent=2))
 
     async def _read_transactions(self) -> dict[str, Any]:
-        """Read transactions from file with lock."""
         async with self._transactions_lock:
             if not self.transactions_file.exists():
                 return {"transactions": []}
@@ -110,12 +81,10 @@ class LedgerClient:
                 return {"transactions": []}
 
     async def _write_transactions(self, data: dict[str, Any]) -> None:
-        """Write transactions to file with lock."""
         async with self._transactions_lock:
             self.transactions_file.write_text(json.dumps(data, indent=2))
 
     async def _read_snapshots(self) -> dict[str, Any]:
-        """Read snapshots from file with lock."""
         async with self._snapshots_lock:
             if not self.snapshots_file.exists():
                 return {"snapshots": []}
@@ -126,7 +95,6 @@ class LedgerClient:
                 return {"snapshots": []}
 
     async def _write_snapshots(self, data: dict[str, Any]) -> None:
-        """Write snapshots to file with lock."""
         async with self._snapshots_lock:
             self.snapshots_file.write_text(json.dumps(data, indent=2))
 
@@ -139,17 +107,6 @@ class LedgerClient:
         limit: int = 100,
         offset: int = 0,
     ) -> StrategyTransactionList:
-        """
-        Fetch a paginated list of transactions for a given strategy wallet address.
-
-        Args:
-            wallet_address: The strategy wallet address to filter by
-            limit: Maximum number of transactions to return
-            offset: Number of transactions to skip
-
-        Returns:
-            StrategyTransactionList with transactions, total, limit, and offset
-        """
         data = await self._read_transactions()
         all_transactions = data.get("transactions", [])
 
@@ -174,15 +131,6 @@ class LedgerClient:
         }
 
     async def get_strategy_net_deposit(self, *, wallet_address: str) -> float:
-        """
-        Calculate the net deposit (deposits - withdrawals) for a strategy wallet.
-
-        Args:
-            wallet_address: The strategy wallet address
-
-        Returns:
-            NetDeposit with net_deposit, total_deposits, total_withdrawals
-        """
         data = await self._read_transactions()
         all_transactions = data.get("transactions", [])
 
@@ -212,16 +160,6 @@ class LedgerClient:
     async def get_strategy_latest_transactions(
         self, *, wallet_address: str, limit: int = 10
     ) -> StrategyTransactionList:
-        """
-        Fetch the most recent transactions for a strategy wallet.
-
-        Args:
-            wallet_address: The strategy wallet address
-            limit: Maximum number of transactions to return (default 10)
-
-        Returns:
-            StrategyTransactionList with the latest transactions
-        """
         return await self.get_strategy_transactions(
             wallet_address=wallet_address,
             limit=limit,
@@ -241,21 +179,6 @@ class LedgerClient:
         data: dict[str, Any] | None = None,
         strategy_name: str | None = None,
     ) -> TransactionRecord:
-        """
-        Record a deposit for a strategy.
-
-        Args:
-            wallet_address: The strategy wallet address
-            chain_id: The blockchain chain ID
-            token_address: The token contract address
-            token_amount: Amount of tokens deposited
-            usd_value: USD value of the deposit
-            data: Additional metadata
-            strategy_name: Name of the strategy
-
-        Returns:
-            TransactionRecord with transaction_id, status, and timestamp
-        """
         transaction_id = str(uuid.uuid4())
         timestamp = datetime.now(UTC).isoformat()
 
@@ -267,7 +190,7 @@ class LedgerClient:
             "chain_id": chain_id,
             "token_address": token_address,
             "token_amount": str(token_amount),
-            "amount": str(token_amount),  # For backward compatibility
+            "amount": str(token_amount),
             "usd_value": str(usd_value),
             "data": data or {},
         }
@@ -275,7 +198,6 @@ class LedgerClient:
         if strategy_name is not None:
             transaction["strategy_name"] = strategy_name
 
-        # Add to transactions
         file_data = await self._read_transactions()
         file_data["transactions"].append(transaction)
         await self._write_transactions(file_data)
@@ -297,21 +219,6 @@ class LedgerClient:
         data: dict[str, Any] | None = None,
         strategy_name: str | None = None,
     ) -> TransactionRecord:
-        """
-        Record a withdrawal for a strategy.
-
-        Args:
-            wallet_address: The strategy wallet address
-            chain_id: The blockchain chain ID
-            token_address: The token contract address
-            token_amount: Amount of tokens withdrawn
-            usd_value: USD value of the withdrawal
-            data: Additional metadata
-            strategy_name: Name of the strategy
-
-        Returns:
-            TransactionRecord with transaction_id, status, and timestamp
-        """
         transaction_id = str(uuid.uuid4())
         timestamp = datetime.now(UTC).isoformat()
 
@@ -323,7 +230,7 @@ class LedgerClient:
             "chain_id": chain_id,
             "token_address": token_address,
             "token_amount": str(token_amount),
-            "amount": str(token_amount),  # For backward compatibility
+            "amount": str(token_amount),
             "usd_value": str(usd_value),
             "data": data or {},
         }
@@ -331,7 +238,6 @@ class LedgerClient:
         if strategy_name is not None:
             transaction["strategy_name"] = strategy_name
 
-        # Add to transactions
         file_data = await self._read_transactions()
         file_data["transactions"].append(transaction)
         await self._write_transactions(file_data)
@@ -350,18 +256,6 @@ class LedgerClient:
         usd_value: str | float,
         strategy_name: str | None = None,
     ) -> TransactionRecord:
-        """
-        Record a strategy operation (e.g., swaps, rebalances) for bookkeeping.
-
-        Args:
-            wallet_address: Strategy wallet address
-            operation_data: Operation model (SWAP, LEND, UNLEND, etc.)
-            usd_value: USD value of the operation
-            strategy_name: Optional strategy name
-
-        Returns:
-            TransactionRecord with transaction_id, status, and timestamp
-        """
         transaction_id = str(uuid.uuid4())
         timestamp = datetime.now(UTC).isoformat()
 
@@ -378,7 +272,6 @@ class LedgerClient:
             "data": {},
         }
 
-        # Extract relevant fields from operation data for easier querying
         if operation_type == "SWAP":
             transaction["token_address"] = op_dict.get("to_token_id", "")
             transaction["amount"] = op_dict.get("to_amount", "0")
@@ -389,7 +282,6 @@ class LedgerClient:
         if strategy_name is not None:
             transaction["strategy_name"] = strategy_name
 
-        # Add to transactions
         file_data = await self._read_transactions()
         file_data["transactions"].append(transaction)
         await self._write_transactions(file_data)
@@ -409,17 +301,6 @@ class LedgerClient:
         gas_available: float,
         gassed_up: bool,
     ) -> None:
-        """
-        Record a periodic snapshot of strategy state.
-
-        Args:
-            wallet_address: Strategy wallet address
-            strat_portfolio_value: Total portfolio value in USD
-            net_deposit: Net deposit amount in USD
-            strategy_status: Arbitrary strategy status data
-            gas_available: Available gas tokens
-            gassed_up: Whether strategy has sufficient gas
-        """
         snapshot_id = str(uuid.uuid4())
         timestamp = datetime.now(UTC).isoformat()
 
@@ -434,7 +315,6 @@ class LedgerClient:
             "strategy_status": strategy_status,
         }
 
-        # Add to snapshots
         file_data = await self._read_snapshots()
         file_data["snapshots"].append(snapshot)
         await self._write_snapshots(file_data)

wayfinder_paths/core/clients/PoolClient.py

@@ -1,5 +1,3 @@
-"""Read-only pool metadata and analytics via public endpoints."""
-
 from __future__ import annotations
 
 from typing import Any, Required, TypedDict

wayfinder_paths/core/clients/TokenClient.py

@@ -1,8 +1,3 @@
-"""
-Token Adapter
-Handles token information, prices, and parsing
-"""
-
 from __future__ import annotations
 
 from typing import NotRequired, Required, TypedDict
@@ -12,8 +7,6 @@ from wayfinder_paths.core.config import get_api_base_url
 
 
 class TokenLinks(TypedDict):
-    """Token links structure"""
-
     github: NotRequired[list[str]]
     reddit: NotRequired[str]
     discord: NotRequired[str]
@@ -23,8 +16,6 @@ class TokenLinks(TypedDict):
 
 
 class ChainAddress(TypedDict):
-    """Chain address structure"""
-
     address: Required[str]
     token_id: Required[str]
     is_contract: NotRequired[bool]
@@ -32,16 +23,12 @@ class ChainAddress(TypedDict):
 
 
 class ChainInfo(TypedDict):
-    """Chain information structure"""
-
     id: Required[int]
     name: Required[str]
     code: Required[str]
 
 
 class TokenMetadata(TypedDict):
-    """Token metadata structure"""
-
     query_processed: NotRequired[str]
     query_type: NotRequired[str]
     has_addresses: NotRequired[bool]
@@ -50,8 +37,6 @@ class TokenMetadata(TypedDict):
 
 
 class TokenDetails(TypedDict):
-    """Token details response structure"""
-
     asset_id: NotRequired[str]
     token_ids: NotRequired[list[str]]
     name: Required[str]
@@ -81,8 +66,6 @@ class TokenDetails(TypedDict):
 
 
 class GasToken(TypedDict):
-    """Gas token response structure"""
-
     id: Required[str]
     coingecko_id: NotRequired[str]
     token_id: Required[str]
@@ -94,8 +77,6 @@ class GasToken(TypedDict):
 
 
 class TokenClient(WayfinderClient):
-    """Adapter for token-related operations"""
-
     def __init__(self):
         super().__init__()
         self.api_base_url = f"{get_api_base_url()}/v1/blockchain/tokens"
@@ -103,17 +84,6 @@ class TokenClient(WayfinderClient):
     async def get_token_details(
         self, query: str, market_data: bool = False, chain_id: int | None = None
     ) -> TokenDetails:
-        """
-        Get token data including price from the token-details endpoint.
-
-        Args:
-            query: Token identifier, address, or symbol to query
-            market_data: Whether to include market data (default: True)
-            chain_id: Optional chain ID
-
-        Returns:
-            Full token data including price information
-        """
         url = f"{self.api_base_url}/detail/"
         params = {
             "query": query,
@@ -127,15 +97,6 @@ class TokenClient(WayfinderClient):
         return data.get("data", data)
 
     async def get_gas_token(self, query: str) -> GasToken:
-        """
-        Fetch the native gas token for a given chain code or query.
-
-        Args:
-            query: Chain code or query string
-
-        Returns:
-            Gas token information including chain details
-        """
         url = f"{self.api_base_url}/gas/"
         params = {"query": query}
         response = await self._authed_request("GET", url, params=params)

wayfinder_paths/core/clients/WalletClient.py

@@ -1,8 +1,3 @@
-"""
-Wallet Client
-Fetches wallet-related data such as aggregated balances for the authenticated user.
-"""
-
 from __future__ import annotations
 
 from typing import NotRequired, Required, TypedDict
@@ -12,8 +7,6 @@ from wayfinder_paths.core.config import get_api_base_url
 
 
 class AddressBalance(TypedDict):
-    """Balance response structure for address/query lookups."""
-
     balance: Required[int]
     balance_human: NotRequired[float | None]
     usd_value: NotRequired[float | None]
@@ -35,14 +28,6 @@ class WalletClient(WayfinderClient):
         query: str,
         chain_id: int | None = None,
     ) -> AddressBalance:
-        """
-        Fetch a balance for a wallet address + chain + query.
-
-        Args:
-            wallet_address: Wallet address
-            query: Token address, pool address, or equivalent identifier
-            chain_id: Chain ID (required)
-        """
         if chain_id is None:
             raise ValueError("chain_id is required")