====== 2. Frame Format ======

===== 2.1 Purpose =====

This document defines the on-wire frame structure currently used by MTRP.

===== 2.2 Scope =====

This document describes:

  * the serialized MTRP header
  * payload placement
  * optional CRC placement
  * compact and native header formats
  * the distinction between wire fields and local metadata

===== 2.3 Frame Model =====

An MTRP frame consists of:

  * a serialized header
  * a payload
  * an optional CRC footer
  * local metadata used internally by the router

Only the serialized header, payload, and optional CRC are transmitted on the wire.

Local metadata is not serialized as part of the MTRP frame.

===== 2.4 Native Frame Layout =====

In native mode, the serialized frame layout is:

  * ''Flags'' (1 byte)
  * ''Version'' (1 byte)
  * ''Payload Length'' (2 bytes)
  * ''Message ID'' (2 bytes)
  * ''Origin Node ID'' (2 bytes)
  * ''Destination Node ID'' (2 bytes)
  * ''Previous Hop Node ID'' (2 bytes)
  * ''Network ID'' (2 bytes)
  * ''TTL'' (1 byte)
  * ''Payload'' (variable)
  * ''CRC16'' (optional, 2 bytes, only if ''WITH_CRC'' is set)

Native header length is 15 bytes.

===== 2.5 Compact Frame Layout =====

In constrained mode, the serialized frame layout is:

  * ''Flags'' (1 byte)
  * ''Version/Length'' (1 byte)
  * ''Message ID'' (2 bytes)
  * ''Origin Node ID'' (2 bytes)
  * ''Destination Node ID'' (2 bytes)
  * ''Previous Hop Node ID'' (2 bytes)
  * ''Network ID'' (2 bytes)
  * ''TTL'' (1 byte)
  * ''Payload'' (variable)
  * ''CRC16'' (optional, 2 bytes, only if ''WITH_CRC'' is set)

Compact header length is 13 bytes.

===== 2.6 Header Field Order =====

The current serialized field order is identical in both modes after the first header bytes.

^ Order ^ Native ^ Compact ^ Size ^ Notes ^
| 1 | Flags | Flags | 1 byte | protocol flags |
| 2 | Version | Version/Length | 1 byte | compact mode packs version and payload length together |
| 3 | Payload Length | Message ID | 2 bytes in native | compact mode does not store payload length separately |
| 4 | Message ID | Origin Node ID | 2 bytes | per-origin message identifier |
| 5 | Origin Node ID | Destination Node ID | 2 bytes | original sender |
| 6 | Destination Node ID | Previous Hop Node ID | 2 bytes | intended recipient |
| 7 | Previous Hop Node ID | Network ID | 2 bytes | most recent forwarding node |
| 8 | Network ID | TTL | 2 bytes native / 1 byte compact | logical network identifier |
| 9 | TTL | Payload | 1 byte | remaining hop count |

For clarity, the actual compact order on wire is:

  - Flags
  - Version/Length
  - Message ID
  - Origin Node ID
  - Destination Node ID
  - Previous Hop Node ID
  - Network ID
  - TTL

===== 2.7 Header Field Definitions =====

==== 2.7.1 Flags ====

The flags byte carries protocol behavior bits.

Current flags are:

^ Bit Mask ^ Name ^ Meaning ^
| ''0x01'' | ''RELIABLE'' | frame requests acknowledgment |
| ''0x02'' | ''ACK'' | frame is an acknowledgment |
| ''0x04'' | ''FRAGMENT'' | frame is a fragment |
| ''0x08'' | ''SECURE'' | frame is secured/encrypted |
| ''0x10'' | ''RELAY_REQ'' | frame is intended for relaying |
| ''0x20'' | ''IS_CONTROL'' | frame carries control-plane content |
| ''0x40'' | ''IS_COMPACT'' | frame uses compact header format |
| ''0x80'' | ''WITH_CRC'' | frame includes trailing CRC16 |

==== 2.7.2 Version ====

The version field identifies the protocol/header format in use.

In native mode, version occupies one full byte.

In compact mode, version occupies the upper 3 bits of the combined ''Version/Length'' byte.

A received frame MUST match the implementation's configured protocol version.

==== 2.7.3 Payload Length ====

In native mode, payload length is stored as a 16-bit value.

In compact mode, payload length is stored in the lower 5 bits of the combined ''Version/Length'' byte.

As currently implemented, compact mode payload length is limited to 31 bytes.

==== 2.7.4 Message ID ====

The message ID is a per-origin identifier used for duplicate suppression and message tracking.

==== 2.7.5 Origin Node ID ====

The origin node ID identifies the original sender of the frame.

==== 2.7.6 Destination Node ID ====

The destination node ID identifies the intended recipient of the frame.

==== 2.7.7 Previous Hop Node ID ====

The previous hop node ID identifies the node that most recently forwarded or transmitted the frame.

==== 2.7.8 Network ID ====

The network ID distinguishes one logical MTRP network from another.

==== 2.7.9 TTL ====

The TTL field limits how many forwarding hops a frame may traverse.

===== 2.8 Compact Version/Length Byte =====

In compact mode, the second header byte is packed as follows:

^ Bit Range ^ Meaning ^
| bits 7..5 | version |
| bits 4..0 | payload length |

Equivalent expression:

  * ''version = (byte >> 5) & 0x07''
  * ''payloadLength = byte & 0x1F''

This means:

  * compact mode supports a 3-bit serialized version value
  * compact mode supports a maximum serialized payload length of 31 bytes

===== 2.9 Payload =====

The payload immediately follows the serialized header.

Payload length is determined by the serialized length field.

The payload may carry:

  * control messages
  * route advertisements
  * application data

===== 2.10 Optional CRC Footer =====

If the ''WITH_CRC'' flag is set, the frame includes a trailing 16-bit CRC after the payload.

Current behavior:

  * CRC algorithm: CRC-16/CCITT
  * CRC is computed over ''header + payload''
  * CRC bytes are appended after the payload
  * received CRC is validated during deserialization

If ''WITH_CRC'' is not set, no CRC footer is serialized.

===== 2.11 Deserialization Rules =====

On receive:

  - the flags byte is read first
  - ''IS_COMPACT'' determines whether compact or native header parsing is used
  - version MUST match the current protocol version
  - payload length MUST not exceed the configured maximum
  - if ''WITH_CRC'' is set, CRC validation MUST succeed

A frame that fails these checks MUST be rejected.

===== 2.12 Local Metadata =====

MTRP also carries internal metadata that is not serialized on wire.

Examples include:

  * ingress path ID
  * ingress path metric
  * egress path ID
  * egress next hop
  * route resolution state
  * fragment bookkeeping
  * transport-source metadata

These values exist only for local router behavior.

===== 2.13 Current Notes =====

  * native mode uses a 15-byte header
  * compact mode uses a 13-byte header
  * compact mode payload length is currently limited to 31 bytes
  * compact mode sets the ''IS_COMPACT'' flag on wire
  * CRC is optional and controlled by the ''WITH_CRC'' flag