wayfinder-paths 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

wayfinder_paths/core/clients/protocols.py

@@ -4,7 +4,7 @@ Protocol definitions for API clients.
 These protocols define the interface that all client implementations must satisfy.
 When used as an SDK, users can provide custom implementations that match these protocols.
 
-Note: AuthClient is excluded as SDK users handle their own authentication.
+Note: Authentication is handled via X-API-KEY header in WayfinderClient base class.
 """
 
 from __future__ import annotations
@@ -12,19 +12,19 @@ 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.BRAPClient import BRAPQuoteResponse
     from wayfinder_paths.core.clients.HyperlendClient import (
         AssetsView,
         LendRateHistory,
         MarketEntry,
-        StableMarket,
+        StableMarketsHeadroomResponse,
     )
     from wayfinder_paths.core.clients.LedgerClient import (
         StrategyTransactionList,
         TransactionRecord,
     )
     from wayfinder_paths.core.clients.PoolClient import (
-        LlamaMatch,
+        LlamaMatchesResponse,
         PoolList,
     )
     from wayfinder_paths.core.clients.TokenClient import (
@@ -32,8 +32,7 @@ if TYPE_CHECKING:
         TokenDetails,
     )
     from wayfinder_paths.core.clients.WalletClient import (
-        PoolBalance,
-        TokenBalance,
+        AddressBalance,
     )
 
 
@@ -41,7 +40,10 @@ class TokenClientProtocol(Protocol):
     """Protocol for token-related operations"""
 
     async def get_token_details(
-        self, token_id: str, force_refresh: bool = False
+        self,
+        query: str,
+        market_data: bool = True,
+        chain_id: int | None = None,
     ) -> TokenDetails:
         """Get token data including price from the token-details endpoint"""
         ...
@@ -57,19 +59,16 @@ class HyperlendClientProtocol(Protocol):
     async def get_stable_markets(
         self,
         *,
-        chain_id: int,
         required_underlying_tokens: float | None = None,
         buffer_bps: int | None = None,
         min_buffer_tokens: float | None = None,
-        is_stable_symbol: bool | None = None,
-    ) -> list[StableMarket]:
-        """Fetch stable markets from Hyperlend"""
+    ) -> StableMarketsHeadroomResponse:
+        """Fetch stable markets headroom from Hyperlend"""
         ...
 
     async def get_assets_view(
         self,
         *,
-        chain_id: int,
         user_address: str,
     ) -> AssetsView:
         """Fetch assets view for a user address from Hyperlend"""
@@ -78,8 +77,7 @@ class HyperlendClientProtocol(Protocol):
     async def get_market_entry(
         self,
         *,
-        chain_id: int,
-        token_address: str,
+        token: str,
     ) -> MarketEntry:
         """Fetch market entry from Hyperlend"""
         ...
@@ -87,9 +85,9 @@ class HyperlendClientProtocol(Protocol):
     async def get_lend_rate_history(
         self,
         *,
-        chain_id: int,
-        token_address: str,
+        token: str,
         lookback_hours: int,
+        force_refresh: bool | None = None,
     ) -> LendRateHistory:
         """Fetch lend rate history from Hyperlend"""
         ...
@@ -161,25 +159,14 @@ class LedgerClientProtocol(Protocol):
 class WalletClientProtocol(Protocol):
     """Protocol for wallet-related operations"""
 
-    async def get_token_balance_for_wallet(
+    async def get_token_balance_for_address(
         self,
         *,
-        token_id: str,
         wallet_address: str,
-        human_readable: bool = True,
-    ) -> TokenBalance:
-        """Fetch a single token balance for an explicit wallet address"""
-        ...
-
-    async def get_pool_balance_for_wallet(
-        self,
-        *,
-        pool_address: str,
-        chain_id: int,
-        user_address: str,
-        human_readable: bool = True,
-    ) -> PoolBalance:
-        """Fetch a wallet's LP/share balance for a given pool address and chain"""
+        query: str,
+        chain_id: int | None = None,
+    ) -> AddressBalance:
+        """Fetch a balance for an address + chain + query (supports compound query formats)"""
         ...
 
 
@@ -189,13 +176,18 @@ class PoolClientProtocol(Protocol):
     async def get_pools_by_ids(
         self,
         *,
-        pool_ids: str,
+        pool_ids: list[str] | str,
     ) -> PoolList:
-        """Fetch pools by comma-separated pool ids"""
+        """Fetch pools by pool IDs (list or comma-separated string)"""
         ...
 
-    async def get_pools(self) -> dict[str, LlamaMatch]:
-        """Fetch Llama matches for pools"""
+    async def get_pools(
+        self,
+        *,
+        chain_id: int | None = None,
+        project: str | None = None,
+    ) -> LlamaMatchesResponse:
+        """Fetch pools (optionally filtered by chain_id and project)"""
         ...
 
 
@@ -205,16 +197,13 @@ class BRAPClientProtocol(Protocol):
     async def get_quote(
         self,
         *,
-        from_token_address: str,
-        to_token_address: str,
-        from_chain_id: int,
-        to_chain_id: int,
-        from_address: str,
-        to_address: str,
-        amount1: str,
-        slippage: float | None = None,
-        wayfinder_fee: float | None = None,
-    ) -> BRAPQuote:
+        from_token: str,
+        to_token: str,
+        from_chain: int,
+        to_chain: int,
+        from_wallet: str,
+        from_amount: str,
+    ) -> BRAPQuoteResponse:
         """Get a quote for a bridge/swap operation"""
         ...
 

wayfinder_paths/core/clients/sdk_example.py

@@ -38,59 +38,74 @@ class MockHyperlendClient:
     async def get_stable_markets(
         self,
         *,
-        chain_id: int,
         required_underlying_tokens: float | None = None,
         buffer_bps: int | None = None,
         min_buffer_tokens: float | None = None,
-        is_stable_symbol: bool | None = None,
     ) -> dict[str, Any]:
         return {
-            "markets": [
-                {
-                    "chain_id": chain_id,
-                    "token_address": "0xMockToken",
+            "markets": {
+                "0xMockToken": {
                     "symbol": "USDC",
-                    "lend_rate": 0.05,
-                    "available_liquidity": 1000000.0,
+                    "symbol_canonical": "usdc",
+                    "display_symbol": "USDC",
+                    "reserve": {},
+                    "decimals": 6,
+                    "headroom": 1000000000000,
+                    "supply_cap": 5000000000000,
                 }
-            ]
+            },
+            "notes": [],
         }
 
     async def get_assets_view(
         self,
         *,
-        chain_id: int,
         user_address: str,
     ) -> dict[str, Any]:
         return {
-            "user_address": user_address,
-            "chain_id": chain_id,
+            "block_number": 12345,
+            "user": user_address,
+            "native_balance_wei": 0,
+            "native_balance": 0.0,
             "assets": [],
+            "account_data": {
+                "total_collateral_base": 0,
+                "total_debt_base": 0,
+                "available_borrows_base": 0,
+                "current_liquidation_threshold": 0,
+                "ltv": 0,
+                "health_factor_wad": 0,
+                "health_factor": 0.0,
+            },
+            "base_currency_info": {
+                "marketReferenceCurrencyUnit": 100000000,
+                "marketReferenceCurrencyPriceInUsd": 100000000,
+                "networkBaseTokenPriceInUsd": 0,
+                "networkBaseTokenPriceDecimals": 8,
+            },
         }
 
     async def get_market_entry(
         self,
         *,
-        chain_id: int,
-        token_address: str,
+        token: str,
     ) -> dict[str, Any]:
         return {
-            "chain_id": chain_id,
-            "token_address": token_address,
-            "market_data": {},
+            "symbol": "USDC",
+            "symbol_canonical": "usdc",
+            "display_symbol": "USDC",
+            "reserve": {},
         }
 
     async def get_lend_rate_history(
         self,
         *,
-        chain_id: int,
-        token_address: str,
+        token: str,
         lookback_hours: int,
+        force_refresh: bool | None = None,
     ) -> dict[str, Any]:
         return {
-            "chain_id": chain_id,
-            "token_address": token_address,
-            "rates": [],
+            "history": [],
         }
 
 

wayfinder_paths/core/constants/erc20_abi.py

@@ -83,17 +83,6 @@ ERC20_ABI = [
     },
 ]
 
-# Minimal ABI for specific use cases (e.g., when you only need certain functions)
-ERC20_MINIMAL_ABI = [
-    {
-        "constant": True,
-        "inputs": [{"name": "account", "type": "address"}],
-        "name": "balanceOf",
-        "outputs": [{"name": "", "type": "uint256"}],
-        "type": "function",
-    }
-]
-
 ERC20_APPROVAL_ABI = [
     {
         "constant": True,

wayfinder_paths/core/engine/StrategyJob.py

@@ -1,5 +1,4 @@
 import asyncio
-import os
 from typing import Any
 
 from loguru import logger
@@ -16,7 +15,6 @@ class StrategyJob:
         config: StrategyJobConfig,
         clients: dict[str, Any] | None = None,
         skip_auth: bool = False,
-        api_key: str | None = None,
     ):
         """
         Initialize a StrategyJob.
@@ -26,16 +24,12 @@ class StrategyJob:
             config: Strategy job configuration.
             clients: Optional dict of pre-instantiated clients to inject directly.
             skip_auth: If True, skips authentication (for SDK usage).
-            api_key: Optional API key for service account authentication.
-                If provided, will be passed to ClientManager and strategy.
         """
         self.strategy = strategy
         self.config = config
 
         self.job_id = strategy.name or "unknown"
-        self.clients = ClientManager(
-            clients=clients, skip_auth=skip_auth, api_key=api_key
-        )
+        self.clients = ClientManager(clients=clients, skip_auth=skip_auth)
 
     def _setup_strategy(self):
         """Setup the strategy instance"""
@@ -44,23 +38,6 @@ class StrategyJob:
 
         self.strategy.log = self.log
 
-    def _is_using_api_key(self) -> bool:
-        """Check if API key authentication is being used."""
-        if self.clients._api_key:
-            return True
-
-        if self.clients.auth:
-            try:
-                creds = self.clients.auth._load_config_credentials()
-                if creds.get("api_key"):
-                    return True
-                if os.getenv("WAYFINDER_API_KEY"):
-                    return True
-            except Exception:
-                pass
-
-        return False
-
     async def setup(self):
         """
         Initialize the strategy job and strategy.
@@ -69,38 +46,13 @@ class StrategyJob:
         """
         self._setup_strategy()
 
-        # Ensure auth token is set for API calls
+        # Ensure API key is set for API calls
+        # All clients inherit from WayfinderClient and have _ensure_api_key()
         if not self.clients._skip_auth:
-            is_api_key_auth = self._is_using_api_key()
-
-            if is_api_key_auth:
-                logger.debug("Using API key authentication")
-                if self.clients.auth:
-                    await self.clients.auth._ensure_bearer_token()
-            else:
-                # Try to ensure bearer token is set, authenticate if needed
-                try:
-                    if self.clients.auth:
-                        await self.clients.auth._ensure_bearer_token()
-                except (PermissionError, Exception) as e:
-                    if not isinstance(e, PermissionError):
-                        logger.warning(
-                            f"Authentication failed: {e}, trying OAuth fallback"
-                        )
-                    username = self.config.user.username
-                    password = self.config.user.password
-                    refresh_token = self.config.user.refresh_token
-                    if refresh_token or (username and password):
-                        await self.clients.authenticate(
-                            username=username,
-                            password=password,
-                            refresh_token=refresh_token,
-                        )
-                    else:
-                        raise ValueError(
-                            "Authentication required: provide api_key parameter for service account auth, "
-                            "or username+password/refresh_token in config.json for personal access"
-                        ) from e
+            # Ensure API key on any client (they all share the same method)
+            token_client = self.clients.token
+            if token_client:
+                token_client._ensure_api_key()
 
         existing_cfg = dict(getattr(self.strategy, "config", {}) or {})
         strategy_cfg = dict(self.config.strategy_config or {})
@@ -110,7 +62,7 @@ class StrategyJob:
         await self.strategy.setup()
 
     async def execute_strategy(self, action: str, **kwargs) -> dict[str, Any]:
-        """Execute a strategy action (deposit, withdraw, update, status, partial_liquidate)"""
+        """Execute a strategy action (deposit, withdraw, update, status, exit, partial_liquidate)"""
         try:
             if action == "deposit":
                 result = await self.strategy.deposit(**kwargs)
@@ -120,6 +72,8 @@ class StrategyJob:
                 result = await self.strategy.update()
             elif action == "status":
                 result = await self.strategy.status()
+            elif action == "exit":
+                result = await self.strategy.exit(**kwargs)
             elif action == "partial_liquidate":
                 usd_value = kwargs.get("usd_value")
                 if usd_value is None:

wayfinder_paths/core/services/base.py

@@ -57,6 +57,7 @@ class EvmTxn(ABC):
         *,
         wait_for_receipt: bool = True,
         timeout: int = DEFAULT_TRANSACTION_TIMEOUT,
+        confirmations: int = 1,
     ) -> tuple[bool, Any]:
         """
         Sign and broadcast a transaction dict.

wayfinder_paths/core/services/local_evm_txn.py

@@ -20,6 +20,9 @@ SUGGESTED_PRIORITY_FEE_MULTIPLIER = 1.5
 MAX_BASE_FEE_GROWTH_MULTIPLIER = 2
 GAS_LIMIT_BUFFER_MULTIPLIER = 1.5
 
+# Base chain ID (Base mainnet)
+BASE_CHAIN_ID = 8453
+
 # Chains that don't support EIP-1559 (London) and need legacy gas pricing
 PRE_LONDON_GAS_CHAIN_IDS: set[int] = {56, 42161}
 POA_MIDDLEWARE_CHAIN_IDS: set = {56, 137, 43114}
@@ -155,13 +158,13 @@ class LocalEvmTxn(EvmTxn):
             gas_price = await self._get_gas_price(w3)
 
             transaction["gasPrice"] = int(gas_price * SUGGESTED_GAS_PRICE_MULTIPLIER)
-        elif chain_id == 999:
-            big_block_gas_price = await w3.hype.big_block_gas_price()
+        # elif chain_id == 999:
+        #     big_block_gas_price = await w3.hype.big_block_gas_price()
 
-            transaction["maxFeePerGas"] = int(
-                big_block_gas_price * SUGGESTED_PRIORITY_FEE_MULTIPLIER
-            )
-            transaction["maxPriorityFeePerGas"] = 0
+        #     transaction["maxFeePerGas"] = int(
+        #         big_block_gas_price * SUGGESTED_PRIORITY_FEE_MULTIPLIER
+        #     )
+        #     transaction["maxPriorityFeePerGas"] = 0
         else:
             base_fee = await self._get_base_fee(w3)
             priority_fee = await self._get_priority_fee(w3)
@@ -182,12 +185,20 @@ class LocalEvmTxn(EvmTxn):
         *,
         wait_for_receipt: bool = True,
         timeout: int = DEFAULT_TRANSACTION_TIMEOUT,
-        confirmations: int = 1,
+        confirmations: int | None = None,
     ) -> tuple[bool, Any]:
         try:
             chain_id = transaction["chainId"]
             from_address = transaction["from"]
 
+            # Default confirmation behavior:
+            # - Base: wait for 2 additional blocks after the receipt block
+            # - Others: do not wait for additional confirmations
+            effective_confirmations = confirmations
+            if effective_confirmations is None:
+                effective_confirmations = 2 if int(chain_id) == BASE_CHAIN_ID else 0
+            effective_confirmations = max(0, int(effective_confirmations))
+
             web3 = self.get_web3(chain_id)
             try:
                 transaction = self._validate_transaction(transaction)
@@ -210,6 +221,8 @@ class LocalEvmTxn(EvmTxn):
                     result["receipt"] = self._format_receipt(receipt)
                     # Add block_number at top level for convenience
                     result["block_number"] = result["receipt"].get("blockNumber")
+                    result["confirmations"] = effective_confirmations
+                    result["confirmed_block_number"] = result["block_number"]
 
                     receipt_status = result["receipt"].get("status")
                     if receipt_status is not None and int(receipt_status) != 1:
@@ -219,11 +232,14 @@ class LocalEvmTxn(EvmTxn):
                         )
 
                     # Wait for additional confirmations if requested
-                    if confirmations > 0:
+                    if effective_confirmations > 0:
                         tx_block = result["receipt"].get("blockNumber")
                         if tx_block:
                             await self._wait_for_confirmations(
-                                web3, tx_block, confirmations
+                                web3, tx_block, effective_confirmations
+                            )
+                            result["confirmed_block_number"] = int(tx_block) + int(
+                                effective_confirmations
                             )
 
                 return (True, result)

wayfinder_paths/core/services/local_token_txn.py

@@ -6,7 +6,7 @@ from typing import Any
 
 from eth_utils import to_checksum_address
 from loguru import logger
-from web3 import AsyncWeb3, Web3
+from web3 import Web3
 
 from wayfinder_paths.core.clients.TokenClient import TokenClient
 from wayfinder_paths.core.constants import ZERO_ADDRESS
@@ -85,7 +85,6 @@ class LocalTokenTxnService(TokenTxn):
     ) -> tuple[bool, dict[str, Any] | str]:
         """Build the transaction dictionary for an ERC20 approval."""
         try:
-            web3 = self.wallet_provider.get_web3(chain_id)
             token_checksum = to_checksum_address(token_address)
             from_checksum = to_checksum_address(from_address)
             spender_checksum = to_checksum_address(spender)
@@ -99,7 +98,6 @@ class LocalTokenTxnService(TokenTxn):
             from_address=from_checksum,
             spender=spender_checksum,
             amount=amount_int,
-            web3=web3,
         )
         return True, approve_tx
 
@@ -154,7 +152,7 @@ class LocalTokenTxnService(TokenTxn):
 
     def _chain_id(self, chain: Any) -> int:
         if isinstance(chain, dict):
-            chain_id = chain.get("id") or chain.get("chain_id")
+            chain_id = chain.get("id")
         else:
             chain_id = getattr(chain, "id", None)
         if chain_id is None:
@@ -215,10 +213,8 @@ class LocalTokenTxnService(TokenTxn):
         from_address: str,
         spender: str,
         amount: int,
-        web3: AsyncWeb3,
     ) -> dict[str, Any]:
         """Build an ERC20 approval transaction dict."""
-        del web3  # Use sync Web3 for encoding (AsyncContract doesn't have encodeABI)
         token_checksum = to_checksum_address(token_address)
         spender_checksum = to_checksum_address(spender)
         from_checksum = to_checksum_address(from_address)

wayfinder_paths/core/services/test_local_evm_txn.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from wayfinder_paths.core.services.local_evm_txn import BASE_CHAIN_ID, LocalEvmTxn
+
+
+class _FakeTxHash:
+    def __init__(self, value: str):
+        self._value = value
+
+    def hex(self) -> str:
+        return self._value
+
+
+@pytest.mark.asyncio
+async def test_base_defaults_to_two_confirmations():
+    txn = LocalEvmTxn(config={})
+
+    fake_web3 = MagicMock()
+    fake_web3.eth = MagicMock()
+    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
+    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
+        return_value={
+            "status": 1,
+            "blockNumber": 100,
+            "transactionHash": "0x1",
+            "gasUsed": 21_000,
+            "logs": [],
+        }
+    )
+
+    txn.get_web3 = MagicMock(return_value=fake_web3)
+    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
+    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
+    txn._sign_transaction = MagicMock(return_value=b"signed")
+    txn._close_web3 = AsyncMock()
+    txn._wait_for_confirmations = AsyncMock()
+
+    ok, result = await txn.broadcast_transaction(
+        {
+            "chainId": BASE_CHAIN_ID,
+            "from": "0x0000000000000000000000000000000000000001",
+            "to": "0x0000000000000000000000000000000000000002",
+            "value": 0,
+        },
+        wait_for_receipt=True,
+        timeout=1,
+    )
+
+    assert ok is True
+    txn._wait_for_confirmations.assert_awaited_once_with(fake_web3, 100, 2)
+    assert result["confirmations"] == 2
+    assert result["confirmed_block_number"] == 102
+
+
+@pytest.mark.asyncio
+async def test_non_base_defaults_to_zero_confirmations():
+    txn = LocalEvmTxn(config={})
+
+    fake_web3 = MagicMock()
+    fake_web3.eth = MagicMock()
+    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
+    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
+        return_value={
+            "status": 1,
+            "blockNumber": 100,
+            "transactionHash": "0x1",
+            "gasUsed": 21_000,
+            "logs": [],
+        }
+    )
+
+    txn.get_web3 = MagicMock(return_value=fake_web3)
+    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
+    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
+    txn._sign_transaction = MagicMock(return_value=b"signed")
+    txn._close_web3 = AsyncMock()
+    txn._wait_for_confirmations = AsyncMock()
+
+    ok, result = await txn.broadcast_transaction(
+        {
+            "chainId": 1,
+            "from": "0x0000000000000000000000000000000000000001",
+            "to": "0x0000000000000000000000000000000000000002",
+            "value": 0,
+        },
+        wait_for_receipt=True,
+        timeout=1,
+    )
+
+    assert ok is True
+    txn._wait_for_confirmations.assert_not_awaited()
+    assert result["confirmations"] == 0
+    assert result["confirmed_block_number"] == 100
+
+
+@pytest.mark.asyncio
+async def test_explicit_confirmations_override_defaults():
+    txn = LocalEvmTxn(config={})
+
+    fake_web3 = MagicMock()
+    fake_web3.eth = MagicMock()
+    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
+    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
+        return_value={
+            "status": 1,
+            "blockNumber": 100,
+            "transactionHash": "0x1",
+            "gasUsed": 21_000,
+            "logs": [],
+        }
+    )
+
+    txn.get_web3 = MagicMock(return_value=fake_web3)
+    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
+    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
+    txn._sign_transaction = MagicMock(return_value=b"signed")
+    txn._close_web3 = AsyncMock()
+    txn._wait_for_confirmations = AsyncMock()
+
+    ok, result = await txn.broadcast_transaction(
+        {
+            "chainId": BASE_CHAIN_ID,
+            "from": "0x0000000000000000000000000000000000000001",
+            "to": "0x0000000000000000000000000000000000000002",
+            "value": 0,
+        },
+        wait_for_receipt=True,
+        timeout=1,
+        confirmations=0,
+    )
+
+    assert ok is True
+    txn._wait_for_confirmations.assert_not_awaited()
+    assert result["confirmations"] == 0
+    assert result["confirmed_block_number"] == 100