filecoin-project / filecoin-project/specs

Increase detail about serialization/encoding in the spec

Open
#877 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
SCSS
Stars
363
Forks
164
PR merge metrics
No merged PRs in 30d

Description

It would be very helpful for implementers if we could increase the level of specification detail about serialization and encoding in the spec. Current spec is: https://filecoin-project.github.io/specs/#systems__filecoin_files__serialization

Specific comments on what is missing and would be valuable to add:

- "The elements that are missing from that are ordering and exact types. For example, there needs to be consistent ordering to the fields in a block header so it can be deserialized correctly. I think the exact types are intended to be interpreted from the spec, but presently there are some inconsistencies where the spec might be saying uint64 but the implementation uses big ints, for example."
- "There was an overview put in about a month ago but would have been nice to have the ipld data format for the types passed over the wire. We have worked out the underlying types for all we need so far but another area I see may be useful is how actor parameters are serialized. There is no specification on order or types."

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the serialization section of the linked specification and review the comments in this issue about field ordering, exact types, IPLD data formats, and actor-parameter serialization. Compare those requirements with the existing specification to identify the affected sections; done means implementers can determine ordering and types unambiguously.

Written by the indexing model from the issue text.

Assessment

Domain
distributed-systems, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.