FIL Spec Sections Restructuring Proposal

[yiannisbot]

The current structure of spec sections does not seem to reflect well the way the Filecoin protocol works, or at least it's not clear enough, e.g., network protocols (e.g., GossipSub, BlockSync) are included under algorithms, or Filecoin Nodes/Files are not really "Systems", which is the section they're included in.

I propose the following restructuring, which does not include CryptoEconomics. I think CryptoEconomics should be a section of its own after section 5. For Section 5, @nicola will have a better idea of how to structure internally.

1. Intro

2. FIL Base Elements 2.1 FIL Nodes 2.2 FIL Files & Data 2.3 FIL Token

3. Network, Data & Value Transfer Protocols 3.1 GossipSub 3.2 BlockSync 3.3 Data Transfer Protocol 3.4 Payment Channels

4. FIL Systems 4.1 FIL VM 4.2 FIL Blockchain 4.3 FIL Storage Mining 4.4 FIL Markets

5. FIL Proofs and Consensus Algorithms 5.1 Expected Consensus 5.2 Stacked DRG Proof of Replication 5.3 Proof of SpaceTime

6. Libraries 6.1 DRAND 6.2 FIL Crypto 6.3 Cryptographic Primitives 6.4 FCS (?) 6.5 Multiformats 6.6 IPLD 6.7 libp2p

7. Listings

8. Glossary

9. Appendix

10. Implementations

Any feedback and further suggestions more than welcome!

cc: @nicola @anorth @whyrusleeping @schomatis @daviddias

[nicola]

This is the direction in which I was going to. However, I think the restructuring should also apply to subsection, for example currently the Storage Power Actor has a section on randomness and I don't think it should belong there.

[yiannisbot]

@nicola I totally agree, I just started from the top level. Another concerning part is the Storage Market section, which is primarily about off-chain processes, but also includes discussion on on-chain processes (deal statuses etc.) and becomes confusing.

I'm happy to go to the (sub-)subsection level.

[yiannisbot]

After a quick sync with @nicola we have agreed that we'll proceed with the above structure with the following issues pending:

• Section 4 on FIL Systems might be renamed to FIL Protocol, or
• we will need a new Section 5 on FIL Protocol.
• it might make sense to move Expected Consensus to the FIL VM section.

This will be decided once @nicola's spec writing effort completes in the next two weeks.