wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/strategies/stablecoin_yield_strategy/test_strategy.py

@@ -0,0 +1,520 @@
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock
+
+# Ensure wayfinder-paths is on path for tests.test_utils import
+# This is a workaround until conftest loading order is resolved
+_wayfinder_path_dir = Path(__file__).parent.parent.parent.resolve()
+_wayfinder_path_str = str(_wayfinder_path_dir)
+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 to take precedence
+    sys.path.remove(_wayfinder_path_str)
+    sys.path.insert(0, _wayfinder_path_str)
+
+import pytest  # noqa: E402
+
+# Import test utilities
+try:
+    from tests.test_utils import get_canonical_examples, load_strategy_examples
+except ImportError:
+    # Fallback if path setup didn't work
+    import importlib.util
+
+    test_utils_path = Path(_wayfinder_path_dir) / "tests" / "test_utils.py"
+    spec = importlib.util.spec_from_file_location("tests.test_utils", test_utils_path)
+    test_utils = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(test_utils)
+    get_canonical_examples = test_utils.get_canonical_examples
+    load_strategy_examples = test_utils.load_strategy_examples
+
+from wayfinder_paths.strategies.stablecoin_yield_strategy.strategy import (  # noqa: E402
+    StablecoinYieldStrategy,
+)
+
+
+@pytest.fixture
+def strategy():
+    """Create a strategy instance for testing with minimal config."""
+    mock_config = {
+        "main_wallet": {"address": "0x1234567890123456789012345678901234567890"},
+        "strategy_wallet": {"address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"},
+    }
+
+    s = StablecoinYieldStrategy(
+        config=mock_config,
+        main_wallet=mock_config["main_wallet"],
+        strategy_wallet=mock_config["strategy_wallet"],
+        simulation=True,
+    )
+
+    if hasattr(s, "balance_adapter") and s.balance_adapter:
+        usdc_balance_mock = AsyncMock(return_value=(True, 60000000))
+        gas_balance_mock = AsyncMock(return_value=(True, 2000000000000000))
+
+        def get_balance_side_effect(token_id, wallet_address, **kwargs):
+            if token_id == "usd-coin-base" or token_id == "usd-coin":
+                return usdc_balance_mock.return_value
+            elif token_id == "ethereum-base" or token_id == "ethereum":
+                return gas_balance_mock.return_value
+            return (True, 1000000000)
+
+        s.balance_adapter.get_balance = AsyncMock(side_effect=get_balance_side_effect)
+
+    if hasattr(s, "token_adapter") and s.token_adapter:
+        default_usdc = {
+            "id": "usd-coin-base",
+            "symbol": "USDC",
+            "name": "USD Coin",
+            "decimals": 6,
+            "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+            "chain": {"code": "base", "id": 8453, "name": "Base"},
+        }
+
+        default_pool_token = {
+            "id": "test-pool-base",
+            "symbol": "POOL",
+            "name": "Test Pool",
+            "decimals": 18,
+            "address": "0x1234567890123456789012345678901234567890",
+            "chain": {"code": "base", "id": 8453, "name": "Base"},
+        }
+
+        def get_token_side_effect(address=None, token_id=None, **kwargs):
+            if token_id == "usd-coin-base" or token_id == "usd-coin":
+                return (True, default_usdc)
+            elif (
+                token_id == "test-pool-base"
+                or address == "0x1234567890123456789012345678901234567890"
+            ):
+                return (True, default_pool_token)
+            return (True, default_usdc)
+
+        s.token_adapter.get_token = AsyncMock(side_effect=get_token_side_effect)
+        s.token_adapter.get_gas_token = AsyncMock(
+            return_value=(
+                True,
+                {
+                    "id": "ethereum-base",
+                    "symbol": "ETH",
+                    "name": "Ethereum",
+                    "decimals": 18,
+                    "address": "0x4200000000000000000000000000000000000006",
+                    "chain": {"code": "base", "id": 8453, "name": "Base"},
+                },
+            )
+        )
+
+    if hasattr(s, "balance_adapter") and s.balance_adapter:
+        s.balance_adapter.move_from_main_wallet_to_strategy_wallet = AsyncMock(
+            return_value=(True, "Transfer successful (simulated)")
+        )
+        s.balance_adapter.move_from_strategy_wallet_to_main_wallet = AsyncMock(
+            return_value=(True, "Transfer successful (simulated)")
+        )
+        if hasattr(s.balance_adapter, "wallet_provider"):
+            s.balance_adapter.wallet_provider.broadcast_transaction = AsyncMock(
+                return_value=(True, {"transaction_hash": "0xDEADBEEF"})
+            )
+
+    if hasattr(s, "ledger_adapter") and s.ledger_adapter:
+        s.ledger_adapter.get_strategy_net_deposit = AsyncMock(
+            return_value=(True, {"net_deposit": 0})
+        )
+        s.ledger_adapter.get_strategy_transactions = AsyncMock(
+            return_value=(True, {"transactions": []})
+        )
+
+    if hasattr(s, "pool_adapter") and s.pool_adapter:
+        s.pool_adapter.find_high_yield_pools = AsyncMock(
+            return_value=(True, {"pools": [], "total_found": 0})
+        )
+        s.pool_adapter.get_pools_by_ids = AsyncMock(
+            return_value=(
+                True,
+                {"pools": [{"id": "test-pool-base", "apy": 15.0, "symbol": "POOL"}]},
+            )
+        )
+        s.pool_adapter.get_llama_matches = AsyncMock(
+            return_value=(
+                True,
+                {
+                    "matches": [
+                        {
+                            "llama_stablecoin": True,
+                            "llama_il_risk": "no",
+                            "llama_tvl_usd": 2000000,
+                            "llama_apy_pct": 5.0,
+                            "network": "base",
+                            "address": "0x1234567890123456789012345678901234567890",
+                            "token_id": "test-pool-base",
+                            "pool_id": "test-pool-base",
+                            "llama_combined_apy_pct": 15.0,
+                        }
+                    ]
+                },
+            )
+        )
+
+    if hasattr(s, "brap_adapter") and s.brap_adapter:
+
+        def get_swap_quote_side_effect(*args, **kwargs):
+            to_token_address = kwargs.get("to_token_address", "")
+            if to_token_address == "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913":
+                return (
+                    True,
+                    {
+                        "quotes": {
+                            "best_quote": {
+                                "output_amount": "99900000",
+                            }
+                        }
+                    },
+                )
+            return (
+                True,
+                {
+                    "quotes": {
+                        "best_quote": {
+                            "output_amount": "105000000",
+                            "input_amount": "50000000000000",
+                            "toAmount": "105000000",
+                            "estimatedGas": "1000000000",
+                            "fromAmount": "100000000",
+                            "fromToken": {"symbol": "USDC"},
+                            "toToken": {"symbol": "POOL"},
+                        }
+                    }
+                },
+            )
+
+        s.brap_adapter.get_swap_quote = AsyncMock(
+            side_effect=get_swap_quote_side_effect
+        )
+
+    if (
+        hasattr(s, "brap_adapter")
+        and s.brap_adapter
+        and hasattr(s.brap_adapter, "swap_from_quote")
+    ):
+        s.brap_adapter.swap_from_quote = AsyncMock(return_value=None)
+    if hasattr(s, "brap_adapter") and hasattr(s.brap_adapter, "wallet_provider"):
+        s.brap_adapter.wallet_provider.broadcast_transaction = AsyncMock(
+            return_value=(True, {"transaction_hash": "0xBEEF"})
+        )
+
+    s.DEPOSIT_USDC = 0
+    s.usdc_token_info = {
+        "id": "usd-coin-base",
+        "symbol": "USDC",
+        "name": "USD Coin",
+        "decimals": 6,
+        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "chain": {"code": "base", "id": 8453, "name": "Base"},
+    }
+    s.gas_token = {
+        "id": "ethereum-base",
+        "symbol": "ETH",
+        "name": "Ethereum",
+        "decimals": 18,
+        "address": "0x4200000000000000000000000000000000000006",
+        "chain": {"code": "base", "id": 8453, "name": "Base"},
+    }
+    s.current_pool = {
+        "id": "usd-coin-base",
+        "symbol": "USDC",
+        "decimals": 6,
+        "chain": {"code": "base", "id": 8453, "name": "Base"},
+    }
+    s.current_pool_balance = 100000000
+    s.current_combined_apy_pct = 0.0
+    s.current_pool_data = None
+
+    if hasattr(s, "token_adapter") and s.token_adapter:
+        if not hasattr(s.token_adapter, "get_token_price"):
+            s.token_adapter.get_token_price = AsyncMock()
+
+        def get_token_price_side_effect(token_id):
+            if token_id == "ethereum-base":
+                return (True, {"current_price": 2000.0})
+            else:
+                return (True, {"current_price": 1.0})
+
+        s.token_adapter.get_token_price = AsyncMock(
+            side_effect=get_token_price_side_effect
+        )
+
+    async def mock_sweep_wallet(target_token):
+        pass
+
+    async def mock_refresh_current_pool_balance():
+        pass
+
+    async def mock_rebalance_gas(target_pool):
+        return (True, "Gas rebalanced")
+
+    async def mock_has_idle_assets(balances, target):
+        return True
+
+    s._sweep_wallet = mock_sweep_wallet
+    s._refresh_current_pool_balance = mock_refresh_current_pool_balance
+    s._rebalance_gas = mock_rebalance_gas
+    s._has_idle_assets = mock_has_idle_assets
+
+    return s
+
+
+@pytest.mark.asyncio
+@pytest.mark.smoke
+async def test_smoke(strategy):
+    """REQUIRED: Basic smoke test - verifies strategy lifecycle."""
+    examples = load_strategy_examples(Path(__file__))
+    smoke_data = examples["smoke"]
+
+    st = await strategy.status()
+    assert isinstance(st, dict)
+    assert "portfolio_value" in st or "net_deposit" in st or "strategy_status" in st
+
+    deposit_params = smoke_data.get("deposit", {})
+    ok, msg = await strategy.deposit(**deposit_params)
+    assert isinstance(ok, bool)
+    assert isinstance(msg, str)
+
+    ok, msg = await strategy.update(**smoke_data.get("update", {}))
+    assert isinstance(ok, bool)
+
+    ok, msg = await strategy.withdraw(**smoke_data.get("withdraw", {}))
+    assert isinstance(ok, bool)
+
+
+@pytest.mark.asyncio
+async def test_canonical_usage(strategy):
+    """REQUIRED: Test canonical usage examples from examples.json (minimum).
+
+    Canonical usage = all positive usage examples (excluding error cases).
+    This is the MINIMUM requirement - feel free to add more test cases here.
+    """
+    examples = load_strategy_examples(Path(__file__))
+    canonical = get_canonical_examples(examples)
+
+    for example_name, example_data in canonical.items():
+        if "deposit" in example_data:
+            deposit_params = example_data.get("deposit", {})
+            ok, _ = await strategy.deposit(**deposit_params)
+            assert ok, f"Canonical example '{example_name}' deposit failed"
+
+        if "update" in example_data:
+            ok, msg = await strategy.update()
+            assert ok, f"Canonical example '{example_name}' update failed: {msg}"
+
+        if "status" in example_data:
+            st = await strategy.status()
+            assert isinstance(st, dict), (
+                f"Canonical example '{example_name}' status failed"
+            )
+
+
+@pytest.mark.asyncio
+async def test_error_cases(strategy):
+    """OPTIONAL: Test error scenarios from examples.json."""
+    examples = load_strategy_examples(Path(__file__))
+
+    for example_name, example_data in examples.items():
+        if isinstance(example_data, dict) and "expect" in example_data:
+            expect = example_data.get("expect", {})
+
+            if "deposit" in example_data:
+                deposit_params = example_data.get("deposit", {})
+                ok, _ = await strategy.deposit(**deposit_params)
+
+                if expect.get("success") is False:
+                    assert ok is False, (
+                        f"Expected {example_name} deposit to fail but it succeeded"
+                    )
+                elif expect.get("success") is True:
+                    assert ok is True, (
+                        f"Expected {example_name} deposit to succeed but it failed"
+                    )
+
+            if "update" in example_data:
+                ok, _ = await strategy.update()
+                if "success" in expect:
+                    expected_success = expect.get("success")
+                    assert ok == expected_success, (
+                        f"Expected {example_name} update to "
+                        f"{'succeed' if expected_success else 'fail'} but got opposite"
+                    )
+
+
+@pytest.mark.asyncio
+async def test_token_tracking_initialization(strategy):
+    """Test that tracked_token_ids and tracked_balances are initialized."""
+    assert hasattr(strategy, "tracked_token_ids")
+    assert hasattr(strategy, "tracked_balances")
+    assert isinstance(strategy.tracked_token_ids, set)
+    assert isinstance(strategy.tracked_balances, dict)
+
+
+@pytest.mark.asyncio
+async def test_track_token(strategy):
+    """Test that _track_token adds tokens to tracked state."""
+    test_token_id = "test-token-base"
+    test_balance = 1000000
+
+    strategy._track_token(test_token_id, test_balance)
+
+    assert test_token_id in strategy.tracked_token_ids
+    assert strategy.tracked_balances.get(test_token_id) == test_balance
+
+
+@pytest.mark.asyncio
+async def test_update_balance(strategy):
+    """Test that _update_balance updates tracked balances."""
+    test_token_id = "test-token-base"
+    initial_balance = 1000000
+    updated_balance = 2000000
+
+    strategy._track_token(test_token_id, initial_balance)
+    assert strategy.tracked_balances.get(test_token_id) == initial_balance
+
+    strategy._update_balance(test_token_id, updated_balance)
+    assert strategy.tracked_balances.get(test_token_id) == updated_balance
+
+
+@pytest.mark.asyncio
+async def test_get_non_zero_tracked_tokens(strategy):
+    """Test that _get_non_zero_tracked_tokens returns only non-zero balances."""
+    strategy._track_token("token-1", 1000000)
+    strategy._track_token("token-2", 0)
+    strategy._track_token("token-3", 5000000)
+
+    non_zero = strategy._get_non_zero_tracked_tokens()
+
+    assert len(non_zero) == 2
+    token_ids = [token_id for token_id, _ in non_zero]
+    assert "token-1" in token_ids
+    assert "token-3" in token_ids
+    assert "token-2" not in token_ids
+
+
+@pytest.mark.asyncio
+async def test_refresh_tracked_balances(strategy):
+    """Test that _refresh_tracked_balances updates all tracked token balances."""
+    # Track some tokens
+    strategy._track_token("usd-coin-base")
+    strategy._track_token("ethereum-base")
+
+    # Refresh balances
+    await strategy._refresh_tracked_balances()
+
+    # Verify balances were fetched
+    assert "usd-coin-base" in strategy.tracked_balances
+    assert "ethereum-base" in strategy.tracked_balances
+
+
+@pytest.mark.asyncio
+async def test_deposit_tracks_usdc(strategy):
+    """Test that deposit operation tracks USDC token."""
+    # Clear tracked state
+    strategy.tracked_token_ids.clear()
+    strategy.tracked_balances.clear()
+
+    # Perform deposit
+    ok, _ = await strategy.deposit(main_token_amount=100.0)
+
+    # Verify USDC is tracked
+    assert ok
+    usdc_token_id = strategy.usdc_token_info.get("token_id")
+    assert usdc_token_id in strategy.tracked_token_ids
+
+
+@pytest.mark.asyncio
+async def test_sweep_wallet_uses_tracked_tokens(strategy):
+    """Test that _sweep_wallet only swaps tracked tokens."""
+    # Setup: track some tokens with balances
+    strategy._track_token("token-1", 1000000)
+    strategy._track_token("token-2", 2000000)
+
+    # Mock balance adapter to return fresh balances
+    strategy.balance_adapter.get_balance = AsyncMock(
+        side_effect=lambda token_id, **kwargs: (
+            True,
+            strategy.tracked_balances.get(token_id, 0),
+        )
+    )
+
+    # Mock brap adapter swap
+    strategy.brap_adapter.swap_from_token_ids = AsyncMock(
+        return_value=(True, "Swap successful")
+    )
+
+    target_token = {
+        "token_id": "usd-coin-base",
+        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "chain": {"code": "base", "name": "Base"},
+    }
+
+    # Call sweep
+    await strategy._sweep_wallet(target_token)
+
+    # Verify that swap was called for tracked tokens
+    assert strategy.brap_adapter.swap_from_token_ids.called
+
+
+@pytest.mark.asyncio
+async def test_get_non_gas_balances_uses_tracked_state(strategy):
+    """Test that _get_non_gas_balances only checks tracked tokens."""
+    # Setup tracked tokens
+    usdc_token_id = "usd-coin-base"
+    pool_token_id = "test-pool-base"
+
+    strategy._track_token(usdc_token_id, 100000000)
+    strategy._track_token(pool_token_id, 50000000000000000000)
+
+    # Mock refresh
+    strategy.balance_adapter.get_balance = AsyncMock(
+        side_effect=lambda token_id, **kwargs: (
+            True,
+            strategy.tracked_balances.get(token_id, 0),
+        )
+    )
+
+    # Get non-gas balances
+    balances = await strategy._get_non_gas_balances()
+
+    # Verify only tracked tokens are returned (excluding gas)
+    token_ids = [b["token_id"] for b in balances]
+    assert usdc_token_id in token_ids or pool_token_id in token_ids
+    assert len(balances) <= len(strategy.tracked_token_ids)
+
+
+@pytest.mark.asyncio
+async def test_partial_liquidate_uses_tracked_tokens(strategy):
+    """Test that partial_liquidate only liquidates tracked tokens."""
+    # Setup tracked tokens with balances
+    strategy._track_token("usd-coin-base", 50000000)  # 50 USDC
+    strategy._track_token("test-pool-base", 100000000000000000000)  # 100 POOL tokens
+
+    # Mock balance and token adapters
+    strategy.balance_adapter.get_balance = AsyncMock(
+        side_effect=lambda token_id, **kwargs: (
+            True,
+            strategy.tracked_balances.get(token_id, 0),
+        )
+    )
+
+    strategy.token_adapter.get_token_price = AsyncMock(
+        return_value=(True, {"current_price": 1.0})
+    )
+
+    strategy.brap_adapter.swap_from_token_ids = AsyncMock(
+        return_value=(True, "Swap successful")
+    )
+
+    # Call partial liquidate
+    ok, msg = await strategy.partial_liquidate(usd_value=75.0)
+
+    # Verify success
+    assert ok
+    assert "liquidation completed" in msg.lower()

wayfinder_paths/templates/adapter/README.md

@@ -0,0 +1,105 @@
+# Adapter Template
+
+Adapters expose protocol-specific capabilities to strategies. They should be thin, async wrappers around one or more clients from `wayfinder_paths.core.clients`.
+
+## Quick start
+
+1. Copy the template:
+   ```
+   cp -r wayfinder_paths/templates/adapter wayfinder_paths/adapters/my_adapter
+   ```
+2. Rename `MyAdapter` in `adapter.py` and update `manifest.yaml` so the `entrypoint` matches (`adapters.my_adapter.adapter.MyAdapter`).
+3. Declare the capabilities your adapter will provide and list any client dependencies (e.g., `PoolClient`, `LedgerClient`).
+4. Implement the public methods that fulfill those capabilities.
+
+## Layout
+
+```
+my_adapter/
+├── adapter.py          # Adapter implementation
+├── manifest.yaml       # Entrypoint + capabilities + dependency list
+├── examples.json       # Example payloads (optional but encouraged)
+├── test_adapter.py     # Pytest smoke tests
+└── README.md           # Adapter-specific notes
+```
+
+## Skeleton adapter
+
+```python
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.clients.PoolClient import PoolClient
+
+
+class MyAdapter(BaseAdapter):
+    adapter_type = "MY_ADAPTER"
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        super().__init__("my_adapter", config)
+        self.pool_client = PoolClient()
+
+    async def connect(self) -> bool:
+        """Optional: prime caches / test connectivity."""
+        return True
+
+    async def get_pools(self, pool_ids: list[str]) -> tuple[bool, Any]:
+        """Example capability that proxies PoolClient."""
+        try:
+            data = await self.pool_client.get_pools_by_ids(
+                pool_ids=",".join(pool_ids), merge_external=True
+            )
+            return (True, data)
+        except Exception as exc:  # noqa: BLE001
+            self.logger.error(f"Failed to fetch pools: {exc}")
+            return (False, str(exc))
+```
+
+Your adapter should return `(success, payload)` tuples for every operation, just like the built-in adapters do.
+
+## Manifest
+
+Every adapter needs a manifest describing its import path, declared capabilities, and runtime dependencies.
+
+```yaml
+schema_version: "0.1"
+entrypoint: "adapters.my_adapter.adapter.MyAdapter"
+capabilities:
+  - "pool.read"
+dependencies:
+  - "PoolClient"
+```
+
+The `dependencies` list is informational today but helps reviewers understand which core clients you rely on.
+
+## Testing
+
+`test_adapter.py` should cover the public methods you expose. Patch out remote clients with `unittest.mock.AsyncMock` so tests run offline.
+
+```python
+import pytest
+from unittest.mock import AsyncMock, patch
+
+from wayfinder_paths.adapters.my_adapter.adapter import MyAdapter
+
+
+@pytest.mark.asyncio
+async def test_get_pools():
+    with patch(
+        "wayfinder_paths.adapters.my_adapter.adapter.PoolClient",
+        return_value=AsyncMock(
+            get_pools_by_ids=AsyncMock(return_value={"pools": []})
+        ),
+    ):
+        adapter = MyAdapter(config={})
+        success, data = await adapter.get_pools(["pool-1"])
+        assert success is True
+        assert "pools" in data
+```
+
+## Best practices
+
+- Capabilities listed in `manifest.yaml` must correspond to methods you implement.
+- Keep adapters stateless and idempotent—strategies may reuse instances across operations.
+- Use `self.logger` for contextual logging (BaseAdapter has already bound the adapter name).
+- Raise `NotImplementedError` for manifest capabilities you intentionally do not support yet.

wayfinder_paths/templates/adapter/adapter.py

@@ -0,0 +1,26 @@
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+
+
+class MyAdapter(BaseAdapter):
+    """
+    Template adapter for a protocol/exchange integration.
+    Copy this folder, rename it (e.g., my_adapter), update manifest entrypoint,
+    and implement the capabilities your manifest declares.
+    """
+
+    adapter_type: str = "MY_ADAPTER"
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        super().__init__("my_adapter", config)
+
+    async def connect(self) -> bool:
+        """Establish connectivity to remote service(s) if needed."""
+        return True
+
+    async def example_operation(self, **kwargs) -> tuple[bool, str]:
+        """
+        Example operation. Replace with your adapter's real API.
+        """
+        return (True, "example.op executed")

wayfinder_paths/templates/adapter/examples.json

@@ -0,0 +1,8 @@
+{
+  "connect": {},
+  "example_operation": {
+    "args": {"foo": "bar"}
+  }
+}
+
+

wayfinder_paths/templates/adapter/manifest.yaml

@@ -0,0 +1,6 @@
+schema_version: "0.1"
+entrypoint: "adapters.my_adapter.adapter.MyAdapter"
+capabilities:
+  - "example.op"
+dependencies:
+  - "MyClient"