naming things

RFC/0002-signed-envelopes.md

@@ -40,12 +40,12 @@ fail.
 Domain strings may be any valid UTF-8 string, but should be fairly short and
 descriptive of their use case, for example `"libp2p-routing-record"`.
 
-## Type Hinting
+## Payload Type Information
 
 The envelope record can contain an arbitrary byte string payload, which will
 need to be interpreted in the context of a specific use case. To assist in
-"hydrating" the payload into an appropriate domain object, we include a "type
-hint" field. The type hint consists of a [multicodec][multicodec] code,
+"hydrating" the payload into an appropriate domain object, we include a "payload
+type" field. This field consists of a [multicodec][multicodec] code,
 optionally followed by an arbitrary byte sequence.
 
 This allows very compact type hints that contain just a multicodec, as well as
@@ -53,6 +53,9 @@ This allows very compact type hints that contain just a multicodec, as well as
 multicodec](https://github.com/multiformats/multicodec/blob/master/table.csv#L23),
 whose binary value is equivalent to the UTF-8 `/` character.
 
+Use of the payload type field is encouraged, but the field may be left empty
+without invalidating the envelope.
+
 ## Wire Format
 
 Since we already have a [protobuf definition for public keys][peer-id-spec], we
@@ -61,23 +64,24 @@ can use protobuf for this as well and easily embed the key in the envelope:
 
 ```protobuf
 message SignedEnvelope {
-  PublicKey publicKey = 1; // see peer id spec for definition
-  bytes typeHint = 2;      // type hint
-  bytes contents = 3;      // payload
+  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 = 4;      // see below for signing rules
 }
 ```
 
-The `publicKey` field contains the public key whose secret counterpart was used
+The `public_key` field contains the public key whose secret counterpart was used
 to sign the message. This MUST be consistent with the peer id of the signing
 peer, as the recipient will derive the peer id of the signer from this key.
 
-The `typeHint` field contains a [multicodec][multicodec]-prefixed type hint as
-described in the [Type Hinting section](#type-hinting).
+The `payload_type` field contains a [multicodec][multicodec]-prefixed type
+indicator as described in the [Payload Type Information
+section](#payload-type-information).
 
-The `contents` field contains the arbitrary byte string payload.
+The `payload` field contains the arbitrary byte string payload.
 
-The `signature` field contains a signature of all fields except `publicKey`,
+The `signature` field contains a signature of all fields except `public_key`,
 generated as described below.
 
 ## Signature Production / Verification
@@ -87,10 +91,10 @@ When signing, a peer will prepare a buffer by concatenating the following:
 - The length of the [domain separation string](#domain-separation) string in
   bytes
 - The domain separation string, encoded as UTF-8
-- The length of the `typeHint` field in bytes
-- The value of the `typeHint` field
-- The length of the `contents` field in bytes
-- The value of the `contents` field
+- The length of the `payload_type` field in bytes
+- The value of the `payload_type` field
+- The length of the `payload` field in bytes
+- The value of the `payload` field
 
 The length values for each field are encoded as 64-bit unsigned integers in
 network order (big-endian).
@@ -98,7 +102,7 @@ network order (big-endian).
 Then they will sign the buffer according to the rules in the [peer id
 spec][peer-id-spec] and set the `signature` field accordingly.
 
-To verify, a peer will "inflate" the `publicKey` into a domain object that can
+To verify, a peer will "inflate" the `public_key` into a domain object that can
 verify signatures, prepare a buffer as above and verify the `signature` field
 against it.
 

RFC/0003-routing-records.md

@@ -91,7 +91,7 @@ message RoutingState {
   }
 
   // the peer id of the subject of the record (who these addresses belong to).
-  bytes peerId = 1;
+  bytes peer_id = 1;
   
   // A monotonically increasing sequence number, used for record ordering.
   uint64 seq = 2;
@@ -114,7 +114,7 @@ epoch time as the `seq` value, however they MUST NOT attempt to interpret a
 
 ```javascript
   {
-    peerId: "QmAlice...",
+    peer_id: "QmAlice...",
     seq: 1570215229,
       
     addresses: [
@@ -147,9 +147,9 @@ support this, implementations may use a global runtime configuration flag or
 environment variable to control whether local addresses will be included.
 
 Once the `RoutingState` has been constructed, it should be serialized to a byte
-string and wrapped in a [signed envelope][envelope-rfc]. The `publicKey` field
-of the envelope MUST be able to derive the `peerId` contained in the record. If
-the envelope's `publicKey` does not match the `peerId` of the routing record,
+string and wrapped in a [signed envelope][envelope-rfc]. The `public_key` field
+of the envelope MUST be able to derive the `peer_id` contained in the record. If
+the envelope's `public_key` does not match the `peer_id` of the routing record,
 the record MUST be rejected as invalid.
 
 ### Signed Envelope Domain
@@ -160,15 +160,15 @@ or purpose of a signature.
 When wrapping a `RoutingState` in a signed envelope, the domain string MUST be
 `libp2p-routing-state`.
 
-### Signed Envelope Type Hint
+### Signed Envelope Payload Type
 
-Signed envelopes contain a "type hint" that indicates how to interpret the
-contents of the envelope.
+Signed envelopes contain a `payload_type` field that indicates how to interpret
+the contents of the envelope.
 
 Ideally, we should define a new multicodec for routing records, so that we can
 identify them in a few bytes. While we're still spec'ing and working on the
 initial implementation, we can use the UTF-8 string
-`"/libp2p/routing-state-record"` as the type hint value.
+`"/libp2p/routing-state-record"` as the `payload_type` value.
 
 ## Peer Store APIs
 
@@ -180,16 +180,16 @@ We will need to add a few methods to the peer store:
     If any certified addresses already exist for the peer, only accept the new
     envelope if it has a greater `seq` value than existing envelopes.
     
-- `CertifiedAddrs(peerId) -> Set<Multiaddr>`
+- `CertifiedAddrs(peer_id) -> Set<Multiaddr>`
   - return the set of self-certified addresses for the given peer id
 
-- `SignedRoutingState(peerId) -> Maybe<SignedEnvelope>`
+- `SignedRoutingState(peer_id) -> Maybe<SignedEnvelope>`
   - retrive the signed envelope that was most recently added to the peerstore
     for the given peer, if any exists.
 
 And possibly:
 
-- `IsCertified(peerId, multiaddr) -> Boolean`
+- `IsCertified(peer_id, multiaddr) -> Boolean`
   - has a particular address been self-certified by the given peer?