Merge pull request #29 from nyonson/proxy-docs

Doc touchups

protocol/README.md

@@ -1,8 +1,10 @@
 # Protocol
 
-Alice and Bob initiate a connection by sending three messages to each other to derive a number of shared secrets. Alice begins the connection by deriving a public/private keypair over `secp256k1`, the typical Bitcoin curve. Alice is known as the initiator. She encodes the public key in the [Elligator Swift](https://eprint.iacr.org/2022/759.pdf) format (64-bytes), optionally pads it with some random garbage bytes, and sends the message to Bob. Bob, known as the responder, decodes the Elligator Swift public key, and derives an ephemeral public/private keypair himself. Using his public and private keys, as well as Alice's public key, Bob performs a variation of the Elliptic Curve Diffie Hellman algorithm to derive a shared key. From this shared key, Bob derives multiple keys and a session ID using the HKDF algorithm. Next, Bob creates garbage data, and sends his public key, garbage data, an encrypted packet using the garbage data, and a version negotiation to Alice. With Bob's public key, Alice derives the shared secret and ensures the decrypted packet is authenticated with the garbage Bob sent her. Finally, Alice sends a "garbage terminator" and an encrypted packet using her garbage data, so Bob may authenticate she derived the correct secret and he can decode her messages. Alice and Bob may now freely exchange encrypted messages over the Bitcoin P2P protocol.
+Alice and Bob initiate a connection by sending three messages to each other to derive a number of shared secrets. Alice begins the connection by deriving a public/private keypair over `secp256k1`, the typical Bitcoin curve. Alice is known as the *initiator*. She encodes the public key in the [Elligator Swift](https://eprint.iacr.org/2022/759.pdf) format (64-bytes), optionally pads it with some random garbage bytes, and sends the message to Bob. Bob, known as the *responder*, decodes the Elligator Swift public key, and derives an ephemeral public/private keypair himself. Using his public and private keys, as well as Alice's public key, Bob performs a variation of the Elliptic Curve Diffie Hellman algorithm to derive a shared key. From this shared key, Bob derives multiple keys and a session ID using the HKDF algorithm. Next, Bob creates garbage data, and sends his public key, garbage data, an encrypted packet using the garbage data, and a version negotiation to Alice. With Bob's public key, Alice derives the shared secret and ensures the decrypted packet is authenticated with the garbage Bob sent her. Finally, Alice sends a "garbage terminator" and an encrypted packet using her garbage data, so Bob may authenticate she derived the correct secret and he can decode her messages. Alice and Bob may now freely exchange encrypted messages over the Bitcoin P2P protocol.
 
-There are also `no_std` compliant versions of these functions which require an RNG to be initialized by the consumer.
+The library exposes two core structures, the `Handshake` and the `PacketHandler`. The handshake is used to generate a packet handler and performs the one-and-a-half roundtrips dance between the peers described above. A successful handshake results in a packet handler which performs the encrypt and decrypt operations for the channel.
+
+Both structures are designed with a bare `no_std` and "Sans I/O" interface to keep them as agnostic as possible to application runtimes. 
 
 ## ChaCha20Poly1305
 

proxy/README.md

@@ -1,3 +1,3 @@
 # Proxy
 
-A simple proxy process to show off the BIP324 protocol.
+A proxy process which allows V1-only clients to communicate over a V2 protocol. The process listens on port `1324` for V1 connections and requires the V1 client to send along the remote peer's IP address in the `addr_recv` field.

proxy/src/lib.rs

@@ -121,7 +121,7 @@ pub async fn peek_addr(client: &TcpStream) -> Result<SocketAddr, Error> {
         return Err(Error::WrongCommand);
     }
 
-    // Pull off address.
+    // Pull off address from the addr_recv field of the version message.
     let mut addr_bytes = &peek_bytes[44..];
     let remote_addr = Address::consensus_decode(&mut addr_bytes).expect("network address bytes");
     let socket_addr = remote_addr.socket_addr().expect("IP");