wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/core/constants/hyperlend_abi.py

@@ -0,0 +1,152 @@
+"""
+HyperLend ABI constants for smart contract interactions.
+
+This module contains ABI definitions for HyperLend protocol contracts,
+including Pool, Protocol Data Provider, Wrapped Token Gateway, and WETH contracts.
+"""
+
+# Minimal Pool ABI for supply and deposit operations
+POOL_ABI = [
+    {
+        "name": "supply",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+            {"name": "onBehalfOf", "type": "address"},
+            {"name": "referralCode", "type": "uint16"},
+        ],
+        "outputs": [],
+    },
+    {
+        "name": "deposit",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+            {"name": "onBehalfOf", "type": "address"},
+            {"name": "referralCode", "type": "uint16"},
+        ],
+        "outputs": [],
+    },
+    {
+        "name": "withdraw",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+            {"name": "to", "type": "address"},
+        ],
+        "outputs": [],
+    },
+]
+
+# Protocol Data Provider ABI for reserve token addresses and user data
+PROTOCOL_DATA_PROVIDER_ABI = [
+    {
+        "type": "function",
+        "stateMutability": "view",
+        "name": "getReserveTokensAddresses",
+        "inputs": [{"name": "asset", "type": "address"}],
+        "outputs": [
+            {"name": "aTokenAddress", "type": "address"},
+            {"name": "stableDebtTokenAddress", "type": "address"},
+            {"name": "variableDebtTokenAddress", "type": "address"},
+        ],
+    },
+    {
+        "type": "function",
+        "stateMutability": "view",
+        "name": "getUserReserveData",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "user", "type": "address"},
+        ],
+        "outputs": [
+            {"name": "currentATokenBalance", "type": "uint256"},
+            {"name": "currentStableDebt", "type": "uint256"},
+            {"name": "currentVariableDebt", "type": "uint256"},
+            {"name": "liquidityRate", "type": "uint256"},
+            {"name": "stableBorrowRate", "type": "uint256"},
+            {"name": "variableBorrowRate", "type": "uint256"},
+            {"name": "liquidityIndex", "type": "uint256"},
+            {"name": "healthFactor", "type": "uint256"},
+        ],
+    },
+]
+
+# Wrapped Token Gateway ABI for native token operations
+WRAPPED_TOKEN_GATEWAY_ABI = [
+    {
+        "type": "function",
+        "stateMutability": "view",
+        "name": "getWETHAddress",
+        "inputs": [],
+        "outputs": [{"type": "address"}],
+    },
+    {
+        "type": "function",
+        "stateMutability": "payable",
+        "name": "depositETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "address"},
+            {"type": "uint16"},
+        ],
+        "outputs": [],
+    },
+    {
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "name": "withdrawETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "uint256"},
+            {"type": "address"},
+        ],
+        "outputs": [],
+    },
+    {
+        "type": "function",
+        "stateMutability": "payable",
+        "name": "repayETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "uint256"},
+            {"type": "address"},
+        ],
+        "outputs": [],
+    },
+    {
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "name": "borrowETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "uint256"},
+            {"type": "uint16"},
+        ],
+        "outputs": [],
+    },
+]
+
+# WETH ABI for native token wrapping
+WETH_ABI = [
+    {
+        "inputs": [],
+        "name": "deposit",
+        "outputs": [],
+        "stateMutability": "payable",
+        "type": "function",
+    },
+    {
+        "inputs": [{"name": "wad", "type": "uint256"}],
+        "name": "withdraw",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function",
+    },
+]

wayfinder_paths/core/engine/VaultJob.py

@@ -0,0 +1,182 @@
+import asyncio
+import os
+from typing import Any
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.ClientManager import ClientManager
+from wayfinder_paths.core.config import VaultConfig
+from wayfinder_paths.core.strategies.Strategy import Strategy
+
+
+class VaultJob:
+    def __init__(
+        self,
+        strategy: Strategy,
+        config: VaultConfig,
+        clients: dict[str, Any] | None = None,
+        skip_auth: bool = False,
+        api_key: str | None = None,
+    ):
+        """
+        Initialize a VaultJob.
+
+        Args:
+            strategy: The strategy to execute.
+            config: Vault configuration.
+            clients: Optional dict of pre-instantiated clients to inject directly.
+            skip_auth: If True, skips authentication (for SDK usage).
+            api_key: Optional API key for service account authentication.
+                If provided, will be passed to ClientManager and strategy.
+        """
+        self.strategy = strategy
+        self.config = config
+
+        self.job_id = strategy.name or "unknown"
+        self.clients = ClientManager(
+            clients=clients, skip_auth=skip_auth, api_key=api_key
+        )
+
+    def _setup_strategy(self):
+        """Setup the strategy instance"""
+        if not self.strategy:
+            raise ValueError("No strategy provided to VaultJob")
+
+        self.strategy.log = self.log
+
+    def _is_using_api_key(self) -> bool:
+        """Check if API key authentication is being used."""
+        if self.clients._api_key:
+            return True
+
+        if self.clients.auth:
+            try:
+                creds = self.clients.auth._load_config_credentials()
+                if creds.get("api_key"):
+                    return True
+                if os.getenv("WAYFINDER_API_KEY"):
+                    return True
+            except Exception:
+                pass
+
+        return False
+
+    async def setup(self):
+        """
+        Initialize the vault job and strategy.
+
+        Sets up authentication and initializes the strategy with merged configuration.
+        """
+        self._setup_strategy()
+
+        # Ensure auth token is set for API calls
+        if not self.clients._skip_auth:
+            is_api_key_auth = self._is_using_api_key()
+
+            if is_api_key_auth:
+                logger.debug("Using API key authentication")
+                if self.clients.auth:
+                    await self.clients.auth._ensure_bearer_token()
+            else:
+                # Try to ensure bearer token is set, authenticate if needed
+                try:
+                    if self.clients.auth:
+                        await self.clients.auth._ensure_bearer_token()
+                except (PermissionError, Exception) as e:
+                    if not isinstance(e, PermissionError):
+                        logger.warning(
+                            f"Authentication failed: {e}, trying OAuth fallback"
+                        )
+                    username = self.config.user.username
+                    password = self.config.user.password
+                    refresh_token = self.config.user.refresh_token
+                    if refresh_token or (username and password):
+                        await self.clients.authenticate(
+                            username=username,
+                            password=password,
+                            refresh_token=refresh_token,
+                        )
+                    else:
+                        raise ValueError(
+                            "Authentication required: provide api_key parameter for service account auth, "
+                            "or username+password/refresh_token in config.json for personal access"
+                        ) from e
+
+        existing_cfg = dict(getattr(self.strategy, "config", {}) or {})
+        vault_cfg = dict(self.config.strategy_config or {})
+        merged_cfg = {**vault_cfg, **existing_cfg}
+        self.strategy.config = merged_cfg
+        self.strategy.clients = self.clients
+        await self.strategy.setup()
+
+    async def execute_strategy(self, action: str, **kwargs) -> dict[str, Any]:
+        """Execute a strategy action (deposit, withdraw, update, status, partial_liquidate)"""
+        try:
+            if action == "deposit":
+                result = await self.strategy.deposit(**kwargs)
+            elif action == "withdraw":
+                result = await self.strategy.withdraw(**kwargs)
+            elif action == "update":
+                result = await self.strategy.update()
+            elif action == "status":
+                result = await self.strategy.status()
+            elif action == "partial_liquidate":
+                usd_value = kwargs.get("usd_value")
+                if usd_value is None:
+                    result = (
+                        False,
+                        "usd_value parameter is required for partial_liquidate",
+                    )
+                else:
+                    result = await self.strategy.partial_liquidate(usd_value)
+            else:
+                result = {"success": False, "message": f"Unknown action: {action}"}
+
+            await self.log(f"Strategy action '{action}' completed: {result}")
+            return result
+
+        except Exception as e:
+            error_msg = f"Strategy action '{action}' failed: {str(e)}"
+            await self.log(error_msg)
+            await self.handle_error({"error": str(e), "action": action})
+            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"
+        )
+
+        while True:
+            try:
+                await self.execute_strategy("update")
+                await asyncio.sleep(interval)
+
+            except asyncio.CancelledError:
+                logger.info("Continuous execution cancelled")
+                break
+            except Exception as e:
+                logger.error(f"Error in continuous execution: {str(e)}")
+                await asyncio.sleep(interval)
+
+    async def message_user(self, msg):
+        if msg is not None:
+            logger.info(f"notifying user: {msg}")
+            await self.clients.chat.send_msg_to_owner(
+                msg, "agent", self.clients.chat.session_id
+            )
+
+    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):
+        pass
+
+    async def stop(self):
+        """Stop the vault job and cleanup"""
+        if hasattr(self.strategy, "stop"):
+            await self.strategy.stop()
+
+        logger.info(f"Vault job {self.job_id} stopped")

wayfinder_paths/core/engine/__init__.py

@@ -0,0 +1,5 @@
+"""Core Engine Module"""
+
+from .VaultJob import VaultJob
+
+__all__ = ["VaultJob", "GLOBAL_IMPORTS"]

wayfinder_paths/core/engine/manifest.py

@@ -0,0 +1,97 @@
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, validator
+
+
+class AdapterRequirement(BaseModel):
+    name: str = Field(
+        ..., description="Adapter symbolic name (e.g., BALANCE, HYPERLIQUID)"
+    )
+    capabilities: list[str] = Field(default_factory=list)
+
+
+class AdapterManifest(BaseModel):
+    schema_version: str = Field(default="0.1")
+    entrypoint: str
+    capabilities: list[str] = Field(default_factory=list)
+    dependencies: list[str] = Field(default_factory=list)
+
+    @validator("entrypoint")
+    def validate_entrypoint(cls, v: str) -> str:
+        if "." not in v:
+            raise ValueError("entrypoint must be a full import path")
+        return v
+
+    @validator("capabilities")
+    def validate_capabilities(cls, v: list[str]) -> list[str]:
+        if not v:
+            raise ValueError("capabilities cannot be empty")
+        return v
+
+    @validator("dependencies")
+    def validate_dependencies(cls, v: list[str]) -> list[str]:
+        if not v:
+            raise ValueError("dependencies cannot be empty")
+        return v
+
+
+class StrategyManifest(BaseModel):
+    schema_version: str = Field(default="0.1")
+    entrypoint: str = Field(
+        ...,
+        description="Python path to class, e.g. vaults.strategies.funding_rate_strategy.FundingRateStrategy",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Unique name identifier for this strategy instance. Used to look up dedicated wallet in wallets.json by label.",
+    )
+    permissions: dict[str, Any] = Field(default_factory=dict)
+    adapters: list[AdapterRequirement] = Field(default_factory=list)
+
+    @validator("entrypoint")
+    def validate_entrypoint(cls, v: str) -> str:
+        if "." not in v:
+            raise ValueError(
+                "entrypoint must be a full import path to a Strategy class"
+            )
+        return v
+
+    @validator("permissions")
+    def validate_permissions(cls, v: dict) -> dict:
+        if "policy" not in v:
+            raise ValueError("permissions.policy is required")
+        if not v["policy"]:
+            raise ValueError("permissions.policy cannot be empty")
+        return v
+
+    @validator("adapters")
+    def validate_adapters(cls, v: list) -> list:
+        if not v:
+            raise ValueError("adapters cannot be empty")
+        return v
+
+
+def load_adapter_manifest(path: str) -> AdapterManifest:
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return AdapterManifest(**data)
+
+
+def load_strategy_manifest(path: str) -> StrategyManifest:
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return StrategyManifest(**data)
+
+
+def load_manifest(path: str) -> StrategyManifest:
+    """Legacy function for backward compatibility."""
+    return load_strategy_manifest(path)
+
+
+def validate_manifest(manifest: StrategyManifest) -> None:
+    # Simple v0.1 rules: require at least one adapter and permissions.policy
+    if not manifest.adapters:
+        raise ValueError("Manifest must declare at least one adapter")
+    if "policy" not in manifest.permissions:
+        raise ValueError("Manifest.permissions must include 'policy'")

wayfinder_paths/core/services/base.py

@@ -0,0 +1,177 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from web3 import AsyncWeb3
+
+
+class TokenTxn(ABC):
+    """Interface describing high-level EVM transaction builders."""
+
+    @abstractmethod
+    async def build_send(
+        self,
+        *,
+        token_id: str,
+        amount: float,
+        from_address: str,
+        to_address: str,
+        token_info: dict[str, Any] | None = None,
+    ) -> tuple[bool, dict[str, Any] | str]:
+        """Build raw transaction data for sending tokens."""
+
+    @abstractmethod
+    def build_erc20_approve(
+        self,
+        *,
+        chain_id: int,
+        token_address: str,
+        from_address: str,
+        spender: str,
+        amount: int,
+    ) -> tuple[bool, dict[str, Any] | str]:
+        """Build raw ERC20 approve transaction data."""
+
+    @abstractmethod
+    async def read_erc20_allowance(
+        self, chain: Any, token_address: str, from_address: str, spender_address: str
+    ) -> dict[str, Any]:
+        """Read allowance granted for a spender."""
+
+
+class EvmTxn(ABC):
+    """
+    Abstract base class for wallet providers.
+
+    This interface abstracts all blockchain interactions needed by adapters so the
+    rest of the vaults codebase never touches raw web3 primitives. Implementations
+    are responsible for RPC resolution, gas estimation, signing, broadcasting and
+    transaction confirmations.
+    """
+
+    @abstractmethod
+    async def get_balance(
+        self,
+        address: str,
+        token_address: str | None,
+        chain_id: int,
+    ) -> tuple[bool, Any]:
+        """
+        Get balance for an address.
+
+        Args:
+            address: Address to query balance for
+            token_address: ERC20 token address, or None for native token
+            chain_id: Chain ID
+
+        Returns:
+            Tuple of (success, balance_integer_or_error_message)
+        """
+        pass
+
+    @abstractmethod
+    async def approve_token(
+        self,
+        token_address: str,
+        spender: str,
+        amount: int,
+        from_address: str,
+        chain_id: int,
+        wait_for_receipt: bool = True,
+        timeout: int = 120,
+    ) -> tuple[bool, Any]:
+        """
+        Approve a spender to spend tokens on behalf of from_address.
+
+        Args:
+            token_address: ERC20 token contract address
+            spender: Address being approved to spend tokens
+            amount: Amount to approve (in token units, not human-readable)
+            from_address: Address approving the tokens
+            chain_id: Chain ID
+            wait_for_receipt: Whether to wait for the transaction receipt
+            timeout: Receipt timeout in seconds
+
+        Returns:
+            Tuple of (success, transaction_result_dict_or_error_message)
+            Transaction result should include 'tx_hash' and optionally 'receipt'
+        """
+        pass
+
+    @abstractmethod
+    async def broadcast_transaction(
+        self,
+        transaction: dict[str, Any],
+        *,
+        wait_for_receipt: bool = True,
+        timeout: int = 120,
+    ) -> tuple[bool, Any]:
+        """
+        Sign and broadcast a transaction dict.
+
+        Providers must handle gas estimation, gas pricing, nonce selection, signing
+        and submission internally so callers can simply pass the transaction data.
+
+        Args:
+            transaction: Dictionary describing the transaction (to, data, value, etc.)
+            wait_for_receipt: Whether to wait for the transaction receipt
+            timeout: Receipt timeout in seconds
+        """
+        pass
+
+    @abstractmethod
+    async def transaction_succeeded(
+        self, tx_hash: str, chain_id: int, timeout: int = 120
+    ) -> bool:
+        """
+        Check if a transaction hash succeeded on-chain.
+
+        Args:
+            tx_hash: Transaction hash to inspect
+            chain_id: Chain ID where the transaction was broadcast
+            timeout: Maximum seconds to wait for a receipt
+
+        Returns:
+            Boolean indicating whether the transaction completed successfully.
+        """
+        pass
+
+    @abstractmethod
+    def get_web3(self, chain_id: int) -> AsyncWeb3:
+        """
+        Return an AsyncWeb3 instance configured for the given chain.
+
+        Implementations may create new instances per call or pull from an internal
+        cache, but they must document whether the caller is responsible for closing
+        the underlying HTTP session.
+        """
+        pass
+
+
+class Web3Service(ABC):
+    """Facade that exposes low-level wallet access and higher-level EVM helpers."""
+
+    @property
+    @abstractmethod
+    def evm_transactions(self) -> EvmTxn:
+        """Return the wallet provider responsible for RPC, signing, and broadcasting."""
+
+    @property
+    @abstractmethod
+    def token_transactions(self) -> TokenTxn:
+        """Returns TokenTxn, for sends and swaps of any token"""
+
+    async def broadcast_transaction(
+        self,
+        transaction: dict[str, Any],
+        *,
+        wait_for_receipt: bool = True,
+        timeout: int = 120,
+    ) -> tuple[bool, Any]:
+        """Proxy convenience wrapper to underlying wallet provider."""
+        return await self.evm_transactions.broadcast_transaction(
+            transaction, wait_for_receipt=wait_for_receipt, timeout=timeout
+        )
+
+    def get_web3(self, chain_id: int):
+        """Expose underlying web3 provider for ABI encoding helpers."""
+        return self.evm_transactions.get_web3(chain_id)