Esiur Protocol (EP) Specification

1. Overview

The Esiur Protocol (EP) [Zamil & Jasim, 2026] is a compact binary application-layer protocol for distributed object computing. It enables first-class sharing of object instances across a TCP or WebSocket connection: property values synchronize in real time, remote methods are called as if local, and events propagate transparently to every subscriber.

EP is fully self-describing: a client can discover the type schema of any resource at runtime (a TypeDef query) and generate strongly-typed proxies without out-of-band API documents. Actively maintained implementations exist for .NET and TypeScript, sharing wire concepts, packet layout, and command names byte-for-byte.

Key design properties:

• Minimal wire overhead — a 1-byte header is a complete, valid notification packet; request/reply packets add a 4-byte callback ID.
• Correlation-safe — every request carries a callback ID matched to its asynchronous reply.
• Streamable — chunked transfers, progress reports, and pausable pull/push streams for long-running operations.
• Authenticated by construction — every connection completes an authentication phase (possibly a no-op, see §4) before any session packet is exchanged.

2. Transport & URI scheme

TCP

EP runs natively over TCP. EpServer defaults to TCP port 10518 in both reference implementations; a bare ep://host URL (no explicit port) resolves to the same default. The server accepts incoming connections and immediately begins the Authentication Phase (§4).

WebSocket

EP also runs as a WebSocket sub-protocol, identifier EP (uppercase, compared case-sensitively/ordinally by both implementations). After the WebSocket handshake, the binary framing is identical to the TCP wire format: each WebSocket message carries exactly one EP packet.

URI scheme

Resources are addressed with an ep:// URL:

ep://<host>[:port]/<store>/<resource-path>

Examples
  ep://server.example.com/sys/thermostat
  ep://localhost:10518/sys/counter
  ep://iot-hub.local/sensors/temperature

The path maps directly to a resource in the server's store hierarchy, analogous to a filesystem path. Omitting the port uses 10518. A bare ep://host[:port] with no path resolves to the connection itself.

3. Connection lifecycle

Client                                        Server
  │                                               │
  │────────── TCP / WebSocket connect ───────────▶│
  │                                               │
  │◀─────── Auth: Initialize ─────────────────────│  server sends first
  │                                               │
  │──────── Auth: Action ─────────────────────────▶  zero or more rounds,
  │◀─────── Auth: Acknowledge ────────────────────│  protocol-dependent
  │                                               │
  │◀─────── Auth: SessionEstablished ─────────────│
  │                                               │
  │◀════════════ EP session packets ═════════════▶│
  │   Request / Reply / Notification              │
  │                                               │
  │────────── connection close ──────────────────▶│

Once the session is established, the connection is fully bidirectional — either peer may send Requests, Replies, or Notifications at any time. A resource attachment stays live until the connection closes or the client explicitly detaches; on reconnect, a client can reattach and resynchronize rather than re-fetch full state from scratch.

4. Authentication phase

Before any EP session packet is transmitted, both sides exchange one or more auth packets, a distinct binary format from session packets. The server always sends the first packet (Initialize). Even a connection configured for anonymous access completes this phase — it just negotiates AuthenticationMode.None with EncryptionMode.None in a single round trip.

4.1 Auth packet header byte

For every command other than Initialize, bits 4–0 (with bit 5 masked off) are instead read as a single EpAuthPacketMethod byte (§4.3) — the low 5 bits given above only apply to the very first, server-sent Initialize packet. hasTDU (bit 5) — when set, a TDU payload (§5) follows, encoding a key–value map of handshake parameters (§4.4).

4.2 Auth commands (bits 7–6)

AuthenticationMode (bits 3–2 of an Initialize packet):

EncryptionMode (bits 1–0 of an Initialize packet):

4.3 EpAuthPacketMethod (Acknowledge / Action / Event byte)

For any command other than Initialize, the byte identifies the specific handshake step:

4.4 Auth TDU header keys

The TDU payload of an auth packet is a keyed map. Integer keys 0–17 are defined:

5. TDU (Transmission Data Unit) encoding

Every value carried inside a session or auth packet — arguments, return values, property contents, handshake parameters — is encoded as a self-describing TDU. Decoders never need out-of-band schema information: each TDU carries its own type tag and, for variable-length types, its own length.

5.1 Identifier byte

For Dynamic, Typed, and Extension classes, the identifier recovered by a parser is headerByte & 0xC7 (class bits + sub-type bits only — the length-field-count bits are stripped once the length has been read). The length bytes themselves are big-endian (most-significant byte first):

5.2 Fixed class (0x00–0x2F)

Multi-byte Fixed-class payload contents (integers, floats, DateTime ticks) are little-endian — see §5.5 for verified examples. 128-bit integers are two little-endian 64-bit halves, low word first.

5.3 Dynamic class (0x40–0x47)

5.4 Typed & Extension classes

5.5 TRU (Type-Representation Unit)

A TRU describes the type of a value — either as a self-contained shape (a primitive kind, or a built-in generic like a typed list, map, or tuple) or as a compact reference to a type registered elsewhere. In source, the class is named Tru; the one place in either codebase that spells the abbreviation out (a comment in the .NET implementation) calls it a "type-representation unit."

A TRU appears on the wire in exactly two places:

• as the entire payload of a standalone TRU (0x82) TDU — used, among other places, for every property's, argument's, return value's, event's, and constant's declared value type inside a TypeDef (§5.7);
• as a metadata block immediately following a plain Typed (0x80) TDU's length prefix, describing the type of the record/enum/list/map/tuple value that follows it.

The TRU header byte is laid out as follows:

Three shapes, selected by the Extended bit (bit 6):

Confirmed identifiers for the reference and composite shapes:

The full set of primitive-shape identifiers (bare scalar kinds below 0x40) isn't reproduced here — consult TruIdentifier in either implementation's source for the exhaustive list; the mechanism above is complete regardless.

5.6 Group-varint integer encoding (GVWIE)

When a TypedList or TypedMap's element TRU is one of Int16/Int32/Int64/UInt16/UInt32/UInt64, its elements are packed with a dedicated compaction codec both codebases call GVWIE — a proper name, not an acronym expansion found anywhere in either implementation's source, comments, or commit history. (Int8/UInt8 lists have no such codec and fall back to per-element encoding.) This is a payload sub-encoding, not a TDU or TRU identifier of its own.

Each value is zig-zag encoded, then: a value whose zig-zagged magnitude fits in 7 bits is written as a single literal byte with the top bit clear ("fast path"). A run of consecutive values that don't fit is grouped behind one header byte packing a count and a shared byte width, followed by that many values at that width, least-significant byte first. Exact bit allocation for the grouped-run header differs slightly by integer width — see GroupInt16Codec/GroupInt32Codec/GroupInt64Codec (and their unsigned counterparts) in either implementation's source for the precise formula.

Verified example — the payload of a TypedList<Int32> holding [1, 2, 3], taken from a golden test vector byte-for-byte identical in both test suites:

5.7 TypeDef

A TypeDef is the schema returned in answer to a TypeDefById or TypeDefByResourceId request (§7): the name, kind, base type, and full set of exported properties, methods, events, and constants for a resource, record, enum, or function type.

Wire mechanism: a TypeDef (0x81) TDU's payload is itself a complete, self-contained plain Typed (0x80) TDU — own length prefix and TRU metadata included — whose content is a sparse map from a one-byte field index to a dynamically-typed value. Only fields that are actually present are written; there is no zero-fill for absent ones, and a receiver ignores any field index it doesn't recognize. This is what lets new optional fields be added at new indices in the future without breaking existing parsers. Every member record below (property, function, argument, event, constant) uses the same indexed-map mechanism recursively.

Indices 0x20–0x25 carry optional descriptive metadata (usage, description, example, category, since, and a string-to-string annotation map) — documentation aids, not load-bearing for interoperability.

Kind (field 0x04):

Every property, function, argument, event, and constant record shares a base shape — index 0x00 (its own member index), 0x01 (name), 0x02 (flags), plus an optional documentation block from 0x20 onward — and adds its own fields from 0x03:

5.8 Verified wire examples

Each of these is a complete TDU (identifier byte, any length bytes, payload), taken from byte-for-byte matching test vectors shared between the .NET and TypeScript test suites. See §5.6 above for a TRU/GVWIE example.

The Int32/Int64 examples above intentionally show a multi-byte payload: note the least-significant byte comes first. This is the opposite byte order from the TDU length-prefix field (§5.1), which is big-endian — the two fields are independent and use different conventions.

6. EP packet format

After the authentication phase completes, all traffic uses EP session packets. Every packet begins with a single header byte; Request and Reply packets additionally carry a 4-byte callback ID. Payloads, when present, are TDU-encoded (§5).

Verified example — a KeepAlive request (no payload) with callback ID 12:

7. Commands reference

Request commands

Reply commands carry the Request's callback ID

Notification commands no callback ID — unsolicited

8. Implementation notes

EP is specified so that independent implementations interoperate over the wire without a translation layer, and the two reference implementations agree on every packet, command, and TDU value covered above. As of this writing, a few areas are implemented in one reference implementation but not (yet) the other:

None of this affects wire compatibility for the features both implementations do support today — it's listed here so implementers building a third party don't assume behavior that isn't universal yet.

9. Security considerations

• For any internet-facing deployment, use InitializerIdentity or DualIdentity authentication together with EncryptWithSessionKey (or EncryptWithSessionKeyAndAddress) encryption — or terminate the connection inside a TLS tunnel (a wss:// reverse proxy, or a TLS-wrapping proxy in front of raw TCP), since neither reference implementation currently wraps raw TCP in transport-layer TLS automatically (§8).
• Implementations parsing TDUs from an untrusted peer should enforce a maximum declared length before allocating a buffer for the length prefix described in §5.1 — an attacker-controlled length field is an obvious resource-exhaustion vector otherwise.
• A conforming WebSocket-hosting server should require and verify the negotiated subprotocol is exactly EP (ordinal, case-sensitive) before treating a connection as an EP session, even though not every implementation enforces this yet (§8).
• Stored password verifiers should be treated as sensitive as a plaintext password: under the password-sha3-v1 protocol, possessing the stored verifier is sufficient to authenticate.
• ppap-mlkem768-v1 is available where post-quantum resistance against key material is a requirement — see the PPAP paper [Zamil & Jasim, 2025] in §10.

10. References

• A. K. Zamil and A. D. Jasim, "Esiur: A Resource-Centric Distributed Runtime Framework for Real-Time State Synchronization," IEEE Access, vol. 14, pp. 107062–107091, 2026, doi: 10.1109/ACCESS.2026.3711683. [Online]. Available: ieeexplore.ieee.org/document/11601010 — the primary reference for Esiur's resource model and this protocol (§1)
• A. K. Zamil and A. D. Jasim, "A Multi-Factor Quantum-Resistant and Privacy-Preserving Authentication Protocol for Decentralized Systems," Mesopotamian Journal of CyberSecurity, vol. 5, no. 3, pp. 1272–1291, 2025. Accessed: Jul. 22, 2026. [Online]. Available: mesopotamian.press/journals/index.php/CyberSecurity/article/view/989 — the PPAP protocol behind ppap-mlkem768-v1 (§9)
• RFC 6455 — The WebSocket Protocol
• RFC 4122 — UUID layout, referenced by the TDU UUID type
• github.com/esiur/esiur-dotnet — reference implementation, .NET
• github.com/esiur/esiur-ts — reference implementation, TypeScript