Comments (4)
Based on the assertion that a spec is a spec and not a mirror of the code, then it would seem that what's in data_structures is actually incorrect. Clearly if there is a code snippet in a spec that looks to the reader that it is telling you what to expect is in a Block, and this is very different to what is in a different document, that this not only confusing, but one of them is incorrect. That said, my suggestions are this:
-
In general aim to have a single, full canonical description of a given thing (algorithm , struct, process, etc) which all other specs refer back to rather than trying to keep multiple copies updated.
-
The data_structure spec would only contain the actual planned structure, and either notate what is currently implemented, or contain a link to the go-filecoin file for reference as to what is the current state of this implementation.
-
The mining spec would link to the data_structures#block section as a reference. This way the Block struct is documented in a single place and need only be edited there.
-
If there is what amounts to a roadmap for the spec, then perhaps there could additional documents in a folder named by version (?) which is sort of what you have with the drafts folder.
from specs.
Another place where specifically what is expected in the Block
struct is inconsistent is in expected_consensus. The fields listed in Block Generation don't match up with what is in data_structures. These need to match; they cannot refer to fields with different names. Implementers should not be in any doubt what field is what even if it seems obvious. For example there is Signature
in the former, it's missing in the latter, and it's called BlockSig
in mining.
from specs.
Also, if "The mining document describes the filecoin implementation of expected consensus," what is the "expected consensus" document describing? So many questions!
from specs.
@shannonwells to quote myself, and elaborate
As it says in the expected consensus document, what is described there is how to generally implement expected consensus. Expected consensus is an algorithm, much like 'merge sort'. Merge sort doesnt specify exactly what sort of things you will be sorting, or even how to compare elements in the list.
Think of it this way, expected consensus is a generic algorithm. Things described in a document specifically about expected consensus should describe how to implement the algorithm, think of this like a paper describing raft, or paxos, or some other consensus algorithm. Things described in such a document express the things needed by that protocol, as general abstract concepts. Such a document should go into more detail around the intuition and theory of the algorithm, and be very light on actual implementation details.
The fact that the structures described in the tendermint paper don't line up one to one with the fields in actual structs in their code is fine.
from specs.
Related Issues (20)
- Architecture diagram SVG fails to render?
- Spec update for FIP 0024 HOT 1
- Spec update for FIP-0020 HOT 3
- Spec update to 0023
- Fix fault fees
- Update faulty period according to FIP-0026 HOT 4
- Add spec section for batch balancer
- Add spec for snap deal HOT 3
- The penalty mechanism of time and space proof
- i too many init miner... can i remove Owned Miner?? HOT 1
- Removal of Fuhon network implementation HOT 3
- Fix the deployment. HOT 6
- Filecoin Verify method is mentioned as Todo, is the implementation available for it. HOT 2
- Internal links/anchors on spec.filecoin.io don't open
- Where to find Filecoin’s network’s handshake specification?
- sector sealing specifics link to lotus source on github leads nowhere
- Multiple links broken HOT 1
- link broken HOT 1
- spec.filecoin.io DOWN HOT 1
- Let's update the spec! HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from specs.