Update Envelope and PeerRecord protobufs to latest version

RFC/0002-signed-envelopes.md

@@ -63,11 +63,33 @@ can use protobuf for this as well and easily embed the key in the envelope:
 
 
 ```protobuf
+syntax = "proto3";
+
+package record.pb;
+
+// Envelope encloses a signed payload produced by a peer, along with the public
+// key of the keypair it was signed with so that it can be statelessly validated
+// by the receiver.
+//
+// The payload is prefixed with a byte string that determines the type, so it
+// can be deserialized deterministically. Often, this byte string is a
+// multicodec.
 message Envelope {
-  PublicKey public_key = 1; // see peer id spec for definition
-  bytes payload_type = 2;   // payload type indicator
-  bytes payload = 3;        // opaque binary payload
-  bytes signature = 5;      // see below for signing rules
+  // public_key is the public key of the keypair the enclosed payload was
+  // signed with.
+  PublicKey public_key = 1;
+
+  // payload_type encodes the type of payload, so that it can be deserialized
+  // deterministically.
+  bytes payload_type = 2;
+
+  // payload is the actual payload carried inside this envelope.
+  bytes payload = 3;
+
+  // signature is the signature produced by the private key corresponding to
+  // the enclosed public key, over the payload, prefixing a domain string for
+  // additional security.
+  bytes signature = 5;
 }
 ```
 

RFC/0003-routing-records.md

@@ -80,23 +80,31 @@ additional metadata in the future. Some thoughts along these lines are in the
 Here's a protobuf that might work:
 
 ```protobuf
+syntax = "proto3";
 
-// PeerRecord contains the listen addresses for a peer at a particular point in time.
+package peer.pb;
+
+// PeerRecord messages contain information that is useful to share with other peers.
+// Currently, a PeerRecord contains the public listen addresses for a peer, but this
+// is expected to expand to include other information in the future.
+//
+// PeerRecords are designed to be serialized to bytes and placed inside of
+// SignedEnvelopes before sharing with other peers.
 message PeerRecord {
-  // AddressInfo wraps a multiaddr. In the future, it may be extended to
-  // contain additional metadata, such as "routability" (whether an address is
-  // local or global, etc).
+
+  // AddressInfo is a wrapper around a binary multiaddr. It is defined as a
+  // separate message to allow us to add per-address metadata in the future.
   message AddressInfo {
     bytes multiaddr = 1;
   }
 
-  // the peer id of the subject of the record (who these addresses belong to).
+  // peer_id contains a libp2p peer id in its binary representation.
   bytes peer_id = 1;
 
-  // A monotonically increasing sequence number, used for record ordering.
+  // seq contains a monotonically-increasing sequence counter to order PeerRecords in time.
   uint64 seq = 2;
 
-  // All current listen addresses
+  // addresses is a list of public listen addresses for the peer.
   repeated AddressInfo addresses = 3;
 }
 ```