Skip to main content
In TVM, the Cell type contains only metadata of the cell: level, hashes, and depths. To read actual data, TVM need to load cell from celldb, key-value storage of the node, which stores cells by their representation hashes. CTOS instruction loads a cell by its metadata from Cell type, and provides a Slice, a read-only wrapper for the cell’s content. To simplify coding cell deserializers in smart contracts, instead of behaving like a simple bit/ref array, Slice is a “read cursor”: it allows loading a piece of data from the beginning of the slice, returning that data and the slice that contains remaining data. On the other hand, there is a Builder type, which provides a convenient way to serialize data to a cell. Only the Cell type can be used outside of TVM: in output actions and in persistent storage.

​
Builder

Builder provides a way to construct a cell from a sequence of values of the following TVM types: integers, cells (as references), slices, and builders. Tuples, continuations, and null are not serializable. For example, serialize the following numbers to a cell: 
1 (uint4)
2 (uint4)
-1 (int8)
First, create an empty builder using NEWC:
Fift
NEWC  // returns empty builder x{}
Then, put a number on the stack:
Fift
1 INT  // stack: x{} 1
And call STU (“STore Unsigned integer”) to store integer into builder (swapping builder and value to meet STU input order):
Fift
SWAP  // stack: 1 x{}
4 STU  // stack: x{0001}
Then, store the other two numbers:
Fift
2 INT  // x{0001} 2
SWAP  // 2 x{0001}
4 STU  // x{00010010}

-1 INT  // x{00010010} -1
SWAP  // -1 x{00010010}
8 STI  // x{0001001011111111}
And, finally, ENDC instruction finalizes the builder to a cell.

​
Slice

Slice allows reading data back from a cell, field by field. For example, deserialize bitstring x{0001001011111111} created above. CTOS (“Cell TO Slice”) loads a Cell to a Slice.
Fift
// assume a cell with bitstring x{0001001011111111} is on the stack
CTOS  // x{0001001011111111}
Then, call LDU (“LoaD Unsigned integer”) to read first value (uint4).
Fift
4 LDU  // 1 x{001011111111}
LDU takes the first 4 bits from a slice and creates a new slice without these 4 bits: x{0001|001011111111} slices into a number 0001 and a slice x{001011111111}. Similarly, read another two numbers:
Fift
4 LDU // 1 2 x{11111111}
8 LDI // 1 2 -1 x{}
A common way to ensure there is no data left inside the slice is to call ENDS.