Encryption & Transport

Trading requests to GoDark are end-to-end encrypted on the WebSocket channel. The bodies the rest of the docs describe — order.place, order.cancel, order.modify — are the logical requests. Actual wire bytes are AES-256-GCM ciphertext produced by an ephemeral session key negotiated with the gateway.

This page specifies that channel: the handshake, the key derivation, the framing, and the authenticated envelope. It exists so auditors and people porting the protocol to an unsupported language can verify the wire behaviour.

Use an SDK. Do not implement this by hand for production. The official SDKs (Python today, JavaScript in progress) perform the handshake, serialize protobuf, manage nonces, and encrypt/decrypt every frame. The spec below is reference material.

Scope

REST is encrypted by TLS only. The extra layer described here is specific to authenticated WebSocket trading, where the gateway must not see plaintext orders in its logs or memory outside a well-defined decryption boundary.

Session lifecycle

A session is the unit of shared-key material. Every new WebSocket connection establishes a fresh session; the session ends when the socket closes (or a rekey is requested). The four steps, in order:

1. Authenticate the socket with op: "login" and a bearer token — see Authentication and WebSocket Trading. session.setup is rejected until login succeeds.
2. Exchange ephemeral keys. The client generates a fresh X25519 keypair per session and sends the public half via op: "session.setup". The gateway replies with its own fresh X25519 public key and an opaque session_id.
3. Derive the session key locally. Both sides run X25519 ECDH on the pair and expand through HKDF-SHA256 into a 256-bit AES key (K). The shared secret never traverses the wire.
4. Encrypt every trading op under K with AES-256-GCM. Responses (ack, order_update, position_update) are returned encrypted under the same K and decrypted client-side.

op: session.setup

Client → server, after op: "login" has succeeded on the same socket:

{
  "id": "c-2",
  "op": "session.setup",
  "args": {
    "client_ecdh_pubkey": "<base64(32 bytes)>"
  }
}

Server response:

{
  "id": "c-2",
  "op": "session.setup",
  "code": 0,
  "data": {
    "session_id": "9007199254740993",
    "server_ecdh_pubkey": "<base64(32 bytes)>"
  }
}

server_ecdh_pubkey is an ephemeral, session-scoped public key delivered in-band by the gateway. It is not a static committee identity key. The session key derived from it binds the channel to this specific (client_pk, server_pk) pair and provides forward secrecy: once the session ends and both sides discard their private halves, past traffic cannot be decrypted.

Rekey

The server may emit an unsolicited rekey_required event (for example before internal session_id exhaustion, or on a scheduled rotation). Clients MUST:

1. Stop sending encrypted ops.
2. Run session.setup again on the same socket with a fresh client keypair.
3. Reset the send-nonce counter to zero.
4. Resume encrypted ops under the new key.

Subscriptions and login state are preserved across a rekey; only the symmetric key and nonce counter are rotated.

Key derivation

Given the two 32-byte X25519 public keys (client_pk, server_pk) and the client's private key:

ikm    = X25519(client_private, server_pk)   // 32-byte shared secret
salt   = min(client_pk, server_pk) || max(client_pk, server_pk)   // 64 bytes
info   = "gdx-e2e-session-key-v1"                                 // ASCII
K      = HKDF-SHA256(ikm, salt=salt, info=info, length=32)

Rules:

• min / max is a byte-lexicographic comparison of the two raw 32-byte public keys. This makes the salt symmetric — both sides compute the same HKDF input without exchanging extra bytes.
• If ikm == 0x00…00 (32 zero bytes), the peer sent a small-subgroup public key. Clients MUST abort the session with invalid_public_key.
• info is a fixed ASCII constant. The -v1 suffix is the protocol version — if the KDF ever changes, info changes too, so old and new keys never collide.
• Output length is fixed at 32 bytes → AES-256-GCM key. There is no separate MAC key; GCM provides authenticity.

Frame encryption

AES-256-GCM, 96-bit nonce, 128-bit authentication tag. Tag is appended to the ciphertext in standard GCM concatenated form:

wire_body = AES-GCM-Encrypt(K, nonce, plaintext, aad)   // ciphertext || 16-byte tag

Nonce construction

nonce = session_id (8 bytes, big-endian)
      || counter    (4 bytes, big-endian)

Counter overflow (> 2^32 - 1 frames in one session) is a hard error — the client MUST close the session and rekey. The SDK raises EncryptionError / nonce_overflow before sending an overflowed frame.

Associated data (AAD)

Every frame carries a protobuf-encoded header as AES-GCM AAD — authenticated but not encrypted. This binds the ciphertext to routing metadata the gateway needs to read before it can decrypt, and prevents a compromised intermediary from swapping headers between frames.

Requests — OrderHeader AAD (client → server):

Responses — ResponseHeader AAD (server → client):

AAD bytes must be byte-identical to what the server produces for the same logical fields; if your protobuf encoding differs by even one byte, GCM tag verification fails with InvalidTag. In practice this means: use the generated protobuf classes from gdx-core/crates/gdx-wire/proto/, emit default-valued fields exactly as the canonical encoder does, and preserve field ordering.

Encrypted request envelope

After session.setup, trading ops carry their protobuf body encrypted. The logical args you would have sent are replaced with a single encrypted blob plus header metadata:

{
  "id": "c-10",
  "op": "order.place",
  "args": {
    "header": {
      "symbol_id": 1,
      "request_type": "place",
      "nonce": 0,
      "body_length": 158
    },
    "ciphertext": "<base64(AES-256-GCM ciphertext || 16-byte tag)>"
  }
}

• args.header is the same struct the SDK serialized as AAD. It's echoed here in JSON (not protobuf) so the gateway can route without decrypting, and the client can sanity-check what the gateway saw.
• args.ciphertext is the AES-GCM output; plaintext is the protobuf-serialized EdgeSequencerRequest (the union of PlaceOrderInput / CancelMessage / ModifyOrderInput). See each endpoint's page for the plaintext field list.
• user_uuid is intentionally omitted from the envelope. The gateway binds the session to the login-authenticated UUID; any user_uuid a client might put on the wire is ignored.

Encrypted response envelope

Responses — both the synchronous ack for a trading op and streaming channel pushes — come back the same way:

{
  "id": "c-10",
  "op": "order.place",
  "code": 0,
  "data": {
    "header": {
      "message_type": "ack",
      "body_length": 42,
      "nonce": 0,
      "fencing_epoch": 7
    },
    "ciphertext": "<base64 ciphertext || tag>"
  }
}

Stream pushes (orders, positions) follow the same shape but with channel + type + seq at the top level instead of id + op + code — see WebSocket Trading for the un-encrypted envelope skeleton.

Plaintext of an ack is a protobuf NodeResponse; plaintext of a stream push is a protobuf SequencerToEdgeMessage. Parse, then map into the public types documented in Orders Channel and Positions Channel.

Security properties

What this channel does not give you

• Authenticity of the gateway's identity. server_ecdh_pubkey is an ephemeral key delivered in-band. Clients trust it transitively through TLS + bearer-token authentication to the gateway, not through a pinned long-lived public key. If an operator rotates the edge deployment, there is no key-pinning alarm.
• Protection against a malicious gateway. A compromised gateway sees plaintext orders after decryption. The encryption layer protects orders from passive observers and from logs / traces; it does not make GoDark non-custodial with respect to the operator. Committee-held decryption keys and threshold schemes are a separate design (not this channel).

Error codes

All failures here surface through the standard error path — code non-zero on an op response, or a code-bearing event if the failure is asynchronous.

See Error Codes for the cross-cutting list.

Reference implementation

The Python SDK under gdx-sdk/python/ is the reference. The interesting files:

The JavaScript SDK reference implementation is tracked on the feat/production-readiness branch and follows the same primitives.