@@ -111,3 +111,41 @@ ducts as unique keys. Stop tracking a peer by sending Ames a
111111`%jilt` `$task`.
112112
113113Debug output can be adjusted using `%sift` and `%spew` `$task`'s.
114+
115+## Packet structure
116+
117+Ames datagram packets are handled as nouns internally by Arvo but as serial data
118+by Unix. Here we document their serial structure.
119+For further information, see `+encode-packet` and `+decode-packet` in `ames.hoon`.
120+
121+There is a 32-bit header followed by a variable width body.
122+
123+### Header
124+
125+The 32-bit header is given by the following data, presented in order:
126+
127+ - 3 bits: Ames `protocol-version`,
128+ - 20 bits: a checksum as a truncated insecure hash of the body, done with
129+ `+mug`,
130+ - 2 bits: the bit width of the sender address encoded as a 2-bit enum,
131+ - 2 bits: the bit width of the receiver address encoded as a 2-bit enum,
132+ - 1 bit: whether the packet is encrypted or not,
133+ - 4 bits: unused.
134+
135+ Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.
136+
137+### Body
138+
139+The body is of variable length and consists of three parts in this order:
140+
141+ - The `@p` of the sending ship,
142+ - The `@p` of the receiving ship,
143+ - The payload, which is the `+jam` (i.e. serialization) of the noun `[origin content]`.
144+
145+ `origin` is the IP and port of the original sender if the packet was proxied
146+ through a relay and null otherwise. `content` is a noun that is either an encrypted ack or an
147+ encrypted message fragment, unless it is a comet attestation packet in which
148+ case it is unencrypted.
149+
150+ The sender and receiver live outside of the jammed data section to simplify
151+ packet filtering for the interpreter.