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

wayfinder_paths/core/engine/StrategyJob.py

@@ -16,15 +16,6 @@ class StrategyJob:
         clients: dict[str, Any] | None = None,
         skip_auth: bool = False,
     ):
-        """
-        Initialize a StrategyJob.
-
-        Args:
-            strategy: The strategy to execute.
-            config: Strategy job configuration.
-            clients: Optional dict of pre-instantiated clients to inject directly.
-            skip_auth: If True, skips authentication (for SDK usage).
-        """
         self.strategy = strategy
         self.config = config
 
@@ -32,18 +23,12 @@ class StrategyJob:
         self.clients = ClientManager(clients=clients, skip_auth=skip_auth)
 
     def _setup_strategy(self):
-        """Setup the strategy instance"""
         if not self.strategy:
             raise ValueError("No strategy provided to StrategyJob")
 
         self.strategy.log = self.log
 
     async def setup(self):
-        """
-        Initialize the strategy job and strategy.
-
-        Sets up authentication and initializes the strategy with merged configuration.
-        """
         self._setup_strategy()
 
         # Ensure API key is set for API calls
@@ -62,7 +47,6 @@ class StrategyJob:
         await self.strategy.setup()
 
     async def execute_strategy(self, action: str, **kwargs) -> dict[str, Any]:
-        """Execute a strategy action (deposit, withdraw, update, status, exit, partial_liquidate)"""
         try:
             if action == "deposit":
                 result = await self.strategy.deposit(**kwargs)
@@ -96,7 +80,6 @@ class StrategyJob:
             return {"success": False, "error": str(e)}
 
     async def run_continuous(self, interval_seconds: int | None = None):
-        """Run the strategy continuously at specified intervals"""
         interval = interval_seconds or self.config.system.update_interval
         logger.info(
             f"Starting continuous execution for strategy: {self.strategy.name} with interval {interval}s"
@@ -115,27 +98,12 @@ class StrategyJob:
                 await asyncio.sleep(interval)
 
     async def log(self, msg: str):
-        """Log messages for the job"""
         logger.info(f"Job {self.job_id}: {msg}")
 
     async def handle_error(self, error_data: dict[str, Any]) -> None:
-        """
-        Handle errors that occur during strategy execution.
-
-        Args:
-            error_data: Dictionary containing error information. Expected keys:
-                - error: Error message or exception string
-                - action: Strategy action that failed (e.g., "deposit", "update")
-
-        Note:
-            Base implementation is a no-op. Subclasses or external systems
-            can override this method to implement custom error handling,
-            logging, alerting, or recovery logic.
-        """
         pass
 
     async def stop(self):
-        """Stop the strategy job and cleanup"""
         if hasattr(self.strategy, "stop"):
             await self.strategy.stop()
 

wayfinder_paths/core/strategies/Strategy.py

@@ -23,8 +23,6 @@ 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
@@ -32,8 +30,6 @@ class WalletConfig(TypedDict, total=False):
 
 
 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
@@ -68,19 +64,15 @@ class Strategy(ABC):
         self.strategy_wallet_signing_callback = strategy_wallet_signing_callback
 
     async def setup(self) -> None:
-        """Initialize strategy-specific setup after construction"""
         pass
 
     async def log(self, msg: str) -> None:
-        """Log messages - can be overridden by subclasses"""
         self.logger.info(msg)
 
     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")
@@ -90,7 +82,6 @@ class Strategy(ABC):
         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")
@@ -101,37 +92,9 @@ class Strategy(ABC):
 
     @abstractmethod
     async def deposit(self, **kwargs) -> StatusTuple:
-        """
-        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.
-
-        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_adapter") and self.ledger_adapter:
             while self.ledger_adapter.positions.operations:
                 node = self.ledger_adapter.positions.operations[-1]
@@ -146,46 +109,21 @@ class Strategy(ABC):
 
     @abstractmethod
     async def update(self) -> StatusTuple:
-        """
-        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
 
     @staticmethod
     async def policies() -> list[str]:
-        """Return policy strings for this strategy."""
         raise NotImplementedError
 
     @abstractmethod
     async def _status(self) -> StatusDict:
-        """
-        Return status payload. Subclasses should implement this.
-        Should include keys (portfolio_value, net_deposit, strategy_status).
-        Backward-compatible keys (active_amount, total_earned) may also be included.
-        """
         pass
 
     async def status(self) -> StatusDict:
-        """
-        Wrapper to compute and return strategy status and record a snapshot.
-        Here we simply delegate to _status for compatibility.
-        """
-
         status = await self._status()
         await self.ledger_adapter.record_strategy_snapshot(
             wallet_address=self._get_strategy_wallet_address(),
@@ -195,7 +133,6 @@ class Strategy(ABC):
         return status
 
     def register_adapters(self, adapters: list[Any]) -> None:
-        """Register adapters for use by the strategy"""
         self.adapters = {}
         for adapter in adapters:
             if hasattr(adapter, "adapter_type"):
@@ -206,11 +143,6 @@ class Strategy(ABC):
     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: Any, **kwargs: Any) -> StatusTuple:
             try:
                 return await func(*args, **kwargs)
@@ -236,17 +168,6 @@ class Strategy(ABC):
 
     @classmethod
     def get_metadata(cls) -> dict[str, Any]:
-        """
-        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": getattr(cls, "name", None),
             "description": getattr(cls, "description", None),
@@ -254,9 +175,6 @@ class Strategy(ABC):
         }
 
     async def health_check(self) -> dict[str, Any]:
-        """
-        Check strategy health and dependencies
-        """
         health = {"status": "healthy", "strategy": self.name, "adapters": {}}
 
         for name, adapter in self.adapters.items():
@@ -270,23 +188,6 @@ class Strategy(ABC):
     async def partial_liquidate(
         self, usd_value: float
     ) -> tuple[bool, LiquidationResult]:
-        """
-        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/strategies/__init__.py

@@ -1,5 +1,3 @@
-"""Core Strategy Module - SDK surface re-export"""
-
 from .base import StatusDict, StatusTuple, Strategy
 
 __all__ = ["Strategy", "StatusDict", "StatusTuple"]

wayfinder_paths/core/utils/__init__.py

@@ -1 +0,0 @@
-"""Utility helpers for local functionality not tied to external APIs."""

wayfinder_paths/core/utils/erc20_service.py

@@ -49,7 +49,6 @@ async def build_approve_transaction(
     spender_address: str,
     amount: int,
 ) -> dict:
-    """Build an ERC20 approve transaction."""
     async with web3_from_chain_id(chain_id) as web3:
         contract = web3.eth.contract(
             address=web3.to_checksum_address(token_address), abi=ERC20_ABI

wayfinder_paths/core/utils/evm_helpers.py

@@ -1,10 +1,3 @@
-"""
-EVM helper utilities for common blockchain operations.
-
-This module provides reusable functions for EVM-related operations that are shared
-across multiple adapters.
-"""
-
 import json
 import os
 from typing import Any
@@ -15,31 +8,12 @@ from wayfinder_paths.core.constants.base import CHAIN_CODE_TO_ID
 
 
 def chain_code_to_chain_id(chain_code: str | None) -> int | None:
-    """
-    Convert chain code to chain ID.
-
-    Args:
-        chain_code: Chain code string (e.g., "ethereum", "base")
-
-    Returns:
-        Chain ID as integer, or None if not found
-    """
     if not chain_code:
         return None
     return CHAIN_CODE_TO_ID.get(chain_code.lower())
 
 
 def resolve_chain_id(token_info: dict[str, Any], logger_instance=None) -> int | None:
-    """
-    Extract chain ID from token_info dictionary.
-
-    Args:
-        token_info: Dictionary containing token information with 'chain' key
-        logger_instance: Optional logger instance for debug messages
-
-    Returns:
-        Chain ID as integer, or None if not found
-    """
     log = logger_instance or logger
     chain_meta = token_info.get("chain") or {}
     chain_id = chain_meta.get("id")
@@ -56,20 +30,6 @@ def resolve_rpc_url(
     config: dict[str, Any],
     explicit_rpc_url: str | None = None,
 ) -> str:
-    """
-    Resolve RPC URL from config.
-
-    Args:
-        chain_id: Chain ID to look up RPC URL for
-        config: Configuration dictionary
-        explicit_rpc_url: Explicitly provided RPC URL (takes precedence)
-
-    Returns:
-        RPC URL string
-
-    Raises:
-        ValueError: If RPC URL cannot be resolved
-    """
     if explicit_rpc_url:
         return explicit_rpc_url
     strategy_cfg = config.get("strategy") or {}
@@ -91,16 +51,6 @@ def resolve_rpc_url(
 def resolve_private_key_for_from_address(
     from_address: str, config: dict[str, Any]
 ) -> str | None:
-    """
-    Resolve private key for the given address from config.
-
-    Args:
-        from_address: Address to resolve private key for
-        config: Configuration dictionary containing wallet information
-
-    Returns:
-        Private key string, or None if not found
-    """
     from_addr_norm = (from_address or "").lower()
     main_wallet = config.get("main_wallet")
     strategy_wallet = config.get("strategy_wallet")

wayfinder_paths/core/utils/transaction.py

@@ -91,7 +91,6 @@ async def gas_price_transaction(
             base_fee = max(base_fees)
             priority_fee = max(priority_fees)
 
-            # The next block can grow base fee by up to 12.5%, we give a flew blocks of landing room. log_1.125(2) ~ 6 blocks of landing room. GPT says this is also what Metamask does.
             max_base_fee_growth_multiplier = 2
             transaction["maxFeePerGas"] = int(
                 base_fee * max_base_fee_growth_multiplier

wayfinder_paths/run_strategy.py

@@ -1,8 +1,4 @@
 #!/usr/bin/env python3
-"""
-Strategy Runner
-Main entry point for running strategies locally
-"""
 
 import argparse
 import asyncio
@@ -23,17 +19,6 @@ def load_strategy(
     *,
     config: StrategyJobConfig,
 ):
-    """
-    Dynamically load a strategy by name
-
-    Args:
-        strategy_name: Name of the strategy to load (directory name in strategies/)
-        config: StrategyJobConfig instance containing user and strategy configuration
-
-    Returns:
-        Strategy instance
-    """
-    # Build the expected module path from strategy name
     strategies_dir = Path(__file__).parent / "strategies"
     strategy_dir = strategies_dir / strategy_name
 
@@ -49,7 +34,6 @@ def load_strategy(
             f"Unknown strategy: {strategy_name}. Available strategies: {available_str}"
         )
 
-    # Import strategy module and find Strategy class
     module_path = f"strategies.{strategy_name}.strategy"
     module = __import__(module_path, fromlist=[""])
 
@@ -70,7 +54,6 @@ def load_strategy(
     if strategy_class is None:
         raise ValueError(f"No Strategy class found in {module_path}")
 
-    # Get wallet addresses from strategy_config (enriched from wallets array in config.json)
     main_wallet = config.strategy_config.get("main_wallet") or {}
     strategy_wallet = config.strategy_config.get("strategy_wallet") or {}
     main_wallet_address = main_wallet.get("address")
@@ -103,19 +86,6 @@ def load_strategy(
 def load_config(
     config_path: str | None = None, strategy_name: str | None = None
 ) -> StrategyJobConfig:
-    """
-    Load configuration from config.json file
-
-    Args:
-        config_path: Path to config file (defaults to "config.json")
-        strategy_name: Optional strategy name for per-strategy wallet lookup
-
-    Returns:
-        StrategyJobConfig instance
-
-    Raises:
-        FileNotFoundError: If config file does not exist
-    """
     # Default to config.json if not provided
     if not config_path:
         config_path = "config.json"
@@ -144,22 +114,12 @@ async def run_strategy(
     action: str = "run",
     **kwargs,
 ):
-    """
-    Run a strategy
-
-    Args:
-        strategy_name: Name of the strategy to run
-        config_path: Optional path to config file
-        action: Action to perform (run, deposit, withdraw, status)
-        **kwargs: Additional arguments for the action
-    """
     try:
         if not strategy_name:
             raise ValueError("strategy_name is required")
 
         logger.debug(f"Loading strategy by name: {strategy_name}")
 
-        # Load configuration with strategy name for wallet lookup
         logger.debug(f"Config path provided: {config_path}")
         config = load_config(config_path, strategy_name=strategy_name)
         main_wallet_cfg = config.strategy_config.get("main_wallet") or {}
@@ -170,20 +130,16 @@ async def run_strategy(
             strategy_wallet_cfg.get("address") or "none",
         )
 
-        # Validate required configuration
         # Authentication is via system.api_key in config.json
 
-        # Load strategy with the enriched config
         strategy = load_strategy(
             strategy_name,
             config=config,
         )
         logger.info(f"Loaded strategy: {strategy.name}")
 
-        # Create strategy job
         strategy_job = StrategyJob(strategy, config)
 
-        # Setup strategy job
         logger.info("Setting up strategy job...")
         logger.debug("Auth mode: API key (from system.api_key)")
         await strategy_job.setup()
@@ -260,7 +216,6 @@ async def run_strategy(
                     seen.add(p)
                     deduped.append(p)
 
-            # Get wallet_id from CLI arg, config, or leave as None
             wallet_id = kwargs.get("wallet_id")
             if not wallet_id:
                 wallet_id = config.strategy_config.get("wallet_id")
@@ -309,7 +264,6 @@ async def run_strategy(
 
 
 def main():
-    """Main entry point"""
     parser = argparse.ArgumentParser(description="Run strategy strategies")
     parser.add_argument(
         "strategy",

wayfinder_paths/scripts/create_strategy.py

@@ -1,12 +1,4 @@
 #!/usr/bin/env python3
-"""
-Create a new strategy from template and generate a dedicated wallet for it.
-
-This script:
-1. Copies the strategy template to a new directory
-2. Generates a wallet with label matching the strategy name
-3. Updates the strategy files with the correct names
-"""
 
 import argparse
 import re
@@ -17,18 +9,14 @@ from wayfinder_paths.core.utils.wallets import make_random_wallet, write_wallet_
 
 
 def sanitize_name(name: str) -> str:
-    """Convert a strategy name to a valid directory/identifier name."""
     # Replace spaces and special chars with underscores, lowercase
     name = re.sub(r"[^a-zA-Z0-9_-]", "_", name)
-    # Remove multiple underscores
     name = re.sub(r"_+", "_", name)
-    # Remove leading/trailing underscores
     name = name.strip("_")
     return name.lower()
 
 
 def update_strategy_file(strategy_path: Path, class_name: str) -> None:
-    """Update strategy.py with new class name."""
     content = strategy_path.read_text()
     # Replace MyStrategy with the new class name
     content = content.replace("MyStrategy", class_name)
@@ -76,18 +64,15 @@ def main():
     dir_name = sanitize_name(args.name)
     strategy_dir = args.strategies_dir / dir_name
 
-    # Check if directory already exists
     if strategy_dir.exists() and not args.override:
         raise SystemExit(
             f"Strategy directory already exists: {strategy_dir}\n"
             "Use --override to replace it"
         )
 
-    # Check template exists
     if not args.template_dir.exists():
         raise SystemExit(f"Template directory not found: {args.template_dir}")
 
-    # Create strategy directory
     if strategy_dir.exists():
         print(f"Removing existing directory: {strategy_dir}")
         shutil.rmtree(strategy_dir)
@@ -109,12 +94,10 @@ def main():
             print(f"  Copied {filename}")
 
     # Generate class name from strategy name
-    # Convert "my_awesome_strategy" -> "MyAwesomeStrategy"
     class_name = "".join(word.capitalize() for word in dir_name.split("_"))
     if not class_name.endswith("Strategy"):
         class_name += "Strategy"
 
-    # Update strategy.py with new class name
     strategy_file = strategy_dir / "strategy.py"
     if strategy_file.exists():
         update_strategy_file(strategy_file, class_name)

wayfinder_paths/scripts/make_wallets.py

@@ -54,7 +54,6 @@ def main():
 
     args.out_dir.mkdir(parents=True, exist_ok=True)
 
-    # Load existing wallets
     existing = load_wallets(args.out_dir, "config.json")
     has_main = any(w.get("label") in ("main", "default") for w in existing)
 
@@ -67,7 +66,6 @@ def main():
         if any(w.get("label") == args.label for w in existing):
             print(f"Wallet with label '{args.label}' already exists, skipping...")
         else:
-            # Create wallet with specified label
             w = make_random_wallet()
             w["label"] = args.label
             rows.append(w)
@@ -96,9 +94,8 @@ def main():
                     ks_path.write_text(json.dumps(ks))
                 index += 1
     else:
-        # Create wallets with auto-generated labels: first one is "main" if main doesn't exist, others are "temporary_N"
         if args.n == 0:
-            args.n = 1  # Default to 1 wallet if neither -n nor --label specified
+            args.n = 1
 
         # Find next temporary number
         existing_labels = {