Network Stack

Discord-PXE owns the networking path needed by the Discord runtime instead of delegating to an operating-system socket API.

The singleton implementation remains the reference path while the sharded transport moves connection-specific state into explicit contexts.

Primary sources:

• legacy_ip_stack.inc
• legacy_net_core.inc
• legacy_shard_tcp.inc

Layer model

NIC / Ethernet
      │
      ▼
ARP / IPv4
      │
      ▼
TCP
      │
      ▼
TLS
      │
      ▼
HTTP / WebSocket
      │
      ▼
Discord Gateway

The project is intentionally explicit about these boundaries because each one has different state and failure behavior.

Shared lower layer, private connection layer

The sharded TCP source describes the intended split directly:

each active shard gets its own local port and sequence space while sharing the machine's IPv4/ARP layer and gateway IP.

That distinction is important.

The physical machine has one interface and one IP identity, but multiple outbound TCP connections still require independent:

• local source ports
• local sequence values
• remote sequence values
• retry state
• callback state
• receive/transmit counters
• reset/failure state

Per-shard TCP context

The TCP workspace stores fields such as:

state
local sequence
remote sequence
retry timer
retry count
local port
remote IP
receive callback
receive callback argument
RX/TX counters
bad packet counter
RST counter
destination MAC

The shard descriptor points to this workspace through SHARD_OFF_TCP_CTX.

Local port derivation

Each shard derives a source port from its shard ID:

base 50000 + (shard_id & 0x0FFF)

This gives active shards distinct connection identities without requiring a full operating-system ephemeral-port allocator.

Port derivation is a design constraint

Mask-based derivation is simple and deterministic, but it is not equivalent to a general-purpose ephemeral-port allocator. Scaling assumptions still need to respect collision behavior and the local shard model.

Remote endpoint

The sharded Discord TCP client targets port 443.

The IP layer and route resolution remain machine-level concerns, while TCP connection state remains shard-level.

TCP checksum

The shard TCP implementation constructs the pseudo-header checksum from:

• local IPv4 address
• remote IPv4 address
• protocol number
• TCP length
• TCP header/payload

The checksum routine handles odd payload lengths and folds the accumulator into the final one's-complement result.

This code runs without a kernel networking stack beneath it.

Packet construction

A send operation constructs:

source port
destination port
local sequence
remote sequence / ACK
header length
flags
window
checksum
urgent pointer
payload

The implementation bounds payload size with SHARD_TCP_MAX_PAYLOAD before copying data into the transmit buffer.

Code example of building a TCP header

NASM equivalent

; RDI = output TCP header, RBX = per-shard TCP context
mov ax, [rbx + STCP_LOCAL_PORT]
xchg al, ah
mov [rdi + 0], ax

mov ax, SHARD_TCP_REMOTE_PORT
xchg al, ah
mov [rdi + 2], ax

mov eax, [rbx + STCP_LOCAL_SEQ]
bswap eax
mov [rdi + 4], eax

mov eax, [rbx + STCP_REMOTE_SEQ]
bswap eax
mov [rdi + 8], eax

mov byte [rdi + 12], 0x50       ; 20-byte header
mov byte [rdi + 13], dl         ; caller-supplied flags
mov word [rdi + 16], 0          ; checksum filled later

This is a compact teaching equivalent of the packet-building path; the real routine also fills window/checksum/payload-related fields.

Execution order

1. Write the shard's local source port.
2. Write destination port 443.
3. Write the local TCP sequence number.
4. Write the remote acknowledgement number.
5. Encode header length and TCP flags.
6. Leave checksum zero while the pseudo-header and payload are assembled.
7. Compute and write the checksum before transmission.

Rust

fn build_tcp_header(ctx: &TcpContext, flags: u8) -> TcpHeader {
    TcpHeader {
        source_port: ctx.local_port as u16,
        destination_port: 443,
        sequence: ctx.local_sequence,
        acknowledgement: ctx.remote_sequence,
        flags,
        window: ctx.receive_window,
        checksum: 0,
    }
}

C

struct tcp_header build_tcp_header(const struct tcp_ctx *ctx, uint8_t flags) {
    return (struct tcp_header) {
        .source_port = (uint16_t)ctx->local_port,
        .destination_port = 443,
        .sequence = ctx->local_sequence,
        .acknowledgement = ctx->remote_sequence,
        .flags = flags,
        .window = ctx->receive_window,
        .checksum = 0,
    };
}

Python

def build_tcp_header(ctx, flags):
    return {
        "source_port": ctx.local_port,
        "destination_port": 443,
        "sequence": ctx.local_sequence,
        "acknowledgement": ctx.remote_sequence,
        "flags": flags,
        "window": ctx.receive_window,
        "checksum": 0,
    }

That protects the fixed packet-building path from oversized caller requests.

Callbacks bind TCP upward

The TCP workspace stores an RX callback and argument.

Higher layers can therefore bind a specific shard's TCP input to that shard's TLS parser without global dispatch guessing which connection received the bytes.

This is one of the critical conversions away from singleton state.

Connection states

The sharded TCP state machine includes:

IDLE
WAIT_ARP
SYN_SENT
UP
FAILED
CLOSED

Lifecycle code can inspect the TCP state directly when deciding whether a shard needs backoff/reset.

Why keep the singleton implementation?

The singleton transport remains valuable because it answers whether a failure is:

network/protocol regression
           or
context/refactor regression

Replacing every layer at once would remove that comparison point.

Relationship to reliable transport

Basic TCP state and reliable retransmission storage are separated.

Connection reset preserves the pointer to the reliable queue allocation, zeros it, and reattaches it to the reset TCP workspace rather than leaking pages on every reconnect.

See TCP Reliability & Flow.

Diagnostics

Counters and state are intentionally kept in memory structures that can be printed by shard diagnostics.

A useful transport dump can include:

• connection state
• source port
• bytes sent/received
• retry count
• RST count
• last shard error

This is especially important on real hardware where there is no external kernel TCP tooling to inspect the socket for you.

Per-shard TCP source-port derivation

NASM original

Context before the block

Symbol	Meaning
RBX	Pointer to the owning shard context.
RAX	Pointer to the allocated TCP context.
SHARD_OFF_ID	Offset of the global shard ID inside the shard descriptor.
SHARD_TCP_PORT_BASE	Base source port, currently 50000.
SHARD_TCP_PORT_MASK	0x0FFF, keeping the low 12 shard-ID bits.

mov edx, [rbx + SHARD_OFF_ID]   ; EDX = this shard's global Discord shard ID.
and edx, SHARD_TCP_PORT_MASK    ; Keep only the low 12 bits used by local port derivation.
add edx, SHARD_TCP_PORT_BASE    ; Translate masked shard ID into the 50000+ source-port range.
mov [rax + STCP_LOCAL_PORT], edx; Store the resulting source port in this shard's TCP context.

Execution order

1. Read the global shard ID from the shard descriptor.
2. Mask the shard ID to the low 12 bits.
3. Add the fixed local-port base of 50000.
4. Store the derived source port in this shard's TCP context.

Rust equivalent

const PORT_BASE: u32 = 50_000;
const PORT_MASK: u32 = 0x0FFF;

fn local_port_for(shard: &ShardContext) -> u32 {
    PORT_BASE + (shard.id & PORT_MASK)
}

C equivalent

uint32_t shard_local_port(const struct shard_ctx *shard) {
    return 50000u + (shard->id & 0x0FFFu);
}

Python model

PORT_BASE = 50_000
PORT_MASK = 0x0FFF

def local_port_for(shard_id: int) -> int:
    return PORT_BASE + (shard_id & PORT_MASK)

Success condition

After this block, the TCP context owns a deterministic source port derived from the shard ID. Two correctly isolated low-numbered local shards should therefore not report the same source port.

State after the block

STCP_LOCAL_PORT is initialized; no packet has been sent yet, and TCP state is still independent of TLS/WebSocket/Gateway state.

TCP checksum finalization

The TCP checksum path folds a wider accumulator into a 16-bit one's-complement value, then converts it to wire byte order.

NASM original

Register context

Register	Meaning at entry to the fold
EBX	Running checksum accumulator after pseudo-header and TCP bytes have been added.
EAX	Scratch register used to carry the high 16 bits during each fold.
AX	Final 16-bit checksum returned in network byte order.

.fold:
    mov eax, ebx        ; Copy the 32-bit accumulator so its high half can be extracted.
    shr eax, 16         ; EAX = high 16 bits from the first accumulation pass.
    and ebx, 0xFFFF     ; Keep only the low 16 bits in EBX.
    add ebx, eax        ; Fold high 16 bits into low 16 bits.

    mov eax, ebx        ; Copy again because the prior add may itself have produced a carry.
    shr eax, 16         ; Extract that carry/high half.
    and ebx, 0xFFFF     ; Retain the low 16 bits again.
    add ebx, eax        ; Fold the final carry back into the checksum.

    mov eax, ebx        ; EAX = folded 16-bit sum.
    not eax             ; One's-complement the folded sum.
    and eax, 0xFFFF     ; Discard complemented bits above the 16-bit checksum.
    xchg al, ah         ; Swap bytes so AX is in TCP/network byte order.

Execution order

1. Split the checksum accumulator into high and low 16-bit halves.
2. Add the high half back into the low half.
3. Repeat once to fold any carry produced by the first addition.
4. One's-complement the folded 16-bit value.
5. Swap the result into network byte order.

Rust equivalent

fn fold_checksum(mut sum: u32) -> u16 {
    sum = (sum & 0xFFFF) + (sum >> 16);
    sum = (sum & 0xFFFF) + (sum >> 16);

    let checksum = !(sum as u16);
    checksum.rotate_left(8)
}

C equivalent

uint16_t fold_checksum(uint32_t sum) {
    sum = (sum & 0xFFFFu) + (sum >> 16);
    sum = (sum & 0xFFFFu) + (sum >> 16);

    uint16_t checksum = (uint16_t)~sum;
    return (uint16_t)((checksum << 8) | (checksum >> 8));
}

Python model

def fold_checksum(total: int) -> int:
    total = (total & 0xFFFF) + (total >> 16)
    total = (total & 0xFFFF) + (total >> 16)

    checksum = (~total) & 0xFFFF
    return ((checksum << 8) | (checksum >> 8)) & 0xFFFF

Debugging implication

A bug here can masquerade as a completely different subsystem failure: remote hosts may silently discard malformed TCP segments, making TLS appear to stall even though TLS never received a valid stream.

Success condition

The returned AX is ready to be written directly into the TCP checksum field.

Source

• legacy_net_core.inc
• legacy_ip_stack.inc
• legacy_tcp.inc
• legacy_shard_tcp.inc
• legacy_shard_tcp_reliable.inc