Add PeerStore content & TEMP generalize PeerID guide

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

@@ -1,56 +1,52 @@
 ---
-title: Peer Identity
+title: All about Peers
 weight: 4
 ---
 
+## 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
 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