wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/core/strategies/descriptors.py

@@ -0,0 +1,81 @@
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class Volatility(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class Frequency(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class Directionality(Enum):
+    LONG = "Long"
+    SHORT = "Short"
+    MARKET_NEUTRAL = "market_neutral"
+    DELTA_NEUTRAL = "delta_neutral"
+
+
+class Complexity(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class TokenExposure(Enum):
+    STABLECOINS = "Stablecoins"
+    MAJORS = "Majors"
+    ALTS = "Alts"
+
+
+# Default token rewards for all strategies
+DEFAULT_TOKEN_REWARDS = [
+    {
+        "symbol": "B3",
+        "name": "B3",
+        "address": "0xB3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3",
+        "image_url": "https://storage.googleapis.com/prod-wayfinder-app-assets/asset-icons/B3.png",
+        "chain_id": 8453,
+    },
+]
+
+
+class StratDescriptor(BaseModel):
+    description: str
+
+    summary: str
+
+    gas_token_symbol: str
+    gas_token_id: str
+    deposit_token_id: str
+    minimum_net_deposit: float
+    gas_maximum: float
+    gas_threshold: float
+
+    available_rewards: dict[str, Any] = {
+        "token_rewards": DEFAULT_TOKEN_REWARDS,
+        "point_rewards": None,
+    }
+
+    # risk indicators
+    volatility: Volatility
+    volatility_description_short: str
+    directionality: Directionality
+    directionality_description: str
+    complexity: Complexity
+    complexity_description: str
+    token_exposure: TokenExposure
+    token_exposure_description: str
+    frequency: Frequency
+    frequency_description: str
+
+    return_drivers: list[str]
+
+    config: dict[str, Any]

wayfinder_paths/core/utils/__init__.py

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

wayfinder_paths/core/utils/evm_helpers.py

@@ -0,0 +1,206 @@
+"""
+EVM helper utilities for common blockchain operations.
+
+This module provides reusable functions for EVM-related operations that are shared
+across multiple adapters, extracted from evm_transaction_adapter.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+from web3 import AsyncHTTPProvider, AsyncWeb3
+
+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("chain_id")
+    try:
+        if chain_id is not None:
+            return int(chain_id)
+    except (ValueError, TypeError):
+        log.debug("Invalid chain_id in token_info.chain_id: %s", chain_id)
+    return chain_code_to_chain_id(chain_meta.get("code"))
+
+
+def resolve_rpc_url(
+    chain_id: int | None,
+    config: dict[str, Any],
+    explicit_rpc_url: str | None = None,
+) -> str:
+    """
+    Resolve RPC URL from config or environment variables.
+
+    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 {}
+    mapping = strategy_cfg.get("rpc_urls") if isinstance(strategy_cfg, dict) else None
+    if chain_id is not None and isinstance(mapping, dict):
+        by_int = mapping.get(chain_id)
+        if by_int:
+            return str(by_int)
+        by_str = mapping.get(str(chain_id))
+        if by_str:
+            return str(by_str)
+    env_rpc = os.getenv("RPC_URL")
+    if env_rpc:
+        return env_rpc
+    raise ValueError("RPC URL not provided. Set strategy.rpc_urls or env RPC_URL.")
+
+
+async def get_next_nonce(
+    from_address: str, rpc_url: str, use_latest: bool = False
+) -> int:
+    """
+    Get the next nonce for the given address.
+
+    Args:
+        from_address: Address to get nonce for
+        rpc_url: RPC URL to connect to
+        use_latest: If True, use 'latest' block instead of 'pending'
+
+    Returns:
+        Next nonce as integer
+    """
+    w3 = AsyncWeb3(AsyncHTTPProvider(rpc_url))
+    try:
+        if use_latest:
+            return await w3.eth.get_transaction_count(from_address, "latest")
+        return await w3.eth.get_transaction_count(from_address)
+    finally:
+        try:
+            await w3.provider.session.close()
+        except Exception:
+            pass
+
+
+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 or environment.
+
+    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")
+
+    main_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(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
+    strategy_addr = None
+    try:
+        main_addr = (main_wallet or {}).get("address") or (
+            (main_wallet or {}).get("evm") or {}
+        ).get("address")
+        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 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_STRATEGY") or os.getenv("PRIVATE_KEY")
+
+
+async def _get_abi(chain_id: int, address: str) -> str | None:
+    os.makedirs(f"abis/{chain_id}/", exist_ok=True)
+
+    abi_file = f"abis/{chain_id}/{address}.json"
+    if not os.path.exists(abi_file):
+        raise ValueError(
+            f"There is no downloaded ABI for {address} on chain {chain_id} -- please download it to ({abi_file})  (make sure to get the implementation if this address is a proxy)"
+        )
+
+    with open(abi_file) as f:
+        abi = f.read()
+
+    return abi
+
+
+# We filter ABIs for Privy Policy since most of the abi is useless, and we don't wanna upload big ABIs for both size and readability reasons.
+async def get_abi_filtered(
+    chain_id: int, address: str, function_names: list[str]
+) -> list | None:
+    full_abi = await _get_abi(chain_id, address)
+    if full_abi is None:
+        raise Exception("Could not pull ABI, get_abi returned None")
+    abi_json = json.loads(full_abi)
+    filtered_abi = [
+        item
+        for item in abi_json
+        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/core/utils/wallets.py

@@ -0,0 +1,77 @@
+import json
+from pathlib import Path
+from typing import Any
+
+from eth_account import Account
+
+
+def make_random_wallet() -> dict[str, str]:
+    """Generate a new random wallet.
+
+    Returns a mapping with keys: "address" and "private_key_hex" (0x-prefixed).
+    """
+    acct = Account.create()  # uses os.urandom
+    return {
+        "address": acct.address,
+        "private_key_hex": acct.key.hex(),
+    }
+
+
+def _load_existing_wallets(file_path: Path) -> list[dict[str, Any]]:
+    if not file_path.exists():
+        return []
+    try:
+        parsed = json.loads(file_path.read_text())
+        if isinstance(parsed, list):
+            return parsed
+        if isinstance(parsed, dict):
+            wallets = parsed.get("wallets")
+            if isinstance(wallets, list):
+                return wallets
+        return []
+    except Exception:
+        # If the file is malformed, start fresh rather than raising.
+        return []
+
+
+def _save_wallets(file_path: Path, wallets: list[dict[str, Any]]) -> None:
+    # Ensure stable ordering by address for readability
+    sorted_wallets = sorted(wallets, key=lambda w: w.get("address", ""))
+    file_path.write_text(json.dumps(sorted_wallets, indent=2))
+
+
+def write_wallet_to_json(
+    wallet: dict[str, str], out_dir: str | Path = ".", filename: str = "wallets.json"
+) -> Path:
+    """Create or update a wallets.json with the provided wallet.
+
+    - Ensures the output directory exists.
+    - Merges with existing entries keyed by address (updates if present, appends otherwise).
+    - Writes a pretty-printed JSON list of wallet objects.
+    """
+    out_dir_path = Path(out_dir)
+    out_dir_path.mkdir(parents=True, exist_ok=True)
+    file_path = out_dir_path / filename
+
+    existing = _load_existing_wallets(file_path)
+    index_by_address: dict[str, int] = {}
+    for i, w in enumerate(existing):
+        addr = w.get("address")
+        if isinstance(addr, str):
+            index_by_address[addr.lower()] = i
+
+    addr_key = wallet["address"].lower()
+    if addr_key in index_by_address:
+        existing[index_by_address[addr_key]] = wallet
+    else:
+        existing.append(wallet)
+
+    _save_wallets(file_path, existing)
+    return file_path
+
+
+def load_wallets(
+    out_dir: str | Path = ".", filename: str = "wallets.json"
+) -> list[dict[str, Any]]:
+    """Public helper to read wallets.json as a list of wallet dicts."""
+    return _load_existing_wallets(Path(out_dir) / filename)

wayfinder_paths/core/wallets/README.md

@@ -0,0 +1,91 @@
+# Wallet Abstraction Layer
+
+Wayfinder strategies interact with blockchains through a single abstraction: the `EvmTxn` interface defined in `wayfinder_paths/core/services/base.py`. The default implementation (`LocalEvmTxn`) signs transactions with private keys pulled from config/environment variables, while `WalletManager` resolves which provider to use at runtime.
+
+## Pieces
+
+1. **`EvmTxn` (interface)** – describes balance lookups, ERC-20 approvals, raw transaction broadcasting, and AsyncWeb3 access.
+2. **`LocalEvmTxn`** – the built-in provider that signs transactions locally via `eth_account`. It handles RPC resolution, nonce management, gas estimation, and status checks.
+3. **`WalletManager`** – light factory that reads `wallet_type` from strategy config and returns the appropriate `EvmTxn`. Today it always returns `LocalEvmTxn` unless you inject your own provider.
+4. **`DefaultWeb3Service`** – convenience wrapper that bundles an `EvmTxn` (wallet provider) with a `LocalTokenTxnService` (transaction builders used by adapters).
+
+## Using the defaults
+
+```python
+from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
+from wayfinder_paths.core.wallets.WalletManager import WalletManager
+
+config = {...}  # contains main_wallet / strategy_wallet entries
+wallet_provider = WalletManager.get_provider(config)
+web3_service = DefaultWeb3Service(config, wallet_provider=wallet_provider)
+
+# Strategies typically pass web3_service.evm_transactions into adapters that require wallet access.
+balance_adapter = BalanceAdapter(config, web3_service=web3_service)
+```
+
+If you want to provide a custom wallet provider (e.g., Privy, Turnkey, Fireblocks), implement the `EvmTxn` interface and hand it to `DefaultWeb3Service`/adapters directly—`WalletManager` is purely a helper.
+
+## Implementing a custom provider
+
+Subclass `EvmTxn` and implement every abstract method:
+
+```python
+from typing import Any
+from web3 import AsyncWeb3
+
+from wayfinder_paths.core.services.base import EvmTxn
+
+
+class PrivyWallet(EvmTxn):
+    def __init__(self, privy_client):
+        self._client = privy_client
+
+    async def get_balance(self, address: str, token_address: str | None, chain_id: int) -> tuple[bool, Any]:
+        ...
+
+    async def read_erc20_allowance(self, chain_id: int, token_address: str, owner_address: str, spender_address: str) -> tuple[bool, Any]:
+        ...
+
+    async def approve_token(...):
+        ...
+
+    async def broadcast_transaction(...):
+        ...
+
+    async def transaction_succeeded(self, tx_hash: str, chain_id: int, timeout: int = 120) -> bool:
+        ...
+
+    def get_web3(self, chain_id: int) -> AsyncWeb3:
+        ...
+```
+
+Methods should mirror `LocalEvmTxn`’s behavior: return `(True, payload)` on success, `(False, "reason")` on failure, and expose AsyncWeb3 instances tied to the requested chain.
+
+Once implemented:
+
+```python
+custom_wallet = PrivyWallet(privy_client)
+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 `strategy_wallet`. Example:
+
+```json
+{
+  "strategy": {
+    "wallet_type": "local",
+    "main_wallet": {"address": "0x...", "wallet_type": "local"},
+    "strategy_wallet": {"address": "0x..."}
+  }
+}
+```
+
+Currently only `"local"` is supported through configuration—the custom path is injection.
+
+## Why this layer?
+
+- Strategies never touch raw `AsyncWeb3`; they call adapters, which call clients, which call a wallet provider.
+- Alternate signing backends can be plugged in without modifying strategy code.
+- Tests can patch `WalletManager.get_provider` or inject stub `EvmTxn` implementations to avoid real RPC calls.

wayfinder_paths/core/wallets/WalletManager.py

@@ -0,0 +1,56 @@
+"""
+Wallet Manager
+
+Factory class for resolving and instantiating wallet providers based on configuration.
+Provides convenience methods for config-based wallet provider resolution.
+"""
+
+from typing import Any
+
+from loguru import logger
+
+from wayfinder_paths.core.services.base import EvmTxn
+from wayfinder_paths.core.services.local_evm_txn import LocalEvmTxn
+
+
+class WalletManager:
+    """
+    Factory class for wallet providers.
+
+    Resolves appropriate wallet provider based on config, defaulting to LocalWalletProvider.
+    This is a convenience helper - adapters support direct injection, making this optional.
+    """
+
+    @staticmethod
+    def get_provider(config: dict[str, Any] | None = None) -> EvmTxn:
+        """
+        Get wallet provider based on configuration.
+
+        Args:
+            config: Configuration dictionary. May contain wallet_type in wallet configs.
+
+        Returns:
+            WalletProvider instance. Defaults to LocalWalletProvider if no type specified.
+        """
+        config = config or {}
+        wallet_type = config.get("wallet_type")
+
+        if not wallet_type:
+            main_wallet = config.get("main_wallet")
+            if isinstance(main_wallet, dict):
+                wallet_type = main_wallet.get("wallet_type")
+
+        if not 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)")
+            return LocalEvmTxn(config)
+
+        logger.warning(
+            f"Unknown wallet_type '{wallet_type}', defaulting to LocalWalletProvider. "
+            "To use custom wallet providers, inject them directly into adapters."
+        )
+        return LocalEvmTxn(config)

wayfinder_paths/core/wallets/__init__.py

@@ -0,0 +1,7 @@
+"""Wallet abstraction layer for supporting multiple wallet types."""
+
+from wayfinder_paths.core.services.base import EvmTxn
+from wayfinder_paths.core.services.local_evm_txn import LocalEvmTxn
+from wayfinder_paths.core.wallets.WalletManager import WalletManager
+
+__all__ = ["EvmTxn", "LocalEvmTxn", "WalletManager"]

wayfinder_paths/policies/enso.py

@@ -0,0 +1,17 @@
+from wayfinder_paths.policies.util import allow_functions
+
+ENSO_ROUTER = "0xf75584ef6673ad213a685a1b58cc0330b8ea22cf"
+
+
+async def enso_swap():
+    return await allow_functions(
+        policy_name="Allow Enso Swap",
+        abi_chain_id=8453,
+        address=ENSO_ROUTER,
+        function_names=[
+            "routeMulti",
+            "routeSingle",
+            "safeRouteMulti",
+            "safeRouteSingle",
+        ],
+    )

wayfinder_paths/policies/erc20.py

@@ -0,0 +1,34 @@
+from wayfinder_paths.core.utils.evm_helpers import ERC20_ABI
+
+
+def any_erc20_function(token_address: str) -> dict:
+    return {
+        "name": "Allow Any ERC20 Transfer To Address",
+        "method": "eth_signTransaction",
+        "action": "ALLOW",
+        "conditions": [
+            {
+                "field_source": "ethereum_transaction",
+                "field": "to",
+                "operator": "eq",
+                "value": token_address,
+            }
+        ],
+    }
+
+
+def erc20_spender_for_any_token(spender_address: str) -> dict:
+    return {
+        "name": "Allow Any ERC20 Approve To Spender",
+        "method": "eth_signTransaction",
+        "action": "ALLOW",
+        "conditions": [
+            {
+                "field_source": "ethereum_calldata",
+                "field": "approve.spender",
+                "abi": ERC20_ABI,
+                "operator": "eq",
+                "value": spender_address,
+            },
+        ],
+    }

wayfinder_paths/policies/evm.py

@@ -0,0 +1,21 @@
+def native_transfer(destination_address: str, value: int) -> dict:
+    # TODO THIS FUNCTION IS NOT DONE CAUSE POLICIES DONT KNOW THE WALLET ADDRESS YET.
+    return {
+        "name": "Allow Native Transfer To Address",
+        "method": "eth_signTransaction",
+        "action": "ALLOW",
+        "conditions": [
+            {
+                "field_source": "ethereum_transaction",
+                "field": "to",
+                "operator": "eq",
+                "value": destination_address,
+            },
+            {
+                "field_source": "ethereum_transaction",
+                "field": "value",
+                "operator": "eq",
+                "value": hex(value),
+            },
+        ],
+    }

wayfinder_paths/policies/hyper_evm.py

@@ -0,0 +1,19 @@
+from wayfinder_paths.policies.evm import native_transfer
+from wayfinder_paths.policies.util import allow_functions
+
+WHYPE_TOKEN = "0x5555555555555555555555555555555555555555"
+HYPERCORE_SENTINEL_ADDRESS = "0x2222222222222222222222222222222222222222"
+HYPERCORE_SENTINEL_VALUE = 100_000_000_000
+
+
+def hypecore_sentinel_deposit():
+    return native_transfer(HYPERCORE_SENTINEL_ADDRESS, HYPERCORE_SENTINEL_VALUE)
+
+
+async def whype_deposit_and_withdraw():
+    return await allow_functions(
+        policy_name="Allow WHYPE Deposit and Withdraw",
+        abi_chain_id=999,
+        address=WHYPE_TOKEN,
+        function_names=["deposit", "withdraw"],
+    )

wayfinder_paths/policies/hyperlend.py

@@ -0,0 +1,12 @@
+from wayfinder_paths.policies.util import allow_functions
+
+HYPERLEND_POOL = "0x00A89d7a5A02160f20150EbEA7a2b5E4879A1A8b"
+
+
+async def hyperlend_supply_and_withdraw():
+    return await allow_functions(
+        policy_name="Allow Hyperlend Supply and Withdraw",
+        abi_chain_id=999,
+        address=HYPERLEND_POOL,
+        function_names=["supply", "withdraw"],
+    )

wayfinder_paths/policies/hyperliquid.py

@@ -0,0 +1,30 @@
+def any_hyperliquid_l1_payload():
+    return {
+        "name": "Allow Hypecore L1 Payload",
+        "method": "eth_signTypedData_v4",
+        "action": "ALLOW",
+        "conditions": [
+            {
+                "field": "chainId",
+                "field_source": "ethereum_typed_data_domain",
+                "operator": "eq",
+                "value": "1337",
+            }
+        ],
+    }
+
+
+def any_hyperliquid_user_payload():
+    return {
+        "name": "Allow User Signed Payload",
+        "method": "eth_signTypedData_v4",
+        "action": "ALLOW",
+        "conditions": [
+            {
+                "field": "chainId",
+                "field_source": "ethereum_typed_data_domain",
+                "operator": "eq",
+                "value": "421614",
+            }
+        ],
+    }