@@ -111,3 +111,42 @@ ducts as unique keys. Stop tracking a peer by sending Ames a
111`%jilt` `$task`.
111`%jilt` `$task`.
113Debug output can be adjusted using `%sift` and `%spew` `$task`'s.
113Debug output can be adjusted using `%sift` and `%spew` `$task`'s.
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`.
121+There is a 32-bit header followed by a variable width body.
125+The 32-bit header is given by the following data:
127+ - 3 bits: Ames `protocol-version`,
128+ - 20 bits: a checksum as a truncated insecure hash of the body, done with
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,
135+ Every packet between Azimuth addresses are encrypted. The only unencrypted
136+ packets are self-signed attestation packets from 128-bit comets.
140+The body is of variable length and consists of three parts:
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]`.
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.
151+ The sender and receiver live outside of the jammed data section to simplify
152+ packet filtering for the interpreter.