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

wayfinder_paths/adapters/hyperliquid_adapter/executor.py

@@ -1,12 +1,3 @@
-"""
-Hyperliquid Executor Protocol and Implementations.
-
-Defines the interface for Hyperliquid order execution and a local-signing implementation.
-
-Other execution environments can provide their own `HyperliquidExecutor` that satisfies
-the protocol (for example, by delegating signing to a hosted signer).
-"""
-
 from __future__ import annotations
 
 import uuid
@@ -39,18 +30,11 @@ except ImportError:
 
 
 def _new_client_id() -> Cloid:
-    """Generate a new client order ID as a Cloid object."""
     cloid_str = "0x" + uuid.uuid4().hex
     return Cloid(cloid_str)
 
 
 class LocalHyperliquidExecutor:
-    """
-    Local Hyperliquid executor using SDK with private key signing.
-
-    Uses the hyperliquid SDK's Exchange class which handles EIP-712 signing internally.
-    """
-
     def __init__(
         self,
         *,
@@ -73,13 +57,11 @@ class LocalHyperliquidExecutor:
                 "Provide strategy_wallet.private_key_hex or strategy_wallet.private_key"
             )
 
-        # Create wallet account
         pk = self._private_key
         if not pk.startswith("0x"):
             pk = "0x" + pk
         self._wallet = Account.from_key(pk)
 
-        # Initialize SDK clients
         base_url = (
             constants.MAINNET_API_URL
             if network == "mainnet"
@@ -94,12 +76,6 @@ class LocalHyperliquidExecutor:
         )
 
     def _get_perp_coin(self, asset_id: int) -> str | None:
-        """
-        Resolve a perp coin name from a perp asset_id.
-
-        Note: newer versions of the hyperliquid SDK expose `coin_to_asset` but not
-        `asset_to_coin`, so we build the reverse mapping when needed.
-        """
         if self._asset_id_to_coin is None:
             mapping: dict[int, str] = {}
 
@@ -131,7 +107,6 @@ class LocalHyperliquidExecutor:
         return self._asset_id_to_coin.get(asset_id) if self._asset_id_to_coin else None
 
     def _resolve_private_key(self, config: dict[str, Any]) -> str | None:
-        """Extract private key from config."""
         # Try strategy_wallet first
         strategy_wallet = config.get("strategy_wallet", {})
         if isinstance(strategy_wallet, dict):
@@ -152,7 +127,6 @@ class LocalHyperliquidExecutor:
 
     @property
     def address(self) -> str:
-        """Get the wallet address."""
         return self._wallet.address
 
     async def place_market_order(
@@ -167,22 +141,15 @@ class LocalHyperliquidExecutor:
         cloid: Any = None,
         builder: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        """Place a market order using the SDK.
-
-        Args:
-            builder: Optional builder fee config with keys 'b' (address) and 'f' (fee bps)
-        """
         if cloid is None:
             cloid = _new_client_id()
         elif isinstance(cloid, str):
             cloid = Cloid(cloid)
 
-        # Convert builder dict to BuilderInfo if provided
         builder_info = None
         if builder:
             builder_info = BuilderInfo(b=builder.get("b", ""), f=builder.get("f", 0))
 
-        # Validate address matches our wallet
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -193,7 +160,6 @@ class LocalHyperliquidExecutor:
             }
 
         try:
-            # The SDK's market_open handles slippage internally
             # For spot (asset_id >= 10000), use different method
             is_spot = asset_id >= 10000
 
@@ -256,7 +222,6 @@ class LocalHyperliquidExecutor:
         order_id: int,
         address: str,
     ) -> dict[str, Any]:
-        """Cancel an open order."""
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -299,7 +264,6 @@ class LocalHyperliquidExecutor:
         is_cross: bool,
         address: str,
     ) -> dict[str, Any]:
-        """Update leverage for an asset."""
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -338,7 +302,6 @@ class LocalHyperliquidExecutor:
         amount: float,
         address: str,
     ) -> dict[str, Any]:
-        """Transfer USDC from spot to perp balance."""
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -366,7 +329,6 @@ class LocalHyperliquidExecutor:
         amount: float,
         address: str,
     ) -> dict[str, Any]:
-        """Transfer USDC from perp to spot balance."""
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -397,7 +359,6 @@ class LocalHyperliquidExecutor:
         size: float,
         address: str,
     ) -> dict[str, Any]:
-        """Place a stop-loss order."""
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -451,20 +412,6 @@ class LocalHyperliquidExecutor:
         reduce_only: bool = False,
         builder: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        """
-        Place a limit order (GTC - Good Till Cancelled).
-
-        Used for spot stop-loss orders in basis trading.
-
-        Args:
-            asset_id: Asset ID (perp or spot)
-            is_buy: True for buy, False for sell
-            price: Limit price
-            size: Order size
-            address: Wallet address
-            reduce_only: If True, only reduces existing position
-            builder: Optional builder fee config
-        """
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -488,7 +435,6 @@ class LocalHyperliquidExecutor:
                         },
                     }
 
-            # Convert builder dict to BuilderInfo if provided
             builder_info = None
             if builder:
                 builder_info = BuilderInfo(
@@ -521,7 +467,6 @@ class LocalHyperliquidExecutor:
         amount: float,
         address: str,
     ) -> dict[str, Any]:
-        """Withdraw USDC from Hyperliquid to Arbitrum."""
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -532,7 +477,7 @@ class LocalHyperliquidExecutor:
             # Use withdraw_from_bridge to withdraw to the wallet's own address on Arbitrum
             result = self.exchange.withdraw_from_bridge(
                 amount=amount,
-                destination=address,  # Withdraw to same address on Arbitrum
+                destination=address,
             )
             logger.debug(f"Withdraw result: {result}")
             return result
@@ -551,20 +496,6 @@ class LocalHyperliquidExecutor:
         max_fee_rate: str,
         address: str,
     ) -> dict[str, Any]:
-        """
-        Approve a builder fee for the user.
-
-        This signs and broadcasts an approveBuilderFee action that allows
-        the specified builder to charge up to max_fee_rate on trades.
-
-        Args:
-            builder: Builder wallet address
-            max_fee_rate: Fee rate as percentage string (e.g., "0.030%" for 30 tenths bp)
-            address: User wallet address (must match executor wallet)
-
-        Returns:
-            Dict with status "ok" or "err" and response data
-        """
         if address.lower() != self._wallet.address.lower():
             return {
                 "status": "err",
@@ -572,7 +503,6 @@ class LocalHyperliquidExecutor:
             }
 
         try:
-            # The SDK's approve_builder_fee method handles the signing internally
             result = self.exchange.approve_builder_fee(
                 builder=builder,
                 max_fee_rate=max_fee_rate,

wayfinder_paths/adapters/hyperliquid_adapter/paired_filler.py

@@ -1,5 +1,3 @@
-"""PairedFiller - atomic paired spot+perp order execution with imbalance repair."""
-
 from __future__ import annotations
 
 import asyncio
@@ -47,7 +45,6 @@ def _round_up_units(units: float, step: Decimal) -> float:
 def _parse_oids_and_immediate_fill(
     resp: dict[str, Any],
 ) -> tuple[list[int], float, float]:
-    """Extract order IDs and immediate fill info from API response."""
     oids: list[int] = []
     filled_units = 0.0
     filled_notional = 0.0
@@ -112,8 +109,6 @@ def _parse_oids_and_immediate_fill(
 
 @dataclass
 class FillConfig:
-    """Configuration for paired order filling."""
-
     max_slip_bps: int = 35
     max_chunk_usd: float = 7_500.0
     max_loops: int = 40
@@ -122,8 +117,6 @@ class FillConfig:
 
 @dataclass
 class FillConfirmCfg:
-    """Configuration for fill confirmation polling."""
-
     max_status_polls: int = 4
     poll_sleep_s: float = 0.20
     fills_time_early_ms: int = 3_000
@@ -132,16 +125,12 @@ class FillConfirmCfg:
 
 @dataclass
 class LegFillResult:
-    """Result of filling a single leg (spot or perp)."""
-
     units: float = 0.0
     notional: float = 0.0
 
 
 @dataclass
 class LegSubmitResult:
-    """Result of submitting a leg order."""
-
     oids: list[int]
     start_ms: int
     coin_label: str
@@ -151,8 +140,6 @@ class LegSubmitResult:
 
 
 class LegConfirmer:
-    """Confirms fill completion for individual legs via polling."""
-
     def __init__(self, adapter: HyperliquidAdapter, cfg: FillConfirmCfg):
         self.adapter = adapter
         self.cfg = cfg
@@ -168,7 +155,6 @@ class LegConfirmer:
         fallback_units: float = 0.0,
         fallback_notional: float = 0.0,
     ) -> LegFillResult:
-        """Confirm that a leg order has been filled."""
         oids: list[int] = list(initial_oids)
 
         if not oids and cloid:
@@ -208,7 +194,6 @@ class LegConfirmer:
         return result
 
     async def _oid_from_cloid(self, cloid: str, address: str) -> int | None:
-        """Get numeric order ID from client order ID."""
         try:
             success, status = await self.adapter.get_order_status(address, cloid)
             if not success:
@@ -227,7 +212,6 @@ class LegConfirmer:
             return None
 
     async def _ensure_not_open(self, address: str, oids: list[int]) -> None:
-        """Cancel any orders that are still open."""
         if not oids:
             return
         try:
@@ -266,7 +250,6 @@ class LegConfirmer:
                 logger.info(f"Cancel failed for oid {oid_int}: {exc}")
 
     def _resolve_asset_id(self, order: dict[str, Any]) -> int | None:
-        """Resolve asset ID from order info."""
         coin = order.get("coin")
         if not isinstance(coin, str):
             return None
@@ -281,7 +264,6 @@ class LegConfirmer:
             return None
 
     def _flatten_open_orders(self, obj: Any) -> list[dict[str, Any]]:
-        """Flatten nested order structures into a flat list."""
         results: list[dict[str, Any]] = []
 
         def walk(node: Any, coin_ctx: str | None = None) -> None:
@@ -315,7 +297,6 @@ class LegConfirmer:
         start_ms: int,
         oids: list[int],
     ) -> LegFillResult:
-        """Sum fills matching order IDs within time window."""
         if not oids:
             return LegFillResult()
 
@@ -393,7 +374,6 @@ class LegConfirmer:
 
     @staticmethod
     def _to_records(data: Any) -> list[dict[str, Any]]:
-        """Convert various data formats to list of dicts."""
         if data is None:
             return []
         if hasattr(data, "to_dict"):
@@ -408,17 +388,6 @@ class LegConfirmer:
 
 
 class PairedFiller:
-    """
-    Executes atomic paired spot+perp orders with imbalance repair.
-
-    Handles:
-    - Chunking large orders into $7,500 pieces
-    - Parallel execution of spot and perp legs
-    - Imbalance repair if one leg fills more than the other
-    - Rollback on failure
-    - Fill confirmation via polling
-    """
-
     def __init__(
         self,
         adapter: HyperliquidAdapter,
@@ -450,21 +419,6 @@ class PairedFiller:
         list[dict[str, Any]],
         list[dict[str, Any]],
     ]:
-        """
-        Fill paired spot+perp positions atomically.
-
-        Args:
-            coin: Asset symbol (e.g., "ETH")
-            spot_asset_id: Spot asset ID (>= 10000)
-            perp_asset_id: Perpetual asset ID (< 10000)
-            total_units: Total units to fill
-            direction: "long_spot_short_perp" or "short_spot_long_perp"
-            builder_fee: Optional builder fee configuration
-
-        Returns:
-            Tuple of (spot_units, perp_units, spot_notional, perp_notional,
-                     spot_pointers, perp_pointers)
-        """
         step = self._common_step(spot_asset_id, perp_asset_id)
         remaining = _round_down_units(total_units, step)
         if remaining <= 0:
@@ -502,7 +456,6 @@ class PairedFiller:
         while loops < self.cfg.max_loops and (
             remaining > 0 or abs(delta_units) >= step_float
         ):
-            # Handle imbalance repair
             if abs(delta_units) >= step_float:
                 loops += 1
                 fix_units = _round_down_units(abs(delta_units), step)
@@ -751,7 +704,6 @@ class PairedFiller:
                 logger.warning("Paired filler made no progress for {}; aborting.", coin)
                 break
 
-            # Handle margin rejection - rollback spot if perp rejected
             if (
                 spot_fill.units > 0.0
                 and perp_fill.units <= 0.0
@@ -794,7 +746,6 @@ class PairedFiller:
 
                 break
 
-            # Handle spot failure - rollback perp if spot failed
             if (
                 perp_fill.units > 0.0
                 and spot_fill.units <= 0.0
@@ -894,7 +845,6 @@ class PairedFiller:
 
     @staticmethod
     def _is_margin_rejected(resp: dict[str, Any]) -> bool:
-        """Detect Hyperliquid margin rejection responses."""
         if not isinstance(resp, dict):
             return False
 
@@ -912,7 +862,6 @@ class PairedFiller:
 
     @staticmethod
     def _is_errorish(resp: dict[str, Any]) -> bool:
-        """Best-effort detection for failed API responses."""
         if not isinstance(resp, dict):
             return True
 
@@ -941,7 +890,6 @@ class PairedFiller:
         cloid: str,
         builder_fee: dict[str, Any] | None = None,
     ) -> LegSubmitResult:
-        """Submit an IOC order for one leg."""
         start_ms = _now_ms()
         rounded_units = self.adapter.get_valid_order_size(asset_id, units)
         if rounded_units <= 0:
@@ -975,7 +923,6 @@ class PairedFiller:
         )
 
     async def _spot_usdc_available(self) -> float:
-        """Get available USDC balance for spot trades."""
         try:
             success, state = await self.adapter.get_spot_user_state(self.address)
             if not success:
@@ -1003,7 +950,6 @@ class PairedFiller:
         step: Decimal,
         min_units: float,
     ) -> float:
-        """Calculate maximum spot units based on available USDC."""
         if desired_units <= 0 or mid_price <= 0:
             return 0.0
         available = await self._spot_usdc_available()
@@ -1019,7 +965,6 @@ class PairedFiller:
         return min(desired_units, max_units)
 
     def _min_units_for_notional(self, mid_price: float, step: Decimal) -> float:
-        """Calculate minimum units to meet notional threshold."""
         if mid_price <= 0:
             return max(float(step), 0.0)
         raw_units = MIN_NOTIONAL_USD / mid_price
@@ -1029,7 +974,6 @@ class PairedFiller:
         return max(float(step), quantized)
 
     def _common_step(self, spot_asset_id: int, perp_asset_id: int) -> Decimal:
-        """Get common step size for both assets."""
         spot_decimals = self.adapter.get_sz_decimals(spot_asset_id)
         perp_decimals = self.adapter.get_sz_decimals(perp_asset_id)
         return Decimal(10) ** -min(spot_decimals, perp_decimals)
@@ -1040,7 +984,6 @@ class PairedFiller:
         reason: str,
         metadata: dict[str, Any],
     ) -> dict[str, Any] | None:
-        """Build order pointer for tracking."""
         if not response or response.get("status") != "ok":
             return None
         return {

wayfinder_paths/adapters/hyperliquid_adapter/test_adapter.py

@@ -1,5 +1,3 @@
-"""Tests for HyperliquidAdapter."""
-
 from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
@@ -7,11 +5,8 @@ import pytest
 
 
 class TestHyperliquidAdapter:
-    """Tests for HyperliquidAdapter functionality."""
-
     @pytest.fixture
     def mock_info(self):
-        """Create a mock Info client."""
         mock = MagicMock()
         mock.meta_and_asset_ctxs.return_value = [
             {"universe": [{"name": "BTC"}, {"name": "ETH"}]},
@@ -36,12 +31,10 @@ class TestHyperliquidAdapter:
 
     @pytest.fixture
     def mock_constants(self):
-        """Create mock constants module."""
         return SimpleNamespace(MAINNET_API_URL="https://api.hyperliquid.xyz")
 
     @pytest.fixture
     def adapter(self, mock_info, mock_constants):
-        """Create adapter with mocked Info client."""
         with patch(
             "wayfinder_paths.adapters.hyperliquid_adapter.adapter.Info",
             return_value=mock_info,
@@ -64,63 +57,53 @@ class TestHyperliquidAdapter:
 
     @pytest.mark.asyncio
     async def test_connect(self, adapter):
-        """Test connection verification."""
         result = await adapter.connect()
         assert result is True
 
     @pytest.mark.asyncio
     async def test_get_meta_and_asset_ctxs(self, adapter):
-        """Test fetching market metadata."""
         success, data = await adapter.get_meta_and_asset_ctxs()
         assert success
         assert "universe" in data[0]
 
     @pytest.mark.asyncio
     async def test_get_spot_meta(self, adapter):
-        """Test fetching spot metadata."""
         success, data = await adapter.get_spot_meta()
         assert success
 
     @pytest.mark.asyncio
     async def test_get_funding_history(self, adapter):
-        """Test fetching funding history."""
         success, data = await adapter.get_funding_history("ETH", 1700000000000)
         assert success
         assert isinstance(data, list)
 
     @pytest.mark.asyncio
     async def test_get_candles(self, adapter):
-        """Test fetching candle data."""
         success, data = await adapter.get_candles("ETH", "1h", 1700000000000)
         assert success
         assert isinstance(data, list)
 
     @pytest.mark.asyncio
     async def test_get_l2_book(self, adapter):
-        """Test fetching order book."""
         success, data = await adapter.get_l2_book("ETH")
         assert success
         assert "levels" in data
 
     @pytest.mark.asyncio
     async def test_get_user_state(self, adapter):
-        """Test fetching user state."""
         success, data = await adapter.get_user_state("0x1234")
         assert success
         assert "assetPositions" in data
 
     @pytest.mark.asyncio
     async def test_health_check(self, adapter):
-        """Test health check."""
         result = await adapter.health_check()
         assert result["status"] == "healthy"
 
     def test_get_sz_decimals(self, adapter):
-        """Test getting size decimals."""
         decimals = adapter.get_sz_decimals(0)
         assert decimals == 4
 
     def test_get_sz_decimals_unknown_asset(self, adapter):
-        """Test error on unknown asset."""
         with pytest.raises(ValueError, match="Unknown asset_id"):
             adapter.get_sz_decimals(99999)