wayfinder-paths 0.1.14__py3-none-any.whl → 0.1.15__py3-none-any.whl

wayfinder_paths/core/services/local_evm_txn.py

@@ -20,6 +20,9 @@ SUGGESTED_PRIORITY_FEE_MULTIPLIER = 1.5
 MAX_BASE_FEE_GROWTH_MULTIPLIER = 2
 GAS_LIMIT_BUFFER_MULTIPLIER = 1.5
 
+# Base chain ID (Base mainnet)
+BASE_CHAIN_ID = 8453
+
 # Chains that don't support EIP-1559 (London) and need legacy gas pricing
 PRE_LONDON_GAS_CHAIN_IDS: set[int] = {56, 42161}
 POA_MIDDLEWARE_CHAIN_IDS: set = {56, 137, 43114}
@@ -182,12 +185,20 @@ class LocalEvmTxn(EvmTxn):
         *,
         wait_for_receipt: bool = True,
         timeout: int = DEFAULT_TRANSACTION_TIMEOUT,
-        confirmations: int = 1,
+        confirmations: int | None = None,
     ) -> tuple[bool, Any]:
         try:
             chain_id = transaction["chainId"]
             from_address = transaction["from"]
 
+            # Default confirmation behavior:
+            # - Base: wait for 2 additional blocks after the receipt block
+            # - Others: do not wait for additional confirmations
+            effective_confirmations = confirmations
+            if effective_confirmations is None:
+                effective_confirmations = 2 if int(chain_id) == BASE_CHAIN_ID else 0
+            effective_confirmations = max(0, int(effective_confirmations))
+
             web3 = self.get_web3(chain_id)
             try:
                 transaction = self._validate_transaction(transaction)
@@ -210,6 +221,8 @@ class LocalEvmTxn(EvmTxn):
                     result["receipt"] = self._format_receipt(receipt)
                     # Add block_number at top level for convenience
                     result["block_number"] = result["receipt"].get("blockNumber")
+                    result["confirmations"] = effective_confirmations
+                    result["confirmed_block_number"] = result["block_number"]
 
                     receipt_status = result["receipt"].get("status")
                     if receipt_status is not None and int(receipt_status) != 1:
@@ -219,11 +232,14 @@ class LocalEvmTxn(EvmTxn):
                         )
 
                     # Wait for additional confirmations if requested
-                    if confirmations > 0:
+                    if effective_confirmations > 0:
                         tx_block = result["receipt"].get("blockNumber")
                         if tx_block:
                             await self._wait_for_confirmations(
-                                web3, tx_block, confirmations
+                                web3, tx_block, effective_confirmations
+                            )
+                            result["confirmed_block_number"] = int(tx_block) + int(
+                                effective_confirmations
                             )
 
                 return (True, result)

wayfinder_paths/core/services/local_token_txn.py

@@ -6,7 +6,7 @@ from typing import Any
 
 from eth_utils import to_checksum_address
 from loguru import logger
-from web3 import AsyncWeb3, Web3
+from web3 import Web3
 
 from wayfinder_paths.core.clients.TokenClient import TokenClient
 from wayfinder_paths.core.constants import ZERO_ADDRESS
@@ -85,7 +85,6 @@ class LocalTokenTxnService(TokenTxn):
     ) -> tuple[bool, dict[str, Any] | str]:
         """Build the transaction dictionary for an ERC20 approval."""
         try:
-            web3 = self.wallet_provider.get_web3(chain_id)
             token_checksum = to_checksum_address(token_address)
             from_checksum = to_checksum_address(from_address)
             spender_checksum = to_checksum_address(spender)
@@ -99,7 +98,6 @@ class LocalTokenTxnService(TokenTxn):
             from_address=from_checksum,
             spender=spender_checksum,
             amount=amount_int,
-            web3=web3,
         )
         return True, approve_tx
 
@@ -215,10 +213,8 @@ class LocalTokenTxnService(TokenTxn):
         from_address: str,
         spender: str,
         amount: int,
-        web3: AsyncWeb3,
     ) -> dict[str, Any]:
         """Build an ERC20 approval transaction dict."""
-        del web3  # Use sync Web3 for encoding (AsyncContract doesn't have encodeABI)
         token_checksum = to_checksum_address(token_address)
         spender_checksum = to_checksum_address(spender)
         from_checksum = to_checksum_address(from_address)

wayfinder_paths/core/services/test_local_evm_txn.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from wayfinder_paths.core.services.local_evm_txn import BASE_CHAIN_ID, LocalEvmTxn
+
+
+class _FakeTxHash:
+    def __init__(self, value: str):
+        self._value = value
+
+    def hex(self) -> str:
+        return self._value
+
+
+@pytest.mark.asyncio
+async def test_base_defaults_to_two_confirmations():
+    txn = LocalEvmTxn(config={})
+
+    fake_web3 = MagicMock()
+    fake_web3.eth = MagicMock()
+    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
+    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
+        return_value={
+            "status": 1,
+            "blockNumber": 100,
+            "transactionHash": "0x1",
+            "gasUsed": 21_000,
+            "logs": [],
+        }
+    )
+
+    txn.get_web3 = MagicMock(return_value=fake_web3)
+    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
+    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
+    txn._sign_transaction = MagicMock(return_value=b"signed")
+    txn._close_web3 = AsyncMock()
+    txn._wait_for_confirmations = AsyncMock()
+
+    ok, result = await txn.broadcast_transaction(
+        {
+            "chainId": BASE_CHAIN_ID,
+            "from": "0x0000000000000000000000000000000000000001",
+            "to": "0x0000000000000000000000000000000000000002",
+            "value": 0,
+        },
+        wait_for_receipt=True,
+        timeout=1,
+    )
+
+    assert ok is True
+    txn._wait_for_confirmations.assert_awaited_once_with(fake_web3, 100, 2)
+    assert result["confirmations"] == 2
+    assert result["confirmed_block_number"] == 102
+
+
+@pytest.mark.asyncio
+async def test_non_base_defaults_to_zero_confirmations():
+    txn = LocalEvmTxn(config={})
+
+    fake_web3 = MagicMock()
+    fake_web3.eth = MagicMock()
+    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
+    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
+        return_value={
+            "status": 1,
+            "blockNumber": 100,
+            "transactionHash": "0x1",
+            "gasUsed": 21_000,
+            "logs": [],
+        }
+    )
+
+    txn.get_web3 = MagicMock(return_value=fake_web3)
+    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
+    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
+    txn._sign_transaction = MagicMock(return_value=b"signed")
+    txn._close_web3 = AsyncMock()
+    txn._wait_for_confirmations = AsyncMock()
+
+    ok, result = await txn.broadcast_transaction(
+        {
+            "chainId": 1,
+            "from": "0x0000000000000000000000000000000000000001",
+            "to": "0x0000000000000000000000000000000000000002",
+            "value": 0,
+        },
+        wait_for_receipt=True,
+        timeout=1,
+    )
+
+    assert ok is True
+    txn._wait_for_confirmations.assert_not_awaited()
+    assert result["confirmations"] == 0
+    assert result["confirmed_block_number"] == 100
+
+
+@pytest.mark.asyncio
+async def test_explicit_confirmations_override_defaults():
+    txn = LocalEvmTxn(config={})
+
+    fake_web3 = MagicMock()
+    fake_web3.eth = MagicMock()
+    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
+    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
+        return_value={
+            "status": 1,
+            "blockNumber": 100,
+            "transactionHash": "0x1",
+            "gasUsed": 21_000,
+            "logs": [],
+        }
+    )
+
+    txn.get_web3 = MagicMock(return_value=fake_web3)
+    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
+    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
+    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
+    txn._sign_transaction = MagicMock(return_value=b"signed")
+    txn._close_web3 = AsyncMock()
+    txn._wait_for_confirmations = AsyncMock()
+
+    ok, result = await txn.broadcast_transaction(
+        {
+            "chainId": BASE_CHAIN_ID,
+            "from": "0x0000000000000000000000000000000000000001",
+            "to": "0x0000000000000000000000000000000000000002",
+            "value": 0,
+        },
+        wait_for_receipt=True,
+        timeout=1,
+        confirmations=0,
+    )
+
+    assert ok is True
+    txn._wait_for_confirmations.assert_not_awaited()
+    assert result["confirmations"] == 0
+    assert result["confirmed_block_number"] == 100

wayfinder_paths/core/strategies/Strategy.py

@@ -143,8 +143,22 @@ class Strategy(ABC):
     @abstractmethod
     async def update(self) -> StatusTuple:
         """
-        Update strategy positions/rebalance
-        Returns: (success: bool, message: str)
+        Deploy funds to protocols (no main wallet access).
+        Called after deposit() has transferred assets to strategy wallet.
+
+        Returns:
+            Tuple of (success: bool, message: str)
+        """
+        pass
+
+    @abstractmethod
+    async def exit(self, **kwargs) -> StatusTuple:
+        """
+        Transfer funds from strategy wallet to main wallet.
+        Called after withdraw() has liquidated all positions.
+
+        Returns:
+            Tuple of (success: bool, message: str)
         """
         pass
 

wayfinder_paths/core/utils/evm_helpers.py

@@ -7,7 +7,6 @@ across multiple adapters, extracted from evm_transaction_adapter.
 
 import json
 import os
-from pathlib import Path
 from typing import Any
 
 from loguru import logger
@@ -170,9 +169,3 @@ async def get_abi_filtered(
         if item.get("type") == "function" and item.get("name") in function_names
     ]
     return filtered_abi
-
-
-with open(Path(__file__).parent.parent.parent.joinpath("abis/generic/erc20.json")) as f:
-    erc20_abi_raw = f.read()
-
-ERC20_ABI = json.loads(erc20_abi_raw)

wayfinder_paths/policies/erc20.py

@@ -1,4 +1,4 @@
-from wayfinder_paths.core.utils.evm_helpers import ERC20_ABI
+from wayfinder_paths.core.constants.erc20_abi import ERC20_ABI
 
 
 def any_erc20_function(token_address: str) -> dict:

wayfinder_paths/run_strategy.py

@@ -197,6 +197,10 @@ async def run_strategy(
             result = await strategy_job.execute_strategy("update")
             logger.info(f"Update result: {result}")
 
+        elif action == "exit":
+            result = await strategy_job.execute_strategy("exit")
+            logger.info(f"Exit result: {result}")
+
         elif action == "partial-liquidate":
             usd_value = kwargs.get("amount")
             if not usd_value:
@@ -292,6 +296,7 @@ def main():
             "withdraw",
             "status",
             "update",
+            "exit",
             "policy",
             "script",
             "partial-liquidate",

wayfinder_paths/strategies/basis_trading_strategy/strategy.py

@@ -1072,6 +1072,73 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
             f"Withdrew ${total_withdrawn:.2f} total to main wallet ({main_address}).",
         )
 
+    async def exit(self, **kwargs) -> StatusTuple:
+        """Transfer funds from strategy wallet to main wallet."""
+        self.logger.info("EXIT: Transferring remaining funds to main wallet")
+
+        strategy_address = self._get_strategy_wallet_address()
+        main_address = self._get_main_wallet_address()
+
+        if strategy_address.lower() == main_address.lower():
+            return (True, "Main wallet is strategy wallet, no transfer needed")
+
+        transferred_items = []
+
+        # Transfer USDC to main wallet
+        usdc_ok, usdc_raw = await self.balance_adapter.get_balance(
+            token_id=USDC_ARBITRUM_TOKEN_ID,
+            wallet_address=strategy_address,
+        )
+        if usdc_ok and usdc_raw:
+            usdc_balance = float(usdc_raw.get("balance", 0))
+            if usdc_balance > 1.0:
+                self.logger.info(f"Transferring {usdc_balance:.2f} USDC to main wallet")
+                (
+                    success,
+                    msg,
+                ) = await self.balance_adapter.move_from_strategy_wallet_to_main_wallet(
+                    query=USDC_ARBITRUM_TOKEN_ID,
+                    amount=usdc_balance,
+                    strategy_name=self.name,
+                    skip_ledger=False,
+                )
+                if success:
+                    transferred_items.append(f"{usdc_balance:.2f} USDC")
+                else:
+                    self.logger.warning(f"USDC transfer failed: {msg}")
+
+        # Transfer ETH (minus reserve for tx fees) to main wallet
+        eth_ok, eth_raw = await self.balance_adapter.get_balance(
+            token_id="ethereum-arbitrum",
+            wallet_address=strategy_address,
+        )
+        if eth_ok and eth_raw:
+            eth_balance = float(eth_raw.get("balance", 0))
+            tx_fee_reserve = 0.0002
+            transferable_eth = eth_balance - tx_fee_reserve
+            if transferable_eth > 0.0001:
+                self.logger.info(
+                    f"Transferring {transferable_eth:.6f} ETH to main wallet"
+                )
+                (
+                    success,
+                    msg,
+                ) = await self.balance_adapter.move_from_strategy_wallet_to_main_wallet(
+                    query="ethereum-arbitrum",
+                    amount=transferable_eth,
+                    strategy_name=self.name,
+                    skip_ledger=False,
+                )
+                if success:
+                    transferred_items.append(f"{transferable_eth:.6f} ETH")
+                else:
+                    self.logger.warning(f"ETH transfer failed: {msg}")
+
+        if not transferred_items:
+            return (True, "No funds to transfer to main wallet")
+
+        return (True, f"Transferred to main wallet: {', '.join(transferred_items)}")
+
     async def _status(self) -> StatusDict:
         """Return portfolio value and strategy status with live data."""
         total_value, hl_value, vault_value = await self._get_total_portfolio_value()

wayfinder_paths/strategies/basis_trading_strategy/test_strategy.py

@@ -461,7 +461,7 @@ class TestBasisTradingStrategy:
         # Try to scale with $5 (below $10 minimum notional)
         # With 2x leverage, order_usd = 5 * (2/3) = 3.33, below $10
         success, msg = await strategy._scale_up_position(5.0)
-        assert success is True  # Returns success=True but with message
+        assert success  # Returns success=True but with message
         assert "below minimum notional" in msg
 
     @pytest.mark.asyncio
@@ -563,7 +563,7 @@ class TestBasisTradingStrategy:
 
             # Should have called fill_pair_units to scale up
             assert mock_filler.fill_pair_units.called
-            assert success is True
+            assert success
 
     @pytest.mark.asyncio
     async def test_ensure_builder_fee_approved_already_approved(
@@ -612,7 +612,7 @@ class TestBasisTradingStrategy:
                             )
 
                             success, msg = await s.ensure_builder_fee_approved()
-                            assert success is True
+                            assert success
                             assert "already approved" in msg.lower()
                             # Should not have called approve_builder_fee
                             mock_hyperliquid_adapter.approve_builder_fee.assert_not_called()
@@ -661,7 +661,7 @@ class TestBasisTradingStrategy:
                             )
 
                             success, msg = await s.ensure_builder_fee_approved()
-                            assert success is True
+                            assert success
                             assert "approved" in msg.lower()
                             # Should have called approve_builder_fee
                             mock_hyperliquid_adapter.approve_builder_fee.assert_called_once()
@@ -832,7 +832,7 @@ class TestBasisTradingStrategy:
             mock_filler_class.return_value = mock_filler
 
             success, _ = await strategy.update()
-            assert success is True
+            assert success
 
         # Target spot was $66.67, so we should transfer $33.33 spot->perp.
         mock_hyperliquid_adapter.transfer_spot_to_perp.assert_called_once()
@@ -907,7 +907,7 @@ class TestBasisTradingStrategy:
         strategy._find_and_open_position = AsyncMock(return_value=(True, "redeployed"))
 
         success, msg = await strategy.update()
-        assert success is True
+        assert success
         assert msg == "redeployed"
         strategy._close_position.assert_awaited_once()
         strategy._find_and_open_position.assert_awaited_once()

wayfinder_paths/strategies/hyperlend_stable_yield_strategy/strategy.py

@@ -719,8 +719,8 @@ class HyperlendStableYieldStrategy(Strategy):
                     result,
                     tx_data,
                 ) = await self.brap_adapter.swap_from_token_ids(
-                    from_query=from_token_id,
-                    to_query=to_token_id,
+                    from_token_id=from_token_id,
+                    to_token_id=to_token_id,
                     from_address=strategy_address,
                     amount=amount_wei_str,
                     slippage=slippage,
@@ -935,6 +935,75 @@ class HyperlendStableYieldStrategy(Strategy):
 
         return (True, ". ".join(messages))
 
+    async def exit(self, **kwargs) -> StatusTuple:
+        """Transfer funds from strategy wallet to main wallet."""
+        self.logger.info("EXIT: Transferring remaining funds to main wallet")
+
+        strategy_address = self._get_strategy_wallet_address()
+        main_address = self._get_main_wallet_address()
+
+        if strategy_address.lower() == main_address.lower():
+            return (True, "Main wallet is strategy wallet, no transfer needed")
+
+        transferred_items = []
+
+        # Transfer USDT0 to main wallet
+        usdt_ok, usdt_raw = await self.balance_adapter.get_balance(
+            token_id="usdt0-hyperevm",
+            wallet_address=strategy_address,
+        )
+        if usdt_ok and usdt_raw:
+            usdt_balance = float(usdt_raw.get("balance", 0))
+            if usdt_balance > 1.0:
+                self.logger.info(
+                    f"Transferring {usdt_balance:.2f} USDT0 to main wallet"
+                )
+                (
+                    success,
+                    msg,
+                ) = await self.balance_adapter.move_from_strategy_wallet_to_main_wallet(
+                    query="usdt0-hyperevm",
+                    amount=usdt_balance,
+                    strategy_name=self.name,
+                    skip_ledger=False,
+                )
+                if success:
+                    transferred_items.append(f"{usdt_balance:.2f} USDT0")
+                else:
+                    self.logger.warning(f"USDT0 transfer failed: {msg}")
+
+        # Transfer HYPE (minus reserve for tx fees) to main wallet
+        hype_ok, hype_raw = await self.balance_adapter.get_balance(
+            token_id="hyperliquid-hyperevm",
+            wallet_address=strategy_address,
+        )
+        if hype_ok and hype_raw:
+            hype_balance = float(hype_raw.get("balance", 0))
+            tx_fee_reserve = 0.1  # Reserve 0.1 HYPE for tx fees
+            transferable_hype = hype_balance - tx_fee_reserve
+            if transferable_hype > 0.01:
+                self.logger.info(
+                    f"Transferring {transferable_hype:.4f} HYPE to main wallet"
+                )
+                (
+                    success,
+                    msg,
+                ) = await self.balance_adapter.move_from_strategy_wallet_to_main_wallet(
+                    query="hyperliquid-hyperevm",
+                    amount=transferable_hype,
+                    strategy_name=self.name,
+                    skip_ledger=False,
+                )
+                if success:
+                    transferred_items.append(f"{transferable_hype:.4f} HYPE")
+                else:
+                    self.logger.warning(f"HYPE transfer failed: {msg}")
+
+        if not transferred_items:
+            return (True, "No funds to transfer to main wallet")
+
+        return (True, f"Transferred to main wallet: {', '.join(transferred_items)}")
+
     async def _swap_residual_balances_to_token(
         self, token_info: dict[str, Any], include_native: bool = False
     ) -> list[str]:

wayfinder_paths/strategies/moonwell_wsteth_loop_strategy/README.md

@@ -31,9 +31,10 @@ The position is **delta-neutral**: WETH debt offsets wstETH collateral, so PnL i
 ## 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.
+- **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.
 
 ## Adapters used
@@ -58,9 +59,9 @@ The position is **delta-neutral**: WETH debt offsets wstETH collateral, so PnL i
 ### 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()`.
+- 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.
 
@@ -75,7 +76,7 @@ The position is **delta-neutral**: WETH debt offsets wstETH collateral, so PnL i
 ### Withdraw
 
 - Sweeps miscellaneous token balances to WETH.
-- Repays all WETH debt via `_repay_debt_loop()`.
+- 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.