> For the complete documentation index, see [llms.txt](https://docs.txflash.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.txflash.io/direct-protocol.md).

# DIRECT protocol

The protocol is a binary stream over TCP. All DIRECT fields use little-endian encoding unless stated otherwise.

## Outer header

Every frame begins with 20 bytes:

| Offset | Size | Field                                    |
| -----: | ---: | ---------------------------------------- |
|      0 |    4 | Payload length and flags, `u32 LE`       |
|      4 |    8 | Relay event timestamp, Unix ns, `u64 LE` |
|     12 |    8 | Relay send timestamp, Unix ns, `u64 LE`  |

```
DIRECT_FLAG = 0x10000000
LENGTH_MASK = 0x0fffffff

direct      = length_and_flags & DIRECT_FLAG != 0
payload_len = length_and_flags & LENGTH_MASK
```

Read exactly `payload_len` bytes after the header.

## DIRECT prefix

Every DIRECT payload begins with 24 bytes:

| Offset | Size | Field                           |
| -----: | ---: | ------------------------------- |
|      0 |    1 | Version, currently `1`          |
|      1 |    1 | Record type                     |
|      2 |    1 | Type-specific field             |
|      3 |    1 | Reserved, must be `0`           |
|      4 |    8 | Sequence number, `u64 LE`       |
|     12 |    4 | Ordinal or item count, `u32 LE` |
|     16 |    4 | First field length, `u32 LE`    |
|     20 |    4 | Second field length, `u32 LE`   |

Always validate:

```
payload_len == 24 + first_len + second_len
version == 1
reserved == 0
```

## DIRECT\_ITEM

For record type `1`:

```
byte 2     = 0
word 12    = ordinal
first_len  = header JSON length
second_len = raw L2 item length

payload = prefix + header_json + raw_l2_item
```

Ordinal zero contains header JSON. Later ordinals have an empty header field. Raw items include their nested L2 kind byte and must not exceed 256 KiB.

## DIRECT\_SEQUENCE\_FINAL

For record type `3`:

```
byte 2     = reconstruction kind
word 12    = item count
first_len  = canonical JSON prefix length
second_len = canonical JSON suffix length

payload = prefix + json_prefix + json_suffix
```

Store FINAL until every expected item is available.

## Reconstructing the L2 message

For reconstruction kind `3`, rebuild the batch as:

```
byte(3)
+ u64_be(len(item_0)) + item_0
+ u64_be(len(item_1)) + item_1
+ ...
```

The item lengths inside the reconstructed batch are big-endian.

For any other reconstruction kind, require one item and copy it opaquely:

```
l2Msg = item_0
```

Encode the reconstructed bytes with standard Base64 and insert them between `json_prefix` and `json_suffix` to obtain the canonical JSON message.

## Timestamps

Approximate relay hold time:

```
relay_hold_us = (relay_send_ns - relay_event_ns) / 1000
```

Approximate network time requires synchronized clocks:

```
wire_us = (consumer_receive_ns - relay_send_ns) / 1000
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.txflash.io/direct-protocol.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.