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

wayfinder_paths/strategies/hyperlend_stable_yield_strategy/strategy.py

@@ -112,7 +112,7 @@ class HyperlendStableYieldStrategy(Strategy):
         gas_threshold=MAX_GAS / 3,
         # risk indicators
         volatility=Volatility.LOW,
-        volatility_description_short=(
+        volatility_description=(
             "Pure HyperLend stablecoin lending keeps NAV steady aside from rate drift."
         ),
         directionality=Directionality.MARKET_NEUTRAL,
@@ -195,7 +195,6 @@ class HyperlendStableYieldStrategy(Strategy):
         *,
         main_wallet: dict[str, Any] | None = None,
         strategy_wallet: dict[str, Any] | None = None,
-        simulation: bool = False,
         web3_service: Web3Service = None,
         api_key: str | None = None,
     ):
@@ -207,7 +206,6 @@ class HyperlendStableYieldStrategy(Strategy):
             merged_config["strategy_wallet"] = strategy_wallet
 
         self.config = merged_config
-        self.simulation = simulation
         self.balance_adapter = None
         self.tx_adapter = None
         self.token_adapter = None
@@ -238,7 +236,6 @@ class HyperlendStableYieldStrategy(Strategy):
                 token_transaction_service = LocalTokenTxnService(
                     adapter_config,
                     wallet_provider=wallet_provider,
-                    simulation=self.simulation,
                 )
                 web3_service = DefaultWeb3Service(
                     wallet_provider=wallet_provider,
@@ -250,12 +247,9 @@ class HyperlendStableYieldStrategy(Strategy):
             balance = BalanceAdapter(adapter_config, web3_service=web3_service)
             token_adapter = TokenAdapter()
             ledger_adapter = LedgerAdapter()  # here
-            brap_adapter = BRAPAdapter(
-                web3_service=web3_service, simulation=self.simulation
-            )
+            brap_adapter = BRAPAdapter(web3_service=web3_service)
             hyperlend_adapter = HyperlendAdapter(
                 adapter_config,
-                simulation=self.simulation,
                 web3_service=web3_service,
             )
 
@@ -323,11 +317,109 @@ class HyperlendStableYieldStrategy(Strategy):
         self.hys_z: float = self.HYSTERESIS_Z
         self.rotation_tx_cost: float = self.ROTATION_TX_COST
 
-    async def deposit(self) -> StatusTuple:
+    async def deposit(
+        self, main_token_amount: float = 0.0, gas_token_amount: float = 0.0
+    ) -> StatusTuple:
+        if main_token_amount == 0.0 and gas_token_amount == 0.0:
+            return (
+                False,
+                "Either main_token_amount or gas_token_amount must be provided",
+            )
+
+        if main_token_amount > 0:
+            if main_token_amount < self.MIN_USDT0_DEPOSIT_AMOUNT:
+                return (
+                    False,
+                    f"Main token amount {main_token_amount} is below minimum {self.MIN_USDT0_DEPOSIT_AMOUNT}",
+                )
+
+        if gas_token_amount and gas_token_amount > self.GAS_MAXIMUM:
+            return (
+                False,
+                f"Gas token amount exceeds maximum configured gas buffer: {self.GAS_MAXIMUM}",
+            )
+
+        if self.balance_adapter is None:
+            return (
+                False,
+                "Balance adapter not initialized. Strategy initialization may have failed.",
+            )
+
+        (
+            success,
+            main_usdt0_balance,
+        ) = await self.balance_adapter.get_balance(
+            token_id=self.usdt_token_info.get("token_id"),
+            wallet_address=self._get_main_wallet_address(),
+        )
+        if not success:
+            return (
+                False,
+                f"Failed to get main wallet USDT0 balance: {main_usdt0_balance}",
+            )
+
+        (
+            success,
+            main_hype_balance,
+        ) = await self.balance_adapter.get_balance(
+            token_id=self.hype_token_info.get("token_id"),
+            wallet_address=self._get_main_wallet_address(),
+        )
+        if not success:
+            return (
+                False,
+                f"Failed to get main wallet HYPE balance: {main_hype_balance}",
+            )
+
+        main_usdt0_native = main_usdt0_balance / (
+            10 ** self.usdt_token_info.get("decimals")
+        )
+        main_hype_native = main_hype_balance / (
+            10 ** self.hype_token_info.get("decimals")
+        )
+
+        if main_token_amount > 0:
+            if main_usdt0_native < main_token_amount:
+                return (
+                    False,
+                    f"Main wallet USDT0 balance is less than the deposit amount: {main_usdt0_native} < {main_token_amount}",
+                )
+
+        if gas_token_amount > 0:
+            if main_hype_native < gas_token_amount:
+                return (
+                    False,
+                    f"Main wallet HYPE balance is less than the deposit amount: {main_hype_native} < {gas_token_amount}",
+                )
+
+        if gas_token_amount > 0:
+            (
+                success,
+                msg,
+            ) = await self.balance_adapter.move_from_main_wallet_to_strategy_wallet(
+                self.hype_token_info.get("token_id"),
+                gas_token_amount,
+                strategy_name=self.name,
+            )
+            if not success:
+                return (False, f"HYPE transfer to strategy failed: {msg}")
+
+        if main_token_amount > 0:
+            (
+                success,
+                msg,
+            ) = await self.balance_adapter.move_from_main_wallet_to_strategy_wallet(
+                self.usdt_token_info.get("token_id"),
+                main_token_amount,
+                strategy_name=self.name,
+            )
+            if not success:
+                return (False, f"USDT0 transfer to strategy failed: {msg}")
+
         self._invalidate_assets_snapshot()
         await self._hydrate_position_from_chain()
 
-        return (True, "hydrated positions")
+        return (success, msg)
 
     async def _estimate_redeploy_tokens(self) -> float:
         positions = await self._get_lent_positions()
@@ -1344,26 +1436,12 @@ class HyperlendStableYieldStrategy(Strategy):
                 continue
 
             balance_tokens = float(entry.get("tokens") or 0)
-            if balance_tokens <= 0:
-                continue
-
-            try:
-                (
-                    transfer_success,
-                    _,
-                ) = await self.balance_adapter.move_from_strategy_wallet_to_main_wallet(
-                    token_id=token.get("token_id"),
-                    amount=balance_tokens,
-                    strategy_name=self.name,
-                )
-            except Exception:
-                continue
-
-            if transfer_success:
-                actions.append(
-                    f"Transferred {balance_tokens:.4f} {token.get('symbol')} to main wallet"
+            if balance_tokens > 0:
+                logger.warning(
+                    f"Failed to swap {balance_tokens:.4f} {token.get('symbol', 'unknown')} "
+                    f"to {target_token.get('symbol', 'target')} during alignment. "
+                    f"Leaving in strategy wallet for next update cycle."
                 )
-                self._invalidate_assets_snapshot()
 
         kept_tokens = float(balances.get("native", {}).get("tokens") or 0)
 

wayfinder_paths/strategies/hyperlend_stable_yield_strategy/test_strategy.py

@@ -46,20 +46,20 @@ def strategy():
         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:
         # Mock balances: 1000 USDT0 (with 6 decimals) and 2 HYPE (with 18 decimals)
-        usdt0_balance_mock = AsyncMock(return_value=(True, 1000000000))
-        hype_balance_mock = AsyncMock(return_value=(True, 2000000000000000000))
-
         def get_balance_side_effect(token_id, wallet_address, **kwargs):
-            if token_id == "usdt0-hyperevm" or token_id == "usdt0":
-                return usdt0_balance_mock.return_value
-            elif token_id == "hype-hyperevm" or token_id == "hype":
-                return hype_balance_mock.return_value
-            return (True, 1000000000)
+            token_id_str = str(token_id).lower() if token_id else ""
+            if "usdt0" in token_id_str or token_id_str == "usdt0":
+                # 1000 USDT0 with 6 decimals = 1000 * 10^6 = 1000000000
+                return (True, 1000000000)
+            elif "hype" in token_id_str or token_id_str == "hype":
+                # 2 HYPE with 18 decimals = 2 * 10^18 = 2000000000000000000
+                return (True, 2000000000000000000)
+            # Default: return high balance for any other token
+            return (True, 2000000000000000000)
 
         s.balance_adapter.get_balance = AsyncMock(side_effect=get_balance_side_effect)
 
@@ -101,15 +101,54 @@ def strategy():
         )
 
     if hasattr(s, "balance_adapter") and s.balance_adapter:
+        # Mock the main methods first
         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": "0xCAFEBABE"})
+        # Mock internal dependencies unconditionally to prevent MagicMock await errors
+        # These are needed if the real method somehow gets called
+        s.balance_adapter.token_client = AsyncMock()
+        s.balance_adapter.token_client.get_token_details = AsyncMock(
+            return_value={
+                "id": "usdt0-hyperevm",
+                "address": "0x1234",
+                "decimals": 6,
+            }
+        )
+        s.balance_adapter.token_transactions = AsyncMock()
+        s.balance_adapter.token_transactions.build_send = AsyncMock(
+            return_value=(True, {"transaction": "0xMOCK"})
+        )
+        s.balance_adapter.wallet_provider = AsyncMock()
+        s.balance_adapter.wallet_provider.broadcast_transaction = AsyncMock(
+            return_value=(True, {"transaction_hash": "0xCAFEBABE"})
+        )
+        # token_adapter might already be set, so check before overriding
+        if (
+            not hasattr(s.balance_adapter, "token_adapter")
+            or s.balance_adapter.token_adapter is None
+        ):
+            s.balance_adapter.token_adapter = AsyncMock()
+        if hasattr(s.balance_adapter.token_adapter, "get_token_price"):
+            s.balance_adapter.token_adapter.get_token_price = AsyncMock(
+                return_value=(True, {"current_price": 1.0})
+            )
+        # ledger_adapter might already be set, so check before overriding
+        if (
+            not hasattr(s.balance_adapter, "ledger_adapter")
+            or s.balance_adapter.ledger_adapter is None
+        ):
+            s.balance_adapter.ledger_adapter = AsyncMock()
+        if hasattr(s.balance_adapter.ledger_adapter, "record_deposit"):
+            s.balance_adapter.ledger_adapter.record_deposit = AsyncMock(
+                return_value=(True, {})
+            )
+        if hasattr(s.balance_adapter.ledger_adapter, "record_withdrawal"):
+            s.balance_adapter.ledger_adapter.record_withdrawal = AsyncMock(
+                return_value=(True, {})
             )
 
     if hasattr(s, "ledger_adapter") and s.ledger_adapter:
@@ -304,8 +343,8 @@ async def test_canonical_usage(strategy):
     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"
+            ok, msg = await strategy.deposit(**deposit_params)
+            assert ok, f"Canonical example '{example_name}' deposit failed: {msg}"
 
         if "update" in example_data:
             result = await strategy.update()

wayfinder_paths/strategies/moonwell_wsteth_loop_strategy/README.md

@@ -0,0 +1,108 @@
+# Moonwell wstETH Loop Strategy
+
+- Entrypoint: `strategies.moonwell_wsteth_loop_strategy.strategy.MoonwellWstethLoopStrategy`
+- Examples: `examples.json`
+- Tests: `test_strategy.py`
+
+## What it does
+
+A leveraged liquid-staking carry trade on Base that loops USDC collateral into wstETH exposure. The strategy:
+
+1. Deposits USDC as initial collateral on Moonwell lending protocol.
+2. Borrows WETH against the USDC collateral.
+3. Swaps WETH to wstETH via Aerodrome/BRAP routing.
+4. Lends wstETH back to Moonwell as additional collateral.
+5. Repeats the loop until target leverage is reached or marginal gains fall below threshold.
+
+The position is **delta-neutral**: WETH debt offsets wstETH collateral, so PnL is driven by the spread between wstETH staking yield and WETH borrow cost.
+
+## Key parameters
+
+- `MIN_GAS = 0.002` ETH (minimum Base ETH for gas)
+- `MIN_USDC_DEPOSIT = 20` USDC (minimum initial collateral)
+- `MAX_DEPEG = 0.01` (1% max stETH/ETH depeg threshold)
+- `MIN_HEALTH_FACTOR = 1.2` (triggers deleveraging if below)
+- `MAX_HEALTH_FACTOR = 1.5` (triggers leverage loop if above)
+- `leverage_limit = 10` (maximum leverage multiplier)
+- `COLLATERAL_SAFETY_FACTOR = 0.98` (2% safety buffer on borrows)
+- `MAX_SLIPPAGE_TOLERANCE = 0.03` (3% max slippage to prevent MEV)
+- `_MIN_LEVERAGE_GAIN_BPS = 50e-4` (stop looping if marginal gain < 50 bps)
+
+## Safety features
+
+- **Depeg guard**: `_max_safe_F()` calculates leverage ceiling based on wstETH collateral factor and max depeg tolerance.
+- **Delta-neutrality**: `_balance_weth_debt()` rebalances when WETH debt exceeds wstETH collateral value.
+- **Swap retries**: `_swap_with_retries()` uses progressive slippage (0.5% → 1% → 1.5%) with exponential backoff.
+- **Health monitoring**: Automatic deleveraging when health factor drops below `MIN_HEALTH_FACTOR`.
+- **Rollback protection**: Checks actual balances before rollback swaps to prevent failed transactions.
+
+## Adapters used
+
+- `BalanceAdapter` for token balances and wallet transfers with ledger tracking.
+- `TokenAdapter` for token metadata and price feeds.
+- `LedgerAdapter` for net deposit tracking.
+- `BRAPAdapter` for swap quotes and execution via Aerodrome/routing.
+- `MoonwellAdapter` for lending, borrowing, collateral management, and position queries.
+- `LocalTokenTxnService` via `DefaultWeb3Service` for low-level sends/approvals.
+
+## Actions
+
+### Deposit
+
+- Validates USDC and ETH balances in the main wallet.
+- Transfers ETH (gas) into the strategy wallet if needed.
+- Moves USDC from main wallet to strategy wallet.
+- Lends USDC on Moonwell and enables as collateral.
+- Executes leverage loop: borrow WETH → swap to wstETH → lend wstETH → repeat.
+
+### Update
+
+- Checks gas balance meets maintenance threshold.
+- Balances WETH debt against wstETH collateral for delta-neutrality.
+- Computes health factor from aggregated positions.
+- If HF < MIN: triggers deleveraging via `_repay_debt_loop()`.
+- If HF > MAX: executes additional leverage loops to optimize yield.
+- Claims WELL rewards if above minimum threshold.
+
+### Status
+
+`_status()` returns:
+
+- `portfolio_value`: sum of all position values (USDC lent + wstETH lent - WETH debt)
+- `net_deposit`: fetched from LedgerAdapter
+- `strategy_status`: includes current leverage, health factor, LTV, peg diff, credit remaining
+
+### Withdraw
+
+- Sweeps miscellaneous token balances to WETH.
+- Repays all WETH debt via `_repay_debt_loop()`.
+- Unlends wstETH, swaps to USDC.
+- Unlends USDC collateral.
+- Returns USDC and remaining ETH to main wallet.
+
+## Running locally
+
+```bash
+# Install dependencies
+poetry install
+
+# Generate wallets (writes wallets.json)
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
+
+# Copy config and edit credentials
+cp wayfinder_paths/config.example.json config.json
+
+# Check status / health
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy --action status --config $(pwd)/config.json
+
+# Perform a deposit/update/withdraw cycle
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy --action deposit --main-token-amount 100 --gas-token-amount 0.01 --config $(pwd)/config.json
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy --action update --config $(pwd)/config.json
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy --action withdraw --config $(pwd)/config.json
+```
+
+## Testing
+
+```bash
+poetry run pytest wayfinder_paths/strategies/moonwell_wsteth_loop_strategy/ -v
+```

wayfinder_paths/strategies/moonwell_wsteth_loop_strategy/examples.json

@@ -0,0 +1,11 @@
+{
+  "smoke": {
+    "deposit": {
+      "main_token_amount": 0.1,
+      "gas_token_amount": 0.001
+    },
+    "update": {},
+    "status": {},
+    "withdraw": {}
+  }
+}