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

MOSH Wiki

Table of Contents