SSZ Visualizer Online

Scotty Poi
4 min readJun 21, 2021

June 2021 now features a Visualization playground!

To demonstrate the SSZ serialization and merkleization algorithms, I built a React web app that could take SSZ data as input, and output a visual representation of its serialized and merkelized forms. Having never built anything like this before, I had only a vague idea of how it would work, but I had a general sense of the experience I hoped to create for users.

Ultimately I realized that the thing I was creating had three parts, each of which needed to be built and functional before any of it would work at all. First, a working implementation of SSZ that would let me capture all of the steps in the process as data for visualization. Second, a user interface that allowed people to tinker with the parameters of each different type. Finally, a way to visually represent not only the input and output, but as many of the details of the process as possible.

  1. A valid SSZ implementation

Using the TypeScript example from Chainsafe as a model, I built as *SIMPLE* an implementation as I could out of JSX. Maybe I could have just figured out how to incorporate their code into my own, but I thought the experience of building it myself would teach me more about both SSZ and React.

While I seem to have succeeded well enough to power the visualizer in its current form, I still need to design a set of tests to actually validate my implementation, and ensure that the information being displayed is actually correct. Never having built anything like this, I have also never built tests before, so that will be another new adventure…

  1. User Interface

The simplest solution would certainly have been to design a set of examples for each type to display, but I really wanted the experience to be interactive in a way that helped explain what is happening better than a static example could. Each SSZ type has its own constraints and it’s own journey towards its Merkle-Tree home. So for Booleans, I made controls that simply switch between a true and a false, and for Uint’s, controls that select a size, and randomize a value within that size. For composite types, length, limit, and type become controllable parameters. Once we get to containers, however, the possibilities become too large, so for now I just have a way to scroll through a set of examples that describe containers of various depths and complexity.

  1. Visualization and Interactivity

A lot of the magic of SSZ comes from the way serialized values are packed together into chunks, the way empty space is padded with zeros like bubble-wrap, and the way additional bits or leaves are put in to describe things like length, limit, or type. My hope was that as users adjusted different parameters, they could observe which parts of the results represented the value itself, and see how the rest of it fits together.

For example, the display of a basic type shows the bits representing the value in green, and the zeros from the “padding” in red. As users change the size of the object, the amount of green vs red in the output changes, demonstrating the way in which a single basic object of any size becomes a single 32 byte chunk for merkelizing.

The display of a list or vector shows the placement of the “length bit” by coloring it black. As users adjust the length parameter, the movement of this contrasting bit demonstrates that function

Finally, I wanted to also demonstrate the merkle-tree itself, and maintain a clear connection between the input value, and “where it ends up” in the tree or serial string. Also, I wanted the structure of a merkle-proof for any given value to somehow reveal itself on command. Currently the merkle tree is responsive to the changing parameters — meaning it grows and shrinks and changes colors as the dataset changes. The trees are built of “nodes” that respond to different mouse events by displaying information from the tree. For example clicking on a value leaf triggers the related merkle-proof hash nodes to animate.


Those three sides of the project currently function *enough* to put together a test-run demonstration of the concept. Beyond those, however, I see three new major tasks ahead.vb

  1. Testing

I need to write a set of tests that validate my SSZ implementation and, quite likely, rewrite much of the SSZ code to be more ‘testable’

  1. Design

The current design is purely utilitarian, and needs a design overhaul to appear professional and improve user experience.

  1. Custom Input and Schema Validation

An ideal version of this could also take a custom SSZ schema as input for both validation and visualization.