feat(l2_diff): implement decoding of compressed l2 diff payload and add tests

kzhdev · kzhdev · commit bc186e0111a0 · 2026-07-07T16:30:33.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,9 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `hyperliquid::decode_l2_diff(std::string_view)` — decodes the compact `data.c` binary payload from Hyperliquid's undocumented `l2` WebSocket channel into a `nlohmann::json` diff object. The payload is standard base64 → raw deflate; decoding uses `EVP_DecodeBlock` (OpenSSL, already linked) and zlib `inflate`.
+- ZLIB added as an explicit CMake dependency (`find_package(ZLIB REQUIRED)` / `ZLIB::ZLIB`); propagated to installed consumers via `find_dependency(ZLIB)` in `hyperliquid-config.cmake`.
+
 ### Changed
+- `market_data_websocket` example now connects to `MAINNET_API_URL` instead of `TESTNET_API_URL`.
 - Suppress ping message logging
 
+### Tests
+- `L2DiffDecoder.DecodesCompressedDiffPayload` — round-trip decode of a captured mainnet `l2` channel payload; asserts coin, timestamp, bid/ask levels, and removed-level arrays.
+- `L2DiffDecoder.RejectsInvalidBase64` — invalid base64 characters throw `std::invalid_argument`.
+- `L2DiffDecoder.RejectsInvalidDeflateData` — valid base64 that is not raw deflate throws `std::runtime_error`.
+- `L2DiffDecoder.RejectsNonJsonDeflatePayload` — valid raw deflate that decompresses to non-JSON throws `std::runtime_error`.
+
 ## [0.2.1] - 2026-06-23
 
 ### Added
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.21)
-project(hyperliquid-cpp VERSION 0.2.1 LANGUAGES CXX)
+project(hyperliquid-cpp VERSION 0.3.0 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -13,6 +13,7 @@ endif()
 
 find_package(nlohmann_json CONFIG REQUIRED)
 find_package(OpenSSL CONFIG REQUIRED)
+find_package(ZLIB REQUIRED)
 
 find_package(slick-net 3.0.0 CONFIG QUIET)
 if (NOT slick-net_FOUND)
@@ -35,6 +36,7 @@ add_library(hyperliquid STATIC
     src/info.cpp
     src/exchange.cpp
     src/websocket_manager.cpp
+    src/utils/l2_diff.cpp
     src/utils/signing.cpp
 )
 
@@ -49,6 +51,7 @@ target_link_libraries(hyperliquid PUBLIC
     nlohmann_json::nlohmann_json
     OpenSSL::SSL
     OpenSSL::Crypto
+    ZLIB::ZLIB
     slick::net
 )
 
diff --git a/cmake/hyperliquid-config.cmake.in b/cmake/hyperliquid-config.cmake.in
@@ -3,6 +3,7 @@
 include(CMakeFindDependencyMacro)
 find_dependency(nlohmann_json CONFIG)
 find_dependency(OpenSSL CONFIG)
+find_dependency(ZLIB)
 find_dependency(slick-net 3.0.0 CONFIG)
 
 include("${CMAKE_CURRENT_LIST_DIR}/hyperliquid-targets.cmake")
diff --git a/examples/market_data_websocket.cpp b/examples/market_data_websocket.cpp
@@ -1,4 +1,4 @@
-// WebSocket market data example: subscribe to public testnet updates.
+// WebSocket market data example: subscribe to public mainnet updates.
 // Usage: market_data_websocket [coin ...] [--seconds N]
 // Defaults: coins=ETH, seconds=30
 
@@ -106,7 +106,7 @@ int main(int argc, char* argv[]) {
     }
 
     hyperliquid::Info info(
-        hyperliquid::TESTNET_API_URL,
+        hyperliquid::MAINNET_API_URL,
         /*skip_ws=*/false,
         /*user_thread_dispatch*/false,
         mux_record_size,
@@ -158,7 +158,7 @@ int main(int argc, char* argv[]) {
         std::cout << "Listening for";
         for (const auto& coin : options.coins)
             std::cout << " " << coin;
-        std::cout << " market data on testnet for " << options.seconds << " seconds...\n";
+        std::cout << " market data on mainnet for " << options.seconds << " seconds...\n";
     }
 
     std::this_thread::sleep_for(std::chrono::seconds(options.seconds));
diff --git a/include/hyperliquid/api.hpp b/include/hyperliquid/api.hpp
@@ -15,7 +15,8 @@ class Api {
     virtual ~Api() = default;
 
     // POST `endpoint` (e.g. "/info" or "/exchange") with `payload` as JSON body.
-    // Throws std::runtime_error on HTTP 4xx/5xx.
+    // Throws Api::HttpError on HTTP 4xx/5xx.
+    // Throws std::runtime_error on network failure or malformed JSON response.
     virtual nlohmann::json post(std::string_view endpoint, const nlohmann::json& payload);
 
     struct HttpError : std::runtime_error {
diff --git a/include/hyperliquid/exchange.hpp b/include/hyperliquid/exchange.hpp
@@ -22,12 +22,18 @@ namespace hyperliquid {
 // info: shared Info instance for asset-index lookups and market data.
 // vault_address: optional sub-account / vault address; signs on behalf of it.
 // account_address: optional sub-account address; signs on behalf of it.
+//
+// All trading methods throw Api::HttpError on HTTP 4xx/5xx, std::runtime_error
+// on network or signing failure, and std::invalid_argument on non-finite or
+// unrepresentable price/size values (propagated from float_to_wire).
 class Exchange : public Api {
 public:
+    // Throws std::runtime_error if private_key_hex is not a valid secp256k1 key.
     Exchange(std::string private_key_hex,
              std::string_view base_url,
              std::shared_ptr<Info> info,
              std::optional<std::string> vault_address = {});
+    // Throws std::runtime_error if private_key_hex is not a valid secp256k1 key.
     Exchange(std::string private_key_hex,
              std::string_view base_url,
              std::shared_ptr<Info> info,
@@ -57,6 +63,7 @@ class Exchange : public Api {
                                 std::optional<Cloid> cloid = {});
 
     // Close current position at mid-price +/- slippage. Queries user_state for sz.
+    // Throws std::runtime_error if there is no open position for coin.
     nlohmann::json market_close(std::string_view coin,
                                  std::optional<double> sz = {},
                                  double slippage = 0.05,
diff --git a/include/hyperliquid/hyperliquid.hpp b/include/hyperliquid/hyperliquid.hpp
@@ -4,6 +4,7 @@
 #include <hyperliquid/utils/constants.hpp>
 #include <hyperliquid/utils/types.hpp>
 #include <hyperliquid/utils/keccak.hpp>
+#include <hyperliquid/utils/l2_diff.hpp>
 #include <hyperliquid/utils/signing.hpp>
 #include <hyperliquid/api.hpp>
 #include <hyperliquid/websocket_manager.hpp>
diff --git a/include/hyperliquid/info.hpp b/include/hyperliquid/info.hpp
@@ -17,6 +17,8 @@ namespace hyperliquid {
 
 // Read-only Hyperliquid API client.
 // Mirrors the Python SDK's Info class.
+// All REST methods throw Api::HttpError on HTTP 4xx/5xx and std::runtime_error
+// on network failure or malformed JSON response.
 class Info : public Api {
 public:
     explicit Info(
@@ -107,6 +109,8 @@ class Info : public Api {
     // Use the same JSON format as the Python SDK:
     //   {"type": "l2Book", "coin": "ETH"}
     //   {"type": "userFills", "user": "0x..."}
+    // Throws std::runtime_error if the WebSocket was not started (skip_ws=true).
+    // Throws std::runtime_error if the channel does not support multiple subscriptions.
     int subscribe(const nlohmann::json& subscription,
                   std::function<void(const nlohmann::json&)> callback);
 
@@ -149,9 +153,11 @@ class Info : public Api {
     std::string canonical_coin(std::string_view coin_or_name);
 
     // Resolve a human-readable market name or canonical coin string to an asset id.
+    // Throws std::invalid_argument if the coin is not found in the loaded metadata.
     int name_to_asset(std::string_view coin_or_name);
 
     // Ensure all asset lookup maps are populated (call before using Exchange).
+    // Throws Api::HttpError or std::runtime_error on network/HTTP failure.
     void load_meta();
 
 private:
diff --git a/include/hyperliquid/utils/l2_diff.hpp b/include/hyperliquid/utils/l2_diff.hpp
@@ -0,0 +1,15 @@
+#pragma once
+
+#include <nlohmann/json.hpp>
+
+#include <string_view>
+
+namespace hyperliquid {
+
+// Decode the compact `data.c` payload from Hyperliquid's undocumented `l2`
+// websocket channel into the JSON diff object used by the web app.
+// Throws std::invalid_argument on malformed base64 or empty payload.
+// Throws std::runtime_error on inflate failure or JSON parse failure.
+nlohmann::json decode_l2_diff(std::string_view compressed_diff);
+
+} // namespace hyperliquid
diff --git a/include/hyperliquid/utils/signing.hpp b/include/hyperliquid/utils/signing.hpp
@@ -17,15 +17,18 @@ namespace hyperliquid::signing {
 // ── Float serialisation (mirrors Python's float_to_wire) ─────────────────────
 // Formats to up to 8 decimal places, strips trailing zeros.
 // "1100.0" → "1100", "0.2" → "0.2"
+// Throws std::invalid_argument if x is non-finite or serialisation would require rounding.
 std::string float_to_wire(double x);
 
-// USD amounts: multiply by 1e6 and round to integer
+// USD amounts: multiply by 1e6 and round to integer.
+// Throws std::invalid_argument if x is non-finite or conversion requires rounding.
 int64_t float_to_usd_int(double x);
 
 // ── Wire-format helpers ───────────────────────────────────────────────────────
 
 // Convert an OrderRequest to the compact wire JSON object {a,b,p,s,r,t,?c}.
 // Uses nlohmann::ordered_json to preserve key insertion order for msgpack hashing.
+// Throws std::invalid_argument (propagated from float_to_wire) on non-finite or unrepresentable prices/sizes.
 nlohmann::ordered_json order_request_to_wire(const OrderRequest& req, int asset);
 
 // Build the "order" action {type, orders, grouping, ?builder}.
@@ -37,6 +40,7 @@ nlohmann::ordered_json order_wires_to_action(
 // ── Action hashing ────────────────────────────────────────────────────────────
 // Reproduces Python's action_hash():
 //   keccak256( msgpack(action) || nonce_be8 || vault_flag || [vault_bytes] || [expires_flag_be8] )
+// Throws std::invalid_argument if vault_address is present but not exactly 20 hex-decoded bytes.
 std::array<uint8_t, 32> action_hash(
     const nlohmann::ordered_json& action,
     const std::optional<std::string>& vault_address,
@@ -47,6 +51,8 @@ std::array<uint8_t, 32> action_hash(
 
 // Sign an L1 action (order/cancel/leverage/margin/…) using the phantom-agent
 // EIP-712 pattern with Exchange domain (chainId 1337).
+// Throws std::runtime_error on invalid private key or OpenSSL failure.
+// Throws std::invalid_argument if vault_address is malformed (propagated from action_hash).
 Signature sign_l1_action(
     std::string_view private_key_hex,
     const nlohmann::ordered_json& action,
@@ -59,6 +65,7 @@ Signature sign_l1_action(
 // with domain "HyperliquidSignTransaction" and chainId 0x66eee.
 // `action` is modified in-place to add signatureChainId and hyperliquidChain.
 // `payload_types` is a list of {field_name, solidity_type} pairs.
+// Throws std::runtime_error on invalid private key or OpenSSL failure.
 Signature sign_user_signed_action(
     std::string_view private_key_hex,
     nlohmann::ordered_json& action,
@@ -69,13 +76,15 @@ Signature sign_user_signed_action(
 // ── Key utilities ─────────────────────────────────────────────────────────────
 
 // Derive Ethereum address (checksummed lower-case "0x...") from secp256k1 private key hex.
+// Throws std::runtime_error on invalid key or OpenSSL failure.
 std::string private_key_to_address(std::string_view private_key_hex);
 
 // Current timestamp in milliseconds since UNIX epoch.
 int64_t get_timestamp_ms();
 
 // Hex helpers
 std::string bytes_to_hex(const uint8_t* data, size_t len, bool prefix = true);
+// Throws std::invalid_argument if hex has odd length.
 std::vector<uint8_t> hex_to_bytes(std::string_view hex);
 
 } // namespace hyperliquid::signing
diff --git a/include/hyperliquid/utils/types.hpp b/include/hyperliquid/utils/types.hpp
@@ -44,6 +44,7 @@ using OrderType = std::variant<LimitOrderType, TriggerOrderType>;
 
 class Cloid {
 public:
+    // Throws std::invalid_argument if raw is not "0x" followed by exactly 32 hex chars.
     explicit Cloid(std::string raw) : raw_(std::move(raw)) { validate(); }
 
     static Cloid from_int(uint64_t v) {
@@ -53,6 +54,7 @@ class Cloid {
         return Cloid{buf};
     }
 
+    // Throws std::invalid_argument if s is not "0x" followed by exactly 32 hex chars.
     static Cloid from_str(std::string_view s) {
         return Cloid{std::string(s)};
     }
diff --git a/include/hyperliquid/websocket_manager.hpp b/include/hyperliquid/websocket_manager.hpp
@@ -60,6 +60,7 @@ class WebsocketManager {
 
     // Subscribe to a channel. Returns a subscription_id for later unsubscribe.
     // `subscription` follows the Python SDK format: {"type": "l2Book", "coin": "ETH"}, etc.
+    // Throws std::runtime_error if the channel does not support multiple simultaneous subscriptions.
     int subscribe(const nlohmann::json& subscription,
                   std::function<void(const nlohmann::json&)> callback);
 
diff --git a/src/utils/l2_diff.cpp b/src/utils/l2_diff.cpp
@@ -0,0 +1,92 @@
+#include <hyperliquid/utils/l2_diff.hpp>
+
+#include <openssl/evp.h>
+#include <zlib.h>
+
+#include <array>
+#include <cctype>
+#include <cstdint>
+#include <limits>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace {
+
+std::vector<std::uint8_t> decode_base64(std::string_view input) {
+    // EVP_DecodeBlock requires whitespace-free padded input whose length is a multiple of 4
+    std::string clean;
+    clean.reserve(input.size());
+    for (unsigned char ch : input) {
+        if (!std::isspace(ch))
+            clean += static_cast<char>(ch);
+    }
+    if (clean.empty())
+        return {};
+
+    std::vector<std::uint8_t> output(clean.size() * 3 / 4);
+    const int decoded = EVP_DecodeBlock(
+        output.data(),
+        reinterpret_cast<const unsigned char*>(clean.data()),
+        static_cast<int>(clean.size()));
+    if (decoded < 0)
+        throw std::invalid_argument("Invalid base64 data");
+
+    // EVP_DecodeBlock counts '=' padding bytes as real output bytes; trim them
+    std::size_t padding = 0;
+    if (clean.size() >= 2 && clean.back() == '=') {
+        ++padding;
+        if (clean[clean.size() - 2] == '=')
+            ++padding;
+    }
+    output.resize(static_cast<std::size_t>(decoded) - padding);
+    return output;
+}
+
+} // namespace
+
+namespace hyperliquid {
+
+nlohmann::json decode_l2_diff(std::string_view compressed_diff) {
+    auto compressed = decode_base64(compressed_diff);
+    if (compressed.empty())
+        throw std::invalid_argument("Empty l2 diff payload");
+
+    if (compressed.size() > static_cast<std::size_t>(std::numeric_limits<uInt>::max()))
+        throw std::invalid_argument("l2 diff payload too large");
+
+    z_stream stream{};
+    stream.next_in = reinterpret_cast<Bytef*>(compressed.data());
+    stream.avail_in = static_cast<uInt>(compressed.size());
+
+    const int init_result = inflateInit2(&stream, -MAX_WBITS);
+    if (init_result != Z_OK)
+        throw std::runtime_error("Failed to initialize raw deflate decoder");
+
+    std::string inflated;
+    inflated.reserve(compressed.size() * 4);
+    std::array<char, 65536> buffer;
+
+    try {
+        int result = Z_OK;
+        while (result != Z_STREAM_END) {
+            stream.next_out = reinterpret_cast<Bytef*>(buffer.data());
+            stream.avail_out = static_cast<uInt>(buffer.size());
+
+            result = inflate(&stream, Z_NO_FLUSH);
+            if (result != Z_OK && result != Z_STREAM_END) {
+                throw std::runtime_error("Failed to inflate l2 diff payload");
+            }
+
+            inflated.append(buffer.data(), buffer.size() - stream.avail_out);
+        }
+    } catch (...) {
+        inflateEnd(&stream);
+        throw;
+    }
+
+    inflateEnd(&stream);
+    return nlohmann::json::parse(inflated);
+}
+
+} // namespace hyperliquid
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
@@ -5,6 +5,7 @@ add_executable(hyperliquid_tests
     test_keccak.cpp
     test_types.cpp
     test_signing.cpp
+    test_l2_diff.cpp
     test_exchange.cpp
     test_websocket_utils.cpp
     test_websocket_dispatch.cpp
diff --git a/tests/test_l2_diff.cpp b/tests/test_l2_diff.cpp
