From d40794580d5983fbe84f88f389e8c4c6248cae53 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 19 Sep 2022 01:11:47 -0400 Subject: [PATCH 1/6] generalize peerid guide and add peerstore --- content/concepts/{peer-id.md => peers.md} | 39 ++++++++++++++++++++--- 1 file changed, 35 insertions(+), 4 deletions(-) rename content/concepts/{peer-id.md => peers.md} (57%) diff --git a/content/concepts/peer-id.md b/content/concepts/peers.md similarity index 57% rename from content/concepts/peer-id.md rename to content/concepts/peers.md index 3f21c76e..975a6bfc 100644 --- a/content/concepts/peer-id.md +++ b/content/concepts/peers.md @@ -1,16 +1,16 @@ --- -title: Peer Identity +title: All about Peers weight: 4 --- +### What is a PeerId + 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 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. @@ -83,7 +83,6 @@ representation in multiaddrs. Which one is rendered in the string format depends on the version of the multiaddr library in use. {{% /notice %}} - ### PeerInfo Another common libp2p data structure related to peer identity is the `PeerInfo` @@ -107,3 +106,35 @@ 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 + +## PeerStore + +`PeerStore`, also known as a `PeerBook`, is a register in libp2p that holds an updated data registry of all known peers, known as `PeerInfo`. Other peers can dial the `PeerStore` and listen for updates and learn about +any peer within the network. The `PeerStore` works like a phone or address book.; think of it like a multiaddr book. To maintain the source of truth for all `PeerInfo`: + +- `addressBook`: holds the known `multiaddrs` of a peer, which may change over time, which the book accounts for. +- `keyBook`: uses the`PeerId` to keep track of the peers' public keys. +- `protocolBook`: holds the protocol identifiers that each peer supports, which may change over time, which the `protocolBook` accounts for. +- `metadataBook`: Keeps track of the available peer metadata, which is stored in a key-value fashion, where a key identifier (string) represents a metadata value (Uint8Array). + +The `PeerStore` also provides an API for the components of the inner book, as well as data events. + +A `datastore` helps with data persistence for peers that may have been offline or reset, to improve connection efficiency on the libp2p network. A libp2p node will need to receive a `datastore` to persist data across restarts—a `datastore` stores data as key-value pairs. The store maintains data persistence and connection efficiency by not constantly updating the `datastore` with new data. Instead, the `datastore` stores new data only after reaching a certain threshold of peers out-of-date, and when a node stops to, batch writes to the datastore. + +The `PeerID` appends the `datastore` key for each data namespace. The namespaces were defined as follows: + +The `PeerStore` also uses an Event Emitter to notify interested parties of relevant events, such as peer discovery. + +### Discovery events + +A discovery method is likely needed if a peer is undiscoverable using the `PeerStore`. A peer `multiaddr` is typically discovered with their `PeerId`. Once the network successfully discovers a peer `multiaddr`, the peer discovery protocol will emit a peer event to add the `PeerInfo` and peer `multiaddr` to the `PeerStore`. Learn more about how to discover un-{known, identified} peers on the Peer Routing guide. + +This is one way that the network updates the `PeerStore`. In general, an identify protocol automatically runs on every connection when multiplexing is enabled. The protocol will put the `multiaddrs` and protocols identifiers provided by the peer to the `PeerStore`. Similarly, an `IdentifyPush` protocol waits for change notifications about protocols that a peer supports and updates the `PeerStore` accordingly. + +### Retreival events + +The `PeerStore` emits a `peer` event to the libp2p network when the network discovers a new peer. Peers can dial the new peer to retrieve its `PeerInfo`. + +The `PeerStore` emits a `change:protocols` event when the supported protocols of a peer change. + +The `PeerStore` emits a `change:multiaddrs` event when the known listening multiaddrs of a peer changes. From 2cea94e94bac6769bae62a238228c59972e43e90 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Tue, 20 Sep 2022 20:02:38 -0400 Subject: [PATCH 2/6] edit store content, generalize + addr pr feedback --- content/concepts/peers.md | 102 ++++++++++++++++++++++---------------- 1 file changed, 58 insertions(+), 44 deletions(-) diff --git a/content/concepts/peers.md b/content/concepts/peers.md index 975a6bfc..cbd3f70d 100644 --- a/content/concepts/peers.md +++ b/content/concepts/peers.md @@ -3,12 +3,12 @@ title: All about Peers weight: 4 --- -### What is a PeerId +## 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. Each libp2p peer controls a private key, which it keeps secret from all other @@ -18,39 +18,39 @@ 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. +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 Pee Id. -PeerIds are encoded using the [multihash][definition_multihash] format, which +Peer Ids 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. ### 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 +71,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 +83,14 @@ 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. - -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/). - [wiki_hash_function]: https://en.wikipedia.org/wiki/Cryptographic_hash_function [wiki_base58]: https://en.wikipedia.org/wiki/Base58 @@ -107,34 +99,56 @@ their addresses using [peer routing](/concepts/peer-routing/). [spec_peerid]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md -## PeerStore - -`PeerStore`, also known as a `PeerBook`, is a register in libp2p that holds an updated data registry of all known peers, known as `PeerInfo`. Other peers can dial the `PeerStore` and listen for updates and learn about -any peer within the network. The `PeerStore` works like a phone or address book.; think of it like a multiaddr book. To maintain the source of truth for all `PeerInfo`: - -- `addressBook`: holds the known `multiaddrs` of a peer, which may change over time, which the book accounts for. -- `keyBook`: uses the`PeerId` to keep track of the peers' public keys. -- `protocolBook`: holds the protocol identifiers that each peer supports, which may change over time, which the `protocolBook` accounts for. -- `metadataBook`: Keeps track of the available peer metadata, which is stored in a key-value fashion, where a key identifier (string) represents a metadata value (Uint8Array). +## Peer Store -The `PeerStore` also provides an API for the components of the inner book, as well as data events. +A libp2p node will typically have a temporary store to store peer keys, +addresses and associated metadata. `PeerStore`, also known as a `PeerBook`, +is a register in libp2p that holds an updated data (Peer Info) registry of all +known peers. Other peers can dial the peer store and listen for updates and learn +about any peer within the network. 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. -A `datastore` helps with data persistence for peers that may have been offline or reset, to improve connection efficiency on the libp2p network. A libp2p node will need to receive a `datastore` to persist data across restarts—a `datastore` stores data as key-value pairs. The store maintains data persistence and connection efficiency by not constantly updating the `datastore` with new data. Instead, the `datastore` stores new data only after reaching a certain threshold of peers out-of-date, and when a node stops to, batch writes to the datastore. - -The `PeerID` appends the `datastore` key for each data namespace. The namespaces were defined as follows: +{{% notice "note" %}} -The `PeerStore` also uses an Event Emitter to notify interested parties of relevant events, such as peer discovery. +With different design choices possible, here is a snapshot of how the js-libp2p +implements the peer store: an `addressBook` holds the known multiaddrs of a peer, +which may change over time, which the book accounts for; a `keyBook` uses the Peer Id +to keep track of the peers' public keys; a `protocolBook` holds the protocol identifiers +that each peer supports, which may change over time, which the `protocolBook` accounts +for; a `metadataBook` keeps track of the available peer metadata, which is stored in a +key-value fashion, where a key identifier (string) represents a metadata value (Uint8Array). +There is also an API to expose the components of the inner book, as well as data events +to emit data about new information and changes. + +{{% /notice %}} -### Discovery events +A datastore helps with data persistence for peers that may have been offline or reset, to +improve connection efficiency on the libp2p network. A libp2p node will need to receive a +datastore to persist data across restarts—a datastore stores data as key-value pairs. The +store maintains data persistence and connection efficiency by not constantly updating the +datastore with new data. Instead, the datastore stores new data only after reaching a certain +threshold of peers out-of-date, and when a node stops to, batch writes to the datastore. +The Peer ID will be appended to the datastore key for each data namespace. -A discovery method is likely needed if a peer is undiscoverable using the `PeerStore`. A peer `multiaddr` is typically discovered with their `PeerId`. Once the network successfully discovers a peer `multiaddr`, the peer discovery protocol will emit a peer event to add the `PeerInfo` and peer `multiaddr` to the `PeerStore`. Learn more about how to discover un-{known, identified} peers on the Peer Routing guide. +### Peer Discovery -This is one way that the network updates the `PeerStore`. In general, an identify protocol automatically runs on every connection when multiplexing is enabled. The protocol will put the `multiaddrs` and protocols identifiers provided by the peer to the `PeerStore`. Similarly, an `IdentifyPush` protocol waits for change notifications about protocols that a peer supports and updates the `PeerStore` accordingly. +A discovery method is likely needed if a peer is undiscoverable using 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. -### Retreival events + -The `PeerStore` emits a `peer` event to the libp2p network when the network discovers a new peer. Peers can dial the new peer to retrieve its `PeerInfo`. +This is one way that the network updates the Peer Store. In general, an Identify protocol +automatically runs on every connection when multiplexing is enabled. The protocol will put +the multiaddrs and protocols identifiers provided by the peer to the Peer Store. Similarly, +the Identity protocol waits for change notifications about protocols that a peer supports +and updates the Peer Store accordingly. -The `PeerStore` emits a `change:protocols` event when the supported protocols of a peer change. +### Peer Retrieval -The `PeerStore` emits a `change:multiaddrs` event when the known listening multiaddrs of a peer changes. +The Peer Store notifies the libp2p network when the network discovers +a new peer. The Peer Store also notifies the network about changes to the Peer Info +about the peer, such as the peer's supported protocols and known multiaddrs. From ee3d2745dc4e37aa64c9cba2ab8cf6d8d5ebddac Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Tue, 20 Sep 2022 20:08:22 -0400 Subject: [PATCH 3/6] added link to identity/push and move links to bottom --- content/concepts/peers.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/content/concepts/peers.md b/content/concepts/peers.md index cbd3f70d..d51ccd6b 100644 --- a/content/concepts/peers.md +++ b/content/concepts/peers.md @@ -91,14 +91,6 @@ structure. Peer Info combines a Peer Id with a set of [multiaddrs][definition_multiaddr] that the peer is listening on. -[wiki_hash_function]: https://en.wikipedia.org/wiki/Cryptographic_hash_function -[wiki_base58]: https://en.wikipedia.org/wiki/Base58 - -[definition_multiaddr]: /reference/glossary/#multiaddr -[definition_multihash]: /reference/glossary/#multihash - -[spec_peerid]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md - ## Peer Store A libp2p node will typically have a temporary store to store peer keys, @@ -141,14 +133,23 @@ un-{known, identified} peers on the peer routing guide. -This is one way that the network updates the Peer Store. In general, an Identify protocol -automatically runs on every connection when multiplexing is enabled. The protocol will put -the multiaddrs and protocols identifiers provided by the peer to the Peer Store. Similarly, -the Identity protocol waits for change notifications about protocols that a peer supports -and updates the Peer Store accordingly. +This is one way that the network updates the Peer Store. +In general, an [Identify protocol][identity] automatically runs on every connection when +multiplexing is enabled. The protocol will put the multiaddrs and protocols identifiers provided +by the peer to the Peer Store. Similarly, the Identity protocol waits for change notifications +about protocols that a peer supports and updates the Peer Store accordingly. ### Peer Retrieval The Peer Store notifies the libp2p network when the network discovers a new peer. The Peer Store also notifies the network about changes to the Peer Info about the peer, such as the peer's supported protocols and known multiaddrs. + +[wiki_hash_function]: https://en.wikipedia.org/wiki/Cryptographic_hash_function +[wiki_base58]: https://en.wikipedia.org/wiki/Base58 + +[definition_multiaddr]: /reference/glossary/#multiaddr +[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 \ No newline at end of file From 64af4f689ae396988220c9ac1682cda5ab7aea4b Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 21 Sep 2022 04:15:11 -0400 Subject: [PATCH 4/6] address pr feedback; simplify --- content/concepts/peers.md | 61 +++++++-------------------------------- 1 file changed, 11 insertions(+), 50 deletions(-) diff --git a/content/concepts/peers.md b/content/concepts/peers.md index d51ccd6b..23906647 100644 --- a/content/concepts/peers.md +++ b/content/concepts/peers.md @@ -24,11 +24,7 @@ verify that the public key used to secure the channel is the same one used to identify the peer. 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 Pee Id. - -Peer Ids 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. +for libp2p public keys and how to hash the key to produce a valid Peer Id. ### How are Peer Ids represented as strings? @@ -94,57 +90,22 @@ that the peer is listening on. ## Peer Store A libp2p node will typically have a temporary store to store peer keys, -addresses and associated metadata. `PeerStore`, also known as a `PeerBook`, -is a register in libp2p that holds an updated data (Peer Info) registry of all -known peers. Other peers can dial the peer store and listen for updates and learn -about any peer within the network. 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 "note" %}} - -With different design choices possible, here is a snapshot of how the js-libp2p -implements the peer store: an `addressBook` holds the known multiaddrs of a peer, -which may change over time, which the book accounts for; a `keyBook` uses the Peer Id -to keep track of the peers' public keys; a `protocolBook` holds the protocol identifiers -that each peer supports, which may change over time, which the `protocolBook` accounts -for; a `metadataBook` keeps track of the available peer metadata, which is stored in a -key-value fashion, where a key identifier (string) represents a metadata value (Uint8Array). -There is also an API to expose the components of the inner book, as well as data events -to emit data about new information and changes. - -{{% /notice %}} - -A datastore helps with data persistence for peers that may have been offline or reset, to -improve connection efficiency on the libp2p network. A libp2p node will need to receive a -datastore to persist data across restarts—a datastore stores data as key-value pairs. The -store maintains data persistence and connection efficiency by not constantly updating the -datastore with new data. Instead, the datastore stores new data only after reaching a certain -threshold of peers out-of-date, and when a node stops to, batch writes to the datastore. -The Peer ID will be appended to the datastore key for each data namespace. +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. 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. ### Peer Discovery -A discovery method is likely needed if a peer is undiscoverable using 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 +A discovery method is likely needed if a peer is undiscoverable using 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. -This is one way that the network updates the Peer Store. -In general, an [Identify protocol][identity] automatically runs on every connection when -multiplexing is enabled. The protocol will put the multiaddrs and protocols identifiers provided -by the peer to the Peer Store. Similarly, the Identity protocol waits for change notifications -about protocols that a peer supports and updates the Peer Store accordingly. - -### Peer Retrieval - -The Peer Store notifies the libp2p network when the network discovers -a new peer. The Peer Store also notifies the network about changes to the Peer Info -about the peer, such as the peer's supported protocols and known multiaddrs. - [wiki_hash_function]: https://en.wikipedia.org/wiki/Cryptographic_hash_function [wiki_base58]: https://en.wikipedia.org/wiki/Base58 @@ -152,4 +113,4 @@ about the peer, such as the peer's supported protocols and known multiaddrs. [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 \ No newline at end of file +[identity]: https://github.com/libp2p/specs/blob/master/identify/README.md#identifypush From af01480690a37edabb1bb50acfc38be428843735 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 21 Sep 2022 04:19:15 -0400 Subject: [PATCH 5/6] edits --- content/concepts/peers.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/content/concepts/peers.md b/content/concepts/peers.md index 23906647..0b6d22a0 100644 --- a/content/concepts/peers.md +++ b/content/concepts/peers.md @@ -92,16 +92,20 @@ that the peer is listening on. 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. 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. +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 a peer is undiscoverable using 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 +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. From 2a1be32966a4fc5dca2f1d36617ca7ff19dad1b8 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Fri, 23 Sep 2022 12:58:42 -0400 Subject: [PATCH 6/6] update peer id ref + replace Id with ID --- content/concepts/addressing.md | 4 ++-- content/concepts/circuit-relay.md | 10 ++++---- content/concepts/nat.md | 2 +- content/concepts/peers.md | 26 ++++++++++----------- content/concepts/protocols.md | 4 ++-- content/concepts/publish-subscribe.md | 2 +- content/concepts/security-considerations.md | 4 ++-- content/concepts/transport.md | 4 ++-- 8 files changed, 28 insertions(+), 28 deletions(-) diff --git a/content/concepts/addressing.md b/content/concepts/addressing.md index 77526533..c86dcc03 100644 --- a/content/concepts/addressing.md +++ b/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. diff --git a/content/concepts/circuit-relay.md b/content/concepts/circuit-relay.md index 9284e73b..ffd44889 100644 --- a/content/concepts/circuit-relay.md +++ b/content/concepts/circuit-relay.md @@ -15,7 +15,7 @@ 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 @@ -23,9 +23,9 @@ Today there are two versions of the circuit relay protocol, [v1](https://github. #### 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`. diff --git a/content/concepts/nat.md b/content/concepts/nat.md index 6d2ad6f8..de32d6c0 100644 --- a/content/concepts/nat.md +++ b/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". diff --git a/content/concepts/peers.md b/content/concepts/peers.md index 0b6d22a0..888d2eab 100644 --- a/content/concepts/peers.md +++ b/content/concepts/peers.md @@ -5,10 +5,10 @@ weight: 4 ## Peer ID -A Peer Identity (often written `PeerId`) is a unique reference to a specific +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 Peer Id 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. Each libp2p peer controls a private key, which it keeps secret from all other @@ -18,13 +18,13 @@ 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 Peer Id 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 [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. +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? @@ -35,7 +35,7 @@ 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 Peer Id 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 @@ -43,12 +43,12 @@ While it's possible to represent multihashes in many textual formats encoding, with no [multibase prefix](https://github.com/multiformats/multibase) when encoded into strings. -### Peer Ids in multiaddrs +### Peer IDs in multiaddrs -A Peer Id can be encoded into a [multiaddr][definition_multiaddr] as a `/p2p` -address with the Peer Id 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: ``` @@ -67,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 Peer Id embedded in the address. +produce the Peer ID embedded in the address. **For more on addresses in libp2p, see [Addressing](/concepts/addressing/)** @@ -84,7 +84,7 @@ depends on the version of the multiaddr library in use. Another common libp2p data structure related to peer identity is the `PeerInfo` structure. -Peer Info combines a Peer Id 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. ## Peer Store @@ -103,7 +103,7 @@ they don’t have to start with an empty peer store when they boot up the next t ### 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 +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. diff --git a/content/concepts/protocols.md b/content/concepts/protocols.md index 8352042a..9b878909 100644 --- a/content/concepts/protocols.md +++ b/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 diff --git a/content/concepts/publish-subscribe.md b/content/concepts/publish-subscribe.md index 376ef448..d8b2a08d 100644 --- a/content/concepts/publish-subscribe.md +++ b/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 diff --git a/content/concepts/security-considerations.md b/content/concepts/security-considerations.md index 2a53b606..ce845d9b 100644 --- a/content/concepts/security-considerations.md +++ b/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. diff --git a/content/concepts/transport.md b/content/concepts/transport.md index b54039e2..79026208 100644 --- a/content/concepts/transport.md +++ b/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" %}}