wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/adapters/balance_adapter/adapter.py

@@ -0,0 +1,238 @@
+from typing import Any
+
+from wayfinder_paths.adapters.ledger_adapter.adapter import LedgerAdapter
+from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
+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.constants.base import DEFAULT_TRANSACTION_TIMEOUT
+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
+
+
+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, str | int]:
+        """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_strategy_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 strategy 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("strategy_wallet"),
+            ledger_method=self.ledger_adapter.record_deposit,
+            ledger_wallet="to",
+            strategy_name=strategy_name,
+            skip_ledger=skip_ledger,
+        )
+
+    async def move_from_strategy_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 strategy wallet back into the main wallet."""
+        return await self._move_between_wallets(
+            token_id=token_id,
+            amount=amount,
+            from_wallet=self.config.get("strategy_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 strategy_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=DEFAULT_TRANSACTION_TIMEOUT
+            )
+
+        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))

wayfinder_paths/adapters/balance_adapter/examples.json

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

wayfinder_paths/adapters/balance_adapter/manifest.yaml

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

wayfinder_paths/adapters/balance_adapter/test_adapter.py

@@ -0,0 +1,59 @@
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from wayfinder_paths.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 mock_web3_service(self):
+        """Mock TokenClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def adapter(self, mock_wallet_client, mock_token_client, mock_web3_service):
+        """Create a BalanceAdapter instance with mocked clients for testing"""
+        with (
+            patch(
+                "wayfinder_paths.adapters.balance_adapter.adapter.WalletClient",
+                return_value=mock_wallet_client,
+            ),
+            patch(
+                "wayfinder_paths.adapters.balance_adapter.adapter.TokenClient",
+                return_value=mock_token_client,
+            ),
+        ):
+            return BalanceAdapter(config={}, web3_service=mock_web3_service)
+
+    @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)
+
+    def test_adapter_type(self, adapter):
+        """Test adapter has adapter_type"""
+        assert adapter.adapter_type == "BALANCE"

wayfinder_paths/adapters/brap_adapter/README.md

@@ -0,0 +1,249 @@
+# BRAP Adapter
+
+A Wayfinder adapter that provides high-level operations for cross-chain swaps and quotes via the BRAP (Bridge/Router/Adapter Protocol). This adapter wraps the `BRAPClient` to offer strategy-friendly methods for getting quotes, comparing routes, and executing cross-chain transactions.
+
+## Capabilities
+
+- `swap.quote`: Get quotes for cross-chain swap operations
+- `swap.execute`: Execute cross-chain swaps
+- `bridge.quote`: Get quotes for bridge operations
+- `bridge.execute`: Execute bridge operations
+- `route.optimize`: Compare and optimize routes
+- `fee.calculate`: Calculate fees and costs
+
+## Configuration
+
+The adapter uses the BRAPClient which automatically handles authentication and API configuration through the Wayfinder settings. Pass a `Web3Service` instance so it can broadcast transactions and reuse the shared `LocalTokenTxnService` for approvals.
+
+The BRAPClient will automatically:
+- Use the WAYFINDER_API_URL from settings
+- Handle authentication via environment variables or config.json
+- Manage token refresh and retry logic
+
+## Usage
+
+### Initialize the Adapter
+
+```python
+from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
+from wayfinder_paths.adapters.brap_adapter.adapter import BRAPAdapter
+
+web3_service = DefaultWeb3Service(config)
+adapter = BRAPAdapter(web3_service=web3_service)
+```
+
+### Get Swap Quote
+
+```python
+success, data = await adapter.get_swap_quote(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,  # Base
+    to_chain_id=1,       # Ethereum
+    from_address="0x1234567890123456789012345678901234567890",
+    to_address="0x1234567890123456789012345678901234567890",
+    amount="1000000000000000000",  # 1 token (18 decimals)
+    slippage=0.01  # 1% slippage
+)
+if success:
+    quotes = data.get("quotes", {})
+    best_quote = quotes.get("best_quote", {})
+    print(f"Output amount: {best_quote.get('output_amount')}")
+    print(f"Total fee: {best_quote.get('total_fee')}")
+else:
+    print(f"Error: {data}")
+```
+
+### Get Best Quote
+
+```python
+success, data = await adapter.get_best_quote(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,
+    to_chain_id=1,
+    from_address="0x1234567890123456789012345678901234567890",
+    to_address="0x1234567890123456789012345678901234567890",
+    amount="1000000000000000000"
+)
+if success:
+    print(f"Best output: {data.get('output_amount')}")
+    print(f"Gas fee: {data.get('gas_fee')}")
+    print(f"Bridge fee: {data.get('bridge_fee')}")
+else:
+    print(f"Error: {data}")
+```
+
+### Calculate Swap Fees
+
+```python
+success, data = await adapter.calculate_swap_fees(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,
+    to_chain_id=1,
+    amount="1000000000000000000",
+    slippage=0.01
+)
+if success:
+    print(f"Input amount: {data.get('input_amount')}")
+    print(f"Output amount: {data.get('output_amount')}")
+    print(f"Gas fee: {data.get('gas_fee')}")
+    print(f"Bridge fee: {data.get('bridge_fee')}")
+    print(f"Protocol fee: {data.get('protocol_fee')}")
+    print(f"Total fee: {data.get('total_fee')}")
+    print(f"Price impact: {data.get('price_impact')}")
+else:
+    print(f"Error: {data}")
+```
+
+### Compare Routes
+
+```python
+success, data = await adapter.compare_routes(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,
+    to_chain_id=1,
+    amount="1000000000000000000"
+)
+if success:
+    print(f"Total routes available: {data.get('total_routes')}")
+    print(f"Best route output: {data.get('best_route', {}).get('output_amount')}")
+    
+    for i, route in enumerate(data.get('all_routes', [])):
+        print(f"Route {i+1}: Output {route.get('output_amount')}, Fee {route.get('total_fee')}")
+else:
+    print(f"Error: {data}")
+```
+
+### Estimate Gas Costs
+
+```python
+success, data = await adapter.estimate_gas_cost(
+    from_chain_id=8453,  # Base
+    to_chain_id=1,       # Ethereum
+    operation_type="swap"
+)
+if success:
+    print(f"From chain: {data.get('from_chain')}")
+    print(f"To chain: {data.get('to_chain')}")
+    print(f"From gas estimate: {data.get('from_gas_estimate')}")
+    print(f"To gas estimate: {data.get('to_gas_estimate')}")
+    print(f"Total operations: {data.get('total_operations')}")
+else:
+    print(f"Error: {data}")
+```
+
+### Validate Swap Parameters
+
+```python
+success, data = await adapter.validate_swap_parameters(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,
+    to_chain_id=1,
+    amount="1000000000000000000"
+)
+if success:
+    if data.get("valid"):
+        print("Parameters are valid")
+        print(f"Estimated output: {data.get('estimated_output')}")
+    else:
+        print("Parameters are invalid:")
+        for error in data.get("errors", []):
+            print(f"  - {error}")
+else:
+    print(f"Error: {data}")
+```
+
+### Get Bridge Quote
+
+```python
+# Bridge operations use the same interface as swaps
+success, data = await adapter.get_bridge_quote(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,
+    to_chain_id=1,
+    amount="1000000000000000000",
+    slippage=0.01
+)
+if success:
+    print(f"Bridge quote received: {data.get('quotes', {}).get('best_quote', {}).get('output_amount')}")
+else:
+    print(f"Error: {data}")
+```
+
+## Advanced Usage
+
+### Route Optimization
+
+```python
+# Compare multiple routes to find the best option
+success, data = await adapter.compare_routes(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,
+    to_chain_id=1,
+    amount="1000000000000000000"
+)
+
+if success:
+    analysis = data.get("route_analysis", {})
+    highest_output = analysis.get("highest_output")
+    lowest_fees = analysis.get("lowest_fees")
+    fastest = analysis.get("fastest")
+    
+    print(f"Highest output route: {highest_output.get('output_amount')}")
+    print(f"Lowest fees route: {lowest_fees.get('total_fee')}")
+    print(f"Fastest route: {fastest.get('estimated_time')} seconds")
+```
+
+### Fee Analysis
+
+```python
+# Analyze fees for a swap operation
+success, data = await adapter.calculate_swap_fees(
+    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+    from_chain_id=8453,
+    to_chain_id=1,
+    amount="1000000000000000000"
+)
+
+if success:
+    input_amount = int(data.get("input_amount", 0))
+    output_amount = int(data.get("output_amount", 0))
+    total_fee = int(data.get("total_fee", 0))
+    
+    # Calculate effective rate
+    effective_rate = (input_amount - output_amount) / input_amount
+    print(f"Effective rate: {effective_rate:.4f} ({effective_rate * 100:.2f}%)")
+    print(f"Total fees: {total_fee / 1e18:.6f} tokens")
+```
+
+## API Endpoints
+
+The adapter uses the following Wayfinder API endpoints:
+
+- `POST /api/v1/public/quotes/` - Get swap/bridge quotes
+
+## Error Handling
+
+All methods return a tuple of `(success: bool, data: Any)` where:
+- `success` is `True` if the operation succeeded
+- `data` contains the response data on success or error message on failure
+
+## Testing
+
+Run the adapter tests:
+
+```bash
+pytest wayfinder_paths/adapters/brap_adapter/test_adapter.py -v
+```
+
+## Dependencies
+
+- `BRAPClient` - Low-level API client for BRAP operations
+- `BaseAdapter` - Base adapter class with common functionality

wayfinder_paths/adapters/brap_adapter/__init__.py

@@ -0,0 +1,7 @@
+"""
+BRAP Adapter Package
+"""
+
+from .adapter import BRAPAdapter
+
+__all__ = ["BRAPAdapter"]