Merge pull request #193 from libp2p/peerstore

Add PeerStore content & TEMP generalize PeerID guide

content/concepts/addressing.md

@@ -12,10 +12,10 @@ For example: `/ip4/127.0.0.1/udp/1234` encodes two protocols along with their es
 Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash](/reference/glossary/#multihash) of my IPFS node's public key.
 
 {{% notice "tip" %}}
-For more on peer identity and its relation to public key cryptography, see [Peer Identity](../peer-id/).
+For more on peer identity and its relation to public key cryptography, see [Peer Identity](../peers/#peer-id/).
 {{% /notice %}}
 
-Let's say that I have the peer id `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` as above, and my public ip is `7.7.7.7`. I start my libp2p application and listen for connections on TCP port `4242`.
+Let's say that I have the Peer ID `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` as above, and my public ip is `7.7.7.7`. I start my libp2p application and listen for connections on TCP port `4242`.
 
 Now I can start [handing out multiaddrs to all my friends](/concepts/peer-routing/), of the form `/ip4/7.7.7.7/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`. Combining my "location multiaddr" (my IP and port) with my "identity multiaddr" (my libp2p `PeerId`), produces a new multiaddr containing both key pieces of information.
 

content/concepts/circuit-relay.md

@@ -15,17 +15,17 @@ The circuit relay protocol is inspired by [TURN](https://tools.ietf.org/html/rfc
 Relay connections are end-to-end encrypted, which means that the peer acting as the relay is unable to read or tamper with any traffic that flows through the connection.
 {{% /notice %}}
 
-An important aspect of the relay protocol is that it is not "transparent". In other words, both the source and destination are aware that traffic is being relayed. This is useful, since the destination can see the relay address used to open the connection and can potentially use it to construct a path back to the source. It is also not anonymous - all participants are identified using their peer id, including the relay node.
+An important aspect of the relay protocol is that it is not "transparent". In other words, both the source and destination are aware that traffic is being relayed. This is useful, since the destination can see the relay address used to open the connection and can potentially use it to construct a path back to the source. It is also not anonymous - all participants are identified using their Peer ID, including the relay node.
 
 #### Protocol Versions
 
 Today there are two versions of the circuit relay protocol, [v1](https://github.com/libp2p/specs/blob/master/relay/circuit-v1.md) and [v2](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md). We recommend using the latter over the former. See the [circuit relay v2 specification](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md#introduction) for a detailed comparison of the two. If not explicitly noted, this document describes the circuit relay v2 protocol.
 
 #### Relay addresses
 
-A relay circuit is identified using a [multiaddr][definition_muiltiaddress] that includes the [peer id](/concepts/peer-id/) of the peer whose traffic is being relayed (the listening peer or "relay target").
+A relay circuit is identified using a [multiaddr][definition_muiltiaddress] that includes the [Peer ID](/concepts/peers/) of the peer whose traffic is being relayed (the listening peer or "relay target").
 
-Let's say that I have a peer with the peer id `QmAlice`. I want to give out my address to my friend `QmBob`, but I'm behind a NAT that won't let anyone dial me directly.
+Let's say that I have a peer with the Peer ID `QmAlice`. I want to give out my address to my friend `QmBob`, but I'm behind a NAT that won't let anyone dial me directly.
 
 The most basic `p2p-circuit` address I can construct looks like this:
 
@@ -35,11 +35,11 @@ The address above is interesting, because it doesn't include any [transport](/co
 
 A better address would be something like `/p2p/QmRelay/p2p-circuit/p2p/QmAlice`. This includes the identity of a specific relay peer, `QmRelay`. If a peer already knows how to open a connection to `QmRelay`, they'll be able to reach us.
 
-Better still is to include the transport addresses for the relay peer in the address. Let's say that I've established a connection to a specific relay with the peer id `QmRelay`. They told me via the identify protocol that they're listening for TCP connections on port `55555` at IPv4 address `7.7.7.7`. I can construct an address that describes a path to me through that specific relay over that transport:
+Better still is to include the transport addresses for the relay peer in the address. Let's say that I've established a connection to a specific relay with the Peer ID `QmRelay`. They told me via the identify protocol that they're listening for TCP connections on port `55555` at IPv4 address `7.7.7.7`. I can construct an address that describes a path to me through that specific relay over that transport:
 
 `/ip4/7.7.7.7/tcp/55555/p2p/QmRelay/p2p-circuit/p2p/QmAlice`
 
-Everything prior to the `/p2p-circuit/` above is the address of the relay peer, which includes the transport address and their peer id `QmRelay`. After `/p2p-circuit/` is the peer id for my peer at the other end of the line, `QmAlice`.
+Everything prior to the `/p2p-circuit/` above is the address of the relay peer, which includes the transport address and their Peer ID `QmRelay`. After `/p2p-circuit/` is the Peer ID for my peer at the other end of the line, `QmAlice`.
 
 By giving the full relay path to my friend `QmBob`, they're able to quickly establish a relayed connection without having to "ask around" for a relay that has a route to `QmAlice`.
 

content/concepts/nat.md

@@ -40,7 +40,7 @@ However, an external peer can tell us what address they observed us on. We can t
 
 This basic premise of peers informing each other of their observed addresses is the foundation of [STUN][wiki_stun] (Session Traversal Utilities for NAT), which [describes][rfc_stun] a client / server protocol for discovering publicly reachable IP address and port combinations.
 
-One of libp2p's core protocols is the [identify protocol][spec_identify], which allows one peer to ask another for some identifying information. When sending over their [public key](/concepts/peer-id/) and some other useful information, the peer being identified includes the set of addresses that it has observed for the peer asking the question.
+One of libp2p's core protocols is the [identify protocol][spec_identify], which allows one peer to ask another for some identifying information. When sending over their [public key](/concepts/peers/) and some other useful information, the peer being identified includes the set of addresses that it has observed for the peer asking the question.
 
 This external discovery mechanism serves the same role as STUN, but without the need for a set of "STUN servers".
 

content/concepts/peer-id.md → content/concepts/peers.md

@@ -1,58 +1,54 @@
 ---
-title: Peer Identity
+title: All about Peers
 weight: 4
 ---
 
-A Peer Identity (often written `PeerId`) is a unique reference to a specific
+## Peer ID
+
+A Peer Identity (often written `PeerID`) is a unique reference to a specific
 peer within the overall peer-to-peer network.
 
-As well as serving as a unique identifier for each peer, a PeerId is a
+As well as serving as a unique identifier for each peer, a Peer ID is a
 verifiable link between a peer and its public cryptographic key.
 
-### What is a PeerId
-
 Each libp2p peer controls a private key, which it keeps secret from all other
 peers. Every private key has a corresponding public key, which is shared with
 other peers.
 
 Together, the public and private key (or "key pair") allow peers to establish
 [secure communication](/concepts/secure-comms/) channels with each other.
 
-Conceptually, a PeerId is a [cryptographic hash][wiki_hash_function] of a peer's
+Conceptually, a Peer ID is a [cryptographic hash][wiki_hash_function] of a peer's
 public key. When peers establish a secure channel, the hash can be used to
 verify that the public key used to secure the channel is the same one used
 to identify the peer.
 
-The [PeerId spec][spec_peerid] goes into detail about the byte formats used
-for libp2p public keys and how to hash the key to produce a valid PeerId.
-
-PeerIds are encoded using the [multihash][definition_multihash] format, which
-adds a small header to the hash itself that identifies the hash algorithm used
-to produce it.
+The [Peer ID spec][spec_peerid] goes into detail about the byte formats used
+for libp2p public keys and how to hash the key to produce a valid Peer ID.
 
 ### How are Peer Ids represented as strings?
 
-PeerIds are [multihashes][definition_multihash], which are defined as a
+Peer Ids are [multihashes][definition_multihash], which are defined as a
 compact binary format.
 
 It's very common to see multihashes encoded into
 [base 58][wiki_base58], using
 [the same alphabet used by bitcoin](https://en.bitcoinwiki.org/wiki/Base58#Alphabet_Base58).
 
-Here's an example of a PeerId represented as a base58-encoded multihash:
+Here's an example of a Peer ID represented as a base58-encoded multihash:
 `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`
 
 While it's possible to represent multihashes in many textual formats
-(for example as hexadecimal, base64, etc), PeerIds *always* use the base58
+(for example as hexadecimal, base64, etc), Peer Ids *always* use the base58
 encoding, with no [multibase prefix](https://github.com/multiformats/multibase)
 when encoded into strings.
 
-### PeerIds in multiaddrs
+### Peer IDs in multiaddrs
 
-A PeerId can be encoded into a [multiaddr][definition_multiaddr] as a `/p2p`
-address with the PeerId as a parameter.
+A Peer ID can be encoded into a [multiaddr][definition_multiaddr] as a `/p2p`
+address with the Peer ID as a parameter.
 
-If my peer id is `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`, a
+If my Peer ID is `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`, a
 libp2p multiaddress for me would be:
 
 ```
@@ -71,7 +67,7 @@ the above with a [transport](/concepts/transport/) address
 This provides enough information to dial a specific peer over a TCP/IP
 transport. If some other peer has taken over that IP address or port, it will be
 immediately obvious, since they will not have control over the key pair used to
-produce the PeerId embedded in the address.
+produce the Peer ID embedded in the address.
 
 **For more on addresses in libp2p, see [Addressing](/concepts/addressing/)**
 
@@ -83,22 +79,36 @@ representation in multiaddrs. Which one is rendered in the string format
 depends on the version of the multiaddr library in use.
 {{% /notice %}}
 
-
-### PeerInfo
+## Peer Info
 
 Another common libp2p data structure related to peer identity is the `PeerInfo`
 structure.
 
-A `PeerInfo` combines a `PeerId` with a set of [multiaddrs][definition_multiaddr]
+Peer Info combines a Peer ID with a set of [multiaddrs][definition_multiaddr]
 that the peer is listening on.
 
-libp2p applications will generally keep a "peer store" or "peer book" that
-maintains a collection of `PeerInfo` objects for all the peers that they're
-aware of.
+## Peer Store
+
+A libp2p node will typically have a temporary store to store peer keys, 
+addresses and associated metadata. The peer store works like a phone or address 
+book; think of it like a universal multiaddr book that maintains the source of truth 
+for all known peers. 
+
+{{% notice "info" %}}
+Implementations may wish to persist a snapshot of the peer store on shutdown, so that 
+they don’t have to start with an empty peer store when they boot up the next time.
+
+{{% /notice %}}
+
+### Peer Discovery
+
+A discovery method is likely needed if no information about a peer is available in the 
+peer store. A peer multiaddr is typically discovered with their Peer ID. Once the network 
+successfully discovers a peer multiaddr (and able to establish a connection), the peer discovery 
+protocol adds the Peer Info and multiaddr to the Peer Store. Learn more about how to discover 
+un-{known, identified} peers on the peer routing guide.
 
-The peer store acts as a sort of "phone book" when dialing out to
-other peers; if a peer is in the peer store, we probably don't need to discover
-their addresses using [peer routing](/concepts/peer-routing/).
+<!-- to add when peer routing guide is up -->
 
 [wiki_hash_function]: https://en.wikipedia.org/wiki/Cryptographic_hash_function
 [wiki_base58]: https://en.wikipedia.org/wiki/Base58
@@ -107,3 +117,4 @@ their addresses using [peer routing](/concepts/peer-routing/).
 [definition_multihash]: /reference/glossary/#multihash
 
 [spec_peerid]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md
+[identity]: https://github.com/libp2p/specs/blob/master/identify/README.md#identifypush

content/concepts/protocols.md

@@ -7,7 +7,7 @@ There are protocols everywhere you look when you're writing network applications
 especially thick with them.
 
 The kind of protocols this article is concerned with are the ones built with libp2p itself,
-using the core libp2p abstractions like [transport](/concepts/transport), [peer identity](/concepts/peer-id/), [addressing](/concepts/addressing/), and so on.
+using the core libp2p abstractions like [transport](/concepts/transport), [peer identity](/concepts/peers#peer-id/), [addressing](/concepts/addressing/), and so on.
 
 Throughout this article, we'll call this kind of protocol that is built with libp2p
 a **libp2p protocol**, but you may also see them referred to as "wire protocols" or "application protocols".
@@ -167,7 +167,7 @@ The basic identify protocol works by establishing a new stream to a peer using t
 shown in the table above.
 
 When the remote peer opens the new stream, they will fill out an [`Identify` protobuf message][identify_proto] containing
-information about themselves, such as their public key, which is used to derive their [`PeerId`](/concepts/peer-id/).
+information about themselves, such as their public key, which is used to derive their [`PeerId`](/concepts/peers/).
 
 Importantly, the `Identify` message includes an `observedAddr` field that contains the [multiaddr][definition_multiaddr] that
 the peer observed the request coming in on. This helps peers determine their NAT status, since it allows them to

content/concepts/publish-subscribe.md

@@ -556,7 +556,7 @@ the full message column populated with a purple speech bubble representing
 that the full message contents are remembered as part of the state for
 messages seen in the last few seconds. All eight of the table rows are
 bracketed with the label “Last 2 minutes”, however for the last four rows
-the full message column is empty. These rows only have the sender (peer ID),
+the full message column is empty. These rows only have the sender (Peer ID),
 sequence number and time first seen columns populated. The table rows are
 listed in order of time first seen, from 1 second ago in the top row to 90
 seconds ago in the bottom row. Some of the sequence numbers are shared between

content/concepts/security-considerations.md

@@ -23,7 +23,7 @@ reasonably succeed.
 
 ## Identity and Trust
 
-Every libp2p peer is uniquely identified by their [peer id](../peer-id/), which
+Every libp2p peer is uniquely identified by their [Peer ID](../peers#peer-id/), which
 is derived from a private cryptographic key. Peer ids and their corresponding
 keys allow us to _authenticate_ remote peers, so that we can be sure we're
 talking to the correct peer and not an imposter.
@@ -40,7 +40,7 @@ hierarchy of roles, the requested resources or services, etc.
 
 To design an authorization system on libp2p, you can rely on the authentication
 of peer ids and build an association between peer ids and permissions, with the
-peer id serving the same function as the "username" in traditional authorization
+Peer ID serving the same function as the "username" in traditional authorization
 frameworks, and the peer's private key serving as the "password". Your [protocol
 handler](../protocols/) could then reject requests from untrusted peers.
 

content/concepts/transport.md

@@ -69,7 +69,7 @@ transport the address you'd like to listen on, and when dialing you provide the
 address to dial to.
 
 When dialing a remote peer, the multiaddress should include the
-[PeerId](/concepts/peer-id/) of the peer you're trying to reach.
+[PeerId](/concepts/peers/) of the peer you're trying to reach.
 This lets libp2p establish a [secure communication channel](/concepts/secure-comms/)
 and prevents impersonation.
 
@@ -81,7 +81,7 @@ An example multiaddress that includes a `PeerId`:
 
 The `/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6` component uniquely
 identifies the remote peer using the hash of its public key.
-For more, see [Peer Identity](/concepts/peer-id/).
+For more, see [Peer Identity](/concepts/peers/).
 
 {{% notice "tip" %}}