wayfinder-paths 0.1.29__py3-none-any.whl → 0.1.31__py3-none-any.whl

wayfinder_paths/mcp/tools/quotes.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
-import re
 from typing import Any
 
 from wayfinder_paths.core.clients.BRAPClient import BRAPClient
 from wayfinder_paths.core.clients.TokenClient import TokenClient
-from wayfinder_paths.core.constants.chains import CHAIN_CODE_TO_ID
+from wayfinder_paths.mcp.tools.execute import (
+    _resolve_token_meta,
+    _select_token_chain,
+)
 from wayfinder_paths.mcp.utils import (
     err,
     find_wallet_by_label,
@@ -15,131 +17,49 @@ from wayfinder_paths.mcp.utils import (
 )
 
 
-def _chain_id(token: dict[str, Any]) -> int | None:
-    # Token payloads often include a database/internal `id` field; do not treat that as a chain id.
-    if token.get("chain_id") is not None:
-        try:
-            return int(token.get("chain_id"))
-        except (TypeError, ValueError):
-            return None
-
-    chain = token.get("chain") or {}
-    if not isinstance(chain, dict):
-        return None
-
-    for key in ("chain_id", "chainId", "id"):
-        if chain.get(key) is None:
-            continue
-        try:
-            return int(chain.get(key))
-        except (TypeError, ValueError):
-            return None
-
-    return None
-
-
-_SIMPLE_CHAIN_SUFFIX_RE = re.compile(r"^[a-z0-9]+\s+[a-z0-9-]+$", re.IGNORECASE)
-_ASSET_CHAIN_SPLIT_RE = re.compile(
-    r"^(?P<asset>[a-z0-9]+)[- _](?P<chain>[a-z0-9-]+)$", re.IGNORECASE
-)
+def _slippage_float(slippage_bps: int) -> float:
+    return max(0.0, float(int(slippage_bps)) / 10_000.0)
 
 
-def _normalize_token_query(query: str) -> str:
-    q = " ".join(str(query).strip().split())
-    if not q or "-" in q or "_" in q:
-        return q
-    if not _SIMPLE_CHAIN_SUFFIX_RE.match(q):
-        return q
-    asset, chain_code = q.rsplit(" ", 1)
-    if chain_code.lower() in CHAIN_CODE_TO_ID:
-        return f"{asset}-{chain_code}"
-    return q
+def _unwrap_brap_quote_response(
+    data: Any,
+) -> tuple[list[dict[str, Any]], dict[str, Any] | None, int]:
+    """
+    BRAP quote responses have historically appeared in two shapes:
 
+    1) {"quotes": [...], "best_quote": {...}}
+    2) {"quotes": {"all_quotes": [...], "best_quote": {...}, "quote_count": N}}
 
-def _is_eth_like_token(meta: dict[str, Any]) -> bool:
-    asset_id = str(meta.get("asset_id") or "").lower()
-    symbol = str(meta.get("symbol") or "").lower()
-    return asset_id == "ethereum" or symbol == "eth"
+    This helper normalizes both to (all_quotes, best_quote, quote_count).
+    """
+    if not isinstance(data, dict):
+        return [], None, 0
 
+    raw_quotes = data.get("quotes")
+    best_quote = data.get("best_quote")
 
-def _split_asset_chain(query: str) -> tuple[str, str] | None:
-    q = str(query).strip()
-    if not q:
-        return None
-    m = _ASSET_CHAIN_SPLIT_RE.match(q)
-    if not m:
-        return None
-    return m.group("asset").lower(), m.group("chain").lower()
+    if isinstance(raw_quotes, list) or isinstance(best_quote, dict):
+        all_quotes = raw_quotes if isinstance(raw_quotes, list) else []
+        best = best_quote if isinstance(best_quote, dict) else None
+        return all_quotes, best, len(all_quotes)
 
+    # Legacy/nested payload under `quotes`
+    if isinstance(raw_quotes, dict):
+        all_quotes = raw_quotes.get("all_quotes") or raw_quotes.get("quotes") or []
+        if not isinstance(all_quotes, list):
+            all_quotes = []
+        best = raw_quotes.get("best_quote")
+        best_out = best if isinstance(best, dict) else None
 
-async def _resolve_token_meta(
-    token_client: TokenClient,
-    *,
-    query: str,
-) -> tuple[str, dict[str, Any]]:
-    q = _normalize_token_query(query)
-    split = _split_asset_chain(q)
-    if split:
-        asset, chain_code = split
-        if asset in {"eth", "ethereum"}:
-            try:
-                gas_meta = await token_client.get_gas_token(chain_code)
-                if isinstance(gas_meta, dict) and _is_eth_like_token(gas_meta):
-                    return q, gas_meta
-            except Exception:
-                pass
-    meta = await token_client.get_token_details(q)
-    return q, meta
-
-
-def _infer_chain_code_from_query(query: str, meta: dict[str, Any]) -> str | None:
-    q = str(query).strip().lower()
-    if not q:
-        return None
-
-    candidates: set[str] = {str(k).lower() for k in CHAIN_CODE_TO_ID.keys()}
-    addrs = meta.get("addresses") or {}
-    if isinstance(addrs, dict):
-        candidates.update(str(k).lower() for k in addrs.keys())
-
-    best: str | None = None
-    for code in candidates:
-        if q.endswith(f"-{code}"):
-            if best is None or len(code) > len(best):
-                best = code
-    return best
-
-
-def _address_for_chain(meta: dict[str, Any], chain_code: str) -> str | None:
-    addrs = meta.get("addresses") or {}
-    if not isinstance(addrs, dict):
-        return None
-    for key, val in addrs.items():
-        if str(key).lower() == chain_code and val:
-            return str(val)
-    return None
-
-
-def _select_token_chain(
-    meta: dict[str, Any], *, query: str
-) -> tuple[int | None, str | None]:
-    chain_id = _chain_id(meta)
-    token_address = meta.get("address")
-
-    desired_chain = _infer_chain_code_from_query(query, meta)
-    if desired_chain:
-        addr = _address_for_chain(meta, desired_chain)
-        if addr:
-            token_address = addr
-        if desired_chain in CHAIN_CODE_TO_ID:
-            chain_id = CHAIN_CODE_TO_ID[desired_chain]
-
-    token_address_out = str(token_address).strip() if token_address else None
-    return chain_id, token_address_out
+        quote_count = raw_quotes.get("quote_count")
+        try:
+            quote_count_i = int(quote_count)
+        except (TypeError, ValueError):
+            quote_count_i = len(all_quotes)
 
+        return all_quotes, best_out, quote_count_i
 
-def _slippage_float(slippage_bps: int) -> float:
-    return max(0.0, float(int(slippage_bps)) / 10_000.0)
+    return [], None, 0
 
 
 async def quote_swap(
@@ -205,13 +125,7 @@ async def quote_swap(
     except Exception as exc:  # noqa: BLE001
         return err("quote_error", str(exc))
 
-    # API returns {"quotes": [...], "best_quote": {...}} at top level
-    raw_quotes = data.get("quotes", []) if isinstance(data, dict) else []
-    if not isinstance(raw_quotes, list):
-        raw_quotes = []
-    all_quotes = raw_quotes
-    best_quote = data.get("best_quote") if isinstance(data, dict) else None
-    quote_count = len(all_quotes)
+    all_quotes, best_quote, quote_count = _unwrap_brap_quote_response(data)
 
     providers: list[str] = []
     seen: set[str] = set()

wayfinder_paths/strategies/basis_trading_strategy/manifest.yaml

@@ -0,0 +1,24 @@
+schema_version: "0.1"
+entrypoint: "wayfinder_paths.strategies.basis_trading_strategy.strategy.BasisTradingStrategy"
+permissions:
+  policy: |
+    (wallet.id == 'FORMAT_WALLET_ID') AND (
+      # Allow Hyperliquid EIP-712 order/transfer actions
+      (action.type == 'hyperliquid_order') OR
+      (action.type == 'hyperliquid_cancel') OR
+      (action.type == 'hyperliquid_transfer') OR
+      (action.type == 'hyperliquid_withdraw') OR
+      # Allow USDC transfers to Hyperliquid bridge
+      (action.type == 'erc20_transfer' AND action.to == '0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7') OR
+      # Allow withdrawals to main wallet
+      (action.type == 'erc20_transfer' AND action.to == main_wallet.address)
+    )
+adapters:
+  - name: "BALANCE"
+    capabilities: ["wallet_read", "wallet_transfer"]
+  - name: "LEDGER"
+    capabilities: ["ledger.read", "ledger.write", "strategy.transactions"]
+  - name: "TOKEN"
+    capabilities: ["token.read"]
+  - name: "HYPERLIQUID"
+    capabilities: ["market.read", "market.meta", "market.funding", "market.candles", "market.orderbook", "order.execute", "order.cancel", "position.manage", "transfer", "withdraw"]

wayfinder_paths/strategies/basis_trading_strategy/strategy.py

@@ -58,7 +58,6 @@ from wayfinder_paths.core.strategies.descriptors import (
     Volatility,
 )
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
-from wayfinder_paths.core.types import HyperliquidSignCallback
 from wayfinder_paths.policies.erc20 import any_erc20_function
 from wayfinder_paths.policies.hyperliquid import (
     any_hyperliquid_l1_payload,
@@ -182,7 +181,7 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
         *,
         main_wallet: dict[str, Any] | None = None,
         strategy_wallet: dict[str, Any] | None = None,
-        strategy_sign_typed_data: HyperliquidSignCallback | None = None,
+        strategy_sign_typed_data: Callable[[dict], Awaitable[str]] | None = None,
         main_wallet_signing_callback: Callable[[dict], Awaitable[str]] | None = None,
         strategy_wallet_signing_callback: Callable[[dict], Awaitable[str]]
         | None = None,
@@ -516,11 +515,14 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
                     f"Found ${strategy_usdc:.2f} USDC in strategy wallet, bridging to Hyperliquid"
                 )
 
+                # Convert USDC to raw units (6 decimals)
+                usdc_raw = int(strategy_usdc * 1e6)
                 success, result = await self.balance_adapter.send_to_address(
                     token_id=USDC_ARBITRUM_TOKEN_ID,
-                    amount=strategy_usdc,
+                    amount=usdc_raw,
                     from_wallet=strategy_wallet,
                     to_address=HYPERLIQUID_BRIDGE,
+                    signing_callback=self.strategy_wallet_signing_callback,
                 )
 
                 if not success:
@@ -560,7 +562,7 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
                 self.logger.warning(f"Failed to bridge USDC to Hyperliquid: {e}")
 
         if self.current_position is None:
-            return await self._find_and_open_position()
+            return await self._find_and_open_position(rotation_reason="initial_open")
 
         # Monitor existing position (handles idle capital, leg balance, stop-loss)
         return await self._monitor_position()
@@ -1030,7 +1032,9 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
     # Position Management                                                 #
     # ------------------------------------------------------------------ #
 
-    async def _find_and_open_position(self) -> StatusTuple:
+    async def _find_and_open_position(
+        self, *, rotation_reason: str | None = None
+    ) -> StatusTuple:
         self.logger.info("Analyzing basis trading opportunities...")
 
         try:
@@ -1256,6 +1260,19 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
                 entry_timestamp=int(time.time() * 1000),
             )
 
+            try:
+                await self._record_rotation(
+                    coin=coin,
+                    spot_asset_id=int(spot_asset_id),
+                    perp_asset_id=int(perp_asset_id),
+                    spot_units=float(spot_filled),
+                    perp_units=float(perp_filled),
+                    leverage=int(leverage),
+                    reason=rotation_reason,
+                )
+            except Exception as exc:  # noqa: BLE001
+                self.logger.debug(f"Failed to record rotation: {exc}")
+
             return (
                 True,
                 f"Opened basis position on {coin}: {spot_filled:.4f} units at {leverage}x, expected net APY: {expected_net_apy_pct:.1f}%",
@@ -1269,6 +1286,128 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
     # Position Scaling                                                    #
     # ------------------------------------------------------------------ #
 
+    async def _unused_usd_now(
+        self,
+        state: dict[str, Any],
+        *,
+        mid_prices: dict[str, Any] | None = None,
+    ) -> tuple[float, float]:
+        """Estimate deployable idle USDC without mistaking perp PnL for new cash.
+
+        `marginSummary.withdrawable` can increase just because the perp leg moves in our favor
+        (unrealized PnL), which frees margin but does not represent a fresh cash deposit.
+        This helper estimates idle capital by comparing current bankroll to what's allocated
+        to the delta-neutral position.
+
+        Returns:
+        - unused_usd: estimated deployable idle USDC.
+        - bankroll_now: estimated bankroll backing the position (perp equity + spot value + spot USDC).
+        """
+        if self.current_position is None:
+            return 0.0, 0.0
+
+        coin = self.current_position.coin
+
+        perp_position = self._get_perp_position(state)
+        if perp_position is None:
+            return 0.0, 0.0
+
+        if mid_prices is None:
+            success, mids = await self.hyperliquid_adapter.get_all_mid_prices()
+            if not success:
+                return 0.0, 0.0
+            mid_prices = mids
+
+        current_price = float(self._resolve_mid_price(coin, mid_prices) or 0.0)
+        if current_price <= 0:
+            return 0.0, 0.0
+
+        # Spot side: only track the strategy coin + USDC. (Other balances are ignored for safety.)
+        address = self._get_strategy_wallet_address()
+        spot_units = 0.0
+        spot_usdc = 0.0
+        success, spot_state = await self.hyperliquid_adapter.get_spot_user_state(
+            address
+        )
+        if success:
+            for bal in spot_state.get("balances", []):
+                bal_coin = str(bal.get("coin", ""))
+                try:
+                    total = float(bal.get("total", 0) or 0.0)
+                except (TypeError, ValueError):
+                    continue
+
+                if bal_coin == "USDC":
+                    spot_usdc = total
+                elif self._coins_match(bal_coin, coin):
+                    spot_units = abs(total)
+
+        spot_value = spot_units * current_price
+
+        # Perp side (account value includes margin + unrealized PnL + funding).
+        margin_summary = state.get("marginSummary") or {}
+        try:
+            perp_equity = float(margin_summary.get("accountValue", 0) or 0.0)
+        except (TypeError, ValueError):
+            perp_equity = 0.0
+
+        bankroll_now = perp_equity + spot_value + spot_usdc
+
+        # Position sizing inputs.
+        try:
+            perp_units = abs(float(perp_position.get("szi", 0) or 0.0))
+        except (TypeError, ValueError):
+            perp_units = 0.0
+
+        if perp_units <= 0 or spot_units <= 0:
+            return 0.0, bankroll_now
+
+        entry_px_raw = perp_position.get("entryPx") or self.current_position.entry_price
+        try:
+            perp_entry_price = float(entry_px_raw or 0.0)
+        except (TypeError, ValueError):
+            perp_entry_price = 0.0
+
+        if perp_entry_price <= 0:
+            return 0.0, bankroll_now
+
+        leverage = float(
+            self.current_position.leverage or self.DEFAULT_MAX_LEVERAGE or 1
+        )
+        lev_raw = perp_position.get("leverage")
+        if isinstance(lev_raw, dict):
+            try:
+                leverage = float(lev_raw.get("value") or leverage)
+            except (TypeError, ValueError):
+                pass
+        elif lev_raw is not None:
+            try:
+                leverage = float(lev_raw)
+            except (TypeError, ValueError):
+                pass
+        if leverage <= 0:
+            leverage = 1.0
+
+        funding_since_open = 0.0
+        cum_funding = perp_position.get("cumFunding") or {}
+        if isinstance(cum_funding, dict):
+            try:
+                funding_since_open = abs(float(cum_funding.get("sinceOpen", 0) or 0.0))
+            except (TypeError, ValueError):
+                funding_since_open = 0.0
+
+        # Margin+PnL contribution of the perp leg for a short at leverage L.
+        current_perp_contrib = (
+            perp_entry_price * (1.0 + 1.0 / leverage) - current_price
+        ) * perp_units
+        # Conservative guard: don't let extreme loss create fake "unused" capital.
+        current_perp_contrib = max(0.0, current_perp_contrib)
+
+        allocated_now = current_perp_contrib + spot_value + funding_since_open
+        unused_usd = max(0.0, bankroll_now - allocated_now)
+
+        return unused_usd, bankroll_now
+
     async def _get_undeployed_capital(self) -> tuple[float, float]:
         address = self._get_strategy_wallet_address()
 
@@ -1496,7 +1635,9 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
                     False,
                     f"Emergency rebalance failed - could not close: {close_msg}",
                 )
-            return await self._find_and_open_position()
+            return await self._find_and_open_position(
+                rotation_reason="near_liquidation"
+            )
 
         needs_rebalance, reason = await self._needs_new_position(state, hl_value)
 
@@ -1515,7 +1656,7 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
             if not close_success:
                 return (False, f"Rebalance failed - could not close: {close_msg}")
 
-            return await self._find_and_open_position()
+            return await self._find_and_open_position(rotation_reason=str(reason))
 
         leg_ok, leg_msg = await self._verify_leg_balance(state)
         if not leg_ok:
@@ -1526,15 +1667,14 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
             else:
                 actions_taken.append(f"Leg imbalance repair failed: {repair_msg}")
 
-        perp_margin, spot_usdc = await self._get_undeployed_capital()
-        total_idle = perp_margin + spot_usdc
-        min_deploy = max(self.MIN_UNUSED_USD, self.UNUSED_REL_EPS * self.deposit_amount)
+        unused_usd, bankroll_now = await self._unused_usd_now(state)
+        min_deploy = max(self.MIN_UNUSED_USD, self.UNUSED_REL_EPS * bankroll_now)
 
-        if total_idle > min_deploy:
+        if unused_usd > min_deploy:
             self.logger.info(
-                f"Found ${total_idle:.2f} idle capital, scaling up position"
+                f"Found ${unused_usd:.2f} deployable idle USDC, scaling up position"
             )
-            scale_ok, scale_msg = await self._scale_up_position(total_idle)
+            scale_ok, scale_msg = await self._scale_up_position(unused_usd)
             if scale_ok:
                 actions_taken.append(f"Scaled up: {scale_msg}")
                 # Refresh state after scale-up so stop-loss uses new position size/liq price
@@ -1551,16 +1691,23 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
             actions_taken.append(sl_msg)
 
         position_age_hours = (time.time() * 1000 - pos.entry_timestamp) / (1000 * 3600)
+        rotation_hint = ""
+        try:
+            rotation_hint = await self._rotation_cooldown_hint()
+        except Exception as exc:  # noqa: BLE001
+            self.logger.debug(f"Could not compute rotation cooldown hint: {exc}")
 
         if actions_taken:
+            suffix = f". Rotation: {rotation_hint}" if rotation_hint else ""
             return (
                 True,
-                f"Position on {coin} monitored, age: {position_age_hours:.1f}h. Actions: {'; '.join(actions_taken)}",
+                f"Position on {coin} monitored, age: {position_age_hours:.1f}h. Actions: {'; '.join(actions_taken)}{suffix}",
             )
 
+        suffix = f". Rotation: {rotation_hint}" if rotation_hint else ""
         return (
             True,
-            f"Position on {coin} healthy, age: {position_age_hours:.1f}h",
+            f"Position on {coin} healthy, age: {position_age_hours:.1f}h{suffix}",
         )
 
     async def _is_near_liquidation(self, state: dict[str, Any]) -> tuple[bool, str]:
@@ -2129,6 +2276,44 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
     # Rotation Cooldown                                                   #
     # ------------------------------------------------------------------ #
 
+    async def _record_rotation(
+        self,
+        *,
+        coin: str,
+        spot_asset_id: int,
+        perp_asset_id: int,
+        spot_units: float,
+        perp_units: float,
+        leverage: int,
+        reason: str | None = None,
+    ) -> None:
+        """Write a rotation marker to the local ledger so cooldown survives restarts."""
+        if not self.ledger_adapter:
+            return
+
+        wallet_address = self._get_strategy_wallet_address()
+        op_data: dict[str, Any] = {
+            "type": "BASIS_ROTATION",
+            "coin": str(coin),
+            "spot_asset_id": int(spot_asset_id),
+            "perp_asset_id": int(perp_asset_id),
+            "spot_units": float(spot_units),
+            "perp_units": float(perp_units),
+            "leverage": int(leverage),
+        }
+        if reason:
+            op_data["reason"] = str(reason)
+
+        try:
+            await self.ledger_adapter.ledger_client.add_strategy_operation(
+                wallet_address=wallet_address,
+                operation_data=op_data,
+                usd_value="0",
+                strategy_name=self.name or "basis_trading_strategy",
+            )
+        except Exception as exc:  # noqa: BLE001
+            self.logger.debug(f"Failed to write BASIS_ROTATION to ledger: {exc}")
+
     async def _get_last_rotation_time(self) -> datetime | None:
         wallet_address = self._get_strategy_wallet_address()
 
@@ -2146,16 +2331,20 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
                 else []
             )
             for txn in tx_list:
-                op_data = txn.get("op_data", {})
-                if (
-                    op_data.get("type") == "HYPE_SPOT"
-                    and op_data.get("buy_or_sell") == "buy"
-                ):
-                    created_str = txn.get("created")
-                    if created_str:
-                        return datetime.fromisoformat(
-                            str(created_str).replace("Z", "+00:00")
-                        )
+                op_data = txn.get("op_data") or {}
+                op_type = str(
+                    txn.get("operation")
+                    or (op_data.get("type") if isinstance(op_data, dict) else "")
+                    or ""
+                )
+                if op_type != "BASIS_ROTATION":
+                    continue
+
+                created_str = txn.get("created") or txn.get("timestamp")
+                if created_str:
+                    return datetime.fromisoformat(
+                        str(created_str).replace("Z", "+00:00")
+                    )
 
             return None
         except Exception as e:
@@ -2175,14 +2364,45 @@ class BasisTradingStrategy(BasisSnapshotMixin, Strategy):
         if last_rotation.tzinfo is None:
             last_rotation = last_rotation.replace(tzinfo=UTC)
 
-        elapsed = now - last_rotation
         cooldown = timedelta(days=self.ROTATION_MIN_INTERVAL_DAYS)
 
-        if elapsed >= cooldown:
+        unlock_at = last_rotation + cooldown
+        remaining = unlock_at - now
+
+        if remaining <= timedelta(0):
             return True, "Cooldown passed"
 
-        remaining = cooldown - elapsed
-        return False, f"Rotation cooldown: {remaining.days} days remaining"
+        days = remaining.days
+        hours = remaining.seconds // 3600
+        unlock_str = unlock_at.strftime("%Y-%m-%d %H:%M UTC")
+        return (
+            False,
+            f"Rotation cooldown: {days}d {hours}h remaining (unlocks {unlock_str})",
+        )
+
+    async def _rotation_cooldown_hint(self) -> str:
+        """Human-readable rotation cooldown status for update() output."""
+        if self.current_position is None:
+            return ""
+
+        last_rotation = await self._get_last_rotation_time()
+        if last_rotation is None:
+            return "unlocked (cooldown inactive; no rotation recorded)"
+
+        now = datetime.now(UTC)
+        if last_rotation.tzinfo is None:
+            last_rotation = last_rotation.replace(tzinfo=UTC)
+
+        cooldown = timedelta(days=self.ROTATION_MIN_INTERVAL_DAYS)
+        unlock_at = last_rotation + cooldown
+        remaining = unlock_at - now
+        if remaining <= timedelta(0):
+            return "unlocked (cooldown passed)"
+
+        days = remaining.days
+        hours = remaining.seconds // 3600
+        unlock_str = unlock_at.strftime("%Y-%m-%d %H:%M UTC")
+        return f"{days}d {hours}h remaining (unlocks {unlock_str})"
 
     # ------------------------------------------------------------------ #
     # Live Portfolio Value                                                #