@@ -25,6 +25,9 @@ protocol itself, including how to route incoming packets to the correct
2525vane or app, is defined in Ames.
2626
2727## Technical Overview
28+This section summarizes the design of Ames. Beyond this section are deeper
29+elaborations on the concepts presented here.
30+
2831Ames extends [Arvo's](@/docs/tutorials/arvo/arvo.md) `%pass`/`%give` `move` semantics across the network.
2932
3033Ames receives packets as Arvo events and emits packets as Arvo
@@ -78,7 +81,7 @@ large. A naxplanation can only give rise to a positive ack --
7881never ack an ack, and never nack a naxplanation.
7982
8083Ames guarantees a total ordering of messages within a "flow",
81−identified in other vanes by a duct and over the wire by a "bone":
84+identified in other vanes by a duct and over the wire by a `bone`:
8285an opaque number. Each flow has a FIFO (first-in-first-out) queue of `%plea` requests
8386from the requesting ship to the responding ship and a FIFO queue
8487of `%boon`'s in the other direction.
@@ -140,7 +143,7 @@ The body is of variable length and consists of three parts in this order:
140143
141144 - The `@p` of the sending ship,
142145 - The `@p` of the receiving ship,
143− - The payload, which is the `+jam` (i.e. serialization) of the noun `[origin content]`.
146+ - The payload, which is the [`+jam`](@/docs/reference/libary/2p.md#jam) (i.e. serialization) of the noun `[origin content]`.
144147
145148 `origin` is the IP and port of the original sender if the packet was proxied
146149 through a relay and null otherwise. `content` is a noun that is either an encrypted ack or an
@@ -153,15 +156,13 @@ The body is of variable length and consists of three parts in this order:
153156### Packeting
154157
155158When Ames has a message to be sent it must first determine how many packets are
156−required to send the message. To do this, it first `+jam`s (serializes) the
159+required to send the message. To do this, it first `+jam`s the
157160message, producing an atom. Ames checks how large the atom is, and if it is
158161bigger than a kilobyte it will split it into packets whose payloads are 1 kB or
159162less. It then numbers each one - this is message 17, packet 12, this is message
16016317, packet 13, etc, so that when the receiver receives these packets it knows
161164which number they are. Finally it encrypts each individual packet and enqueues
162−them to be sent along their stated flow. Encryption is the last step to happen
163−before a packet is sent, since the receivers keys could potentially change in
164−the time between when
165+them to be sent along their stated flow.
165166
166167Network packets aren't always received in order, so this numbering is important
167168for reconstruction, and also pakcets may get lost. So Ames does transmission
@@ -174,21 +175,64 @@ works in the same fashion as TCP, namely exponential backoff.
174175Once all packets are received, the receiving Ames decrypts them, deserializes
175176them, and puts them back together.
176177
177−## Acks and nacks
178−
179−There are two types of acks: packet-level acks and message-level acks. They are
178+### Acks
179+
180+In this section we discuss acks, short for acknowledgements, which are small
181+packets attesting that packets were successfully received. Ames makes use of
182+acks maintain synchrony between two communicating parties. Nacks are 'negative
183+acknowledgments' and are used when something goes wrong. This topic is more
184+complicated and so discussion of them is deferred.
185+
186+Every message (i.e. a `%plea` or a `%boon`) is split up by Ames into some number
187+of _fragments_ that are 1kB in size or less. The fragments are then encrypted
188+and encapsulated into
189+packets and sent along a flow. The message will be considered successfully
190+received once the sender has received the appropriate set of acks in response,
191+defined as follows.
192+
193+There are two types of acks: fragment acks and message acks. Acks are
180194not considered messages, and thus are not `%plea`s or `%boon`s, and so are not
181−required to appear in a particular order.
182−
183−There is only one kind of nack, which may only be sent in response to a `%plea`,
184−and requires a naxplanation.
185−
186−Each packet forming part of a `%plea` or `%boon` must be acked, and can never be nacked.
187−
188−Each `%plea` must be acked or nacked. A nack requires a naxplanation message (a `%boon`)?
189−
190−Each `%boon` must be acked.
191−
195+required to appear in a particular order. Given a message split into N
196+fragments, the sender of the message will expect N-1 fragment acks followed
197+by exactly one message ack. This is because the receiver
198+will send a fragment ack for the first N-1 packets it received, and what
199+would have been the final fragment ack will instead be a message ack.
200+
201+Acks are considered to be part of the flow in which that `%plea` or
202+`%boon` lives, as the packets containing their fragments and packets acking the
203+receipt of those packets are considered to be what makes up a given message.
204+Thus a message-level ack must be received before the next message on the flow
205+can begin.
206+
207+```hoon
208++$ ack-meat (each fragment-num [ok=? lag=@dr])
209+```
210+
211+#### Ack packets
212+
213+The contents of a given ack packet are deterministic. The `content` (i.e. the
214+encrypted portion of the packet) of a fragment ack is obtained by encrypting the `+jam` of the
215+following noun:
216+
217+```hoon
218+[our-life her-life bone message-num fragment-num]
219+```
220+Each datum in this noun is an atom with the aura `@ud` or an aura that nests
221+under `@ud`.
222+
223+Here, `our-life` refers to the [`life`](@/docs/glossary/breach), or revision
224+number, of the acking ship's networking keys, and `her-life` is the `life` of
225+the ack-receiving ship's networking keys. `bone` is an opaque number identifying the flow, `message-num` denotes the number of the
226+message in the flow identified by `bone`, and
227+`fragment-num` denotes the number of the fragment of the message identified by
228+`message-num` being acked.
229+
230+A message ack is an extended fragment ack that is obtained by encrypting the
231+`+jam` of the following noun:
232+
233+```hoon
234+[our-life her-life bone message-num fragment-num ok=? lag=@dr]
235+```
192236
193237## A typical successful Ames exchange
194238