Add docs

developer_docs/transport/LIBUDX.md

@@ -0,0 +1,38 @@
+# Transport — Official libudx
+
+## Decision
+
+HyperDart binds the **official Holepunch libudx** C library via Dart FFI.
+
+It deliberately does **not** use the pub.dev package `dart_udx`. That package implements a different on-the-wire format and would break interoperability with the existing Hyperswarm network.
+
+## What libudx Provides
+
+- Reliable, ordered, congestion-controlled streams over UDP
+- Multiplexing of many streams over a single UDP socket
+- Built-in support for the holepunch and relay patterns used by HyperDHT
+- The exact packet formats and stream identifiers expected by Node `udx-native`
+
+## Integration Points
+
+Higher layers obtain UDX capabilities through:
+
+- `Udx` / socket / stream objects exposed by `package:udx`
+- The `SocketPool` inside HyperDHT
+- Direct use only when writing low-level tests or custom transports
+
+## Build Requirements
+
+See [guides/BUILDING_NATIVE.md](../guides/BUILDING_NATIVE.md).
+
+Critical points:
+
+- Position-independent code (`-fPIC` / `CMAKE_POSITION_INDEPENDENT_CODE=ON`)
+- Matching libuv built with the same flags
+- The CMake target produces `libhyper_udx` (shared library) that the Dart FFI loader can open
+
+## Lifecycle Ownership
+
+- Long-lived sockets are owned by HyperDHT’s `SocketPool`.
+- Individual streams are owned by the secret-stream or relay connection that created them.
+- Application code should rarely call `dispose` on UDX objects directly; going through the high-level close/destroy methods is preferred.