wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/adapters/token_adapter/test_adapter.py

@@ -0,0 +1,125 @@
+from unittest.mock import patch
+
+import pytest
+
+from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
+
+
+class TestTokenAdapter:
+    """Test cases for TokenAdapter"""
+
+    @pytest.fixture
+    def adapter(self):
+        return TokenAdapter()
+
+    def test_init_with_default_config(self):
+        """Test adapter initialization with default config"""
+        adapter = TokenAdapter()
+        assert adapter.adapter_type == "TOKEN"
+        assert adapter.token_client is not None
+
+    @pytest.mark.asyncio
+    async def test_get_token_success(self, adapter):
+        """Test successful token retrieval by address"""
+        mock_token_data = {
+            "address": "0x1234...",
+            "symbol": "TEST",
+            "name": "Test Token",
+            "decimals": 18,
+        }
+
+        with patch.object(
+            adapter.token_client, "get_token_details", return_value=mock_token_data
+        ):
+            success, data = await adapter.get_token("0x1234...")
+
+            assert success is True
+            assert data == mock_token_data
+
+    @pytest.mark.asyncio
+    async def test_get_token_not_found(self, adapter):
+        """Test token not found by address"""
+        with patch.object(adapter.token_client, "get_token_details", return_value=None):
+            success, data = await adapter.get_token("0x1234...")
+
+            assert success is False
+            assert "No token found for" in data
+
+    @pytest.mark.asyncio
+    async def test_get_token_by_token_id(self, adapter):
+        """Test token retrieval with token_id"""
+        mock_token_data = {"address": "0x1234...", "symbol": "TEST"}
+
+        with patch.object(
+            adapter.token_client, "get_token_details", return_value=mock_token_data
+        ):
+            success, data = await adapter.get_token("token-123")
+
+            assert success is True
+            assert data == mock_token_data
+
+    def test_adapter_type(self, adapter):
+        """Test adapter has adapter_type"""
+        assert adapter.adapter_type == "TOKEN"
+
+    @pytest.mark.asyncio
+    async def test_get_token_price_success(self, adapter):
+        """Test successful token price retrieval"""
+        mock_token_data = {
+            "current_price": 1.50,
+            "price_change_24h": 0.05,
+            "price_change_percentage_24h": 3.45,
+            "market_cap": 1000000,
+            "total_volume": 50000,
+            "symbol": "TEST",
+            "name": "Test Token",
+            "address": "0x1234...",
+        }
+
+        with patch.object(
+            adapter.token_client, "get_token_details", return_value=mock_token_data
+        ):
+            success, data = await adapter.get_token_price("test-token")
+
+            assert success is True
+            assert data["current_price"] == 1.50
+            assert data["symbol"] == "TEST"
+            assert data["name"] == "Test Token"
+
+    @pytest.mark.asyncio
+    async def test_get_token_price_not_found(self, adapter):
+        """Test token price not found"""
+        with patch.object(adapter.token_client, "get_token_details", return_value=None):
+            success, data = await adapter.get_token_price("invalid-token")
+
+            assert success is False
+            assert "No token found for" in data
+
+    @pytest.mark.asyncio
+    async def test_get_gas_token_success(self, adapter):
+        """Test successful gas token retrieval"""
+        mock_gas_token_data = {
+            "id": "ethereum-base",
+            "symbol": "ETH",
+            "name": "Ethereum",
+            "address": "0x0000000000000000000000000000000000000000",
+            "decimals": 18,
+        }
+
+        with patch.object(
+            adapter.token_client, "get_gas_token", return_value=mock_gas_token_data
+        ):
+            success, data = await adapter.get_gas_token("base")
+
+            assert success is True
+            assert data["symbol"] == "ETH"
+            assert data["name"] == "Ethereum"
+
+    @pytest.mark.asyncio
+    async def test_get_gas_token_not_found(self, adapter):
+        """Test gas token not found"""
+        with patch.object(adapter.token_client, "get_gas_token", return_value=None):
+            success, data = await adapter.get_gas_token("invalid-chain")
+
+            assert success is False
+            assert "No gas token found for chain" in data

wayfinder_paths/config.example.json

@@ -0,0 +1,22 @@
+{
+    "user": {
+      "username": "your_username",
+      "password": "your_password",
+      "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": {
+      "rpc_urls": {
+        "1": "https://eth.llamarpc.com",
+        "42161": "https://arb1.arbitrum.io/rpc",
+        "8453": "https://mainnet.base.org",
+        "solana": "https://api.mainnet-beta.solana.com",
+        "999": "https://rpc.hyperliquid.xyz/evm"
+      }
+    }
+  }

wayfinder_paths/conftest.py

@@ -0,0 +1,31 @@
+"""
+Conftest for wayfinder-paths package tests.
+Adds wayfinder-paths directory to Python path for imports.
+This must run early, so imports like 'from tests.test_utils' work.
+"""
+
+import sys
+from pathlib import Path
+
+# Add wayfinder-paths directory to Python path for imports (for tests.test_utils)
+# This needs to be at index 0 to take precedence over repo root 'tests/' directory
+_wayfinder_path_dir = Path(__file__).parent
+_wayfinder_path_str = str(_wayfinder_path_dir)
+
+
+def pytest_configure(config):
+    """Configure pytest - runs early to set up imports."""
+    if _wayfinder_path_str not in sys.path:
+        sys.path.insert(0, _wayfinder_path_str)
+    elif sys.path.index(_wayfinder_path_str) > 0:
+        # Move to front if it exists but isn't first
+        sys.path.remove(_wayfinder_path_str)
+        sys.path.insert(0, _wayfinder_path_str)
+
+
+# Also set it immediately (in case pytest_configure hasn't run yet)
+if _wayfinder_path_str not in sys.path:
+    sys.path.insert(0, _wayfinder_path_str)
+elif sys.path.index(_wayfinder_path_str) > 0:
+    sys.path.remove(_wayfinder_path_str)
+    sys.path.insert(0, _wayfinder_path_str)

wayfinder_paths/core/__init__.py

@@ -0,0 +1,18 @@
+"""Wayfinder Paths Core Engine"""
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.engine.StrategyJob import StrategyJob
+from wayfinder_paths.core.strategies.Strategy import (
+    LiquidationResult,
+    StatusDict,
+    StatusTuple,
+    Strategy,
+)
+
+__all__ = [
+    "Strategy",
+    "StatusDict",
+    "StatusTuple",
+    "BaseAdapter",
+    "StrategyJob",
+]

wayfinder_paths/core/adapters/BaseAdapter.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import Any
+
+from loguru import logger
+
+
+class BaseAdapter(ABC):
+    """Base adapter class for exchange/protocol integrations"""
+
+    adapter_type: str | None = None
+
+    def __init__(self, name: str, config: dict[str, Any] | None = None):
+        self.name = name
+        self.config = config or {}
+        self.logger = logger.bind(adapter=self.__class__.__name__)
+
+    async def connect(self) -> bool:
+        """Optional: establish connectivity. Defaults to True."""
+        return True
+
+    async def get_balance(self, asset: str) -> dict[str, Any]:
+        """
+        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__}"
+        )
+
+    async def health_check(self) -> dict[str, Any]:
+        """
+        Check adapter health and connectivity
+        Returns: Health status dictionary
+        """
+        try:
+            connected = await self.connect()
+            return {
+                "status": "healthy" if connected else "unhealthy",
+                "connected": connected,
+                "adapter": self.adapter_type or self.__class__.__name__,
+            }
+        except Exception as e:
+            return {
+                "status": "error",
+                "error": str(e),
+                "adapter": self.adapter_type or self.__class__.__name__,
+            }
+
+    async def close(self) -> None:
+        """Clean up resources"""
+        pass

wayfinder_paths/core/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Core Adapter Module - SDK surface re-export"""
+
+from .base import BaseAdapter
+
+__all__ = ["BaseAdapter"]

wayfinder_paths/core/adapters/base.py

@@ -0,0 +1,5 @@
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+
+__all__ = [
+    "BaseAdapter",
+]

wayfinder_paths/core/adapters/models.py

@@ -0,0 +1,46 @@
+"""Pydantic models for ledger operations."""
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class OperationBase(BaseModel):
+    adapter: str
+    transaction_hash: str | None
+    transaction_chain_id: int | None
+
+
+class SWAP(OperationBase):
+    """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_status: str | None = None
+    transaction_receipt: dict[str, Any] | None = None
+
+
+class LEND(OperationBase):
+    type: Literal["LEND"] = "LEND"
+    contract: str
+    amount: int
+
+
+class UNLEND(OperationBase):
+    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/analytics/__init__.py

@@ -0,0 +1,11 @@
+"""Reusable, strategy-agnostic analytics helpers."""
+
+from .bootstrap import block_bootstrap_paths
+from .stats import percentile, rolling_min_sum, z_from_conf
+
+__all__ = [
+    "block_bootstrap_paths",
+    "percentile",
+    "rolling_min_sum",
+    "z_from_conf",
+]

wayfinder_paths/core/analytics/bootstrap.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import random
+from collections.abc import Sequence
+
+
+def block_bootstrap_paths(
+    *series: Sequence[float],
+    block_hours: int,
+    sims: int,
+    rng: random.Random,
+) -> list[tuple[list[float], ...]]:
+    """
+    Block-bootstrap aligned series together.
+
+    Samples contiguous blocks from the same indices across every series so their
+    time alignment is preserved (useful for resampling correlated paths).
+
+    Args:
+        *series: One or more equal-frequency series (funding, closes, highs, ...)
+        block_hours: Block length for sampling (clamped to [1, base_len])
+        sims: Number of bootstrap paths to return
+        rng: Random generator
+
+    Returns:
+        List of tuples, each containing resampled series lists (truncated to the
+        shared base length).
+    """
+    if sims <= 0 or not series:
+        return []
+
+    base_len = min(len(s) for s in series)
+    if base_len <= 1:
+        return []
+
+    block_hours = max(1, min(int(block_hours), base_len))
+    max_start = max(0, base_len - block_hours)
+
+    if max_start == 0:
+        # Series are shorter than a full block; just return copies.
+        out: list[tuple[list[float], ...]] = []
+        for _ in range(sims):
+            out.append(tuple(list(s[:base_len]) for s in series))
+        return out
+
+    bootstrap_paths: list[tuple[list[float], ...]] = []
+    for _ in range(sims):
+        sampled: list[list[float]] = [[] for _ in series]
+        while len(sampled[0]) < base_len:
+            start = rng.randint(0, max_start)
+            end = start + block_hours
+            for i, s in enumerate(series):
+                sampled[i].extend(s[start:end])
+
+        bootstrap_paths.append(tuple(x[:base_len] for x in sampled))
+
+    return bootstrap_paths

wayfinder_paths/core/analytics/stats.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from statistics import NormalDist
+
+
+def z_from_conf(confidence: float) -> float:
+    """Return the two-sided z-score for a confidence level (e.g. 0.975)."""
+    return NormalDist().inv_cdf((1 + float(confidence)) / 2)
+
+
+def rolling_min_sum(arr: Sequence[float], window: int) -> float:
+    """Return the minimum rolling window sum over `arr`."""
+    values = list(arr)
+    if window <= 0:
+        return 0.0
+    if len(values) < window:
+        return float(sum(values))
+
+    current_sum = sum(values[:window])
+    min_sum = current_sum
+    for i in range(window, len(values)):
+        current_sum = current_sum - values[i - window] + values[i]
+        min_sum = min(min_sum, current_sum)
+    return float(min_sum)
+
+
+def percentile(sorted_values: Sequence[float], pct: float) -> float:
+    """
+    Inclusive percentile on a pre-sorted list.
+
+    Mirrors a simple linear interpolation between closest ranks.
+    """
+    values = list(sorted_values)
+    if not values:
+        return float("nan")
+    if len(values) == 1:
+        return float(values[0])
+
+    pct = min(max(float(pct), 0.0), 1.0)
+    idx = (len(values) - 1) * pct
+    lower = math.floor(idx)
+    upper = math.ceil(idx)
+    if lower == upper:
+        return float(values[lower])
+    weight = idx - lower
+    return float(values[lower] + weight * (values[upper] - values[lower]))

wayfinder_paths/core/analytics/test_analytics.py

@@ -0,0 +1,170 @@
+"""Tests for core analytics modules (bootstrap, stats)."""
+
+import math
+import random
+
+from wayfinder_paths.core.analytics.bootstrap import block_bootstrap_paths
+from wayfinder_paths.core.analytics.stats import (
+    percentile,
+    rolling_min_sum,
+    z_from_conf,
+)
+
+
+class TestBlockBootstrapPaths:
+    """Tests for block_bootstrap_paths function."""
+
+    def test_returns_empty_when_sims_zero(self):
+        """Should return empty list when sims=0."""
+        result = block_bootstrap_paths(
+            [1.0, 2.0, 3.0], block_hours=2, sims=0, rng=random.Random(42)
+        )
+        assert result == []
+
+    def test_returns_empty_when_series_empty(self):
+        """Should return empty list when no series provided."""
+        result = block_bootstrap_paths(block_hours=2, sims=10, rng=random.Random(42))
+        assert result == []
+
+    def test_returns_empty_when_base_len_one(self):
+        """Should return empty list when series has only one element."""
+        result = block_bootstrap_paths(
+            [1.0], block_hours=2, sims=10, rng=random.Random(42)
+        )
+        assert result == []
+
+    def test_single_series(self):
+        """Should bootstrap a single series correctly."""
+        series = [1.0, 2.0, 3.0, 4.0, 5.0]
+        result = block_bootstrap_paths(
+            series, block_hours=2, sims=5, rng=random.Random(42)
+        )
+
+        assert len(result) == 5
+        for path in result:
+            assert len(path) == 1  # One series
+            assert len(path[0]) == 5  # Same length as original
+
+    def test_multiple_aligned_series(self):
+        """Should bootstrap multiple series with aligned indices."""
+        series_a = [1.0, 2.0, 3.0, 4.0, 5.0]
+        series_b = [10.0, 20.0, 30.0, 40.0, 50.0]
+        result = block_bootstrap_paths(
+            series_a, series_b, block_hours=2, sims=3, rng=random.Random(42)
+        )
+
+        assert len(result) == 3
+        for path in result:
+            assert len(path) == 2  # Two series
+            assert len(path[0]) == 5
+            assert len(path[1]) == 5
+
+    def test_preserves_length(self):
+        """Bootstrapped paths should have same length as input."""
+        series = list(range(100))
+        series_float = [float(x) for x in series]
+        result = block_bootstrap_paths(
+            series_float, block_hours=24, sims=10, rng=random.Random(42)
+        )
+
+        for path in result:
+            assert len(path[0]) == 100
+
+    def test_block_clamping(self):
+        """Block hours should be clamped to valid range."""
+        series = [1.0, 2.0, 3.0]
+
+        # Block larger than series - should still work
+        result = block_bootstrap_paths(
+            series, block_hours=100, sims=2, rng=random.Random(42)
+        )
+        assert len(result) == 2
+
+        # Block of zero - should clamp to 1
+        result = block_bootstrap_paths(
+            series, block_hours=0, sims=2, rng=random.Random(42)
+        )
+        assert len(result) == 2
+
+
+class TestZFromConf:
+    """Tests for z_from_conf function."""
+
+    def test_95_confidence(self):
+        """95% confidence should give z ≈ 1.96."""
+        z = z_from_conf(0.95)
+        assert 1.95 < z < 1.97
+
+    def test_99_confidence(self):
+        """99% confidence should give z ≈ 2.576."""
+        z = z_from_conf(0.99)
+        assert 2.57 < z < 2.58
+
+    def test_90_confidence(self):
+        """90% confidence should give z ≈ 1.645."""
+        z = z_from_conf(0.90)
+        assert 1.64 < z < 1.66
+
+
+class TestRollingMinSum:
+    """Tests for rolling_min_sum function."""
+
+    def test_basic(self):
+        """Basic rolling min sum calculation."""
+        arr = [1, -2, 3, -4, 5]
+        result = rolling_min_sum(arr, 2)
+        # Windows: [1,-2]=-1, [-2,3]=1, [3,-4]=-1, [-4,5]=1
+        assert result == -1
+
+    def test_window_larger_than_arr(self):
+        """Window larger than array returns sum of array."""
+        arr = [1.0, 2.0, 3.0]
+        result = rolling_min_sum(arr, 10)
+        assert result == 6.0
+
+    def test_window_zero(self):
+        """Window of zero returns 0."""
+        arr = [1.0, 2.0, 3.0]
+        result = rolling_min_sum(arr, 0)
+        assert result == 0.0
+
+    def test_all_negative(self):
+        """All negative values."""
+        arr = [-1.0, -2.0, -3.0, -4.0]
+        result = rolling_min_sum(arr, 2)
+        # Windows: [-1,-2]=-3, [-2,-3]=-5, [-3,-4]=-7
+        assert result == -7.0
+
+
+class TestPercentile:
+    """Tests for percentile function."""
+
+    def test_empty_returns_nan(self):
+        """Empty list returns nan."""
+        result = percentile([], 0.5)
+        assert math.isnan(result)
+
+    def test_single_value(self):
+        """Single value returns that value regardless of percentile."""
+        assert percentile([42.0], 0.0) == 42.0
+        assert percentile([42.0], 0.5) == 42.0
+        assert percentile([42.0], 1.0) == 42.0
+
+    def test_median(self):
+        """50th percentile (median) calculation."""
+        sorted_values = [1.0, 2.0, 3.0, 4.0, 5.0]
+        result = percentile(sorted_values, 0.5)
+        assert result == 3.0
+
+    def test_interpolation(self):
+        """Percentile with interpolation."""
+        sorted_values = [0.0, 10.0]
+        # 25th percentile should interpolate to 2.5
+        result = percentile(sorted_values, 0.25)
+        assert result == 2.5
+
+    def test_bounds_clamped(self):
+        """Percentile values outside [0,1] are clamped."""
+        sorted_values = [1.0, 2.0, 3.0]
+        assert percentile(sorted_values, -1.0) == 1.0  # Clamped to 0
+        assert percentile(sorted_values, 2.0) == 3.0  # Clamped to 1