wayfinder-paths 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

wayfinder_paths/core/strategies/Strategy.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import os
 import traceback
 from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
 from typing import Any, TypedDict
 
 from loguru import logger
@@ -13,32 +16,53 @@ class StatusDict(TypedDict):
     portfolio_value: float
     net_deposit: float
     strategy_status: Any
+    gas_available: float
+    gassed_up: bool
 
 
 StatusTuple = tuple[bool, str]
 
 
+class WalletConfig(TypedDict, total=False):
+    """Wallet configuration structure - allows additional fields for flexibility"""
+
+    address: str
+    private_key: str | None
+    private_key_hex: str | None
+    wallet_type: str | None
+
+
+class StrategyConfig(TypedDict, total=False):
+    """Base strategy configuration structure - allows additional fields for flexibility"""
+
+    main_wallet: WalletConfig | None
+    strategy_wallet: WalletConfig | None
+    wallet_type: str | None
+
+
 class Strategy(ABC):
-    name: str = None
-    INFO: StratDescriptor = None
+    name: str | None = None
+    INFO: StratDescriptor | None = None
 
     def __init__(
         self,
-        config: dict[str, Any] | None = None,
+        config: StrategyConfig | dict[str, Any] | None = None,
         *,
-        main_wallet: dict[str, Any] | None = None,
-        vault_wallet: dict[str, Any] | None = None,
+        main_wallet: WalletConfig | dict[str, Any] | None = None,
+        strategy_wallet: WalletConfig | dict[str, Any] | None = None,
         simulation: bool = False,
-        web3_service: Web3Service = None,
+        web3_service: Web3Service | None = None,
         api_key: str | None = None,
     ):
         self.adapters = {}
-        self.ledger = None
+        self.ledger_adapter = None
         self.logger = logger.bind(strategy=self.__class__.__name__)
         if api_key:
             os.environ["WAYFINDER_API_KEY"] = api_key
 
-    async def setup(self):
+        self.config = config
+
+    async def setup(self) -> None:
         """Initialize strategy-specific setup after construction"""
         pass
 
@@ -46,38 +70,72 @@ class Strategy(ABC):
         """Log messages - can be overridden by subclasses"""
         self.logger.info(msg)
 
-    async def temp_ui_message(self, msg: str) -> None:
-        """Hook for temporary UI messages (e.g., progress) to the chat window."""
-        # No-op by default; strategies/hosts can override
-        return None
-
-    async def quote(self):
+    async def quote(self) -> None:
         """Get quotes for potential trades - optional for strategies"""
         pass
 
+    def _get_strategy_wallet_address(self) -> str:
+        """Get strategy wallet address with validation."""
+        strategy_wallet = self.config.get("strategy_wallet")
+        if not strategy_wallet or not isinstance(strategy_wallet, dict):
+            raise ValueError("strategy_wallet not configured in strategy config")
+        address = strategy_wallet.get("address")
+        if not address:
+            raise ValueError("strategy_wallet address not found in config")
+        return str(address)
+
+    def _get_main_wallet_address(self) -> str:
+        """Get main wallet address with validation."""
+        main_wallet = self.config.get("main_wallet")
+        if not main_wallet or not isinstance(main_wallet, dict):
+            raise ValueError("main_wallet not configured in strategy config")
+        address = main_wallet.get("address")
+        if not address:
+            raise ValueError("main_wallet address not found in config")
+        return str(address)
+
     @abstractmethod
     async def deposit(self, **kwargs) -> StatusTuple:
         """
-        Deposit funds into the strategy
-        Returns: (success: bool, message: str)
+        Deposit funds into the strategy.
+
+        Args:
+            **kwargs: Strategy-specific deposit parameters. Common parameters include:
+                - main_token_amount: Amount of main token to deposit (float)
+                - gas_token_amount: Amount of gas token to deposit (float)
+
+        Returns:
+            Tuple of (success: bool, message: str)
+
+        Raises:
+            ValueError: If required parameters are missing or invalid.
         """
         pass
 
     async def withdraw(self, **kwargs) -> StatusTuple:
         """
-        Withdraw funds from the strategy
-        Default implementation unwinds all operations
-        Returns: (success: bool, message: str)
+        Withdraw funds from the strategy.
+        Default implementation unwinds all operations.
+
+        Args:
+            **kwargs: Strategy-specific withdrawal parameters (optional).
+
+        Returns:
+            Tuple of (success: bool, message: str)
+
+        Note:
+            Subclasses may override this method to add validation or custom
+            withdrawal logic. The base implementation unwinds all ledger operations.
         """
-        if hasattr(self, "ledger") and self.ledger:
-            while self.ledger.positions.operations:
-                node = self.ledger.positions.operations[-1]
+        if hasattr(self, "ledger_adapter") and self.ledger_adapter:
+            while self.ledger_adapter.positions.operations:
+                node = self.ledger_adapter.positions.operations[-1]
                 adapter = self.adapters.get(node.adapter)
                 if adapter and hasattr(adapter, "unwind_op"):
                     await adapter.unwind_op(node)
-                self.ledger.positions.operations.pop()
+                self.ledger_adapter.positions.operations.pop()
 
-            await self.ledger.save()
+            await self.ledger_adapter.save()
 
         return (True, "Withdrawal complete")
 
@@ -108,7 +166,12 @@ class Strategy(ABC):
         Wrapper to compute and return strategy status. In Django, this also snapshots.
         Here we simply delegate to _status for compatibility.
         """
-        return await self._status()
+
+        status = await self._status()
+        await self.ledger_adapter.record_strategy_snapshot(
+            wallet_address=self._get_strategy_wallet_address(),
+            strategy_status=status,
+        )
 
     def register_adapters(self, adapters: list[Any]) -> None:
         """Register adapters for use by the strategy"""
@@ -119,13 +182,15 @@ class Strategy(ABC):
             elif hasattr(adapter, "__class__"):
                 self.adapters[adapter.__class__.__name__] = adapter
 
-    def unwind_on_error(self, func):
+    def unwind_on_error(
+        self, func: Callable[..., Awaitable[StatusTuple]]
+    ) -> Callable[..., Awaitable[StatusTuple]]:
         """
         Decorator to unwind operations on error
         Useful for deposit operations that need cleanup on failure
         """
 
-        async def wrapper(*args, **kwargs):
+        async def wrapper(*args: Any, **kwargs: Any) -> StatusTuple:
             try:
                 return await func(*args, **kwargs)
             except Exception:
@@ -143,21 +208,28 @@ class Strategy(ABC):
                         f"Strategy failed and unwinding also failed. Operation error: {trace}. Unwind error: {trace2}",
                     )
             finally:
-                if hasattr(self, "ledger") and self.ledger:
-                    await self.ledger.save()
+                if hasattr(self, "ledger_adapter") and self.ledger_adapter:
+                    await self.ledger_adapter.save()
 
         return wrapper
 
     @classmethod
     def get_metadata(cls) -> dict[str, Any]:
         """
-        Return metadata about this strategy
-        Can be overridden to provide discovery information
+        Return metadata about this strategy.
+        Can be overridden to provide discovery information.
+
+        Returns:
+            Dictionary containing strategy metadata. The following keys are optional
+            and will be None if not defined on the class:
+            - name: Strategy name
+            - description: Strategy description
+            - summary: Strategy summary
         """
         return {
-            "name": cls.name,
-            "description": cls.description,
-            "summary": cls.summary,
+            "name": getattr(cls, "name", None),
+            "description": getattr(cls, "description", None),
+            "summary": getattr(cls, "summary", None),
         }
 
     async def health_check(self) -> dict[str, Any]:
@@ -176,8 +248,22 @@ class Strategy(ABC):
 
     async def partial_liquidate(self, usd_value: float) -> StatusTuple:
         """
-        Partially liquidate strategy positions by USD value
-        Optional method that can be overridden by subclasses
-        Returns: (success: bool, message: str)
+        Partially liquidate strategy positions by USD value.
+        Optional method that can be overridden by subclasses.
+
+        Args:
+            usd_value: USD value to liquidate (must be positive).
+
+        Returns:
+            Tuple of (success: bool, message: str)
+
+        Raises:
+            ValueError: If usd_value is not positive.
+
+        Note:
+            Base implementation returns failure. Subclasses should override
+            to implement partial liquidation logic.
         """
+        if usd_value <= 0:
+            raise ValueError(f"usd_value must be positive, got {usd_value}")
         return (False, "Partial liquidation not implemented for this strategy")

wayfinder_paths/core/utils/evm_helpers.py

@@ -130,41 +130,43 @@ def resolve_private_key_for_from_address(
     """
     from_addr_norm = (from_address or "").lower()
     main_wallet = config.get("main_wallet")
-    vault_wallet = config.get("vault_wallet")
+    strategy_wallet = config.get("strategy_wallet")
 
     main_pk = None
-    vault_pk = None
+    strategy_pk = None
     try:
         if isinstance(main_wallet, dict):
             main_pk = main_wallet.get("private_key") or main_wallet.get(
                 "private_key_hex"
             )
-        if isinstance(vault_wallet, dict):
-            vault_pk = vault_wallet.get("private_key") or vault_wallet.get(
+        if isinstance(strategy_wallet, dict):
+            strategy_pk = strategy_wallet.get("private_key") or strategy_wallet.get(
                 "private_key_hex"
             )
     except (AttributeError, TypeError) as e:
         logger.debug("Error resolving private keys from wallet config: %s", e)
 
     main_addr = None
-    vault_addr = None
+    strategy_addr = None
     try:
         main_addr = (main_wallet or {}).get("address") or (
             (main_wallet or {}).get("evm") or {}
         ).get("address")
-        vault_addr = (vault_wallet or {}).get("address") or (
-            (vault_wallet or {}).get("evm") or {}
+        strategy_addr = (strategy_wallet or {}).get("address") or (
+            (strategy_wallet or {}).get("evm") or {}
         ).get("address")
     except (AttributeError, TypeError) as e:
         logger.debug("Error resolving addresses from wallet config: %s", e)
 
     if main_addr and from_addr_norm == (main_addr or "").lower():
         return main_pk or os.getenv("PRIVATE_KEY")
-    if vault_addr and from_addr_norm == (vault_addr or "").lower():
-        return vault_pk or os.getenv("PRIVATE_KEY_VAULT") or os.getenv("PRIVATE_KEY")
+    if strategy_addr and from_addr_norm == (strategy_addr or "").lower():
+        return (
+            strategy_pk or os.getenv("PRIVATE_KEY_STRATEGY") or os.getenv("PRIVATE_KEY")
+        )
 
     # Fallback to environment variables
-    return os.getenv("PRIVATE_KEY_VAULT") or os.getenv("PRIVATE_KEY")
+    return os.getenv("PRIVATE_KEY_STRATEGY") or os.getenv("PRIVATE_KEY")
 
 
 async def _get_abi(chain_id: int, address: str) -> str | None:

wayfinder_paths/core/wallets/README.md

@@ -15,7 +15,7 @@ Wayfinder strategies interact with blockchains through a single abstraction: the
 from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
 from wayfinder_paths.core.wallets.WalletManager import WalletManager
 
-config = {...}  # contains main_wallet / vault_wallet entries
+config = {...}  # contains main_wallet / strategy_wallet entries
 wallet_provider = WalletManager.get_provider(config)
 web3_service = DefaultWeb3Service(config, wallet_provider=wallet_provider)
 
@@ -70,14 +70,14 @@ web3_service = DefaultWeb3Service(config, wallet_provider=custom_wallet)
 
 ## Configuration hints
 
-`WalletManager.get_provider` looks for `wallet_type` on the top-level config, `main_wallet`, and `vault_wallet`. Example:
+`WalletManager.get_provider` looks for `wallet_type` on the top-level config, `main_wallet`, and `strategy_wallet`. Example:
 
 ```json
 {
   "strategy": {
     "wallet_type": "local",
     "main_wallet": {"address": "0x...", "wallet_type": "local"},
-    "vault_wallet": {"address": "0x..."}
+    "strategy_wallet": {"address": "0x..."}
   }
 }
 ```

wayfinder_paths/core/wallets/WalletManager.py

@@ -41,9 +41,9 @@ class WalletManager:
                 wallet_type = main_wallet.get("wallet_type")
 
         if not wallet_type:
-            vault_wallet = config.get("vault_wallet")
-            if isinstance(vault_wallet, dict):
-                wallet_type = vault_wallet.get("wallet_type")
+            strategy_wallet = config.get("strategy_wallet")
+            if isinstance(strategy_wallet, dict):
+                wallet_type = strategy_wallet.get("wallet_type")
 
         if not wallet_type or wallet_type == "local":
             logger.debug("Using LocalWalletProvider (default)")

wayfinder_paths/run_strategy.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
 Strategy Runner
-Main entry point for running vault strategies locally
+Main entry point for running strategies locally
 """
 
 import argparse
@@ -12,9 +12,9 @@ from pathlib import Path
 
 from loguru import logger
 
-from wayfinder_paths.core.config import VaultConfig, load_config_from_env
+from wayfinder_paths.core.config import StrategyJobConfig, load_config_from_env
 from wayfinder_paths.core.engine.manifest import load_manifest, validate_manifest
-from wayfinder_paths.core.engine.VaultJob import VaultJob
+from wayfinder_paths.core.engine.StrategyJob import StrategyJob
 
 
 def load_strategy(
@@ -66,7 +66,7 @@ def load_strategy(
 
 def load_config(
     config_path: str | None = None, strategy_name: str | None = None
-) -> VaultConfig:
+) -> StrategyJobConfig:
     """
     Load configuration from file or environment
 
@@ -75,13 +75,13 @@ def load_config(
         strategy_name: Optional strategy name for per-strategy wallet lookup
 
     Returns:
-        VaultConfig instance
+        StrategyJobConfig instance
     """
     if config_path and Path(config_path).exists():
         logger.info(f"Loading config from {config_path}")
         with open(config_path) as f:
             config_data = json.load(f)
-        return VaultConfig.from_dict(config_data, strategy_name=strategy_name)
+        return StrategyJobConfig.from_dict(config_data, strategy_name=strategy_name)
     else:
         logger.info("Loading config from environment variables")
         config = load_config_from_env()
@@ -100,7 +100,7 @@ async def run_strategy(
     **kwargs,
 ):
     """
-    Run a vault strategy
+    Run a strategy
 
     Args:
         strategy_name: Name of the strategy to run
@@ -141,13 +141,13 @@ async def run_strategy(
         logger.debug(f"Config path provided: {config_path}")
         config = load_config(config_path, strategy_name=strategy_name_for_wallet)
         logger.debug(
-            "Loaded config: creds=%s wallets(main=%s vault=%s)",
+            "Loaded config: creds=%s wallets(main=%s strategy=%s)",
             "yes"
             if (config.user.username and config.user.password)
             or config.user.refresh_token
             else "no",
             (config.user.main_wallet_address or "none"),
-            (config.user.vault_wallet_address or "none"),
+            (config.user.strategy_wallet_address or "none"),
         )
 
         # Validate required configuration
@@ -173,11 +173,11 @@ async def run_strategy(
             )
             logger.info(f"Loaded strategy: {strategy.name}")
 
-        # Create vault job
-        vault_job = VaultJob(strategy, config)
+        # Create strategy job
+        strategy_job = StrategyJob(strategy, config)
 
-        # Setup vault job
-        logger.info("Setting up vault job...")
+        # Setup strategy job
+        logger.info("Setting up strategy job...")
         logger.debug(
             "Auth mode: %s",
             "credentials"
@@ -185,12 +185,12 @@ async def run_strategy(
             or config.user.refresh_token
             else "missing",
         )
-        await vault_job.setup()
+        await strategy_job.setup()
 
         # Execute action
         if action == "run":
             logger.info("Starting continuous execution...")
-            await vault_job.run_continuous(interval_seconds=kwargs.get("interval"))
+            await strategy_job.run_continuous(interval_seconds=kwargs.get("interval"))
 
         elif action == "deposit":
             main_token_amount = kwargs.get("main_token_amount")
@@ -207,7 +207,7 @@ async def run_strategy(
             if gas_token_amount is None:
                 gas_token_amount = 0.0
 
-            result = await vault_job.execute_strategy(
+            result = await strategy_job.execute_strategy(
                 "deposit",
                 main_token_amount=main_token_amount,
                 gas_token_amount=gas_token_amount,
@@ -216,22 +216,22 @@ async def run_strategy(
 
         elif action == "withdraw":
             amount = kwargs.get("amount")
-            result = await vault_job.execute_strategy("withdraw", amount=amount)
+            result = await strategy_job.execute_strategy("withdraw", amount=amount)
             logger.info(f"Withdraw result: {result}")
 
         elif action == "status":
-            result = await vault_job.execute_strategy("status")
+            result = await strategy_job.execute_strategy("status")
             logger.info(f"Status: {json.dumps(result, indent=2)}")
 
         elif action == "update":
-            result = await vault_job.execute_strategy("update")
+            result = await strategy_job.execute_strategy("update")
             logger.info(f"Update result: {result}")
 
         elif action == "partial-liquidate":
             usd_value = kwargs.get("amount")
             if not usd_value:
                 raise ValueError("Amount (USD value) required for partial-liquidate")
-            result = await vault_job.execute_strategy(
+            result = await strategy_job.execute_strategy(
                 "partial_liquidate", usd_value=usd_value
             )
             logger.info(f"Partial liquidation result: {result}")
@@ -289,7 +289,9 @@ async def run_strategy(
             duration = kwargs.get("duration") or 300
             logger.info(f"Running script mode for {duration}s...")
             task = asyncio.create_task(
-                vault_job.run_continuous(interval_seconds=kwargs.get("interval") or 60)
+                strategy_job.run_continuous(
+                    interval_seconds=kwargs.get("interval") or 60
+                )
             )
             await asyncio.sleep(duration)
             task.cancel()
@@ -307,13 +309,13 @@ async def run_strategy(
         logger.error(f"Error: {e}")
         sys.exit(1)
     finally:
-        if "vault_job" in locals():
-            await vault_job.stop()
+        if "strategy_job" in locals():
+            await strategy_job.stop()
 
 
 def main():
     """Main entry point"""
-    parser = argparse.ArgumentParser(description="Run vault strategies")
+    parser = argparse.ArgumentParser(description="Run strategy strategies")
     parser.add_argument(
         "strategy",
         nargs="?",

wayfinder_paths/scripts/make_wallets.py

@@ -22,18 +22,18 @@ def write_env(rows: list[dict[str, str]], out_dir: Path) -> None:
             main_w = (
                 label_to_wallet.get("main") or label_to_wallet.get("default") or rows[0]
             )
-            vault_w = label_to_wallet.get("vault")
+            strategy_w = label_to_wallet.get("strategy")
 
             f.write("RPC_URL=https://rpc.ankr.com/eth\n")
             # Back-compat defaults
             f.write(f"PRIVATE_KEY={main_w['private_key_hex']}\n")
             f.write(f"FROM_ADDRESS={main_w['address']}\n")
-            # Explicit main/vault variables
+            # Explicit main/strategy variables
             f.write(f"MAIN_WALLET_ADDRESS={main_w['address']}\n")
-            if vault_w:
-                f.write(f"VAULT_WALLET_ADDRESS={vault_w['address']}\n")
-                # Optional: expose vault private key for local dev only
-                f.write(f"PRIVATE_KEY_VAULT={vault_w['private_key_hex']}\n")
+            if strategy_w:
+                f.write(f"STRATEGY_WALLET_ADDRESS={strategy_w['address']}\n")
+                # Optional: expose strategy private key for local dev only
+                f.write(f"PRIVATE_KEY_STRATEGY={strategy_w['private_key_hex']}\n")
 
 
 def main():

wayfinder_paths/strategies/hyperlend_stable_yield_strategy/README.md

@@ -9,14 +9,14 @@
 
 Allocates USDT0 on HyperEVM across HyperLend stablecoin markets. The strategy:
 
-1. Pulls USDT0 (plus a configurable HYPE gas buffer) from the main wallet into the vault wallet.
+1. Pulls USDT0 (plus a configurable HYPE gas buffer) from the main wallet into the strategy wallet.
 2. Samples HyperLend hourly rate history, applies a bootstrap tournament (horizon = 6h, blocks = 6h, 4,000 trials, 7-day half-life) to estimate which stablecoin should outperform.
 3. Tops up the small HYPE gas buffer if needed, swaps USDT0 into the target stablecoin, and supplies it to HyperLend.
 4. Enforces a hysteresis rotation policy so minor APY noise does not churn capital.
 
 ## Policy
 
-The manifest policy simply locks transactions to the vault wallet ID:
+The manifest policy simply locks transactions to the strategy wallet ID:
 
 ```
 (wallet.id == 'FORMAT_WALLET_ID')
@@ -46,14 +46,14 @@ The manifest policy simply locks transactions to the vault wallet ID:
 ### Deposit
 
 - Validates USDT0 and HYPE balances in the main wallet.
-- Transfers HYPE into the vault wallet when a top-up is required, ensuring the vault maintains the configured buffer.
-- Moves USDT0 from the main wallet into the vault wallet through `BalanceAdapter.move_from_main_wallet_to_vault_wallet`.
+- Transfers HYPE into the strategy wallet when a top-up is required, ensuring the strategy maintains the configured buffer.
+- Moves USDT0 from the main wallet into the strategy wallet through `BalanceAdapter.move_from_main_wallet_to_strategy_wallet`.
 - Clears cached asset snapshots so the next update starts from on-chain reality.
 
 ### Update
 
 - Refreshes HyperLend asset snapshots, calculates tournament winners, and filters markets that respect supply caps + buffer requirements.
-- Reads rotation history through `LedgerAdapter.get_vault_latest_transactions` to enforce the cooldown (unless the short-circuit policy is triggered).
+- Reads rotation history through `LedgerAdapter.get_strategy_latest_transactions` to enforce the cooldown (unless the short-circuit policy is triggered).
 - If a new asset wins the tournament and passes hysteresis checks, BRAP quotes are fetched and executed to rotate into the better performer.
 - Sweeps residual stable balances, lends via `HyperlendAdapter`, and records ledger operations.
 
@@ -94,7 +94,7 @@ poetry run python wayfinder_paths/run_strategy.py hyperlend_stable_yield_strateg
 Use the manifest directly if you prefer:
 
 ```bash
-poetry run python wayfinder_paths/run_strategy.py --manifest wayfinder_paths/vaults/strategies/hyperlend_stable_yield_strategy/manifest.yaml --action status --config $(pwd)/config.json
+poetry run python wayfinder_paths/run_strategy.py --manifest wayfinder_paths/strategies/hyperlend_stable_yield_strategy/manifest.yaml --action status --config $(pwd)/config.json
 ```
 
 Wallet addresses/labels are auto-resolved from `wallets.json`. Set `NETWORK=testnet` in your config to run the orchestration without touching live HyperEVM endpoints.