FIL nodes update

content/appendix/network_params.md

@@ -16,9 +16,6 @@ Most are generated/finalized using the [orient framework](https://github.com/fil
 ⚠️ **WARNING:** Filecoin is not yet launched, and we are finishing protocol spec and implementations. Parameters are set here as placeholders and highly likely to change to fit product and security requirements.
 {{</hint>}}
 
-## Code parameters
-
-{{<embed src="../systems/filecoin_nodes/node_base/network_params.go" lang="go" >}}
 
 ## Orient parameters
 

content/intro/systems/impl_systems.md

@@ -34,11 +34,7 @@ All Systems, as defined in this document, require the following:
   Systems expect to be initialized with a Clock from which to tell network time. Some systems (like Blockchain)
   require very little clock drift, and require _secure_ time.
 
-For this purpose, we use the `FilecoinNode` data structure, which is passed into all systems at initialization:
-
-{{<embed src="../../systems/filecoin_nodes/node_base/filecoin_node.id" lang="go">}}
-
-{{<embed src="../../systems/filecoin_nodes/repository/repository_subsystem.id" lang="go" >}}
+For this purpose, we use the `FilecoinNode` data structure, which is passed into all systems at initialization.
 
 ## System Limitations
 

content/systems/filecoin_nodes/_index.md

@@ -3,15 +3,15 @@ title: Filecoin Nodes
 bookCollapseSection: true
 weight: 1
 dashboardWeight: 1
-dashboardState: wip
+dashboardState: reliable
 dashboardAudit: n/a
 dashboardTests: 0
 ---
 
 # Filecoin Nodes
 
-This section is providing all the details needed in order to implement any of the different Filecoin Nodes. Although node types in the Filecoin blockchain are less strictly defined than in other blockchains, there are still a few different types of nodes each with its own features and characteristics.
+This section starts by discussing the concept of Filecoin Nodes. Although different node types in the Lotus implementation of Filecoin are less strictly defined than in other blockchain networks, there are different properties and features that different types of nodes should implement. In short, nodes are defined based on the set of _services_ they provide.
 
-In this section we also discuss issues related to storage of system files in Filecoin nodes. Note that by storage in this section we do not refer to the storage that a node is commiting for mining in the network, but rather the local storage that it needs to have available for keys and IPLD data among other things.
+In this section we also discuss issues related to storage of system files in Filecoin nodes. Note that by storage in this section we do not refer to the storage that a node commits for mining in the network, but rather the local storage repositories that it needs to have available for keys and IPLD data among other things.
 
-The network interface and how nodes connect with each other and interact using libp2p, as well as how to set the node's clock is also discussed here.
+In this section we are also discussing the network interface and how nodes find and connect with each other, how they interact and propagate messages using libp2p, as well as how to set the node's clock.

content/systems/filecoin_nodes/clock/_index.md

@@ -2,23 +2,20 @@
 title: Clock
 weight: 4
 dashboardWeight: 1
-dashboardState: wip
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---
 
 # Clock
 
-{{<embed src="clock_subsystem.id" lang="go" >}}
-{{<embed src="clock_subsystem.go" lang="go" >}}
-
-
 Filecoin assumes weak clock synchrony amongst participants in the system. That is, the system relies on participants having access to a globally synchronized clock (tolerating some bounded drift).
 
 Filecoin relies on this system clock in order to secure consensus.  Specifically the clock is necessary to support validation rules that prevent block producers from mining blocks with a future timstamp, and running leader elections more frequently than the protocol allows.
 
 
 ## Clock uses
+
 The Filecoin system clock is used:
 
 - by syncing nodes to validate that incoming blocks were mined in the appropriate epoch given their timestamp (see [Block Validation](block#block-syntax-validation)).  This is possible because the system clock maps all times to a unique epoch number totally determined by the start time in the genesis block.
@@ -30,7 +27,7 @@ In order to allow miners to do the above, the system clock must:
 1. Have low enough clock drift (sub 1s) relative to other nodes so that blocks are not mined in epochs considered future epochs from the persective of other nodes (those blocks should not be validated until the proper epoch/time as per [validation rules](block#block-semantic-validation)).
 2. Set epoch number on node initialization equal to `epoch = Floor[(current_time - genesis_time) / epoch_time]`
 
-It is expected that other subsystems will register to a NewRound() event from the clock subsystem.
+It is expected that other subsystems will register to a `NewRound()` event from the clock subsystem.
 
 ## Clock Requirements
 
@@ -44,17 +41,8 @@ Computer-grade clock crystals can be expected to have drift rates on the order o
     - `time.cloudflare.com:1234` (more on [Cloudflare time services](https://www.cloudflare.com/time/))
     - `time.google.com` (more on [Google Public NTP](https://developers.google.com/time))
     - `ntp-b.nist.gov` ([NIST](https://tf.nist.gov/tf-cgi/servers.cgi) servers require registration)
-  - We further recommend making 3 measurements in order to drop by using the network to drop outliers
-  - See how [go-ethereum does this](https://github.com/ethereum/go-ethereum/blob/master/p2p/discv5/ntp.go) for inspiration
+  - We further recommend making three (3) measurements in order to drop outliers
 - clients MAY consider using cesium clocks instead for accurate synchrony within larger mining operations
 
 Mining operations have a strong incentive to prevent their clock from drifting ahead more than one epoch to keep their block submissions from being rejected.  Likewise they have an incentive to prevent their clocks from drifting behind more than one epoch to avoid partitioning themselves off from the synchronized nodes in the network.
 
-## Future work
-
-If either of the above metrics show significant network skew over time, future versions of Filecoin may include potential timestamp/epoch correction periods at regular intervals.
-
-When recoverying from exceptional chain halting outages (for example all implementations panic on a given block) the network can potentially opt for per-outage "dead zone" rules banning the authoring of blocks during the outage epochs to prevent attack vectors related to unmined epochs during chain restart.
-
-Future versions of the Filecoin protocol may use Verifiable Delay Functions (VDFs) to strongly enforce block time and fulfill this leader election requirement; we choose to explicitly assume clock synchrony until hardware VDF security has been proven more extensively.
-

content/systems/filecoin_nodes/network/_index.md

@@ -2,59 +2,24 @@
 title: Network Interface
 weight: 3
 dashboardWeight: 1
-dashboardState: wip
-dashboardAudit: wip
+dashboardState: stable
+dashboardAudit: n/a
 dashboardTests: 0
 ---
 
-# Interface
+# Network Interface
 
-{{<embed src="network.id" lang="go" >}}
-
-
-Filecoin nodes use the libp2p protocol for peer discovery, peer routing, and message multicast, and so on. Libp2p is a set of modular protocols common to the peer-to-peer networking stack. Nodes open connections with one another and mount different protocols or streams over the same connection. In the initial handshake, nodes exchange the protocols that each of them supports and all Filecoin related protcols will be mounted under `/fil/...` protocol identifiers.
+Filecoin nodes use several protocols of the libp2p networking stack for peer discovery, peer routing and block and message propagation. Libp2p is a modular networking stack for peer-to-peer networks. It includes several protocols and mechanisms to enable efficient, secure and resilient peer-to-peer communication. Libp2p nodes open connections with one another and mount different protocols or streams over the same connection. In the initial handshake, nodes exchange the protocols that each of them supports and all Filecoin related protocols will be mounted under `/fil/...` protocol identifiers.
 
+The complete specification of libp2p can be found at [https://github.com/libp2p/specs](https://github.com/libp2p/specs).
 Here is the list of libp2p protocols used by Filecoin.
 
-- Graphsync: 
-	- Graphsync is used to transfer blockchain and user data
-	- [Draft spec](https://github.com/ipld/specs/blob/master/block-layer/graphsync/graphsync.md)
-	- No filecoin specific modifications to the protocol id
-- Gossipsub: 
-	- block headers and messages are broadcasted through a Gossip PubSub protocol where nodes can subscribe to topics for blockchain data and receive messages in those topics. When receiving messages related to a topic, nodes process the message and forward it to peers who also subscribed to the same topic.
-	- Spec is [here](https://github.com/libp2p/specs/tree/master/pubsub/gossipsub)
-	- No filecoin specific modifications to the protocol id.  However the topic identifiers MUST be of the form `fil/blocks/<network-name>` and `fil/msgs/<network-name>`
-- KademliaDHT: 
-	- Kademlia DHT is a distributed hash table with a logarithmic bound on the maximum number of lookups for a particular node. Kad DHT is used primarily for peer routing as well as peer discovery in the Filecoin protocol.
-	- Spec TODO [reference implementation](https://github.com/libp2p/go-libp2p-kad-dht)
-	- The protocol id must be of the form `fil/<network-name>/kad/1.0.0`
-- Bootstrap List: 
-	- Bootstrap is a list of nodes that a new node attempts to connect to upon joining the network. The list of bootstrap nodes and their addresses are defined by the users.
-- Peer Exchange: 
-	- Peer Exchange is a discovery protocol enabling peers to create and issue queries for desired peers against their existing peers
-	- spec [TODO](https://github.com/libp2p/specs/issues/222)
-	- No Filecoin specific modifications to the protocol id.
-- DNSDiscovery: Design and spec needed before implementing
-- HTTPDiscovery: Design and spec needed before implementing
-- Hello:
-	- Hello protocol handles new connections to filecoin nodes to facilitate discovery
-	- the protocol string is `fil/hello/1.0.0`. 
-
-## Hello Spec 
-
-### Protocol Flow
-
-`fil/hello` is a filecoin specific protocol built on the libp2p stack.  It consists of two conceptual
-procedures: `hello_connect` and `hello_listen`.   
-
-`hello_listen`: `on new stream` -> `read peer hello msg from stream` -> `write latency message to stream` -> `close stream`
-
-`hello_connect`: `on connected` -> `open stream` -> `write own hello msg to stream` -> `read peer latency msg from stream`  -> `close stream`
+- **Graphsync:** Graphsync is a protocol to synchronize graphs across peers. It is used to reference, address, request and transfer blockchain and user data between Filecoin nodes. The [draft specification of GraphSync](https://github.com/ipld/specs/blob/master/block-layer/graphsync/graphsync.md) provides more details on the concepts, the interfaces and the network messages used by GraphSync. There are no Filecoin-specific modifications to the protocol id.
 
-where stream and connection operations are all standard libp2p operations.  Nodes running the Hello Protocol should consume the incoming Hello Message and use it to help manage peers and sync the chain.
+- **Gossipsub:** Block headers and Transaction messages are propagating through the Filecoin network using a gossip-based pubsub protocol acronymed _GossipSub_. As is traditionally the case with pubsub protocols, nodes subscribe to topics and receive messages published on those topics. When nodes receive messages from a topic they are subscribed to, they run a validation process and i) pass the message to the application, ii) forward the message further to nodes they know off being subscribed to the same topic. Furthermore, v1.1 version of GossipSub, which is the one used in Filecoin is enhanced with security mechanisms that make the protocol resilient against security attacks. The [GossipSub Specification](https://github.com/libp2p/specs/tree/master/pubsub/gossipsub) provides all the protocol details pertaining to its design and implementation, as well as specific settings for the protocols parameters. There have been no filecoin specific modifications to the protocol id. However the topic identifiers MUST be of the form `fil/blocks/<network-name>` and `fil/msgs/<network-name>`
 
-### Messages
-{{<embed src="hello.id" lang="go" >}}
+- **Kademlia DHT:** The Kademlia DHT is a distributed hash table with a logarithmic bound on the maximum number of lookups for a particular node. In the Filecoin network, the Kademlia DHT is used primarily for peer discovery and peer routing. In particular, when a node wants to store data in the Filecoin network, they get a list of miners and their node information. This node information includes (among other things) the PeerID of the miner. In order to connect to the miner and exchange data, the node that wants to store data in the network has to find the Multiaddress of the miner, which they do by queering the DHT. The [libp2p Kad DHT Specification](https://github.com/libp2p/go-libp2p-kad-dht) provides implementation details of the DHT structure. For the Filecoin network, the protocol id must be of the form `fil/<network-name>/kad/1.0.0`.
 
+- **Bootstrap List:** This is a list of nodes that a new node attempts to connect to upon joining the network. The list of bootstrap nodes and their addresses are defined by the users (i.e., applications).
 
-When writing the `HelloMessage` to the stream the peer must inspect its current head to provide accurate information.  When writing the `LatencyMessage` to the stream the peer should set `TArrival` immediately upon receipt and `TSent` immediately before writing the message to the stream.
+- **Peer Exchange:** This protocol is the realisation of the peer discovery process discussed above at Kademlia DHT. It enables peers to find information and addresses of other peers in the network by interfacing with the DHT and create and issue queries for the peers they want to connect to.