wayfinder-paths 0.1.19__py3-none-any.whl → 0.1.20__py3-none-any.whl

wayfinder_paths/strategies/moonwell_wsteth_loop_strategy/README.md

@@ -1,106 +1,105 @@
 # Moonwell wstETH Loop Strategy
 
-- Entrypoint: `strategies.moonwell_wsteth_loop_strategy.strategy.MoonwellWstethLoopStrategy`
-- Examples: `examples.json`
-- Tests: `test_strategy.py`
+Leveraged wstETH carry trade on Base via Moonwell.
 
-## What it does
+- **Module**: `wayfinder_paths.strategies.moonwell_wsteth_loop_strategy.strategy.MoonwellWstethLoopStrategy`
+- **Chain**: Base (8453)
+- **Tokens**: USDC, WETH, wstETH
 
-A leveraged liquid-staking carry trade on Base that loops USDC collateral into wstETH exposure. The strategy:
+## Overview
 
-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.
+This strategy creates a leveraged liquid-staking carry trade by:
+1. Depositing USDC as initial collateral on Moonwell
+2. Borrowing WETH against the USDC collateral
+3. Swapping WETH to wstETH via Aerodrome/BRAP
+4. Lending wstETH back to Moonwell as additional collateral
+5. Repeating the loop until target leverage is reached
 
 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
+## 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)
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `MIN_GAS` | 0.002 ETH | Minimum gas buffer |
+| `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 |
 
-## Safety features
+## Safety Features
 
-- **Depeg guard**: `_max_safe_F()` calculates leverage ceiling based on wstETH collateral factor and max depeg tolerance.
-- **Delta-neutrality**: `_post_run_guard()` enforces wstETH collateral ≥ WETH debt (within tolerance) via `_reconcile_wallet_into_position()` and `_settle_weth_debt_to_target_usd()`.
-- **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`.
-- **Deterministic Base reads**: waits 2 blocks after receipts by default and pins ETH/ERC20 balance reads to the confirmed block to avoid stale RPC reads on Base.
-- **Rollback protection**: Checks actual balances before rollback swaps to prevent failed transactions.
+- **Depeg guard**: Calculates leverage ceiling based on collateral factor and max depeg tolerance
+- **Delta-neutrality**: Enforces wstETH collateral >= WETH debt
+- **Swap retries**: Progressive slippage (0.5% -> 1% -> 1.5%) with exponential backoff
+- **Health monitoring**: Automatic deleveraging when health factor drops
+- **Deterministic reads**: Waits 2 blocks after receipts to avoid stale RPC data
 
-## Adapters used
+## 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.
+- **BalanceAdapter**: Token balances, wallet transfers
+- **TokenAdapter**: Token metadata, price feeds
+- **LedgerAdapter**: Net deposit tracking
+- **BRAPAdapter**: Swap quotes and execution
+- **MoonwellAdapter**: Lending, borrowing, collateral management
 
 ## 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.
+```bash
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy \
+    --action deposit --main-token-amount 100 --gas-token-amount 0.01 --config config.json
+```
+
+- Validates USDC and ETH balances
+- Transfers ETH gas buffer if needed
+- Moves USDC to strategy wallet
+- Lends USDC on Moonwell and enables as collateral
+- Executes leverage loop (borrow WETH -> swap to wstETH -> lend)
 
 ### Update
 
-- Checks gas balance meets maintenance threshold.
-- Reconciles wallet leftovers into the intended position (`_reconcile_wallet_into_position()`).
-- Computes HF/LTV/delta from a single accounting snapshot.
-- If HF < MIN: triggers deleveraging via `_settle_weth_debt_to_target_usd()`.
-- If HF > MAX: executes additional leverage loops to optimize yield.
-- Claims WELL rewards if above minimum threshold.
+```bash
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy \
+    --action update --config config.json
+```
+
+- Checks gas balance meets threshold
+- Reconciles wallet leftovers into position
+- Computes health factor/LTV/delta
+- If HF < MIN: triggers deleveraging
+- If HF > MAX: executes additional leverage loops
+- Claims WELL rewards if above threshold
 
 ### Status
 
-`_status()` returns:
+```bash
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy \
+    --action status --config config.json
+```
 
-- `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
+Returns:
+- `portfolio_value`: USDC lent + wstETH lent - WETH debt
+- `net_deposit`: From LedgerAdapter
+- `strategy_status`: Leverage, health factor, LTV, peg diff, credit remaining
 
 ### Withdraw
 
-- Sweeps miscellaneous token balances to WETH.
-- Repays all WETH debt via `_settle_weth_debt_to_target_usd(target_debt_usd=0.0, mode="exit")`.
-- 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 config.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
+poetry run python wayfinder_paths/run_strategy.py moonwell_wsteth_loop_strategy \
+    --action withdraw --config config.json
 ```
 
+- Sweeps miscellaneous token balances to WETH
+- Repays all WETH debt
+- Unlends wstETH, swaps to USDC
+- Unlends USDC collateral
+- Returns USDC and remaining ETH to main wallet
+
 ## Testing
 
 ```bash