wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/vaults/adapters/pool_adapter/adapter.py

@@ -0,0 +1,289 @@
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.clients.PoolClient import PoolClient
+
+
+class PoolAdapter(BaseAdapter):
+    """
+    Pool adapter for DeFi pool data and analytics operations.
+
+    Provides high-level operations for:
+    - Fetching pool information and metadata
+    - Getting pool analytics and reports
+    - Accessing Llama protocol data
+    - Pool discovery and filtering
+    """
+
+    adapter_type: str = "POOL"
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        pool_client: PoolClient | None = None,
+    ):
+        super().__init__("pool_adapter", config)
+        self.pool_client = pool_client or PoolClient()
+
+    async def get_pools_by_ids(
+        self, pool_ids: list[str], merge_external: bool | None = None
+    ) -> tuple[bool, Any]:
+        """
+        Get pool information by pool IDs.
+
+        Args:
+            pool_ids: List of pool identifiers
+            merge_external: Whether to merge external data
+
+        Returns:
+            Tuple of (success, data) where data is pool information or error message
+        """
+        try:
+            pool_ids_str = ",".join(pool_ids)
+            data = await self.pool_client.get_pools_by_ids(
+                pool_ids=pool_ids_str, merge_external=merge_external
+            )
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching pools by IDs: {e}")
+            return (False, str(e))
+
+    async def get_all_pools(
+        self, merge_external: bool | None = None
+    ) -> tuple[bool, Any]:
+        """
+        Get all available pools.
+
+        Args:
+            merge_external: Whether to merge external data
+
+        Returns:
+            Tuple of (success, data) where data is all pools or error message
+        """
+        try:
+            data = await self.pool_client.get_all_pools(merge_external=merge_external)
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching all pools: {e}")
+            return (False, str(e))
+
+    async def get_combined_pool_reports(self) -> tuple[bool, Any]:
+        """
+        Get combined pool reports with analytics.
+
+        Returns:
+            Tuple of (success, data) where data is combined reports or error message
+        """
+        try:
+            data = await self.pool_client.get_combined_pool_reports()
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching combined pool reports: {e}")
+            return (False, str(e))
+
+    async def get_llama_matches(self) -> tuple[bool, Any]:
+        """
+        Get Llama protocol matches for pools.
+
+        Returns:
+            Tuple of (success, data) where data is Llama matches or error message
+        """
+        try:
+            data = await self.pool_client.get_llama_matches()
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching Llama matches: {e}")
+            return (False, str(e))
+
+    async def get_llama_reports(self, identifiers: list[str]) -> tuple[bool, Any]:
+        """
+        Get Llama reports for specific identifiers.
+
+        Args:
+            identifiers: List of identifiers (token IDs, addresses, pool IDs)
+
+        Returns:
+            Tuple of (success, data) where data is Llama reports or error message
+        """
+        try:
+            identifiers_str = ",".join(identifiers)
+            data = await self.pool_client.get_llama_reports(identifiers=identifiers_str)
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching Llama reports: {e}")
+            return (False, str(e))
+
+    async def find_high_yield_pools(
+        self,
+        min_apy: float = 0.01,
+        min_tvl: float = 1000000,
+        stablecoin_only: bool = True,
+        network_codes: list[str] | None = None,
+    ) -> tuple[bool, Any]:
+        """
+        Find high-yield pools based on criteria.
+
+        Args:
+            min_apy: Minimum APY threshold (as decimal, e.g., 0.01 for 1%)
+            min_tvl: Minimum TVL threshold in USD
+            stablecoin_only: Whether to filter for stablecoin pools only
+            network_codes: List of network codes to filter by
+
+        Returns:
+            Tuple of (success, data) where data is filtered pools or error message
+        """
+        try:
+            # Get Llama matches for yield data
+            success, llama_data = await self.get_llama_matches()
+            if not success:
+                return (False, f"Failed to fetch Llama data: {llama_data}")
+
+            matches = llama_data.get("matches", [])
+            filtered_pools = []
+
+            for pool in matches:
+                # Apply filters
+                if stablecoin_only and not pool.get("llama_stablecoin", False):
+                    continue
+
+                if pool.get("llama_tvl_usd", 0) < min_tvl:
+                    continue
+
+                if (
+                    pool.get("llama_apy_pct", 0) < min_apy * 100
+                ):  # Convert to percentage
+                    continue
+
+                if network_codes and pool.get("network", "").lower() not in [
+                    nc.lower() for nc in network_codes
+                ]:
+                    continue
+
+                filtered_pools.append(pool)
+
+            # Sort by APY descending
+            filtered_pools.sort(key=lambda x: x.get("llama_apy_pct", 0), reverse=True)
+
+            return (
+                True,
+                {
+                    "pools": filtered_pools,
+                    "total_found": len(filtered_pools),
+                    "filters_applied": {
+                        "min_apy": min_apy,
+                        "min_tvl": min_tvl,
+                        "stablecoin_only": stablecoin_only,
+                        "network_codes": network_codes,
+                    },
+                },
+            )
+        except Exception as e:
+            self.logger.error(f"Error finding high yield pools: {e}")
+            return (False, str(e))
+
+    async def get_pool_analytics(self, pool_ids: list[str]) -> tuple[bool, Any]:
+        """
+        Get comprehensive analytics for specific pools.
+
+        Args:
+            pool_ids: List of pool identifiers
+
+        Returns:
+            Tuple of (success, data) where data is pool analytics or error message
+        """
+        try:
+            # Get pool data
+            success, pool_data = await self.get_pools_by_ids(pool_ids)
+            if not success:
+                return (False, f"Failed to fetch pool data: {pool_data}")
+
+            # Get Llama reports
+            success, llama_data = await self.get_llama_reports(pool_ids)
+            if not success:
+                self.logger.warning(f"Failed to fetch Llama data: {llama_data}")
+                llama_data = {}
+
+            pools = pool_data.get("pools", [])
+            llama_reports = llama_data
+
+            # Combine data
+            analytics = []
+            for pool in pools:
+                pool_id = pool.get("id")
+                llama_report = llama_reports.get(pool_id.lower()) if pool_id else None
+
+                analytics.append(
+                    {
+                        "pool": pool,
+                        "llama_data": llama_report,
+                        "combined_apy": (
+                            llama_report.get("llama_combined_apy_pct", 0) / 100
+                            if llama_report
+                            and llama_report.get("llama_combined_apy_pct") is not None
+                            else pool.get("apy", 0)
+                        ),
+                        "tvl_usd": (
+                            llama_report.get("llama_tvl_usd", 0)
+                            if llama_report and llama_report.get("llama_tvl_usd")
+                            else pool.get("tvl", 0)
+                        ),
+                    }
+                )
+
+            return (True, {"analytics": analytics, "total_pools": len(analytics)})
+        except Exception as e:
+            self.logger.error(f"Error getting pool analytics: {e}")
+            return (False, str(e))
+
+    async def search_pools(self, query: str, limit: int = 10) -> tuple[bool, Any]:
+        """
+        Search pools by name, symbol, or other criteria.
+
+        Args:
+            query: Search query string
+            limit: Maximum number of results
+
+        Returns:
+            Tuple of (success, data) where data is search results or error message
+        """
+        try:
+            success, all_pools_data = await self.get_all_pools()
+            if not success:
+                return (False, f"Failed to fetch pools: {all_pools_data}")
+
+            pools = all_pools_data.get("pools", [])
+            query_lower = query.lower()
+
+            # Simple text search
+            matching_pools = []
+            for pool in pools:
+                name = pool.get("name", "").lower()
+                symbol = pool.get("symbol", "").lower()
+                description = pool.get("description", "").lower()
+
+                if (
+                    query_lower in name
+                    or query_lower in symbol
+                    or query_lower in description
+                ):
+                    matching_pools.append(pool)
+
+            # Sort by relevance (exact matches first)
+            matching_pools.sort(
+                key=lambda x: (
+                    query_lower not in x.get("name", "").lower(),
+                    query_lower not in x.get("symbol", "").lower(),
+                )
+            )
+
+            return (
+                True,
+                {
+                    "pools": matching_pools[:limit],
+                    "total_found": len(matching_pools),
+                    "query": query,
+                },
+            )
+        except Exception as e:
+            self.logger.error(f"Error searching pools: {e}")
+            return (False, str(e))

wayfinder_paths/vaults/adapters/pool_adapter/examples.json

@@ -0,0 +1,143 @@
+{
+  "get_pools_by_ids": {
+    "description": "Get pool information by pool IDs",
+    "input": {
+      "pool_ids": ["pool-123", "pool-456"],
+      "merge_external": true
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "name": "USDC/USDT Pool",
+            "symbol": "USDC-USDT",
+            "apy": 0.05,
+            "tvl": 1000000,
+            "chain": "base"
+          }
+        ]
+      }
+    }
+  },
+  "get_all_pools": {
+    "description": "Get all available pools",
+    "input": {
+      "merge_external": false
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "name": "USDC/USDT Pool",
+            "symbol": "USDC-USDT",
+            "apy": 0.05,
+            "tvl": 1000000
+          }
+        ],
+        "total": 1
+      }
+    }
+  },
+  "get_llama_matches": {
+    "description": "Get Llama protocol matches for pools",
+    "input": {},
+    "output": {
+      "success": true,
+      "data": {
+        "matches": [
+          {
+            "id": "pool-123",
+            "llama_apy_pct": 5.2,
+            "llama_tvl_usd": 1000000,
+            "llama_stablecoin": true,
+            "llama_il_risk": "no",
+            "network": "base"
+          }
+        ]
+      }
+    }
+  },
+  "find_high_yield_pools": {
+    "description": "Find high-yield pools based on criteria",
+    "input": {
+      "min_apy": 0.03,
+      "min_tvl": 500000,
+      "stablecoin_only": true,
+      "network_codes": ["base", "ethereum"]
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "llama_apy_pct": 5.2,
+            "llama_tvl_usd": 1000000,
+            "llama_stablecoin": true,
+            "network": "base"
+          }
+        ],
+        "total_found": 1,
+        "filters_applied": {
+          "min_apy": 0.03,
+          "min_tvl": 500000,
+          "stablecoin_only": true,
+          "network_codes": ["base", "ethereum"]
+        }
+      }
+    }
+  },
+  "get_pool_analytics": {
+    "description": "Get comprehensive analytics for specific pools",
+    "input": {
+      "pool_ids": ["pool-123"]
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "analytics": [
+          {
+            "pool": {
+              "id": "pool-123",
+              "name": "USDC/USDT Pool",
+              "symbol": "USDC-USDT"
+            },
+            "llama_data": {
+              "llama_apy_pct": 5.2,
+              "llama_tvl_usd": 1000000
+            },
+            "combined_apy": 0.052,
+            "tvl_usd": 1000000
+          }
+        ],
+        "total_pools": 1
+      }
+    }
+  },
+  "search_pools": {
+    "description": "Search pools by name, symbol, or other criteria",
+    "input": {
+      "query": "USDC",
+      "limit": 5
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "name": "USDC/USDT Pool",
+            "symbol": "USDC-USDT",
+            "description": "Stablecoin pool on Base"
+          }
+        ],
+        "total_found": 1,
+        "query": "USDC"
+      }
+    }
+  }
+}

wayfinder_paths/vaults/adapters/pool_adapter/manifest.yaml

@@ -0,0 +1,10 @@
+schema_version: "0.1"
+entrypoint: "vaults.adapters.pool_adapter.adapter.PoolAdapter"
+capabilities:
+  - "pool.read"
+  - "pool.analytics"
+  - "pool.discovery"
+  - "llama.data"
+  - "pool.reports"
+dependencies:
+  - "PoolClient"

wayfinder_paths/vaults/adapters/pool_adapter/test_adapter.py

@@ -0,0 +1,222 @@
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from wayfinder_paths.vaults.adapters.pool_adapter.adapter import PoolAdapter
+
+
+class TestPoolAdapter:
+    """Test cases for PoolAdapter"""
+
+    @pytest.fixture
+    def mock_pool_client(self):
+        """Mock PoolClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def adapter(self, mock_pool_client):
+        """Create a PoolAdapter instance with mocked client for testing"""
+        with patch(
+            "vaults.adapters.pool_adapter.adapter.PoolClient",
+            return_value=mock_pool_client,
+        ):
+            return PoolAdapter()
+
+    @pytest.mark.asyncio
+    async def test_get_pools_by_ids_success(self, adapter, mock_pool_client):
+        """Test successful pool retrieval by IDs"""
+        mock_response = {
+            "pools": [
+                {
+                    "id": "pool-123",
+                    "name": "USDC/USDT Pool",
+                    "symbol": "USDC-USDT",
+                    "apy": 0.05,
+                    "tvl": 1000000,
+                }
+            ]
+        }
+        mock_pool_client.get_pools_by_ids = AsyncMock(return_value=mock_response)
+
+        success, data = await adapter.get_pools_by_ids(
+            pool_ids=["pool-123", "pool-456"], merge_external=True
+        )
+
+        assert success is True
+        assert data == mock_response
+        mock_pool_client.get_pools_by_ids.assert_called_once_with(
+            pool_ids="pool-123,pool-456", merge_external=True
+        )
+
+    @pytest.mark.asyncio
+    async def test_get_all_pools_success(self, adapter, mock_pool_client):
+        """Test successful retrieval of all pools"""
+        # Mock response
+        mock_response = {
+            "pools": [
+                {"id": "pool-123", "name": "Pool 1"},
+                {"id": "pool-456", "name": "Pool 2"},
+            ],
+            "total": 2,
+        }
+        mock_pool_client.get_all_pools = AsyncMock(return_value=mock_response)
+
+        success, data = await adapter.get_all_pools(merge_external=False)
+
+        assert success is True
+        assert data == mock_response
+        mock_pool_client.get_all_pools.assert_called_once_with(merge_external=False)
+
+    @pytest.mark.asyncio
+    async def test_get_llama_matches_success(self, adapter, mock_pool_client):
+        """Test successful Llama matches retrieval"""
+        # Mock response
+        mock_response = {
+            "matches": [
+                {
+                    "id": "pool-123",
+                    "llama_apy_pct": 5.2,
+                    "llama_tvl_usd": 1000000,
+                    "llama_stablecoin": True,
+                    "network": "base",
+                }
+            ]
+        }
+        mock_pool_client.get_llama_matches = AsyncMock(return_value=mock_response)
+
+        success, data = await adapter.get_llama_matches()
+
+        assert success is True
+        assert data == mock_response
+
+    @pytest.mark.asyncio
+    async def test_find_high_yield_pools_success(self, adapter, mock_pool_client):
+        """Test successful high yield pool discovery"""
+        mock_llama_response = {
+            "matches": [
+                {
+                    "pool_id": "pool-123",
+                    "llama_apy_pct": 5.2,
+                    "llama_tvl_usd": 1000000,
+                    "llama_stablecoin": True,
+                    "network": "base",
+                },
+                {
+                    "pool_id": "pool-456",
+                    "llama_apy_pct": 2.0,
+                    "llama_tvl_usd": 500000,
+                    "llama_stablecoin": True,
+                    "network": "ethereum",
+                },
+                {
+                    "pool_id": "pool-789",
+                    "llama_apy_pct": 6.0,
+                    "llama_tvl_usd": 2000000,
+                    "llama_stablecoin": False,
+                    "network": "base",
+                },
+            ]
+        }
+        mock_pool_client.get_llama_matches = AsyncMock(return_value=mock_llama_response)
+
+        success, data = await adapter.find_high_yield_pools(
+            min_apy=0.03, min_tvl=500000, stablecoin_only=True, network_codes=["base"]
+        )
+
+        assert success is True
+        assert len(data["pools"]) == 1  # Only pool-123 meets criteria
+        assert (
+            data["pools"][0].get("pool_id") == "pool-123"
+            or data["pools"][0].get("id") == "pool-123"
+        )
+        assert data["total_found"] == 1
+        assert data["filters_applied"]["min_apy"] == 0.03
+        assert data["filters_applied"]["stablecoin_only"] is True
+
+    @pytest.mark.asyncio
+    async def test_get_pool_analytics_success(self, adapter, mock_pool_client):
+        """Test successful pool analytics generation"""
+        mock_pool_data = {
+            "pools": [
+                {"id": "pool-123", "name": "USDC/USDT Pool", "symbol": "USDC-USDT"}
+            ]
+        }
+        mock_pool_client.get_pools_by_ids = AsyncMock(return_value=mock_pool_data)
+
+        mock_llama_data = {
+            "pool-123": {
+                "llama_apy_pct": 5.2,
+                "llama_combined_apy_pct": 5.2,
+                "llama_tvl_usd": 1000000,
+            }
+        }
+        mock_pool_client.get_llama_reports = AsyncMock(return_value=mock_llama_data)
+
+        success, data = await adapter.get_pool_analytics(["pool-123"])
+
+        assert success is True
+        assert len(data["analytics"]) == 1
+        assert data["analytics"][0]["pool"]["id"] == "pool-123"
+        assert round(data["analytics"][0]["combined_apy"], 6) == round(0.052, 6)
+        assert data["analytics"][0]["tvl_usd"] == 1000000
+
+    @pytest.mark.asyncio
+    async def test_search_pools_success(self, adapter, mock_pool_client):
+        """Test successful pool search"""
+        mock_all_pools = {
+            "pools": [
+                {
+                    "id": "pool-123",
+                    "name": "USDC/USDT Pool",
+                    "symbol": "USDC-USDT",
+                    "description": "Stablecoin pool on Base",
+                },
+                {
+                    "id": "pool-456",
+                    "name": "ETH/WETH Pool",
+                    "symbol": "ETH-WETH",
+                    "description": "Ethereum pool",
+                },
+            ]
+        }
+        mock_pool_client.get_all_pools = AsyncMock(return_value=mock_all_pools)
+
+        success, data = await adapter.search_pools("USDC", limit=5)
+
+        assert success is True
+        assert len(data["pools"]) == 1
+        assert data["pools"][0]["id"] == "pool-123"
+        assert data["total_found"] == 1
+        assert data["query"] == "USDC"
+
+    @pytest.mark.asyncio
+    async def test_get_pools_by_ids_failure(self, adapter, mock_pool_client):
+        """Test pool retrieval failure"""
+        mock_pool_client.get_pools_by_ids = AsyncMock(
+            side_effect=Exception("API Error")
+        )
+
+        success, data = await adapter.get_pools_by_ids(["pool-123"])
+
+        assert success is False
+        assert "API Error" in data
+
+    @pytest.mark.asyncio
+    async def test_find_high_yield_pools_no_matches(self, adapter, mock_pool_client):
+        """Test high yield pool discovery with no matches"""
+        mock_llama_response = {"matches": []}
+        mock_pool_client.get_llama_matches.return_value = mock_llama_response
+
+        success, data = await adapter.find_high_yield_pools(
+            min_apy=0.10,
+            min_tvl=10000000,
+        )
+
+        assert success is True
+        assert len(data["pools"]) == 0
+        assert data["total_found"] == 0
+
+    def test_adapter_type(self, adapter):
+        """Test adapter has adapter_type"""
+        assert adapter.adapter_type == "POOL"