Skip to main content

Cells as Data Storage

Everything in TOS is stored in cells. A cell is a data structure containing:

  • up to 1023 bits of data (not bytes!)
  • up to 4 references to other cells

Bits and references are not intermixed (they are stored separately). Circular references are forbidden: for any cell, none of its descendant cells can have this original cell as reference.

Thus, all cells constitute a directed acyclic graph (DAG). Here is a good picture to illustrate:

Directed Acylic Graph

Cell types​

Currently, there are 5 types of cell: ordinary and 4 exotic. The exotic types are the following:

  • Pruned branch cell
  • Library reference cell
  • Merkle proof cell
  • Merkle update cell
tip

For more on exotic cells see: TVM Whitepaper, Section 3.

Cell flavors​

A cell is an opaque object optimized for compact storage.

In particular, it deduplicates data: if there are several eqivalent sub-cells referenced in different branches, their content is only stored once. However, opaqueness means that a cell cannot be modified or read directly. Thus, there are 2 additional flavors of the cells:

  • Builder for partially constructed cells, for which fast operations for appending bitstrings, integers, other cells and references to other cells can be defined.
  • Slice for 'dissected' cells representing either the remainder of a partially parsed cell or a value (subcell) residing inside such a cell and extracted from it via a parsing instruction.

Another special cell flavor is used in TVM:

Serialization of data to cells​

Any object in TOS (message, message queue, block, whole blockchain state, contract code and data) serializes to a cell.

The process of serialization is described by a TL-B scheme: a formal description of how this object can be serialized into Builder or how to parse an object of a given type from the Slice. TL-B for cells is the same as TL or ProtoBuf for byte-streams.

If you want to know more details about cell (de)serialization, you could read Cell & Bag of Cells article.

What's next?​

  • Navigate to the TL-B section for more information.