feat: assert minimum hyperliquid-python-sdk version at bot startup (#155)

If a stale venv ends up with an older SDK than what pyproject.toml
pins, the bot can otherwise crash deep inside the SDK during exchange
initialization with an opaque traceback. Validating the installed
version up front turns that into a single, actionable error message
and prevents watchdog crash loops on a deployment that is silently
out of sync.

The minimum is a code-level invariant (like `requires-python`) rather
than a runtime-tunable parameter, so it is kept as a module-scope
constant in `bot.py` and bumped in lockstep with the pyproject pin.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: keitaj

bot.py

@@ -1,14 +1,82 @@
 import logging
 import os
+import sys
 import time
 import signal
 import types
 import warnings
-from typing import Any, Dict, List, Optional
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from typing import Any, Dict, List, Optional, Tuple
 
 from log_config import setup_logging
 setup_logging()
 
+# ---------------------------------------------------------------------------
+# SDK compatibility gate
+# ---------------------------------------------------------------------------
+# Hyperliquid mainnet metadata evolves over time. The installed
+# ``hyperliquid-python-sdk`` must be at least this version to handle the
+# current spot universe correctly. When upgrading the SDK, bump this constant
+# in the same PR so deployed environments are validated at startup.
+MINIMUM_HYPERLIQUID_SDK_VERSION: Tuple[int, int, int] = (0, 23, 0)
+
+
+def _parse_version_tuple(version: str) -> Tuple[int, int, int]:
+    """Parse a version string into a comparable ``MAJOR.MINOR.PATCH`` tuple.
+
+    Only the first three numeric components are considered. Pre-release or
+    development suffixes (e.g. ``rc1``, ``a2``) on any component are stripped
+    so that ``0.23.0rc1`` is treated as ``(0, 23, 0)``. Missing components
+    default to 0 (``"1.0"`` becomes ``(1, 0, 0)``).
+    """
+    parts = version.split(".")
+    nums: List[int] = []
+    for part in parts[:3]:
+        digits = ""
+        for ch in part:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        nums.append(int(digits) if digits else 0)
+    while len(nums) < 3:
+        nums.append(0)
+    return (nums[0], nums[1], nums[2])
+
+
+def _assert_sdk_version() -> None:
+    """Abort startup if ``hyperliquid-python-sdk`` is below the minimum.
+
+    Exits with status 2 (configuration error) and a clear remediation message
+    so a crash loop in production can be diagnosed from a single log line
+    rather than a deep API traceback.
+    """
+    pkg = "hyperliquid-python-sdk"
+    try:
+        installed = _pkg_version(pkg)
+    except PackageNotFoundError:
+        min_str = ".".join(str(n) for n in MINIMUM_HYPERLIQUID_SDK_VERSION)
+        sys.stderr.write(
+            f"FATAL: {pkg} is not installed but is required (>= {min_str}). "
+            f"Run `pip install \".[dev]\"` from the bot repo to install all "
+            f"dependencies.\n"
+        )
+        sys.exit(2)
+
+    if _parse_version_tuple(installed) < MINIMUM_HYPERLIQUID_SDK_VERSION:
+        min_str = ".".join(str(n) for n in MINIMUM_HYPERLIQUID_SDK_VERSION)
+        sys.stderr.write(
+            f"FATAL: {pkg} {installed} is installed, but minimum required "
+            f"version is {min_str}. The bot will not function correctly with "
+            f"this SDK due to upstream API metadata changes.\n"
+            f"To fix: `pip install \".[dev]\"` from the bot repo "
+            f"(or `pip install --upgrade '{pkg}>={min_str}'`).\n"
+        )
+        sys.exit(2)
+
+
+_assert_sdk_version()
+
 from hyperliquid.exchange import Exchange  # noqa: E402
 from config import Config  # noqa: E402
 from market_data import MarketDataManager  # noqa: E402

tests/test_sdk_version_check.py

@@ -0,0 +1,215 @@
+"""Tests for the hyperliquid-python-sdk minimum-version startup gate.
+
+The gate lives at module scope in ``bot.py`` and runs at import time.
+Importing ``bot`` directly therefore has side effects (it tries to read
+the installed SDK version) and pulls in the rest of the bot. Here we
+import only the gate's helpers via a lazy importer that loads bot.py's
+source and extracts the two functions, avoiding the heavy import graph
+while still exercising the real implementation.
+"""
+
+import importlib.util
+from importlib.metadata import PackageNotFoundError
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Helpers — load the two gate functions from bot.py without executing
+# the module body (which would import hyperliquid and call _assert_sdk_version).
+# ---------------------------------------------------------------------------
+
+_BOT_PATH = Path(__file__).resolve().parent.parent / "bot.py"
+
+
+def _extract_gate_module():
+    """Compile bot.py's gate block as a standalone module.
+
+    We slice the file up to (but excluding) the ``_assert_sdk_version()``
+    invocation at module scope, so the helpers are defined but not run.
+    """
+    source = _BOT_PATH.read_text()
+    marker = "\n_assert_sdk_version()\n"
+    idx = source.index(marker)
+    head = source[:idx]
+    spec = importlib.util.spec_from_loader("bot_gate_under_test", loader=None)
+    module = importlib.util.module_from_spec(spec)
+    exec(compile(head, str(_BOT_PATH), "exec"), module.__dict__)
+    return module
+
+
+@pytest.fixture(scope="module")
+def gate():
+    return _extract_gate_module()
+
+
+def _parse(gate, v: str):
+    return gate._parse_version_tuple(v)
+
+
+def _run_assert(gate, version_or_exc):
+    """Return a patch context-manager for the gate's ``_pkg_version``.
+
+    Uses ``patch.object`` because the gate module is dynamically built and
+    not registered in ``sys.modules``, so the string-target form of
+    ``patch`` cannot locate it.
+    """
+    if isinstance(version_or_exc, Exception):
+        return patch.object(gate, "_pkg_version", side_effect=version_or_exc)
+    return patch.object(gate, "_pkg_version", return_value=version_or_exc)
+
+
+# ---------------------------------------------------------------------------
+# _parse_version_tuple
+# ---------------------------------------------------------------------------
+
+class TestParseVersionTuple:
+    def test_standard_three_components(self, gate):
+        assert _parse(gate, "0.23.0") == (0, 23, 0)
+        assert _parse(gate, "1.2.3") == (1, 2, 3)
+        assert _parse(gate, "10.20.30") == (10, 20, 30)
+
+    def test_pre_release_suffix_on_patch(self, gate):
+        # "0.23.0rc1" → digits before suffix: 0, 23, 0
+        assert _parse(gate, "0.23.0rc1") == (0, 23, 0)
+        assert _parse(gate, "0.23.0a2") == (0, 23, 0)
+        assert _parse(gate, "0.23.0.dev5") == (0, 23, 0)
+
+    def test_pre_release_suffix_on_minor(self, gate):
+        # "0.23a1.0" → minor digits "23"; patch "0"
+        assert _parse(gate, "0.23a1.0") == (0, 23, 0)
+
+    def test_two_components_pads_to_three(self, gate):
+        assert _parse(gate, "1.0") == (1, 0, 0)
+        assert _parse(gate, "2.5") == (2, 5, 0)
+
+    def test_one_component_pads_to_three(self, gate):
+        assert _parse(gate, "1") == (1, 0, 0)
+
+    def test_extra_components_ignored(self, gate):
+        # Anything beyond the first 3 is dropped.
+        assert _parse(gate, "0.23.0.1") == (0, 23, 0)
+        assert _parse(gate, "1.2.3.4.5") == (1, 2, 3)
+
+    def test_non_numeric_component_yields_zero(self, gate):
+        # A component with no leading digits → 0.
+        assert _parse(gate, "0.foo.0") == (0, 0, 0)
+        assert _parse(gate, "0.23.bar") == (0, 23, 0)
+
+    def test_ordering_consistent_with_semver(self, gate):
+        # Sanity: ordering used by the gate must match human intuition.
+        assert _parse(gate, "0.22.0") < _parse(gate, "0.23.0")
+        assert _parse(gate, "0.23.0") < _parse(gate, "0.23.1")
+        assert _parse(gate, "0.23.0") < _parse(gate, "1.0.0")
+        assert _parse(gate, "0.23.0") == _parse(gate, "0.23.0")
+
+
+# ---------------------------------------------------------------------------
+# _assert_sdk_version
+# ---------------------------------------------------------------------------
+
+class TestAssertSdkVersion:
+    def test_minimum_version_passes(self, gate, capsys):
+        """SDK == MINIMUM_HYPERLIQUID_SDK_VERSION → no exit."""
+        min_str = ".".join(str(n) for n in gate.MINIMUM_HYPERLIQUID_SDK_VERSION)
+        with _run_assert(gate, min_str):
+            # Must NOT raise SystemExit.
+            gate._assert_sdk_version()
+        captured = capsys.readouterr()
+        assert captured.err == ""
+
+    def test_above_minimum_passes(self, gate, capsys):
+        """SDK > minimum → no exit."""
+        major, minor, patch_ = gate.MINIMUM_HYPERLIQUID_SDK_VERSION
+        higher = f"{major}.{minor}.{patch_ + 1}"
+        with _run_assert(gate, higher):
+            gate._assert_sdk_version()
+        captured = capsys.readouterr()
+        assert captured.err == ""
+
+    def test_much_above_minimum_passes(self, gate, capsys):
+        """SDK far above minimum (e.g. major bump) → no exit."""
+        major, _, _ = gate.MINIMUM_HYPERLIQUID_SDK_VERSION
+        higher = f"{major + 1}.0.0"
+        with _run_assert(gate, higher):
+            gate._assert_sdk_version()
+        captured = capsys.readouterr()
+        assert captured.err == ""
+
+    def test_below_minimum_exits_with_status_2(self, gate, capsys):
+        """SDK < minimum → SystemExit(2) with remediation message."""
+        major, minor, patch_ = gate.MINIMUM_HYPERLIQUID_SDK_VERSION
+        # Construct a version strictly less than the minimum.
+        if patch_ > 0:
+            lower = f"{major}.{minor}.{patch_ - 1}"
+        elif minor > 0:
+            lower = f"{major}.{minor - 1}.0"
+        else:
+            lower = f"{major - 1}.0.0" if major > 0 else "0.0.0rc1"  # pragma: no cover
+
+        with _run_assert(gate, lower):
+            with pytest.raises(SystemExit) as exc_info:
+                gate._assert_sdk_version()
+        assert exc_info.value.code == 2
+        captured = capsys.readouterr()
+        assert "hyperliquid-python-sdk" in captured.err
+        assert lower in captured.err
+        # Remediation hint must be present.
+        assert "pip install" in captured.err
+
+    def test_package_not_installed_exits_with_status_2(self, gate, capsys):
+        """Missing SDK package → SystemExit(2)."""
+        with _run_assert(gate, PackageNotFoundError("hyperliquid-python-sdk")):
+            with pytest.raises(SystemExit) as exc_info:
+                gate._assert_sdk_version()
+        assert exc_info.value.code == 2
+        captured = capsys.readouterr()
+        assert "not installed" in captured.err
+        assert "pip install" in captured.err
+
+    def test_pre_release_of_minimum_passes(self, gate, capsys):
+        """0.23.0rc1 → parses as (0, 23, 0); passes minimum (0, 23, 0)."""
+        min_str = ".".join(str(n) for n in gate.MINIMUM_HYPERLIQUID_SDK_VERSION)
+        with _run_assert(gate, f"{min_str}rc1"):
+            gate._assert_sdk_version()
+        captured = capsys.readouterr()
+        assert captured.err == ""
+
+
+# ---------------------------------------------------------------------------
+# Constant invariant
+# ---------------------------------------------------------------------------
+
+class TestMinimumConstant:
+    def test_constant_is_three_tuple_of_ints(self, gate):
+        v = gate.MINIMUM_HYPERLIQUID_SDK_VERSION
+        assert isinstance(v, tuple)
+        assert len(v) == 3
+        assert all(isinstance(n, int) and n >= 0 for n in v)
+
+    def test_constant_matches_pyproject(self, gate):
+        """The gate's minimum must match the pin in pyproject.toml so that
+        a `pip install .` deployment satisfies the gate by construction."""
+        pyproject = (Path(__file__).resolve().parent.parent / "pyproject.toml").read_text()
+        # Find a line like:    "hyperliquid-python-sdk==X.Y.Z",
+        pinned = None
+        for raw in pyproject.splitlines():
+            line = raw.strip().strip(",").strip('"').strip("'")
+            if line.startswith("hyperliquid-python-sdk"):
+                # Strip env-marker suffix (e.g. "; python_version>=3.11") just in case.
+                line = line.split(";", 1)[0].strip()
+                for sep in ("==", ">=", "~="):
+                    if sep in line:
+                        _, pinned_str = line.split(sep, 1)
+                        pinned = pinned_str.strip()
+                        break
+                if pinned is not None:
+                    break
+        assert pinned is not None, "could not find hyperliquid-python-sdk pin in pyproject.toml"
+        pinned_tuple = gate._parse_version_tuple(pinned)
+        assert pinned_tuple >= gate.MINIMUM_HYPERLIQUID_SDK_VERSION, (
+            f"pyproject.toml pins {pinned} but bot.py requires "
+            f">= {gate.MINIMUM_HYPERLIQUID_SDK_VERSION}"
+        )