Cell & Bag of Cells (BoC)
Cell
A cell represents a data structure on TON Blockchain. Cells are able to store up to 1023 bits and possess up to 4 references to other cells.
Bag of Cells
Bag of Cells (BoC) is a format for serializing cells into byte arrays, which is further described in the TL-B schema.
On TON, everything consists of cells, including contract code, stored data, blocks, achieving streamline and robust flexibility in the process.
Cell serialization
Let's analyze our first example of a Bag of Cells :
1[8_] -> {
24[0AAAAA],
7[FE] -> {
24[0AAAAA]
}
}
In this example we have a 1-bit size root cell that has 2 links: the first to a 24-bit cell and the second to a 7-bit cell which possesses 1 link to a 24-bit cell.
For this framework to work as intended, it’s necessary to turn the cells into a single sequence of bytes. To accomplish this, first, we leverage only unique cell types, below 3 out of 4 are presented as follows:
1[8_]
24[0AAAAA]
7[FE]
In order to leave only unique cells they need to be compared. To do this, we need to compare the hashes of the cells.
Now let's arrange them in such an order that the parent cells do not point backwards. The cell pointed to by the rest must be in the list after the ones that point to it. We get:
1[8_] -> index 0 (root cell)
7[FE] -> index 1
24[0AAAAA] -> index 2
Now, let's calculate descriptions for each of the 3 cells touched on above. These descriptions are made up of 2 bytes that store flags composed of information about the length of the data and the number of data linkages.
The first byte - refs descriptor - is calculated as r+8s+32l, where 0 ≤ r ≤ 4 is amount of the Cell references (links), 0 ≤ s ≤ 1 is 1 for exotic cells and 0 for ordinary ones, and 0 ≤ l ≤ 3 is the level of the Cell.
The second one - bits descriptor - is equals floor(b / 8) + ceil (b / 8) where 0 <= b <= 1023 is number of bits in the Cell. This descriptor represents the length of the full 4-bit groups of the Cell data (but at least 1 if it isn’t empty).
The result is:
1[8_] -> 0201 -> 2 refs, length 1
7[FE] -> 0101 -> 1 ref, length 1
24[0AAAAA] -> 0006 -> 0 refs, length 6
For data with incomplete 4-bit groups, 1 bit is added to the end of the sequence. This means it denotes the end bit of the group and is used to determine the true size of incomplete groups. Let's add the bits below:
1[8_] -> C0 -> 0b10000000->0b11000000
7[FE] -> FF -> 0b11111110->0b11111111
24[0AAAAA] -> 0AAAAA -> do not change (full groups)
Now let's add the refs indexes:
0 1[8_] -> 0201 -> refers to 2 cells with such indexes
1 7[FE] -> 02 -> refers to cells with index 2
2 24[0AAAAA] -> no refs
And put it all together:
0201 C0 0201
0101 FF 02
0006 0AAAAA
And concat it by joining the corresponding strings into a single array of bytes:
0201c002010101ff0200060aaaaa, size 14 bytes.
Show example
func (c *Cell) descriptors() []byte {
ceilBytes := c.bitsSz / 8
if c.bitsSz%8 ! = 0 {
ceilBytes++
}
// calc size
ln := ceilBytes + c.bitsSz/8
specBit := byte(0)
if c.special {
specBit = 8
}
return []byte{byte(len(c.refs)) + specBit + c.level*32, byte(ln)}
}
Packing a Bag of Cells
Let's pack the cell from the section directly above. We have already serialized it into a flat 14 byte array.
Therefore, we build the header according to its schema.
b5ee9c72 -> id tl-b of the BoC structure
01 -> flags and size:(## 3), in our case the flags are all 0,
and the number of bytes needed to store the number of cells is 1.
we get - 0b0_0_0_00_001
01 -> number of bytes to store the size of the serialized cells
03 -> number of cells, 1 byte (defined by 3 bits size:(## 3), equal to 3.
01 -> number of root cells - 1
00 -> absent, always 0 (in current implementations)
0e -> size of serialized cells, 1 byte (size defined above), equal to 14
00 -> root cell index, size 1 (determined by 3 size:(## 3) bits from header),
always 0
0201c002010101ff0200060aaaaa -> serialized cells
Next, we concat everything above into an array of bytes into our final BoC:
b5ee9c7201010301000e000201c002010101ff0200060aaaaa
Bag of Cells Implementation Examples: Serialization, Deserialization
Special (Exotic) Cells
Generally, cells operating on TON are divided into two main types: ordinary cells and special cells. Most of the cells that the users work with are ordinary cells responsible for carrying information.
Nevertheless, to realize internal functionality of the network, special cells are sometimes needed and are used for a diverse range of purposes, depending on their subtype.
Cell Level
Every Cell has an attribute called Level, which is represented by an integer from 0 to 3.
Ordinary cells level
The Level of an ordinary Cell is always equal to the maximum of the levels of all its references:
Lvl(c) = max(Lvl(r_0), ..., Lvl(r_i), ..., Lvl(r_e))
Where i is a c reference index, e is a c reference amount.
Ordinary Cell without refs level is zero
Exotic cells level
Exotic cells have different rules for setting their level, which are described in this article.
Cell hash
In most cases users work with ordinary cells with level 0 which have only one hash, called representation hash (or hash infinity).
Cell c with level Lvl(c) = l, where 1 ≤ l ≤ 3 has representation hash and l "higher" hashes.
Standard Cell representation hash calculation
First, we need to calculate Cell representation (which is similar to Cell serialization described above)
- Compute descriptors bytes
- Add serialized Cell data
- For every Cell's refs add its depth
- For every Cell's refs add its representation hash
- Compute SHA256 hash of the result
Let's analyze the following examples:
Cell without references
32[0000000F]
- Descriptors computation
The reference descriptor is equals to r+8s+32l = 0 + 0 + 0 = 0 = 00
The bits descriptor is equals to floor(b / 8) + ceil (b / 8) = 8 = 08
Concatenating these bytes we get 0008
- Cell data serialization
In this case we have complete 4-bit groups, so we don't have to add any bits to the Cell data. The result is 0000000f
- Refs depth
We skip this part, because our Cell doesn't have any refs
- Refs hashes
We skip this part, because our Cell doesn't have any refs
- SHA256 computation
Concatenating bytes from the previous steps we get 00080000000f and the SHA256 from this bytestring is 57b520dbcb9d135863fc33963cde9f6db2ded1430d88056810a2c9434a3860f9 - that's the Cell representation hash.
Cell with references
24[00000B] -> {
32[0000000F],
32[0000000F]
}
- Descriptors computation
The reference descriptor is equals to r+8s+32l = 2 + 0 + 0 = 0 = 02
The bits descriptor is equals to floor(b / 8) + ceil (b / 8) = 6 = 06
Concatenating these bytes we get 0206
- Cell data serialization
In this case we have complete 4-bit groups, so we don't have to add any bits to the Cell data. The result is 00000b
- Refs depth
The depth is represented by 2 bytes. Our Cell has 2 refs and depth of each is zero so the result of this step is 00000000.
- Refs hashes
For every reference we add its hash (we computed above), so the result is 57b520dbcb9d135863fc33963cde9f6db2ded1430d88056810a2c9434a3860f957b520dbcb9d135863fc33963cde9f6db2ded1430d88056810a2c9434a3860f9
- SHA256 computation
Concatenating bytes from the previous steps we get 020600000b0000000057b520dbcb9d135863fc33963cde9f6db2ded1430d88056810a2c9434a3860f957b520dbcb9d135863fc33963cde9f6db2ded1430d88056810a2c9434a3860f9
and the SHA256 from this bytestring is f345277cc6cfa747f001367e1e873dcfa8a936b8492431248b7a3eeafa8030e7 - that's the Cell representation hash.
Higher hashes calculation
Higher hashes of an Ordinary Cell c are computed similarly to its representation hash,
but using the higher hashes of its references instead of their representation hashes.
Exotic cells have their own rules for computing their higher hashes, which are described in this article.