wayfinder-paths 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

wayfinder_paths/core/constants/__init__.py

@@ -1,17 +1,88 @@
-from .base import (
-    CHAIN_CODE_TO_ID,
+from wayfinder_paths.core.constants.base import (
+    ADAPTER_BALANCE,
+    ADAPTER_BRAP,
+    ADAPTER_HYPERLEND,
+    ADAPTER_HYPERLIQUID,
+    ADAPTER_LEDGER,
+    ADAPTER_MOONWELL,
+    ADAPTER_POOL,
+    ADAPTER_TOKEN,
+    DEFAULT_HTTP_TIMEOUT,
     DEFAULT_NATIVE_GAS_UNITS,
+    DEFAULT_PAGINATION_LIMIT,
     DEFAULT_SLIPPAGE,
     GAS_BUFFER_MULTIPLIER,
+    MANTISSA,
+    MAX_UINT256,
     ONE_GWEI,
+    SECONDS_PER_YEAR,
+    SUGGESTED_GAS_PRICE_MULTIPLIER,
+    SUGGESTED_PRIORITY_FEE_MULTIPLIER,
+)
+from wayfinder_paths.core.constants.chains import (
+    CHAIN_CODE_TO_ID,
+    CHAIN_ID_ARBITRUM,
+    CHAIN_ID_AVALANCHE,
+    CHAIN_ID_BASE,
+    CHAIN_ID_BSC,
+    CHAIN_ID_ETHEREUM,
+    CHAIN_ID_HYPEREVM,
+    CHAIN_ID_POLYGON,
+    POA_MIDDLEWARE_CHAIN_IDS,
+    PRE_EIP_1559_CHAIN_IDS,
+    SUPPORTED_CHAINS,
+)
+from wayfinder_paths.core.constants.contracts import (
+    NATIVE_TOKEN_SENTINEL,
     ZERO_ADDRESS,
 )
 
+from .hyperliquid import (
+    ARBITRUM_USDC_ADDRESS,
+    ARBITRUM_USDC_TOKEN_ID,
+    DEFAULT_HYPERLIQUID_BUILDER_FEE,
+    DEFAULT_HYPERLIQUID_BUILDER_FEE_TENTHS_BP,
+    HYPE_FEE_WALLET,
+    HYPERLIQUID_BRIDGE_ADDRESS,
+)
+
 __all__ = [
+    "NATIVE_TOKEN_SENTINEL",
     "ZERO_ADDRESS",
     "CHAIN_CODE_TO_ID",
     "DEFAULT_NATIVE_GAS_UNITS",
     "GAS_BUFFER_MULTIPLIER",
     "ONE_GWEI",
+    "SUGGESTED_PRIORITY_FEE_MULTIPLIER",
+    "SUGGESTED_GAS_PRICE_MULTIPLIER",
     "DEFAULT_SLIPPAGE",
+    "DEFAULT_HTTP_TIMEOUT",
+    "DEFAULT_PAGINATION_LIMIT",
+    "MANTISSA",
+    "SECONDS_PER_YEAR",
+    "MAX_UINT256",
+    "ADAPTER_BALANCE",
+    "ADAPTER_BRAP",
+    "ADAPTER_MOONWELL",
+    "ADAPTER_HYPERLIQUID",
+    "ADAPTER_POOL",
+    "ADAPTER_TOKEN",
+    "ADAPTER_LEDGER",
+    "ADAPTER_HYPERLEND",
+    "CHAIN_ID_ETHEREUM",
+    "CHAIN_ID_BASE",
+    "CHAIN_ID_ARBITRUM",
+    "CHAIN_ID_BSC",
+    "CHAIN_ID_POLYGON",
+    "CHAIN_ID_AVALANCHE",
+    "CHAIN_ID_HYPEREVM",
+    "SUPPORTED_CHAINS",
+    "POA_MIDDLEWARE_CHAIN_IDS",
+    "PRE_EIP_1559_CHAIN_IDS",
+    "HYPERLIQUID_BRIDGE_ADDRESS",
+    "ARBITRUM_USDC_ADDRESS",
+    "ARBITRUM_USDC_TOKEN_ID",
+    "HYPE_FEE_WALLET",
+    "DEFAULT_HYPERLIQUID_BUILDER_FEE_TENTHS_BP",
+    "DEFAULT_HYPERLIQUID_BUILDER_FEE",
 ]

wayfinder_paths/core/constants/base.py

@@ -1,21 +1,9 @@
-ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
-
-# Chain code to EVM chain id mapping
-CHAIN_CODE_TO_ID = {
-    "base": 8453,
-    "arbitrum": 42161,
-    "arbitrum-one": 42161,
-    "ethereum": 1,
-    "mainnet": 1,
-    "hyperevm": 999,
-}
-
-# Gas/defaults
 DEFAULT_NATIVE_GAS_UNITS = 21000
-# Fallback gas limit used only when RPC gas estimation fails for non-revert reasons.
-# Must be high enough for typical DeFi interactions (lending, swaps, etc.).
 GAS_BUFFER_MULTIPLIER = 1.1
 ONE_GWEI = 1_000_000_000
+SUGGESTED_PRIORITY_FEE_MULTIPLIER = 1.5
+SUGGESTED_GAS_PRICE_MULTIPLIER = 1.5
+
 DEFAULT_SLIPPAGE = 0.005
 
 # Timeout constants (seconds)
@@ -23,8 +11,8 @@ DEFAULT_SLIPPAGE = 0.005
 # even if the transaction is eventually mined. A longer timeout reduces false negatives that
 # can lead to unsafe retry behavior (nonce gaps, duplicate swaps, etc.).
 DEFAULT_HTTP_TIMEOUT = 30.0  # HTTP client timeout
+DEFAULT_TRANSACTION_TIMEOUT = 180  # Transaction receipt timeout (seconds)
 
-# Adapter type identifiers
 ADAPTER_BALANCE = "BALANCE"
 ADAPTER_BRAP = "BRAP"
 ADAPTER_MOONWELL = "MOONWELL"
@@ -34,5 +22,8 @@ ADAPTER_TOKEN = "TOKEN"
 ADAPTER_LEDGER = "LEDGER"
 ADAPTER_HYPERLEND = "HYPERLEND"
 
-# Pagination defaults
 DEFAULT_PAGINATION_LIMIT = 50
+
+MANTISSA = 10**18
+SECONDS_PER_YEAR = 365 * 24 * 60 * 60
+MAX_UINT256 = 2**256 - 1

wayfinder_paths/core/constants/chains.py

@@ -0,0 +1,36 @@
+CHAIN_ID_ETHEREUM = 1
+CHAIN_ID_BASE = 8453
+CHAIN_ID_ARBITRUM = 42161
+CHAIN_ID_BSC = 56
+CHAIN_ID_POLYGON = 137
+CHAIN_ID_AVALANCHE = 43114
+CHAIN_ID_HYPEREVM = 999
+
+CHAIN_CODE_TO_ID = {
+    "base": CHAIN_ID_BASE,
+    "arbitrum": CHAIN_ID_ARBITRUM,
+    "arbitrum-one": CHAIN_ID_ARBITRUM,
+    "ethereum": CHAIN_ID_ETHEREUM,
+    "mainnet": CHAIN_ID_ETHEREUM,
+    "hyperevm": CHAIN_ID_HYPEREVM,
+}
+
+SUPPORTED_CHAINS = [
+    CHAIN_ID_ETHEREUM,
+    CHAIN_ID_BASE,
+    CHAIN_ID_BSC,
+    CHAIN_ID_ARBITRUM,
+    CHAIN_ID_POLYGON,
+    CHAIN_ID_HYPEREVM,
+]
+
+POA_MIDDLEWARE_CHAIN_IDS: set[int] = {
+    CHAIN_ID_BSC,
+    CHAIN_ID_POLYGON,
+    CHAIN_ID_AVALANCHE,
+}
+
+PRE_EIP_1559_CHAIN_IDS: set[int] = {
+    CHAIN_ID_BSC,
+    CHAIN_ID_ARBITRUM,
+}

wayfinder_paths/core/constants/contracts.py

@@ -0,0 +1,52 @@
+from eth_utils import to_checksum_address
+
+ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+NATIVE_TOKEN_SENTINEL = to_checksum_address(
+    "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
+)
+
+BASE_WETH = to_checksum_address("0x4200000000000000000000000000000000000006")
+BASE_USDC = to_checksum_address("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
+BASE_WSTETH = to_checksum_address("0xc1CBa3fCea344f92D9239c08C0568f6F2F0ee452")
+
+MOONWELL_M_USDC = to_checksum_address("0xEdc817A28E8B93B03976FBd4a3dDBc9f7D176c22")
+MOONWELL_M_WETH = to_checksum_address("0x628ff693426583D9a7FB391E54366292F509D457")
+MOONWELL_M_WSTETH = to_checksum_address("0x627Fe393Bc6EdDA28e99AE648fD6fF362514304b")
+MOONWELL_COMPTROLLER = to_checksum_address("0xfBb21d0380beE3312B33c4353c8936a0F13EF26C")
+MOONWELL_REWARD_DISTRIBUTOR = to_checksum_address(
+    "0xe9005b078701e2A0948D2EaC43010D35870Ad9d2"
+)
+MOONWELL_WELL_TOKEN = to_checksum_address("0xA88594D404727625A9437C3f886C7643872296AE")
+
+ENSO_ROUTER = to_checksum_address("0xF75584eF6673aD213a685a1B58Cc0330B8eA22Cf")
+
+HYPEREVM_WHYPE = to_checksum_address("0x5555555555555555555555555555555555555555")
+HYPERCORE_SENTINEL_ADDRESS = to_checksum_address(
+    "0x2222222222222222222222222222222222222222"
+)
+HYPERCORE_SENTINEL_VALUE = 100_000_000_000
+
+HYPERLEND_POOL = to_checksum_address("0x00A89d7a5A02160f20150EbEA7a2b5E4879A1A8b")
+HYPERLEND_WRAPPED_TOKEN_GATEWAY = to_checksum_address(
+    "0x49558c794ea2aC8974C9F27886DDfAa951E99171"
+)
+
+PRJX_ROUTER = to_checksum_address("0x1EbDFC75FfE3ba3de61E7138a3E8706aC841Af9B")
+PRJX_NPM = to_checksum_address("0xeaD19AE861c29bBb2101E834922B2FEee69B9091")
+
+ARBITRUM_USDC = to_checksum_address("0xaf88d065e77c8cC2239327C5EDb3A432268e5831")
+
+HYPERLIQUID_BRIDGE = to_checksum_address("0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7")
+
+BOROS_ROUTER = to_checksum_address("0x8080808080dab95efed788a9214e400ba552def6")
+BOROS_MARKET_HUB = to_checksum_address("0x1080808080f145b14228443212e62447c112adad")
+
+USDT_ETHEREUM = to_checksum_address("0xdAC17F958D2ee523a2206206994597C13D831ec7")
+USDT_POLYGON = to_checksum_address("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
+USDT_BSC = to_checksum_address("0x55d398326f99059fF775485246999027B3197955")
+
+TOKENS_REQUIRING_APPROVAL_RESET: set[tuple[int, str]] = {
+    (1, USDT_ETHEREUM),
+    (137, USDT_POLYGON),
+    (56, USDT_BSC),
+}

wayfinder_paths/core/constants/erc20_abi.py

@@ -1,4 +1,3 @@
-# Standard ERC20 ABI - includes common functions needed for token operations
 ERC20_ABI = [
     {
         "constant": True,

wayfinder_paths/core/constants/hyperlend_abi.py

@@ -1,4 +1,3 @@
-# Minimal Pool ABI for supply and deposit operations
 POOL_ABI = [
     {
         "name": "supply",
@@ -37,7 +36,6 @@ POOL_ABI = [
     },
 ]
 
-# Protocol Data Provider ABI for reserve token addresses and user data
 PROTOCOL_DATA_PROVIDER_ABI = [
     {
         "type": "function",
@@ -71,7 +69,6 @@ PROTOCOL_DATA_PROVIDER_ABI = [
     },
 ]
 
-# Wrapped Token Gateway ABI for native token operations
 WRAPPED_TOKEN_GATEWAY_ABI = [
     {
         "type": "function",
@@ -126,7 +123,6 @@ WRAPPED_TOKEN_GATEWAY_ABI = [
     },
 ]
 
-# WETH ABI for native token wrapping
 WETH_ABI = [
     {
         "inputs": [],

wayfinder_paths/core/constants/hyperliquid.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+HYPERLIQUID_BRIDGE_ADDRESS: str = "0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7"
+ARBITRUM_USDC_ADDRESS: str = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
+ARBITRUM_USDC_TOKEN_ID: str = "usd-coin-arbitrum"
+HYPE_FEE_WALLET: str = "0xaA1D89f333857eD78F8434CC4f896A9293EFE65c"
+
+# Tenths of a basis point: 30 -> 0.030% (3 bps)
+DEFAULT_HYPERLIQUID_BUILDER_FEE_TENTHS_BP: int = 30
+
+DEFAULT_HYPERLIQUID_BUILDER_FEE: dict[str, Any] = {
+    "b": HYPE_FEE_WALLET,
+    "f": DEFAULT_HYPERLIQUID_BUILDER_FEE_TENTHS_BP,
+}

wayfinder_paths/core/constants/moonwell_abi.py

@@ -1,6 +1,4 @@
-# mToken (CErc20Delegator) ABI - for lending, borrowing, and position management
 MTOKEN_ABI = [
-    # Lend (supply) tokens by minting mTokens
     {
         "name": "mint",
         "type": "function",
@@ -8,7 +6,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "mintAmount", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Withdraw (redeem) underlying by burning mTokens
     {
         "name": "redeem",
         "type": "function",
@@ -16,7 +13,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "redeemTokens", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Withdraw exact underlying amount
     {
         "name": "redeemUnderlying",
         "type": "function",
@@ -24,7 +20,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "redeemAmount", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Borrow underlying tokens
     {
         "name": "borrow",
         "type": "function",
@@ -32,7 +27,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "borrowAmount", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Repay borrowed tokens
     {
         "name": "repayBorrow",
         "type": "function",
@@ -124,7 +118,6 @@ MTOKEN_ABI = [
         "inputs": [],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Accrue interest
     {
         "name": "accrueInterest",
         "type": "function",
@@ -141,9 +134,7 @@ MTOKEN_ABI = [
     },
 ]
 
-# Comptroller ABI - for collateral management and account liquidity
 COMPTROLLER_ABI = [
-    # Enable a market as collateral
     {
         "name": "enterMarkets",
         "type": "function",
@@ -151,7 +142,6 @@ COMPTROLLER_ABI = [
         "inputs": [{"name": "mTokens", "type": "address[]"}],
         "outputs": [{"name": "", "type": "uint256[]"}],
     },
-    # Disable a market as collateral
     {
         "name": "exitMarket",
         "type": "function",
@@ -234,7 +224,6 @@ COMPTROLLER_ABI = [
         "inputs": [],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Claim rewards for a user (called on comptroller in some versions)
     {
         "name": "claimReward",
         "type": "function",
@@ -244,9 +233,7 @@ COMPTROLLER_ABI = [
     },
 ]
 
-# Reward Distributor ABI - for claiming WELL rewards
 REWARD_DISTRIBUTOR_ABI = [
-    # Claim rewards for all markets
     {
         "name": "claimReward",
         "type": "function",
@@ -254,7 +241,6 @@ REWARD_DISTRIBUTOR_ABI = [
         "inputs": [],
         "outputs": [],
     },
-    # Claim rewards for specific holder and markets
     {
         "name": "claimReward",
         "type": "function",
@@ -350,7 +336,6 @@ REWARD_DISTRIBUTOR_ABI = [
     },
 ]
 
-# WETH ABI for wrapping/unwrapping ETH
 WETH_ABI = [
     {
         "name": "deposit",

wayfinder_paths/core/constants/tokens.py

@@ -0,0 +1,9 @@
+TOKEN_ID_USDC_BASE = "usd-coin-base"
+TOKEN_ID_WETH_BASE = "l2-standard-bridged-weth-base-base"
+TOKEN_ID_WSTETH_BASE = "superbridge-bridged-wsteth-base-base"
+TOKEN_ID_ETH_BASE = "ethereum-base"
+TOKEN_ID_WELL_BASE = "moonwell-artemis-base"
+
+TOKEN_ID_STETH = "staked-ether-ethereum"
+
+TOKEN_ID_USDC_ARBITRUM = "usd-coin-arbitrum"

wayfinder_paths/core/engine/manifest.py

@@ -0,0 +1,66 @@
+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 StrategyManifest(BaseModel):
+    schema_version: str = Field(default="0.1")
+    entrypoint: str = Field(
+        ...,
+        description="Python path to class, e.g. 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_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/strategies/Strategy.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import traceback
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
 from typing import Any, TypedDict
@@ -56,7 +55,6 @@ class Strategy(ABC):
         strategy_wallet_signing_callback: Callable[[dict], Awaitable[str]]
         | None = None,
     ):
-        self.adapters = {}
         self.ledger_adapter = None
         self.logger = logger.bind(strategy=self.__class__.__name__)
         self.config = config
@@ -66,12 +64,6 @@ class Strategy(ABC):
     async def setup(self) -> None:
         pass
 
-    async def log(self, msg: str) -> None:
-        self.logger.info(msg)
-
-    async def quote(self) -> None:
-        pass
-
     def _get_strategy_wallet_address(self) -> str:
         strategy_wallet = self.config.get("strategy_wallet")
         if not strategy_wallet or not isinstance(strategy_wallet, dict):
@@ -95,16 +87,6 @@ class Strategy(ABC):
         pass
 
     async def withdraw(self, **kwargs) -> StatusTuple:
-        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_adapter.positions.operations.pop()
-
-            await self.ledger_adapter.save()
-
         return (True, "Withdrawal complete")
 
     @abstractmethod
@@ -132,59 +114,6 @@ class Strategy(ABC):
 
         return status
 
-    def register_adapters(self, adapters: list[Any]) -> None:
-        self.adapters = {}
-        for adapter in adapters:
-            if hasattr(adapter, "adapter_type"):
-                self.adapters[adapter.adapter_type] = adapter
-            elif hasattr(adapter, "__class__"):
-                self.adapters[adapter.__class__.__name__] = adapter
-
-    def unwind_on_error(
-        self, func: Callable[..., Awaitable[StatusTuple]]
-    ) -> Callable[..., Awaitable[StatusTuple]]:
-        async def wrapper(*args: Any, **kwargs: Any) -> StatusTuple:
-            try:
-                return await func(*args, **kwargs)
-            except Exception:
-                trace = traceback.format_exc()
-                try:
-                    await self.withdraw()
-                    return (
-                        False,
-                        f"Strategy failed during operation and was unwound. Failure: {trace}",
-                    )
-                except Exception:
-                    trace2 = traceback.format_exc()
-                    return (
-                        False,
-                        f"Strategy failed and unwinding also failed. Operation error: {trace}. Unwind error: {trace2}",
-                    )
-            finally:
-                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 {
-            "name": getattr(cls, "name", None),
-            "description": getattr(cls, "description", None),
-            "summary": getattr(cls, "summary", None),
-        }
-
-    async def health_check(self) -> dict[str, Any]:
-        health = {"status": "healthy", "strategy": self.name, "adapters": {}}
-
-        for name, adapter in self.adapters.items():
-            if hasattr(adapter, "health_check"):
-                health["adapters"][name] = await adapter.health_check()
-            else:
-                health["adapters"][name] = {"status": "unknown"}
-
-        return health
-
     async def partial_liquidate(
         self, usd_value: float
     ) -> tuple[bool, LiquidationResult]:

wayfinder_paths/core/strategies/__init__.py

@@ -1,3 +1,12 @@
 from .base import StatusDict, StatusTuple, Strategy
+from .opa_loop import OPAConfig, OPALoopMixin, Plan, PlanStep
 
-__all__ = ["Strategy", "StatusDict", "StatusTuple"]
+__all__ = [
+    "Strategy",
+    "StatusDict",
+    "StatusTuple",
+    "OPALoopMixin",
+    "OPAConfig",
+    "Plan",
+    "PlanStep",
+]