# eth2.0-ssz notes/suggestions

## General notes

- Missing a description of hashTreeRoot
- Proto: Some definition is probably in place, but trying to draw more attention to merkleization in general in SSZ. hash-tree-root is just the function name.
- Missing standardization stages for pages
- Proto: these are TBD, will do this after getting contents down

## [Base](https://github.com/protolambda/eth2.0-ssz/tree/master/specs/base)

- [ ] I was looking for an explainer of how the structure of objects map to a merkle tree, maybe a list of core operations. It seems the 'kinds' described are only/mostly applicable in merkleization, not serialization. An analysis of the concerns/properties of the two operations would be helpful.
- [x] Maybe a description of 'representation', used elsewhere will be useful.

### [Base Model](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/base/model.md)

- [x] Introduction - "SSZ concepts" => "SSZ types" or "SSZ data structures", helpful to stay concrete
- [x] Pull "fixed-size and dynamic size" out of composition of types
- [x] description of fixed-size is confusing (static compositions not defined beforehand)
- [x] description of variable-size should probably be included (even if only to say "not fixed")
- [x] Maybe use the name 'sequence' instead of 'series'
- [x] The series construct is a bit confusing, as vectors are not really accounted for here, I realize they're being abstracted away, but mentioning this a little more explicitly may be helpful
- Proto: reduced it to a single description of serializing a sequence of elements. Focus on representation. Separating merkleization. "Base" to be renamed.
- [x] Move merkle mix-ins to merkleization
- looks like it was included here so the sections could be read sequentially

## [Types](https://github.com/protolambda/eth2.0-ssz/tree/master/specs/types)

- [x] General explanation of the role of default values & aliases missing
- [ ] Examples of each type may be helpful
- [x] How do the base kinds fit in to the types?
- Proto: removed base kinds, types are more descriptive.

### [Basic Types](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/types/basic.md)

- [x] Use consistent way of saying injunctive mapping/ one-to-one mapping
- One-to-one correspondence seems most correct here; the most important thing is that it is non-injective from value to byte, and the unused byte values are invalid.
- [x] Typo: Unsinged => unsigned
- [x] Merkleization is confusing in explaining the types, might be better explained elsewhere, after general overview of all types explained
- Tried to clarify it more, but do think merkleization of a specific type should just live with the type info.

### [Complex Types](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/types/complex.md)

- [x] Intro, final sentence is confusing
- [x] Vector last sentence, offset prologue should be noted separately.
- [x] List - typo garantees -> guarantees
- [x] List - allocation - first sentence is not clear.
- [x] List - zero-hashes TODO link
- [x] Like the merkleization in basic types, I think the functionality might be better explained elsewhere, after a general overview of all the

### [Bitfields](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/types/bitfields.md)

- [x] Maybe make explicit comparison between Bitvector and Vector
- [x] First sentence of bitlist serialization is a little confusing.

### [Union](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/types/union.md)

- [x] define null representation

## [Merkleization](https://github.com/protolambda/eth2.0-ssz/tree/master/specs/merkleization)

- [ ] Add tree-offset proof backing
- [ ] Add turboproof-style proof backing

### [Hashing](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/merkleization/hashing.md)

- [x] Link to sha256 spec/wiki may be warranted

### [Merkle Proofs](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/merkleization/merkle_proofs.md)

- [x] Typo first sentence: "proof" -> "prove"
- [ ] For beginners section may link to additional help material
- [x] For beginners section: explicitly define "witness"
- Proto: the accumulator part talking about witnesses is a different section than the beginners section. And explains it as the branch data necessary to proof a value. "witness" itself is closer accumulator terminology, for which I sadly can't find a good standard reference for.
- [x] Accumulator, first sentence, explicitly mention changing position of contents changes hashes
- [x] Binary merkle tree bullet list: "minimal base to merkleize" - not sure what that means
- Proto: literally (base 2, smallest radix tree) and figuratively (can't merkleize with some smaller node combination). And any other positional collection can be translated to a binary tree. Will clarify.
- [ ] Examples may benefit from simple graphviz images
- [x] Multiproof example: explicitly call out shared witnesses
- [x] Proof backings: define what a backing is first
- [x] May be worth creating a section for multiproofs to define more explicitly

### [Classic proof backing](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/merkleization/proof_backings/classic.md)

- [ ] introductory bullet list: link to "regular single-leaf merkle proofs" material
- [ ] Contents: "top-to-bottom branch" needs more explanation
- [ ] Contents: Consider renaming "Description" to something more descriptive, confusing the first read through. Maybe "leaf indices"
- [ ] Description, typo, add dash: "proof producing/consuming" -> "proof-producing/consuming"
- [ ] Description: make it more clear when you're referring to the indices vs the leaves

## [Navigation](https://github.com/protolambda/eth2.0-ssz/tree/master/specs/navigation)

### [Generalized Indices](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/navigation/generalized_indices.md)

- [ ] Introduction: bitfield interpretation of path could use more explanation.
- [ ] Introduction (or in an additional section): explain use of generalized index as a way of identifying a chunk of data
- [ ] Representation: more explanation of 'root bit' needed here

### [Paths](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/navigation/paths.md)

- [ ] Explicitly mention that the path components are taken from the ssz type's field names, maybe include 'validation' of paths
- [ ] Mention potential non 1-to-1 mapping of paths to generalized indices, mention the types/situations involved
- [ ] Mention paths that stop at a non-leaf
- [ ] Interface: fix spacing/formatting of functions

### [Summaries/Expansions](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/navigation/summaries_expansions.md)

- [ ] Introduction: this explanation feels difficult because the properties of hash_tree_root haven't been explained elsewhere.
- [ ] Introduction: The last sentence needs additional explanation, since a single summary can potentially be expanded into several partial expansions. eg: a hash can be expanded to a BeaconBlockHeader and a BeaconBlock (and more)
- [ ] Introduction: There should be some explanation that goes summary -> expansion, or that explains that expansions can only be done on bytes32
- [ ] Transparency: In the bullet list, it feels strange to be referencing eth2-specific types for the explanation (it's useful tho)
- [ ] Transparancy: Last sentence, I don't see the tips to avoid arbitrary expansions
- [ ] As types: signing_root should be defined in more detail elsewhere
- [ ] As types: not sure if this is worth referencing, but expansions across fork boundaries should be taken into account. Eg: In a fork that adds fields to the BeaconState, a proof from a BeaconBlock after a fork, traversing in ways that navigate before the fork need to account for pre/post BeaconState type schemas/indices

## [Partials](https://github.com/protolambda/eth2.0-ssz/tree/master/specs/partials)

### [Partials](https://github.com/protolambda/eth2.0-ssz/blob/master/specs/partials/partials.md)

- [ ] Introduction: Explicitly mention using the proof as a stand-in for the full datastructure in the context of computation/the interface

### Misc

- [ ] Missing explanation of selectors, dynamic vs static selectors