Docs: SSZ usage docs for TypeScript devs

[philknows]

The goal of these docs are to enable more TypeScript devs to easily learn and experiment with the SSZ library. More tutorials, more detailed docs about usage for the greater community is desired and open for contributions.

Currently, there are some docs located here https://github.com/ChainSafe/lodestar/tree/unstable/packages/types describing the organization of the SSZ library. It should describe basic primary operations such as serialize, deserialize and hashTreeRoot.

Include example usage such as:

import {ssz} from '@lodestar/types'

// create an attestation (default value is all 0s)
const attestation = ssz.phase0.Attestation.defaultValue()

// the object can be accessed / modified normally (and typescript should help ensure you're setting the values properly)
attestation.data.source.epoch = 100

// get the merkle root of the attestation
const root = ssz.phase0.Attestation.hashTreeRoot(attestation)

// serialize the attestation
const serialized = ssz.phase0.Attestation.serialize(attestation)

// deserialize the attestation
const attestation2 = ssz.phase0.Attestation.deserialize(serialized)

// the deserialized value should equal the original value
ssz.phase0.Attestation.equals(attestation, attestation2) === true

// you can also convert to/from a json-serializable format
const json = ssz.phase0.Attestation.toJson(attestation)
const attestation3 = ssz.phase0.Attestation.fromJson(json)
ssz.phase0.Attestation.equals(attestation, attestation3) === true

Creating and consuming proofs can use additional and clearer examples of usage.

Some of the readme is already located here: https://github.com/ChainSafe/ssz/tree/master/packages/ssz

Additional usage to add:

import {ssz} from '@lodestar/types'

// create a default attestation optimized for proofs
const attestation = ssz.phase0.Attestation.defaultView()

// this object combines a merkle tree and the ssz object information to provide the interface of the object
// with a few caveats

// retrieve the type and merkle tree from the view (usually this is not necessary)
attestation.type === ssz.phase0.Attestation
attestation.tree // <- underlying binary merkle tree

// subproperties that are not primitives or byte vectors are subviews
attestation.data // <- this is a view

// subproperties that are primitives and byte vectors are represented as javascript native types and can be modified normally
attestation.data.source.epoch = 100
// subproperties that aren't primitives and byte vectors must be modified by setting as a view
attestation.data = ssz.phase0.AttestationData.defaultView()
// subproperties that are byte vectors must be set all at once, not element-by-element
// attestation.data.source.root[0] = 100 // <- NO
attestation.data.source.root = new Uint8Array(32) // <- yes

// proofs can be created by selecting specific subproperties to include in the proof
// eg: create a proof that proves the source and target epoch in an attestation
const proof = attestation.createProof([
  ['data', 'source', 'epoch'],
  ['data', 'target', 'epoch'],
])

// the proof can be consumed like so
const partialAttestation = ssz.phase0.Attestation.createFromProof(proof)

// any part of object that the proof included can be accessed normally
partialAttestation.source.epoch === 100

// accessing part of the object that the proof did not include will throw
try {
  partialAttestation.committeeIndex
} catch (e) {}

[shaansundar]

Hey @philknows! I'd like to start contributing to lodestar, is this a beginner friendly task to assign myself upon?

[philknows]

Hey @shaansundar! I think docs are generally a great way to start contributing! It'll allow you to document your process and knowledge while learning. Feel free to join our discord and ask any questions in our Lodestar>SSZ channel as you go through it. It's a great way to start learning how Lodestar works.

[philknows]

related to #5961