@@ -111,3 +111,42 @@ 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:
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 between Azimuth addresses are encrypted. The only unencrypted
136+ packets are self-signed attestation packets from 128-bit comets.
137+
138+### Body
139+
140+The body is of variable length and consists of three parts:
141+
142+ - The `@p` of the sender,
143+ - The `@p` of the receiver,
144+ - The payload, which is the `+jam` (i.e. serialization) of the noun `[origin content]`.
145+
146+ `origin` is the IP and port of the original sender if the packet was proxied
147+ through a relay and null otherwise. `content` is a noun that is either an encrypted ack or an
148+ encrypted message fragment, unless it is a comet attestation packet in which
149+ case it is unencrypted.
150+
151+ The sender and receiver live outside of the jammed data section to simplify
152+ packet filtering for the interpreter.