Frame Types

Broadcast Packet

Broadcast packets carry a source and payload, but no security info.

+-----+-----------+-------+-----+---------+
| FCF | [OPTIONS] |[FHOPS]| SRC | PAYLOAD |
+-----+-----------+-------+-----+---------+
  1 B    variable   0/1 B  3/32B   var.

A broadcast with an empty payload is a Beacon.

MAC Ack Packet

A MAC acknowledgement is generated by the final destination — the node that successfully processes and accepts the original packet. Repeaters do not generate MAC acks; they forward ack packets like any other packet type.

The ack identifies the original sender by destination hint and carries an ack tag — a cryptographically derived value that the sender can verify. See Ack Tag Construction for the derivation.

+-----+-----------+-------+-----+---------+
| FCF | [OPTIONS] |[FHOPS]| DST | ACK TAG |
+-----+-----------+-------+-----+---------+
  1 B    variable   0/1 B   3 B    8 B

Where:

• DST is a 3-byte prefix of the original sender’s public key
• ACK TAG is an 8-byte value derived from the original packet’s MIC and the pairwise encryption key (see Ack Tag Construction)

Because the ack tag requires knowledge of the pairwise K_enc, it cannot be forged by a passive observer — even one who received the original packet in its entirety.

The ack is routed back to the original sender using whatever routing state is available — a cached source route, a flood scoped by FHOPS_ACC, or both. See Route Learning for how nodes learn and cache routing information from incoming packets. For reliable ack delivery over long source-routed paths, the original sender should include a trace-route option.

Unicast Packet

Unicast packets are addressed by destination hint and carry the source address.

+-----+-----------+------+-----+-----+---------+---------+------+
| FCF | [OPTIONS] |[FHOPS]| DST | SRC | SECINFO | PAYLOAD | MIC  |
+-----+-----------+------+-----+-----+---------+---------+------+
  1 B    variable   0/1 B  3 B  3/32B    5/7 B     var.    4-16 B

DST is the first three bytes of the recipient’s public key.

Receivers first use DST as a cheap filter, then use the source public key (or its cached equivalent when only a hint is present) and their own key to derive the shared secret and authenticate/decrypt the packet.

Unicast Packet with Ack Requested

This is identical to unicast, but the packet-type value signals that a MAC acknowledgement is requested.

+-----+-----------+------+-----+------+---------+---------+------+
| FCF | [OPTIONS] |[FHOPS]| DST | SRC  | SECINFO | PAYLOAD | MIC  |
+-----+-----------+------+-----+------+---------+---------+------+
  1 B    variable   0/1 B  3 B   3/32B    5/7 B     var.    4-16 B

Semantics differ, wire layout does not.

Multicast Packet

Multicast packets carry a 2-byte channel identifier derived from the channel key.

Channel Identifier Derivation

channel_id = first_2_bytes( HKDF-SHA256(channel_key, salt="UMSH-CHAN-ID", info="", L=2) )

Encrypted Multicast (E = 1)

When encryption is enabled, the source address is encrypted together with the payload, concealing the sender’s identity from observers who do not possess the channel key.

+-----+-----------+------+---------+---------+----------------------+------+
| FCF | [OPTIONS] |[FHOPS]| CHANNEL | SECINFO | ENCRYPT(SRC+PAYLOAD) | MIC  |
+-----+-----------+------+---------+---------+----------------------+------+
  1 B    variable   0/1 B    2 B     5/7 B          3/32 + var.      4-16 B

The SRC inside the ciphertext follows the S flag convention: a 3-byte hint when S is clear, or the full 32-byte public key when S is set.

Only a node with the correct channel key can recover the source address and payload.

Unencrypted Multicast (E = 0)

When encryption is not enabled, the source address appears in cleartext, but in the same place that it appeared in encrypted multicast:

+-----+-----------+-------+---------+---------+------+---------+------+
| FCF | [OPTIONS] |[FHOPS]| CHANNEL | SECINFO | SRC  | PAYLOAD | MIC  |
+-----+-----------+-------+---------+---------+------+---------+------+
  1 B    variable   0/1 B     2 B      5/7 B   3/32 B    var.   4-16 B

Blind Unicast Packet

Blind unicast uses a multicast channel to conceal sender and destination metadata from observers without the channel key while still protecting the payload end-to-end for the actual destination.

Like other channel-addressed packets, blind unicast honors the E flag in SECINFO.

Encrypted Blind Unicast (E = 1)

+-----+-----------+-------+---------+---------+-------------+-------------+------+
| FCF | [OPTIONS] |[FHOPS]| CHANNEL | SECINFO | ENC_DST_SRC | ENC_PAYLOAD | MIC  |
+-----+-----------+-------+---------+---------+-------------+-------------+------+
  1 B    variable   0/1 B     2 B      5/7 B       6/35 B         var.     4-16 B

The MIC is computed over the payload using the blind unicast payload keys, which combine the pairwise shared secret with the channel key. ENC_DST_SRC is encrypted using the channel’s derived encryption key K_enc_channel (see Multicast Packet Keys) and the MIC as IV (see Security & Cryptography). Because ENC_DST_SRC decryption depends on the MIC, any tampering with the source address will produce an incorrect public key, causing pairwise key derivation to fail and payload authentication to reject.

Unencrypted Blind Unicast (E = 0)

When encryption is disabled, blind unicast still uses the channel identifier and the blind-unicast packet type, but the destination hint, source address, and payload appear in cleartext:

+-----+-----------+-------+---------+---------+-----+------+---------+------+
| FCF | [OPTIONS] |[FHOPS]| CHANNEL | SECINFO | DST | SRC  | PAYLOAD | MIC  |
+-----+-----------+-------+---------+---------+-----+------+---------+------+
  1 B    variable   0/1 B     2 B      5/7 B    3 B  3/32 B    var.   4-16 B

In this mode, the packet remains channel-associated and authenticated with the blind-unicast keys, but it does not conceal sender or destination metadata. This can still be useful when an implementation wants channel-associated unicast semantics without encryption.

Blind Unicast Processing

1. Receiver uses CHANNEL to identify candidate channel keys.
2. Receiver derives the channel’s candidate keys via HKDF.
3. If E = 1, receiver reads the MIC and uses K_enc_channel plus MIC to decrypt ENC_DST_SRC, recovering the destination hint and sender address.
4. If E = 0, receiver reads DST and SRC directly from the cleartext packet.
5. Receiver converts the sender Ed25519 public key into an X25519 public key.
6. Receiver converts its own Ed25519 private key into an X25519 private key.
7. Receiver performs ECDH and derives the stable pairwise keys.
8. Receiver computes the blind unicast payload keys by XORing the pairwise keys with the channel keys.
9. Receiver authenticates the packet using the blind-unicast MIC.
10. If E = 1, receiver decrypts ENC_PAYLOAD using the blind unicast payload keys.
11. If authentication fails, the packet is rejected.

Some repeaters may decline to forward blind unicast packets for unknown channels.

Blind Unicast with Ack Requested

Same wire layout as blind unicast, but with ack-requested semantics.

+-----+-----------+-------+---------+---------+-------------+-------------+------+
| FCF | [OPTIONS] |[FHOPS]| CHANNEL | SECINFO | ENC_DST_SRC | ENC_PAYLOAD | MIC  |
+-----+-----------+-------+---------+---------+-------------+-------------+------+
  1 B    variable   0/1 B      2 B     5/7 B       6/35 B         var.     4-16 B