Another editing pass for hspow-spec and friends

This mostly updates formatting and links. I added a little bit of new
context, primarily a disclaimer and updated benchmark info for
analysis-discussion.md

1 files changed, 16 insertions, 12 deletions

diff --git a/spec/hspow-spec/analysis-discussion.md b/spec/hspow-spec/analysis-discussion.md
index 483bd31..8f25623 100644
--- a/spec/hspow-spec/analysis-discussion.md
+++ b/spec/hspow-spec/analysis-discussion.md
@@ -1,23 +1,27 @@
 # Analysis and discussion
 
+*Warning*: Take all the PoW performance numbers on this page with a large grain of salt. Most of this is based on very early analysis that has not been updated for the current state of implementation.
+
+For current performance numbers on a specific piece of hardware, please run `cargo bench` from the [`equix/bench`](https://gitlab.torproject.org/tpo/core/arti/-/tree/main/crates/equix/bench) crate within [Arti](https://gitlab.torproject.org/tpo/core/arti/). This framework tests both the C and Rust implementations side-by-side.
+
 ## Attacker strategies {#attacker-strategies}
 
 To design a protocol and choose its parameters, we first need to understand a few high-level attacker strategies to see what we are fighting against.
 
-### Overwhelm PoW verification (aka "Overwhelm top half") {#attack-top-half}
+### Overwhelm PoW verification ("top half") {#attack-top-half}
 
-A basic attack here is the adversary spamming with bogus INTRO cells so that the service does not have computing capacity to even verify the proof-of-work. This adversary tries to overwhelm the procedure in the [POW_VERIFY] section.
+A basic attack here is the adversary spamming with bogus INTRO cells so that the service does not have computing capacity to even verify the proof-of-work. This adversary tries to overwhelm the procedure in the [`v1` verification algorithm](./v1-equix.md#service-verify) section.
 
-That's why we need the PoW algorithm to have a cheap verification time so that this attack is not possible: we tune this PoW parameter in section [POW_TUNING_VERIFICATION].
+That's why we need the PoW algorithm to have a cheap verification time so that this attack is not possible: we explore this PoW parameter below in the section on [PoW verification](#pow-tuning-verification).
 
-### Overwhelm rendezvous capacity (aka "Overwhelm bottom half") {#attack-bottom-half}
+### Overwhelm rendezvous capacity ("bottom half") {#attack-bottom-half}
 
-Given the way the introduction queue works (see [HANDLE_QUEUE]), a very effective strategy for the attacker is to totally overwhelm the queue processing by sending more high-effort introductions than the onion service can handle at any given tick.
-This adversary tries to overwhelm the procedure in the [HANDLE_QUEUE] section.
+Given the way [the introduction queue](./common-protocol.md#intro-queue) works, a very effective strategy for the attacker is to totally overwhelm the queue processing by sending more high-effort introductions than the onion service can handle at any given tick.
+This adversary tries to overwhelm the process of [handling queued introductions](./common-protocol.md#handling-queue).
 
-To do so, the attacker would have to send at least 20 high-effort introduction cells every 100ms, where high-effort is a PoW which is above the estimated level of "the motivated user" (see [USER_MODEL]).
+To do so, the attacker would have to send at least 20 high-effort introduction cells every 100ms, where high-effort is a PoW which is above the estimated level of ["the motivated user"](./motivation.md#user-profiles).
 
-An easier attack for the adversary, is the same strategy but with introduction cells that are all above the comfortable level of "the standard user" (see [USER_MODEL]).
+An easier attack for the adversary, is the same strategy but with introduction cells that are all above the comfortable level of ["the standard user"](./motivation.md#user-profiles).
 This would block out all standard users and only allow motivated users to pass.
 
 ### Hybrid overwhelm strategy {#attack-hybrid}
@@ -240,11 +244,11 @@ Nevertheless, there are some massive differences in both the scale and the dynam
 We think we aren't making a bad situation worse: DoS attacks on the Tor network are already happening and attackers are already burning energy to carry them out.
 As we see in the [denial-of-service overview](../dos-spec/overview.md#hs-intro), attacks on onion services are in a position to cause downstream resource consumption of nearly every type.
 Each relay involved experiences increased CPU load from the circuit floods they process.
-We think that asking legitimate clients to carry out PoW computations is not gonna affect the equation too much, since an attacker right now can very quickly use the same resources that hundreds of legitimate clients do in a whole day.
+We think that asking legitimate clients to carry out PoW computations doesn't affect the equation too much, since an attacker right now can very quickly use the same resources that hundreds of legitimate clients do in a whole day.
 
 We hope to make things better: The hope is that systems like this will make the DoS actors go away and hence the PoW system will not be used.
 As long as DoS is happening there will be a waste of energy, but if we manage to demotivate them with technical means, the network as a whole will less wasteful.
-Also see [The DoS Catch-22](./motivation.md#catch22) for a similar argument.
+Also see [The DoS Catch-22](./motivation.md#catch22).
 
 ## Acknowledgements {#acknowledgements}
 
@@ -272,8 +276,8 @@ Processing an INTRODUCE2 cell at the onion service means a series of operations
 2. Decrypt cell (AES operations).
 3. Parse cell header and process it depending on its RELAY_COMMAND.
 4. INTRODUCE2 cell handling which means building a rendezvous circuit:
-  -  Path selection
-  - Launch circuit to first hop.
+   -  Path selection
+   - Launch circuit to first hop.
 5. Return to mainloop event which essentially means back to step (1).
 
 Tor will read at most 32 cells out of the inbuf per mainloop round.