wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/tests/test_utils.py

@@ -0,0 +1,64 @@
+"""Shared utilities for testing strategies and adapters."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_strategy_examples(strategy_test_file: Path) -> dict[str, Any]:
+    """Load examples.json for a strategy test file.
+
+    This is REQUIRED for all strategy tests. The examples.json file serves
+    as both documentation and test data, ensuring tests stay in sync with examples.
+
+    Args:
+        strategy_test_file: Path to the test_strategy.py file
+
+    Returns:
+        Dictionary containing examples from examples.json
+
+    Raises:
+        FileNotFoundError: If examples.json does not exist
+        json.JSONDecodeError: If examples.json is invalid JSON
+    """
+    examples_path = strategy_test_file.parent / "examples.json"
+
+    if not examples_path.exists():
+        raise FileNotFoundError(
+            f"examples.json is REQUIRED for strategy tests. "
+            f"Create it at: {examples_path}\n"
+            f"See TESTING.md for the required structure."
+        )
+
+    with open(examples_path) as f:
+        return json.load(f)
+
+
+def get_canonical_examples(examples: dict[str, Any]) -> dict[str, Any]:
+    """Extract canonical usage examples from examples.json.
+
+    Canonical usage is defined as the primary, documented usage patterns
+    that demonstrate how the strategy should be used. This includes:
+    - 'smoke' example: The basic lifecycle test (deposit → update → status → withdraw)
+    - Any examples without 'expect' fields (positive usage patterns)
+
+    Args:
+        examples: The full examples.json dictionary
+
+    Returns:
+        Dictionary of canonical examples keyed by their example name
+    """
+    canonical = {}
+
+    # 'smoke' is always canonical
+    if "smoke" in examples:
+        canonical["smoke"] = examples["smoke"]
+
+    # Any example without 'expect' is considered canonical usage
+    for name, example_data in examples.items():
+        if name == "smoke":
+            continue  # Already added
+        if isinstance(example_data, dict) and "expect" not in example_data:
+            canonical[name] = example_data
+
+    return canonical

wayfinder_paths/vaults/adapters/balance_adapter/README.md

@@ -0,0 +1,104 @@
+# Balance Adapter
+
+Adapter that exposes wallet, token, and pool balances backed by `WalletClient`/`TokenClient` and now orchestrates transfers between the configured main/vault wallets (with ledger bookkeeping).
+
+- Entrypoint: `vaults.adapters.balance_adapter.adapter.BalanceAdapter`
+- Manifest: `manifest.yaml`
+- Tests: `test_adapter.py`
+
+## Capabilities
+
+The adapter declares both `wallet_read` and `wallet_transfer` capabilities in its manifest. Transfers are executed by leveraging the shared `DefaultWeb3Service.token_transactions` helper, but ledger recording + wallet selection now live inside the adapter.
+
+## Construction
+
+```python
+from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
+from wayfinder_paths.vaults.adapters.balance_adapter.adapter import BalanceAdapter
+
+web3_service = DefaultWeb3Service(config)
+balance = BalanceAdapter(config, web3_service=web3_service)
+```
+
+`web3_service` is required so the adapter can share the same wallet provider (and `TokenTxn` helper) as the rest of the strategy.
+
+## API surface
+
+### `get_balance(token_id: str, wallet_address: str)`
+Returns the raw balance (as an integer) for a specific token on a wallet.
+
+```python
+success, balance = await balance.get_balance(
+    token_id="usd-coin-base",
+    wallet_address=config["main_wallet"]["address"],
+)
+```
+
+### `get_pool_balance(pool_address: str, chain_id: int, user_address: str)`
+Fetches the amount supplied to a specific pool, using the `/wallets/pool-balance` endpoint.
+
+```python
+success, amount = await balance.get_pool_balance(
+    pool_address="0xPool",
+    chain_id=8453,
+    user_address=config["vault_wallet"]["address"],
+)
+```
+
+### `get_all_balances(wallet_address: str, enrich=True, from_cache=False, add_llama=True)`
+Returns the enriched token balance payload Wayfinder exposes (including USD value, metadata, and optional DeFi Llama overlays).
+
+```python
+success, snapshot = await balance.get_all_balances(
+    wallet_address=config["vault_wallet"]["address"],
+    enrich=True,
+)
+```
+
+### `move_from_main_wallet_to_vault_wallet(token_id: str, amount: float, strategy_name="unknown", skip_ledger=False)`
+Sends the specified token from the configured `main_wallet` to the `vault_wallet`, records the ledger deposit (unless `skip_ledger=True`), and returns the `(success, tx_result)` tuple from the underlying send helper.
+
+```python
+success, tx = await balance.move_from_main_wallet_to_vault_wallet(
+    token_id="usd-coin-base",
+    amount=1.5,
+    strategy_name="MyStrategy",
+)
+```
+
+### `move_from_vault_wallet_to_main_wallet(token_id: str, amount: float, strategy_name="unknown", skip_ledger=False)`
+Mirrors the previous method but withdraws from the vault wallet back to the main wallet while recording a ledger withdrawal entry.
+
+```python
+await balance.move_from_vault_wallet_to_main_wallet(
+    token_id="usd-coin-base",
+    amount=0.75,
+    strategy_name="MyStrategy",
+)
+```
+
+All methods return `(success: bool, payload: Any)` tuples. On failure the payload is an error string.
+
+## Usage inside strategies
+
+```python
+class MyStrategy(Strategy):
+    def __init__(self, config):
+        super().__init__()
+        web3_service = DefaultWeb3Service(config)
+        balance_adapter = BalanceAdapter(config, web3_service=web3_service)
+        self.register_adapters([balance_adapter])
+        self.balance_adapter = balance_adapter
+
+    async def _status(self):
+        success, pool_balance = await self.balance_adapter.get_pool_balance(
+            pool_address=self.current_pool["address"],
+            chain_id=self.current_pool["chain"]["id"],
+            user_address=self.config["vault_wallet"]["address"],
+        )
+        return {"portfolio_value": float(pool_balance or 0), ...}
+```
+
+## Error handling and health checks
+
+Any exception raised by the underlying `WalletClient`/`TokenClient` is caught and emitted as a `(False, "message")` tuple. The inherited `health_check()` method reports adapter status plus dependency status, making it safe to call from `Strategy.health_check`.

wayfinder_paths/vaults/adapters/balance_adapter/adapter.py

@@ -0,0 +1,257 @@
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.clients.TokenClient import TokenClient
+from wayfinder_paths.core.clients.WalletClient import WalletClient
+from wayfinder_paths.core.services.base import Web3Service
+from wayfinder_paths.core.settings import settings
+from wayfinder_paths.core.utils.evm_helpers import resolve_chain_id
+from wayfinder_paths.vaults.adapters.ledger_adapter.adapter import LedgerAdapter
+from wayfinder_paths.vaults.adapters.token_adapter.adapter import TokenAdapter
+
+
+class BalanceAdapter(BaseAdapter):
+    adapter_type = "BALANCE"
+
+    def __init__(
+        self,
+        config: dict[str, Any],
+        web3_service: Web3Service,
+    ):
+        super().__init__("balance", config)
+        self.wallet_client = WalletClient()
+        self.token_client = TokenClient()
+        self.token_adapter = TokenAdapter()
+        self.ledger_adapter = LedgerAdapter()
+
+        self.wallet_provider = web3_service.evm_transactions
+        self.token_transactions = web3_service.token_transactions
+
+    def _parse_balance(self, raw: Any) -> int:
+        """Parse balance value to integer, handling various formats."""
+        if raw is None:
+            return 0
+        try:
+            return int(raw)
+        except (ValueError, TypeError):
+            try:
+                return int(float(raw))
+            except (ValueError, TypeError):
+                return 0
+
+    async def get_balance(
+        self,
+        *,
+        token_id: str,
+        wallet_address: str,
+    ) -> tuple[bool, Any]:
+        """Get token balance for a wallet."""
+        try:
+            data = await self.wallet_client.get_token_balance_for_wallet(
+                token_id=token_id,
+                wallet_address=wallet_address,
+            )
+            return (True, data.get("balance"))
+        except Exception as e:
+            return (False, str(e))
+
+    async def move_from_main_wallet_to_vault_wallet(
+        self,
+        token_id: str,
+        amount: float,
+        strategy_name: str = "unknown",
+        skip_ledger: bool = False,
+    ) -> tuple[bool, Any]:
+        """Move funds from the configured main wallet into the vault wallet."""
+        return await self._move_between_wallets(
+            token_id=token_id,
+            amount=amount,
+            from_wallet=self.config.get("main_wallet"),
+            to_wallet=self.config.get("vault_wallet"),
+            ledger_method=self.ledger_adapter.record_deposit,
+            ledger_wallet="to",
+            strategy_name=strategy_name,
+            skip_ledger=skip_ledger,
+        )
+
+    async def move_from_vault_wallet_to_main_wallet(
+        self,
+        token_id: str,
+        amount: float,
+        strategy_name: str = "unknown",
+        skip_ledger: bool = False,
+    ) -> tuple[bool, Any]:
+        """Move funds from the vault wallet back into the main wallet."""
+        return await self._move_between_wallets(
+            token_id=token_id,
+            amount=amount,
+            from_wallet=self.config.get("vault_wallet"),
+            to_wallet=self.config.get("main_wallet"),
+            ledger_method=self.ledger_adapter.record_withdrawal,
+            ledger_wallet="from",
+            strategy_name=strategy_name,
+            skip_ledger=skip_ledger,
+        )
+
+    async def _move_between_wallets(
+        self,
+        *,
+        token_id: str,
+        amount: float,
+        from_wallet: dict[str, Any] | None,
+        to_wallet: dict[str, Any] | None,
+        ledger_method,
+        ledger_wallet: str,
+        strategy_name: str,
+        skip_ledger: bool,
+    ) -> tuple[bool, Any]:
+        if self.token_transactions is None:
+            return False, "Token transaction service not configured"
+
+        from_address = self._wallet_address(from_wallet)
+        to_address = self._wallet_address(to_wallet)
+        if not from_address or not to_address:
+            return False, "main_wallet or vault_wallet missing"
+
+        token_info = await self.token_client.get_token_details(token_id)
+        if not token_info:
+            return False, f"Token not found: {token_id}"
+
+        build_success, tx_data = await self.token_transactions.build_send(
+            token_id=token_id,
+            amount=amount,
+            from_address=from_address,
+            to_address=to_address,
+            token_info=token_info,
+        )
+        if not build_success:
+            return False, tx_data
+
+        tx = tx_data
+        if getattr(settings, "DRY_RUN", False):
+            broadcast_result = (True, {"dry_run": True, "transaction": tx})
+        else:
+            broadcast_result = await self.wallet_provider.broadcast_transaction(
+                tx, wait_for_receipt=True, timeout=120
+            )
+
+        if broadcast_result[0] and not skip_ledger and ledger_method is not None:
+            wallet_for_ledger = from_address if ledger_wallet == "from" else to_address
+            await self._record_ledger_entry(
+                ledger_method=ledger_method,
+                wallet_address=wallet_for_ledger,
+                token_info=token_info,
+                amount=amount,
+                strategy_name=strategy_name,
+            )
+
+        return broadcast_result
+
+    async def _record_ledger_entry(
+        self,
+        *,
+        ledger_method,
+        wallet_address: str,
+        token_info: dict[str, Any],
+        amount: float,
+        strategy_name: str,
+    ) -> None:
+        chain_id = resolve_chain_id(token_info, self.logger)
+        if chain_id is None:
+            return
+
+        usd_value = await self._token_amount_usd(token_info, amount)
+        try:
+            success, response = await ledger_method(
+                wallet_address=wallet_address,
+                chain_id=chain_id,
+                token_address=token_info.get("address"),
+                token_amount=str(amount),
+                usd_value=usd_value,
+                data={
+                    "token_id": token_info.get("id"),
+                    "amount": str(amount),
+                    "usd_value": usd_value,
+                },
+                strategy_name=strategy_name,
+            )
+            if not success:
+                self.logger.warning(
+                    "Ledger entry failed",
+                    wallet=wallet_address,
+                    token_id=token_info.get("id"),
+                    amount=amount,
+                    error=response,
+                )
+        except Exception as exc:  # noqa: BLE001
+            self.logger.warning(
+                f"Ledger entry raised: {exc}",
+                wallet=wallet_address,
+                token_id=token_info.get("id"),
+            )
+
+    async def _token_amount_usd(
+        self, token_info: dict[str, Any], amount: float
+    ) -> float:
+        token_id = token_info.get("id")
+        if not token_id:
+            return 0.0
+        success, price_data = await self.token_adapter.get_token_price(token_id)
+        if not success or not price_data:
+            return 0.0
+        return float(price_data.get("current_price", 0.0)) * float(amount)
+
+    def _wallet_address(self, wallet: dict[str, Any] | None) -> str | None:
+        if not wallet:
+            return None
+        address = wallet.get("address")
+        if address:
+            return str(address)
+        evm_wallet = wallet.get("evm") if isinstance(wallet, dict) else None
+        if isinstance(evm_wallet, dict):
+            return evm_wallet.get("address")
+        return None
+
+    async def get_pool_balance(
+        self,
+        *,
+        pool_address: str,
+        chain_id: int,
+        user_address: str,
+    ) -> tuple[bool, Any]:
+        """Get pool balance for a wallet."""
+        try:
+            data = await self.wallet_client.get_pool_balance_for_wallet(
+                pool_address=pool_address,
+                chain_id=chain_id,
+                user_address=user_address,
+                human_readable=False,
+            )
+            raw = (
+                data.get("balance_raw") or data.get("balance")
+                if isinstance(data, dict)
+                else None
+            )
+            return (True, self._parse_balance(raw))
+        except Exception as e:
+            return (False, str(e))
+
+    async def get_all_balances(
+        self,
+        *,
+        wallet_address: str,
+        enrich: bool = True,
+        from_cache: bool = False,
+        add_llama: bool = True,
+    ) -> tuple[bool, Any]:
+        """Get all enriched token balances for a wallet."""
+        try:
+            data = await self.wallet_client.get_all_enriched_token_balances_for_wallet(
+                wallet_address=wallet_address,
+                enrich=enrich,
+                from_cache=from_cache,
+                add_llama=add_llama,
+            )
+            return (True, data)
+        except Exception as e:
+            return (False, str(e))

wayfinder_paths/vaults/adapters/balance_adapter/examples.json

@@ -0,0 +1,6 @@
+{
+  "smoke": {
+    "get_balance": {"asset": "base_0x0000000000000000000000000000000000000000", "wallet_type": "vault"}
+  }
+}
+

wayfinder_paths/vaults/adapters/balance_adapter/manifest.yaml

@@ -0,0 +1,8 @@
+schema_version: "0.1"
+entrypoint: "vaults.adapters.balance_adapter.adapter.BalanceAdapter"
+capabilities:
+  - "wallet_read"
+  - "wallet_transfer"
+dependencies:
+  - "TokenClient"
+  - "WalletClient"

wayfinder_paths/vaults/adapters/balance_adapter/test_adapter.py

@@ -0,0 +1,83 @@
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from wayfinder_paths.vaults.adapters.balance_adapter.adapter import BalanceAdapter
+
+
+class TestBalanceAdapter:
+    """Test cases for BalanceAdapter"""
+
+    @pytest.fixture
+    def mock_wallet_client(self):
+        """Mock WalletClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def mock_token_client(self):
+        """Mock TokenClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def adapter(self, mock_wallet_client, mock_token_client):
+        """Create a BalanceAdapter instance with mocked clients for testing"""
+        with (
+            patch(
+                "wayfinder_paths.vaults.adapters.balance_adapter.adapter.WalletClient",
+                return_value=mock_wallet_client,
+            ),
+            patch(
+                "wayfinder_paths.vaults.adapters.balance_adapter.adapter.TokenClient",
+                return_value=mock_token_client,
+            ),
+        ):
+            return BalanceAdapter(config={})
+
+    @pytest.mark.asyncio
+    async def test_health_check(self, adapter):
+        """Test adapter health check"""
+        health = await adapter.health_check()
+        assert isinstance(health, dict)
+        assert health.get("status") in {"healthy", "unhealthy", "error"}
+
+    @pytest.mark.asyncio
+    async def test_connect(self, adapter):
+        """Test adapter connection"""
+        ok = await adapter.connect()
+        assert isinstance(ok, bool)
+
+    @pytest.mark.asyncio
+    async def test_get_all_enriched_token_balances_for_wallet_success(
+        self, adapter, mock_wallet_client
+    ):
+        """Test successful retrieval of enriched token balances"""
+        mock_response = {
+            "balances": [
+                {
+                    "token_id": "usd-coin-base",
+                    "symbol": "USDC",
+                    "balance": "1000000000",
+                    "usd_value": 1000.0,
+                }
+            ],
+            "total_usd_value": 1000.0,
+        }
+        mock_wallet_client.get_all_enriched_token_balances_for_wallet = AsyncMock(
+            return_value=(True, mock_response)
+        )
+
+        success, data = await adapter.get_all_enriched_token_balances_for_wallet(
+            wallet_address="0x1234567890123456789012345678901234567890",
+            enrich=True,
+        )
+
+        assert success is True
+        assert isinstance(data, (dict, tuple))
+        if isinstance(data, dict):
+            assert "balances" in data
+
+    def test_adapter_type(self, adapter):
+        """Test adapter has adapter_type"""
+        assert adapter.adapter_type == "BALANCE"