add more info about peer discovery (#143)

* add more info about peer discovery

Co-authored-by: Nicolas MASSART <[email protected]>

docs/Concepts/p2p-discovery.md

@@ -4,10 +4,21 @@ description: P2P Tessera Node Discovery
 
 # Node discovery
 
-Tessera uses peer discovery to discover Tessera nodes in the network. Tessera nodes share their
-entire peer lists, enabling new nodes to discover all nodes in the network. When sharing their peer lists,
-Tessera broadcasts the public keys for each node and the list of URLs with which each node has
-current active communication.
+Tessera peer discovery works in a similar way to peer discovery in
+[Hyperledger Besu](https://besu.hyperledger.org/en/stable/HowTo/Find-and-Connect/Managing-Peers/#manage-peers)
+and [GoQuorum](https://consensys.net/docs/goquorum/en/stable/configure-and-manage/configure/bootnodes/).
+Tessera nodes share their list of peer URLs, and the public keys of those peers. In this way, nodes joining
+the network can discover other nodes in the network, and the public keys of other participants.
+
+Nodes in the network do not all need to have the same list of [configured peers](../HowTo/Configure/Peer-discovery.md#specify-peers).
+You can think of this list as the starting point for discovering other nodes, similar to bootnodes in [Hyperledger Besu](https://besu.hyperledger.org/en/stable/HowTo/Find-and-Connect/Bootnodes/) or [GoQuorum](https://consensys.net/docs/goquorum/en/stable/configure-and-manage/configure/bootnodes/).
+
+The [`partyinfo` API method](https://consensys.github.io/doc.tessera/#operation/getPartyInfo) returns nodes
+with which Tessera has a current active connection.
+
+[Configure peer discovery](../HowTo/Configure/Peer-discovery.md) in the Tessera configuration file.
+
+## Under the hood
 
 Tessera maintains two node lists, `PartyStore` and `NetworkStore`. `NetworkStore` lists nodes with
 which an active connection has been established. `PartyStore` lists URLs from the [`peer` entry in the Tessera configuration file](../HowTo/Configure/Peer-discovery.md#specify-peers)
@@ -16,10 +27,11 @@ removed from both the `PartyStore` and `NetworkStore` lists.
 
 If all peers are removed from the `PartyStore` and `NetworkStore` lists, the `PartyStore` list is repopulated
 from the [`peer` entry in the Tessera configuration file](../HowTo/Configure/Peer-discovery.md#specify-peers).
+
 A dropped remote peer is added to the `NetworkStore` list only after establishing direct communication with
 the peer. That is, discovering a dropped remote peer is not enough for a node to be added to the active peer list.
 
-The [`partyinfo` API method](https://consensys.github.io/doc.tessera/#operation/getPartyInfo) returns nodes
-with which Tessera has a current active connection (that is, nodes listed in `NetworkStore`).
+## Multi-tenancy
 
-[Configure peer discovery in the Tessera configuration file](../HowTo/Configure/Peer-discovery.md).
+Adding a new key to a multi-tenant Tessera node (and restarting that node) results in the new key being propagated
+to other nodes in the network via peer discovery.

docs/HowTo/Configure/Peer-discovery.md

@@ -59,7 +59,7 @@ Specify the peer list using [`peer`](../../Reference/SampleConfiguration.md#peer
 ## Enable allowlist
 
 The Tessera allowlist (whitelist) restricts connections for Tessera in the same way the [`permissioned-nodes.json`
-file does for GoQuorum](https://docs.goquorum.consensys.net/en/stable/Concepts/PermissionsOverview/#basic-network-permissioning).
+file does for GoQuorum](https://consensys.net/docs/goquorum/en/stable/configure-and-manage/configure/permissioning/basic-permissions/).
 
 Set [`useWhitelist`](../../Reference/SampleConfiguration.md#usewhitelist) in the configuration file to `true` to indicate
 that only [specified peers](#specify-peers) can connect or submit transactions.
@@ -70,7 +70,7 @@ that only [specified peers](#specify-peers) can connect or submit transactions.
     "useWhiteList": true,
     ```
 
-### Enable remote key validation
+## Enable remote key validation
 
 Remote key validation checks that a remote node owns the public keys being advertised.
 Enable remote key validation by setting [`enableRemoteKeyValidation`](../../Reference/SampleConfiguration.md#features)