wayfinder-paths 0.1.9__py3-none-any.whl → 0.1.10__py3-none-any.whl

wayfinder_paths/CONFIG_GUIDE.md

@@ -138,7 +138,7 @@ just create-strategy "My Strategy Name"
 # This automatically:
 # - Creates the strategy directory
 # - Generates a wallet with label matching the directory name
-# - Updates the manifest with the correct name and entrypoint
+# - Updates the strategy files with the correct names
 ```
 
 ### Wallet Structure

wayfinder_paths/adapters/balance_adapter/README.md

@@ -3,12 +3,11 @@
 Adapter that exposes wallet, token, and pool balances backed by `WalletClient`/`TokenClient` and now orchestrates transfers between the configured main/strategy wallets (with ledger bookkeeping).
 
 - Entrypoint: `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.
+The adapter provides both wallet read and wallet transfer capabilities. Transfers are executed by leveraging the shared `DefaultWeb3Service.token_transactions` helper, but ledger recording + wallet selection now live inside the adapter.
 
 ## Construction
 

wayfinder_paths/adapters/balance_adapter/adapter.py

@@ -170,7 +170,7 @@ class BalanceAdapter(BaseAdapter):
                 token_amount=str(amount),
                 usd_value=usd_value,
                 data={
-                    "token_id": token_info.get("id"),
+                    "token_id": token_info.get("token_id"),
                     "amount": str(amount),
                     "usd_value": usd_value,
                 },
@@ -180,7 +180,7 @@ class BalanceAdapter(BaseAdapter):
                 self.logger.warning(
                     "Ledger entry failed",
                     wallet=wallet_address,
-                    token_id=token_info.get("id"),
+                    token_id=token_info.get("token_id"),
                     amount=amount,
                     error=response,
                 )
@@ -188,13 +188,13 @@ class BalanceAdapter(BaseAdapter):
             self.logger.warning(
                 f"Ledger entry raised: {exc}",
                 wallet=wallet_address,
-                token_id=token_info.get("id"),
+                token_id=token_info.get("token_id"),
             )
 
     async def _token_amount_usd(
         self, token_info: dict[str, Any], amount: float
     ) -> float:
-        token_id = token_info.get("id")
+        token_id = token_info.get("token_id")
         if not token_id:
             return 0.0
         success, price_data = await self.token_adapter.get_token_price(token_id)

wayfinder_paths/adapters/brap_adapter/adapter.py

@@ -11,7 +11,7 @@ from wayfinder_paths.core.adapters.models import SWAP
 from wayfinder_paths.core.clients.BRAPClient import BRAPClient, BRAPQuote
 from wayfinder_paths.core.clients.LedgerClient import TransactionRecord
 from wayfinder_paths.core.clients.TokenClient import TokenClient
-from wayfinder_paths.core.constants import DEFAULT_SLIPPAGE
+from wayfinder_paths.core.constants import DEFAULT_SLIPPAGE, ZERO_ADDRESS
 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
@@ -108,6 +108,7 @@ class BRAPAdapter(BaseAdapter):
         amount: str,
         slippage: float | None = None,
         wayfinder_fee: float | None = None,
+        preferred_providers: list[str] | None = None,
     ) -> tuple[bool, dict[str, Any] | str]:
         """
         Get the best available quote for a swap operation.
@@ -122,6 +123,8 @@ class BRAPAdapter(BaseAdapter):
             amount: Amount to swap (in smallest units)
             slippage: Maximum slippage tolerance (optional)
             wayfinder_fee: Wayfinder fee (optional)
+            preferred_providers: List of provider names in order of preference (optional).
+                                 If provided, selects first matching provider instead of "best".
 
         Returns:
             Tuple of (success, data) where data is best quote or error message
@@ -139,8 +142,27 @@ class BRAPAdapter(BaseAdapter):
                 wayfinder_fee=wayfinder_fee,
             )
 
-            # Extract best quote from response
-            best_quote = data["best_route"]
+            quotes_container = data.get("quotes", {})
+            # BRAP returns quotes in "all_quotes" not "quotes"
+            all_quotes = quotes_container.get("all_quotes", []) or quotes_container.get(
+                "quotes", []
+            )
+
+            # If preferred providers specified, select by provider preference
+            if preferred_providers and all_quotes:
+                selected_quote = self._select_quote_by_provider(
+                    all_quotes, preferred_providers
+                )
+                if selected_quote:
+                    return (True, selected_quote)
+                # Fall through to best_quote if no preferred provider found
+
+            # Extract best quote from response - check nested quotes first, then top level
+            best_quote = (
+                quotes_container.get("best_quote")
+                or data.get("best_quote")
+                or data.get("best_route")
+            )
 
             if not best_quote:
                 return (False, "No quotes available")
@@ -150,6 +172,58 @@ class BRAPAdapter(BaseAdapter):
             self.logger.error(f"Error getting best quote: {e}")
             return (False, str(e))
 
+    def _select_quote_by_provider(
+        self,
+        quotes: list[dict[str, Any]],
+        preferred_providers: list[str],
+    ) -> dict[str, Any] | None:
+        """
+        Select a quote from the list based on provider preference order.
+
+        Args:
+            quotes: List of quote objects from BRAP API
+            preferred_providers: List of provider names in order of preference (case-insensitive)
+
+        Returns:
+            The first matching quote, or None if no preferred provider found
+        """
+        # Normalize preferred providers to lowercase for case-insensitive matching
+        preferred_lower = [p.lower() for p in preferred_providers]
+
+        # Build a map of provider name -> quotes
+        provider_quotes: dict[str, list[dict[str, Any]]] = {}
+        for quote in quotes:
+            # Provider name might be in different fields depending on BRAP response structure
+            provider = (
+                quote.get("provider")
+                or quote.get("provider_name")
+                or quote.get("source")
+                or quote.get("protocol")
+                or ""
+            ).lower()
+            if provider:
+                if provider not in provider_quotes:
+                    provider_quotes[provider] = []
+                provider_quotes[provider].append(quote)
+
+        # Select first matching provider in preference order
+        for pref in preferred_lower:
+            if pref in provider_quotes:
+                # Return the quote with highest output for this provider
+                provider_list = provider_quotes[pref]
+                best_for_provider = max(
+                    provider_list, key=lambda q: int(q.get("output_amount", 0) or 0)
+                )
+                self.logger.info(f"Selected quote from preferred provider: {pref}")
+                return best_for_provider
+
+        # Log available providers for debugging
+        available = list(provider_quotes.keys())
+        self.logger.warning(
+            f"No preferred provider found. Wanted: {preferred_providers}, Available: {available}"
+        )
+        return None
+
     async def calculate_swap_fees(
         self,
         from_token_address: str,
@@ -248,7 +322,7 @@ class BRAPAdapter(BaseAdapter):
             )
 
             quotes = data.get("quotes", {})
-            all_quotes = quotes.get("quotes", [])
+            all_quotes = quotes.get("all_quotes", []) or quotes.get("quotes", [])
             best_quote = quotes.get("best_quote")
 
             if not all_quotes:
@@ -291,9 +365,20 @@ class BRAPAdapter(BaseAdapter):
         amount: str,
         slippage: float = DEFAULT_SLIPPAGE,
         strategy_name: str | None = None,
+        preferred_providers: list[str] | None = None,
     ) -> tuple[bool, Any]:
         """
         Execute a swap by looking up token metadata via token IDs.
+
+        Args:
+            from_token_id: Source token ID
+            to_token_id: Destination token ID
+            from_address: Wallet address
+            amount: Amount to swap (in smallest units)
+            slippage: Maximum slippage tolerance
+            strategy_name: Strategy name for ledger recording
+            preferred_providers: List of provider names in order of preference (e.g., ["enso", "aerodrome"]).
+                                 If provided, selects first matching provider instead of "best".
         """
         from_token = await self.token_client.get_token_details(from_token_id)
         if not from_token:
@@ -311,6 +396,7 @@ class BRAPAdapter(BaseAdapter):
             to_address=from_address,
             amount=amount,
             slippage=slippage,
+            preferred_providers=preferred_providers,
         )
         if not success:
             return (False, best_quote)
@@ -349,7 +435,14 @@ class BRAPAdapter(BaseAdapter):
             or quote.get("inputAmount")
             or transaction.get("value")
         )
-        if from_token.get("address") and spender and approve_amount:
+        token_address = from_token.get("address")
+        token_address_l = str(token_address or "").lower()
+        is_native = token_address_l in {
+            "",
+            ZERO_ADDRESS.lower(),
+            "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        }
+        if token_address and (not is_native) and spender and approve_amount:
             approve_success, approve_response = await self._handle_token_approval(
                 chain=chain,
                 token_address=from_token.get("address"),
@@ -363,17 +456,36 @@ class BRAPAdapter(BaseAdapter):
         broadcast_success, broadcast_response = await self._broadcast_transaction(
             transaction
         )
+        self.logger.info(
+            f"Swap broadcast result: success={broadcast_success}, "
+            f"response={broadcast_response}"
+        )
         if not broadcast_success:
             return (False, broadcast_response)
 
-        ledger_record = await self._record_swap_operation(
-            from_token=from_token,
-            to_token=to_token,
-            wallet_address=from_address,
-            quote=quote,
-            broadcast_response=broadcast_response,
-            strategy_name=strategy_name,
-        )
+        # Record the swap operation in ledger - but don't let ledger errors fail the swap
+        # since the on-chain transaction already succeeded
+        try:
+            ledger_record = await self._record_swap_operation(
+                from_token=from_token,
+                to_token=to_token,
+                wallet_address=from_address,
+                quote=quote,
+                broadcast_response=broadcast_response,
+                strategy_name=strategy_name,
+            )
+        except Exception as e:
+            self.logger.warning(
+                f"Ledger recording failed (swap succeeded on-chain): {e}"
+            )
+            # Return the quote with output amount so caller can proceed
+            ledger_record = {
+                "to_amount": quote.get("output_amount"),
+                "from_amount": quote.get("input_amount"),
+                "tx_hash": broadcast_response.get("tx_hash")
+                if isinstance(broadcast_response, dict)
+                else None,
+            }
         return (True, ledger_record)
 
     async def get_bridge_quote(
@@ -581,10 +693,10 @@ class BRAPAdapter(BaseAdapter):
         )
         if not build_success:
             return False, approve_tx
-        return await self._broadcast_transaction(approve_tx)
+        return await self._broadcast_transaction(approve_tx, confirmations=2)
 
     async def _broadcast_transaction(
-        self, transaction: dict[str, Any]
+        self, transaction: dict[str, Any], confirmations: int = 0
     ) -> tuple[bool, Any]:
         if getattr(settings, "DRY_RUN", False):
             return True, {"dry_run": True, "transaction": transaction}
@@ -592,6 +704,7 @@ class BRAPAdapter(BaseAdapter):
             transaction,
             wait_for_receipt=True,
             timeout=DEFAULT_TRANSACTION_TIMEOUT,
+            confirmations=confirmations,
         )
 
     async def _record_swap_operation(
@@ -618,16 +731,19 @@ class BRAPAdapter(BaseAdapter):
         response = broadcast_response if isinstance(broadcast_response, dict) else {}
         operation_data = SWAP(
             adapter=self.adapter_type,
-            from_token_id=from_token.get("id"),
-            to_token_id=to_token.get("id"),
-            from_amount=quote.get("input_amount"),
-            to_amount=quote.get("output_amount"),
+            from_token_id=str(from_token.get("id")),
+            to_token_id=str(to_token.get("id")),
+            from_amount=str(quote.get("input_amount")),
+            to_amount=str(quote.get("output_amount")),
             from_amount_usd=from_amount_usd or 0,
             to_amount_usd=to_amount_usd or 0,
-            transaction_hash=response.get("transaction_hash"),
-            transaction_chain_id=from_token.get("chain_id"),
+            transaction_hash=response.get("tx_hash")
+            or response.get("transaction_hash"),
+            transaction_chain_id=from_token.get("chain_id")
+            or (from_token.get("chain") or {}).get("id"),
             transaction_status=response.get("transaction_status"),
-            transaction_receipt=response.get("transaction_receipt"),
+            # Don't pass raw receipt - it contains HexBytes that can't be JSON serialized
+            transaction_receipt=None,
         )
 
         try:
@@ -653,7 +769,7 @@ class BRAPAdapter(BaseAdapter):
         if raw_amount is None:
             return None
         success, price_data = await self.token_adapter.get_token_price(
-            token_info.get("id")
+            token_info.get("token_id")
         )
         if not success or not price_data:
             return None

wayfinder_paths/adapters/moonwell_adapter/README.md

@@ -0,0 +1,174 @@
+# Moonwell Adapter
+
+Adapter for interacting with the [Moonwell](https://moonwell.fi/) lending protocol on Base chain.
+
+- Entrypoint: `adapters.moonwell_adapter.adapter.MoonwellAdapter`
+- Tests: `test_adapter.py`
+
+## Capabilities
+
+The adapter provides the following capabilities:
+- Lending: Supply and withdraw tokens
+- Borrowing: Borrow and repay tokens
+- Collateral management: Enable/disable markets as collateral
+- Rewards: Claim WELL token rewards
+- Position & market queries: Get balances, APYs, and liquidity info
+
+## Overview
+
+The MoonwellAdapter provides functionality for:
+- **Lending**: Supply tokens to earn yield
+- **Borrowing**: Borrow against collateral
+- **Collateral Management**: Enable/disable markets as collateral
+- **Rewards**: Claim WELL token rewards
+- **Position Queries**: Get balances, APYs, and liquidity info
+
+## Supported Markets (Base Chain)
+
+| Token | mToken Address | Underlying Address |
+|-------|----------------|-------------------|
+| USDC | `0xEdc817A28E8B93B03976FBd4a3dDBc9f7D176c22` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| WETH | `0x628ff693426583D9a7FB391E54366292F509D457` | `0x4200000000000000000000000000000000000006` |
+| wstETH | `0x627Fe393Bc6EdDA28e99AE648fD6fF362514304b` | `0xc1CBa3fCea344f92D9239c08C0568f6F2F0ee452` |
+
+## Protocol Addresses (Base Chain)
+
+- **Comptroller**: `0xfbb21d0380bee3312b33c4353c8936a0f13ef26c`
+- **Reward Distributor**: `0xe9005b078701e2a0948d2eac43010d35870ad9d2`
+- **WELL Token**: `0xA88594D404727625A9437C3f886C7643872296AE`
+
+## Construction
+
+```python
+from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
+from wayfinder_paths.adapters.moonwell_adapter import MoonwellAdapter
+
+config = {
+    "strategy_wallet": {"address": "0x...your_wallet..."},
+    "moonwell_adapter": {
+        "chain_id": 8453,  # Base chain (default)
+    }
+}
+web3_service = DefaultWeb3Service(config)
+adapter = MoonwellAdapter(config=config, web3_service=web3_service)
+```
+
+`web3_service` is required so the adapter can share the same wallet provider as the rest of the strategy.
+
+## Usage
+
+```python
+# Supply tokens
+await adapter.lend(
+    mtoken="0xEdc817A28E8B93B03976FBd4a3dDBc9f7D176c22",  # mUSDC
+    underlying_token="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  # USDC
+    amount=1000 * 10**6,  # 1000 USDC
+)
+
+# Enable as collateral
+await adapter.set_collateral(
+    mtoken="0x627Fe393Bc6EdDA28e99AE648fD6fF362514304b",  # mwstETH
+)
+
+# Borrow
+await adapter.borrow(
+    mtoken="0x628ff693426583D9a7FB391E54366292F509D457",  # mWETH
+    amount=10**17,  # 0.1 WETH
+)
+
+# Get position info
+success, position = await adapter.get_pos(
+    mtoken="0xEdc817A28E8B93B03976FBd4a3dDBc9f7D176c22",
+)
+# Returns: {mtoken_balance, underlying_balance, borrow_balance, exchange_rate, balances}
+
+# Get collateral factor
+success, cf = await adapter.get_collateral_factor(
+    mtoken="0x627Fe393Bc6EdDA28e99AE648fD6fF362514304b",
+)
+# Returns: 0.75 (75% LTV)
+
+# Get APY
+success, apy = await adapter.get_apy(
+    mtoken="0xEdc817A28E8B93B03976FBd4a3dDBc9f7D176c22",
+    apy_type="supply",  # or "borrow"
+)
+
+# Claim rewards
+await adapter.claim_rewards()
+```
+
+## API Reference
+
+### Lending Operations
+
+| Method | Description |
+|--------|-------------|
+| `lend(mtoken, underlying_token, amount)` | Supply tokens to earn yield |
+| `unlend(mtoken, amount)` | Withdraw by redeeming mTokens |
+
+### Borrowing Operations
+
+| Method | Description |
+|--------|-------------|
+| `borrow(mtoken, amount)` | Borrow underlying tokens |
+| `repay(mtoken, underlying_token, amount)` | Repay borrowed tokens |
+
+### Collateral Management
+
+| Method | Description |
+|--------|-------------|
+| `set_collateral(mtoken)` | Enable market as collateral (enterMarkets) |
+| `remove_collateral(mtoken)` | Disable market as collateral (exitMarket) |
+
+### Position & Market Data
+
+| Method | Description |
+|--------|-------------|
+| `get_pos(mtoken, account)` | Get position data (balances, debt, rewards) |
+| `get_collateral_factor(mtoken)` | Get collateral factor (LTV) |
+| `get_apy(mtoken, apy_type)` | Get supply or borrow APY |
+| `get_borrowable_amount(account)` | Get max borrowable in USD |
+| `max_withdrawable_mtoken(mtoken, account)` | Calculate safe withdrawal amount via binary search |
+
+### Rewards
+
+| Method | Description |
+|--------|-------------|
+| `claim_rewards(min_rewards_usd)` | Claim WELL rewards (skips if below threshold) |
+
+### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `wrap_eth(amount)` | Wrap ETH to WETH |
+
+All methods return `(success: bool, payload: Any)` tuples. On failure the payload is an error string.
+
+## Testing
+
+```bash
+poetry run pytest wayfinder_paths/adapters/moonwell_adapter/ -v
+```
+
+## Configuration
+
+The adapter can be configured via the `moonwell_adapter` config key:
+
+```python
+config = {
+    "strategy_wallet": {"address": "0x..."},
+    "moonwell_adapter": {
+        "chain_id": 8453,  # Chain ID (default: Base)
+        "comptroller": "0x...",  # Override comptroller address
+        "reward_distributor": "0x...",  # Override reward distributor
+        "m_usdc": "0x...",  # Override mUSDC address
+        "m_weth": "0x...",  # Override mWETH address
+        "m_wsteth": "0x...",  # Override mwstETH address
+    }
+}
+```
+
+## Error handling
+
+Any exception raised by the underlying web3 calls is caught and returned as a `(False, "message")` tuple. The inherited `health_check()` method reports adapter status, making it safe to call from `Strategy.health_check`.

wayfinder_paths/adapters/moonwell_adapter/__init__.py

@@ -0,0 +1,7 @@
+"""
+Moonwell Adapter
+"""
+
+from wayfinder_paths.adapters.moonwell_adapter.adapter import MoonwellAdapter
+
+__all__ = ["MoonwellAdapter"]