feat(websocket): add user-thread dispatch and shared-memory examples

- Upgrade slick-net integration to 3.0.0 dynamic-buffer backend
- Add caller-thread WebSocket dispatch APIs and external mux support
- Add market data examples for user-thread dispatch and shared-memory reading
- Add offline tests for dispatch routing and shared-memory attachment
- Update README and changelog for the new APIs, examples, and logging hooks

Author: kzhdev

CHANGELOG.md

@@ -12,13 +12,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Add a `market_data_websocket` example that subscribes to public testnet `allMids` and per-coin `l2Book` WebSocket updates for one or more coins.
 - Add a `market_data_websocket_per_coin` example that subscribes to ETH and BTC market data using one WebSocket connection per coin.
+- Add user-thread WebSocket dispatch support through `Info::dispatch()`, `WebsocketManager::dispatch()`, and `user_thread_dispatch` constructor options.
+- Add `Info` and `WebsocketManager` constructors that accept an external `slick::stream_buffer_multiplexer` for shared dispatch queues.
+- Add `market_data_websocket_user_thread_dispatch`, `market_data_websocket_per_coin_user_thread_dispatch`, and `market_data_websocket_shm_reader` examples.
+- Add shared-memory WebSocket buffer configuration options so external readers can attach to the market-data stream.
 
 ### Changed
 - Normalize line ending to LF
+- Update the WebSocket transport integration for `slick-net` 3.0.0 and the slick dynamic-buffer stream-buffer-multiplexer backend.
+- Move example target registration into `examples/CMakeLists.txt`.
+- Publish `market_data_websocket` records to named shared-memory segments that `market_data_websocket_shm_reader` can open.
 - Move test CMake setup into `tests/CMakeLists.txt`, register GoogleTest cases with `gtest_discover_tests()`, and keep CI integration tests running as a single executable to avoid repeated testnet setup per discovered test case.
 - Defer GoogleTest discovery to CTest with a longer discovery timeout so test executables are not run during the build.
 - Stabilize the WebSocket partial-unsubscribe integration test by waiting for the next `allMids` event instead of assuming one arrives within a fixed one-second sleep.
 
+### Tests
+- Add offline regression tests for user-thread WebSocket dispatch routing, foreign producer filtering, and shared-memory writer/reader attachment.
+
 ## [0.1.2] - 2026-06-09
 
 ### Added

CMakeLists.txt

@@ -14,18 +14,20 @@ endif()
 find_package(nlohmann_json CONFIG REQUIRED)
 find_package(OpenSSL REQUIRED)
 
-find_package(slick-net 2.1.0 CONFIG QUIET)
+find_package(slick-net 3.0.0 CONFIG QUIET)
 if (NOT slick-net_FOUND)
     message(STATUS "Fetching slick-net...")
     include(FetchContent)
+    set(BUILD_SLICK_NET_EXAMPLES OFF CACHE BOOL "" FORCE)
+    set(BUILD_SLICK_NET_TESTS OFF CACHE BOOL "" FORCE)
     FetchContent_Declare(
         slick-net
         GIT_REPOSITORY https://github.com/SlickQuant/slick-net.git
-        GIT_TAG v2.1.0
+        GIT_TAG v3.0.0
     )
     FetchContent_MakeAvailable(slick-net)
 else()
-    message(STATUS "Found slick-net: ${slick-net_DIR}")
+    message(STATUS "Found slick-net ${slick-net_VERSION}: ${slick-net_DIR}")
 endif()
 
 add_library(hyperliquid STATIC
@@ -51,14 +53,7 @@ target_link_libraries(hyperliquid PUBLIC
 )
 
 if(HYPERLIQUID_BUILD_EXAMPLES)
-    add_executable(basic_order examples/basic_order.cpp)
-    target_link_libraries(basic_order PRIVATE hyperliquid)
-
-    add_executable(market_data_websocket examples/market_data_websocket.cpp)
-    target_link_libraries(market_data_websocket PRIVATE hyperliquid)
-
-    add_executable(market_data_websocket_per_coin examples/market_data_websocket_per_coin.cpp)
-    target_link_libraries(market_data_websocket_per_coin PRIVATE hyperliquid)
+    add_subdirectory(examples)
 endif()
 
 if(HYPERLIQUID_BUILD_TESTS)

README.md

@@ -26,6 +26,8 @@ All authenticated actions are signed locally using EIP-712 / secp256k1; your pri
 - Read-only market data (`Info`): universe metadata, mid prices, order books, candles, funding history, account state
 - Authenticated trading (`Exchange`): limit/market/trigger orders, bulk ops, cancel, modify, leverage, margin, USD/spot transfers, bridge withdrawal
 - Real-time WebSocket subscriptions via `Info::subscribe` with multi-callback fan-out per channel
+- Optional caller-thread WebSocket dispatch via `Info::dispatch()` for applications that own their event loop
+- Optional shared-memory WebSocket buffers backed by `slick::stream_buffer_multiplexer`
 - Native EIP-712 signing for both L1 actions (orders, leverage) and user-signed actions (transfers) using OpenSSL secp256k1
 - `nlohmann::ordered_json` + msgpack action hashing — byte-for-byte compatible with the Python SDK signing output
 - Embedded Keccak-256 (Ethereum's pre-FIPS variant — distinct from OpenSSL's SHA3-256)
@@ -58,7 +60,7 @@ cd vcpkg
 vcpkg install nlohmann-json openssl gtest
 ```
 
-`slick-net` is the HTTP/WebSocket library used by this SDK. Install it through its own distribution and register it in the same vcpkg instance:
+`slick-net` 3.0.0 is the HTTP/WebSocket library used by this SDK. Install it through its own distribution and register it in the same vcpkg instance:
 
 ```bash
 vcpkg install slick-net
@@ -88,7 +90,10 @@ Targets produced:
 | `hyperliquid` | Static library |
 | `basic_order` | Example executable |
 | `market_data_websocket` | Public market data WebSocket example |
+| `market_data_websocket_user_thread_dispatch` | Public market data WebSocket example that dispatches callbacks on the caller thread |
 | `market_data_websocket_per_coin` | Public market data WebSocket example using one connection per coin and slick-net logging hooks |
+| `market_data_websocket_per_coin_user_thread_dispatch` | Per-coin WebSocket example using a shared dispatch multiplexer and slick-net logging hooks |
+| `market_data_websocket_shm_reader` | Shared-memory reader for records published by `market_data_websocket` |
 | `hyperliquid_tests` | Offline unit tests |
 | `hyperliquid_integration_tests` | Live testnet integration tests |
 
@@ -189,17 +194,57 @@ info->unsubscribe({{"type", "l2Book"}, {"coin", "ETH"}}, sid2);
 The WebSocket manager sends periodic pings to keep connections alive and uses
 bounded atomic shutdown checks so teardown does not wait for the full ping interval.
 
+For applications that need callbacks on their own thread, enable caller-thread dispatch
+and poll queued WebSocket records:
+
+```cpp
+hyperliquid::Info info(
+    hyperliquid::TESTNET_API_URL,
+    /*skip_ws=*/false,
+    /*user_thread_dispatch=*/true);
+
+info.subscribe({{"type", "allMids"}}, [](const nlohmann::json& msg) {
+    std::cout << msg.dump() << "\n";
+});
+
+while (running) {
+    info.dispatch();
+    std::this_thread::sleep_for(std::chrono::milliseconds(1));
+}
+```
+
 ---
 
 ## API Reference — Info
 
 Construct with:
 
 ```cpp
-hyperliquid::Info info(base_url, skip_ws = false);
+hyperliquid::Info info(
+    base_url,
+    skip_ws = false,
+    user_thread_dispatch = false,
+    mux_record_size = 1u << 18,
+    mux_shm_name = nullptr,
+    read_buffer_size = 1u << 24,
+    read_control_size = 1u << 16,
+    read_buffer_shm_name = nullptr,
+    write_buffer_size = 1u << 20);
+
+hyperliquid::Info info_with_mux(
+    base_url,
+    mux,
+    skip_ws = false,
+    user_thread_dispatch = false,
+    read_buffer_size = 1u << 24,
+    read_control_size = 1u << 16,
+    read_buffer_shm_name = nullptr,
+    write_buffer_size = 1u << 20);
 ```
 
 Setting `skip_ws = true` disables the WebSocket connection (REST-only mode, lower overhead).
+Setting `user_thread_dispatch = true` queues inbound WebSocket records in the slick stream-buffer multiplexer; call `dispatch()` to invoke matching callbacks on the caller thread.
+The multiplexer parameters can name shared-memory segments, and the external `mux` overload lets multiple `Info` instances share one dispatch queue.
 
 ### Market data
 
@@ -237,6 +282,10 @@ Candle `interval` values: `"1m"` `"5m"` `"15m"` `"30m"` `"1h"` `"4h"` `"8h"` `"1
 |--------|-------------|
 | `subscribe(sub_json, callback)` | Subscribe to a channel; returns `subscription_id` (positive int) |
 | `unsubscribe(sub_json, subscription_id)` | Remove one callback; double-unsubscribe is a no-op |
+| `websocket()` | Return the underlying `WebsocketManager*`, or `nullptr` when WebSocket support is disabled |
+| `ws_producer_id()` | Return this WebSocket's stream-buffer producer id, or `INVALID_PRODUCER_ID` when unavailable |
+| `dispatch(max_count=100)` | Scan queued records and invoke this `Info` instance's callbacks on the caller thread |
+| `dispatch(producer_id, data, length)` | Dispatch one queued message for this `Info` instance's producer id |
 | `load_meta()` | Populate `coin_to_asset`, `name_to_coin`, and `asset_to_sz_decimals` (called automatically by `Exchange`) |
 
 `coin_to_asset` maps canonical wire coins to asset ids. Perps are 0-based; spot assets use `10000 + spot index`.
@@ -419,15 +468,33 @@ Each callback receives the full message object:
 # Subscribe to allMids and l2Book updates on one WebSocket connection
 ./build/Debug/market_data_websocket ETH BTC --seconds 30
 
+# Same subscriptions, but callbacks are dispatched by the caller thread
+./build/Debug/market_data_websocket_user_thread_dispatch ETH BTC --seconds 30
+
 # Subscribe to ETH and BTC l2Book updates using one WebSocket connection per coin
 ./build/Debug/market_data_websocket_per_coin 30
+
+# Per-coin connections sharing one dispatch multiplexer
+./build/Debug/market_data_websocket_per_coin_user_thread_dispatch 30
+
+# Terminal 1: publish WebSocket records to named shared-memory segments
+./build/Debug/market_data_websocket ETH BTC --seconds 30
+
+# Terminal 2: read records from the same shared-memory segments
+./build/Debug/market_data_websocket_shm_reader --seconds 30
 ```
 
 `basic_order` places a resting limit buy on testnet and cancels it if it is resting.
 The market data examples subscribe to public testnet WebSocket feeds and print
 received updates for the requested duration.
 `market_data_websocket_per_coin` also demonstrates configuring slick-net's
 runtime logging hooks and routing `LOG_INFO` / `LOG_ERROR` output to `std::cout`.
+`market_data_websocket_per_coin_user_thread_dispatch` demonstrates the same
+slick-net logging hooks while dispatching one feed on the caller thread through
+a shared `slick::stream_buffer_multiplexer`.
+`market_data_websocket` publishes records to the `mux_queue` and `md_buf`
+shared-memory segments so `market_data_websocket_shm_reader` can attach from a
+separate process.
 
 ---
 
@@ -440,7 +507,7 @@ cmake --build build --config Debug --target hyperliquid_tests
 ctest --test-dir build -C Debug -R hyperliquid_tests -V
 ```
 
-Covers: Keccak-256 vectors, EIP-712 signing round-trips, type serialisation (`float_to_wire`, `Cloid`, `Tif`), WebSocket URL conversion, and channel identifier generation.
+Covers: Keccak-256 vectors, EIP-712 signing round-trips, type serialisation (`float_to_wire`, `Cloid`, `Tif`), WebSocket URL conversion, channel identifier generation, caller-thread WebSocket dispatch routing, and shared-memory stream-buffer attachment.
 
 ### Integration tests (requires testnet)
 

cmake/hyperliquid-config.cmake.in

@@ -1,17 +1,19 @@
 @PACKAGE_INIT@
 
 include(CMakeFindDependencyMacro)
-find_dependency(nlohmann_json CONFIG)
-find_dependency(OpenSSL)
+find_dependency(nlohmann_json CONFIG REQUIRED)
+find_dependency(OpenSSL REQUIRED)
 
-find_package(slick-net 2.1.0 CONFIG QUIET)
+find_package(slick-net 3.0.0 CONFIG QUIET)
 if (NOT slick-net_FOUND)
     message(STATUS "Fetching slick-net...")
     include(FetchContent)
+    set(BUILD_SLICK_NET_EXAMPLES OFF CACHE BOOL "" FORCE)
+    set(BUILD_SLICK_NET_TESTS OFF CACHE BOOL "" FORCE)
     FetchContent_Declare(
         slick-net
         GIT_REPOSITORY https://github.com/SlickQuant/slick-net.git
-        GIT_TAG v2.1.0
+        GIT_TAG v3.0.0
     )
     FetchContent_MakeAvailable(slick-net)
 endif()

examples/CMakeLists.txt

@@ -0,0 +1,17 @@
+add_executable(basic_order basic_order.cpp)
+target_link_libraries(basic_order PRIVATE hyperliquid)
+
+add_executable(market_data_websocket market_data_websocket.cpp)
+target_link_libraries(market_data_websocket PRIVATE hyperliquid)
+
+add_executable(market_data_websocket_user_thread_dispatch market_data_websocket_user_thread_dispatch.cpp)
+target_link_libraries(market_data_websocket_user_thread_dispatch PRIVATE hyperliquid)
+
+add_executable(market_data_websocket_per_coin market_data_websocket_per_coin.cpp)
+target_link_libraries(market_data_websocket_per_coin PRIVATE hyperliquid)
+
+add_executable(market_data_websocket_per_coin_user_thread_dispatch market_data_websocket_per_coin_user_thread_dispatch.cpp)
+target_link_libraries(market_data_websocket_per_coin_user_thread_dispatch PRIVATE hyperliquid)
+
+add_executable(market_data_websocket_shm_reader market_data_websocket_shm_reader.cpp)
+target_link_libraries(market_data_websocket_shm_reader PRIVATE hyperliquid slick::stream_buffer_multiplexer)

examples/market_data_websocket.cpp

@@ -17,6 +17,12 @@
 
 namespace {
 
+static constexpr const char* SHM_MUX_QUEUE_NAME = "mux_queue";
+static constexpr const char* SHM_MD_BUF_NAME    = "md_buf";
+static constexpr uint32_t mux_record_size = 1 << 20;
+static constexpr uint32_t read_buffer_size = 1 << 24;
+static constexpr uint32_t read_control_size = 1 << 16;
+
 struct Options {
     std::vector<std::string> coins{"ETH"};
     int seconds = 30;
@@ -99,7 +105,16 @@ int main(int argc, char* argv[]) {
         return 1;
     }
 
-    hyperliquid::Info info(hyperliquid::TESTNET_API_URL, /*skip_ws=*/false);
+    hyperliquid::Info info(
+        hyperliquid::TESTNET_API_URL,
+        /*skip_ws=*/false,
+        /*user_thread_dispatch*/false,
+        mux_record_size,
+        SHM_MUX_QUEUE_NAME,
+        read_buffer_size,
+        read_control_size,
+        SHM_MD_BUF_NAME
+    );
 
     std::mutex cout_mutex;
     std::atomic<int> all_mids_updates{0};