Fill boc serialization page

[Karkarmath]

Closes #229

[github-actions]

Thanks for the updates to the BoC serialization docs and examples. I found several clarity and consistency issues in tvm/serialization/boc.mdx that need fixes before merge.

Findings (19)

High (3)

[HIGH] Conflicting reuse of symbol s (index bits vs descriptor flag)

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L41-L54

Description:
s is defined as the index-bit width and then reused as the 1‑bit exotic/ordinary flag in the descriptor, making d1 ambiguous and risking incorrect implementations. Use distinct identifiers for index width and the exotic flag.

Suggestion:
Option 1 — Rename the descriptor flag to x (formula and bullet):

-      setting `d1 = r + 8s + 16h + 32l` and $d2 = \lfloor \frac{b}{8} \rfloor + \lceil \frac{b}{8}\rceil$ (for absent cells, 
+      setting `d1 = r + 8x + 16h + 32l` and $d2 = \lfloor \frac{b}{8} \rfloor + \lceil \frac{b}{8}\rceil$ (for absent cells, 
       only `d1` is present, always equals to `7 + 16 + 32l`), where:
 ...
-      - `s = 1` for exotic cells and `s = 0` for ordinary cells;
+      - `x = 1` for exotic cells and `x = 0` for ordinary cells;

Option 2 — Rename the index bit‑width to i_bits and keep s for the flag:

- -  Choose an integer number `s`, such that `n ≤ 2^s`. Represent each cell `ci` by an integral number of bytes
- as in standard representation cell algorithm, but using unsigned big-endian 
- s-bit integer `j` instead of hash `Hash(cj)` to represent internal references to cell `cj`. More precisely, each
- individual cell `c` serialized as follows, provided `s` is a multiple of eight.
+ -  Choose an integer number `i_bits`, such that `n ≤ 2^i_bits`. Represent each cell `ci` by an integral number of
+ bytes as in standard representation cell algorithm, but using an unsigned big‑endian
+ `i_bits`-bit integer `j` instead of `Hash(cj)` to represent internal references to cell `cj`. More precisely, each
+ individual cell `c` is serialized as follows, provided `i_bits` is a multiple of eight.

[HIGH] Incorrect root and absent-cell index ranges

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L84-L91

Description:
The root range “c1, …, c_{k−1}” yields only k−1 roots; the absent range “c_{n−l}, …, c_{n−1}” yields l−1 items. Fix the off‑by‑one errors to match one‑based indexing.

Suggestion:

- cells themselves are $c_1, \ldots, c_{k−1}$. All other cells present in the bag of
+ cells themselves are $c_1, \ldots, c_{k}$. All other cells present in the bag of
@@
- absent cells themselves are represented by $c_{n−l}, \ldots, c_{n−1}$, and only
+ absent cells themselves are represented by $c_{n−l+1}, \ldots, c_{n}$, and only

[HIGH] Non copy-pasteable import path in TypeScript example

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L131-L133

Description:
The example imports from an internal deep path with a .ts extension, which is not part of the published API and breaks copy‑pasteability.

Suggestion:

-import { beginCell } from "@ton/core";
-import { serializeBoc } from "@ton/core/src/boc/cell/serialization.ts"
+import { beginCell, serializeBoc } from "@ton/core";

Medium (12)

Click to expand

[MEDIUM] Incorrect abbreviation and casing for “BoC/BoCs” and “TON Blockchain”

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L8-L12

Description:
Multiple instances use “Boc/Bocs” instead of “BoC/BoCs”, and “Ton Blockchain” instead of “TON Blockchain”, reducing consistency and searchability.

Suggestion:

- Thus a _bag of cells (Boc)_ is obtained.
+ Thus a bag of cells (BoC) is obtained.

- In general, a Boc can be obtained from several trees of cells, thus forming a forest.
+ In general, a BoC can be obtained from several trees of cells, thus forming a forest.

- However, this Boc needs to be serialized into a file, suitable for disk storage or network transfer.
+ However, this BoC needs to be serialized into a file, suitable for disk storage or network transfer.

Also update (same replacements):

• tvm/serialization/boc.mdx:9, 12, 20, 22–27, 31, 39, 122, 127, 129: “Boc/Bocs” → “BoC/BoCs”
• tvm/serialization/boc.mdx:99: “Ton Blockchain” → “TON Blockchain”

[MEDIUM] Typos in heading and body: “adsent” and plural form

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L20-L27

Description:
The heading/body misspell “adsent” and use “Bocs” instead of “BoCs,” which reduces clarity and polish.

Suggestion:

- ### Internal references, adsent cells, and complete Bocs
+ ### Internal references, absent cells, and complete BoCs

- Although most real-world cases only deal with complete Bocs, in general, the serialization of adsent cells in Boc 
+ Although most real-world cases only deal with complete BoCs, in general, the serialization of absent cells in a BoC

[MEDIUM] Ambiguous “Let’s”/“we”; use neutral/second-person voice

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L22-L24

Description:
“Let’s fix an arbitrary cell …” uses inclusive “we,” which the style guide discourages. Neutral phrasing avoids ambiguity.

Suggestion:

- Let's fix an arbitrary cell `c` in a given Boc. A reference of `c` is called _internal_ if 
+ Consider an arbitrary cell `c` in a given BoC. A reference of `c` is called internal if

[MEDIUM] Missing verb in sentence (“is serialized”)

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L44-L44

Description:
“each individual cell c serialized as follows” is missing “is,” which hinders readability.

Suggestion:

- individual cell `c` serialized as follows, provided `s` is a multiple of eight.
+ individual cell `c` is serialized as follows, provided `s` is a multiple of eight.

[MEDIUM] Code span errors and stray backticks

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L48-L53

Description:
There is a stray backtick and extra space inside code spans (“c is” and “0 ≤ l ≤ 3 is”), which render incorrectly.

Suggestion:

- - `0 ≤ r ≤ 4` is the number of cell references present in cell `c`, if `c `is
+ - `0 ≤ r ≤ 4` is the number of cell references present in cell `c`, if `c` is

- - `0 ≤ l ≤ 3 `is the level of cell `c`;
+ - `0 ≤ l ≤ 3` is the level of cell `c`;

[MEDIUM] Punctuation inside code span and missing preposition

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L62-L66

Description:
The trailing comma is inside the code span for entries L1, ..., Ln,. Also, “any cell ci the serialized bag of cells” is missing “in.” Align singular “index” with the earlier construction.

Suggestion:

- - Optionally, an index can be constructed that consists of `n + 1` t-bit integer entries `L1, ..., Ln,` where `Li`
+ - Optionally, an index can be constructed that consists of `n + 1` t-bit integer entries `L1, ..., Ln`, where `Li`

- that `Ln ≤ 2^t`. If the indexes are included, any cell `ci` the serialized bag of cells may be easily
+ that `Ln ≤ 2^t`. If the index is included, any cell `ci` in the serialized bag of cells may be easily

[MEDIUM] Unstable link to source; use a stable permalink

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L126-L127

Description:
The SDK link targets the moving main branch, which can drift. Pin to a commit permalink for stability.

Suggestion:
Replace “https://github.com/ton-org/ton-core/blob/main/src/boc/cell/serialization.ts#L1” with a commit permalink, e.g. “https://github.com/ton-org/ton-core/blob//src/boc/cell/serialization.ts#L1”.

[MEDIUM] Banned time-relative “Currently”

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L129-L129

Description:
Time-relative wording stales quickly. Prefer timeless phrasing.

Suggestion:

- Currently, only serialization of Bocs containing only one root and without absent cells is supported.
+ Only serialization of BoCs with one root and no absent cells is supported.

[MEDIUM] Code identifiers must use code font

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L115-L115

Description:
Field names appear in prose without code formatting while others are formatted. Apply code spans consistently.

Suggestion:

-Field cells is `n`, roots is `k`, absent is `l`, and `tot_cells_size` is `Ln` (the total
+Field `cells` is `n`, `roots` is `k`, `absent` is `l`, and `tot_cells_size` is `Ln` (the total

[MEDIUM] Grammar — “we must be h = 1”

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L54-L54

Description:
“we must be h = 1” is ungrammatical. State the requirement directly.

Suggestion:

-      - `h = 1` if the cell’s hashes are explicitly included into the serialization; otherwise, `h = 0` (when `r = 7`, we must be `h = 1`).
+      - `h = 1` if the cell’s hashes are explicitly included into the serialization; otherwise, `h = 0` (when `r = 7`, `h` must be `1`).

[MEDIUM] CRC term inconsistency (CRC32 vs CRC32C)

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L71-L71

Description:
The narrative mentions “CRC32” while the TL‑B scheme below uses has_crc32c/crc32c. Align terminology.

Suggestion:

-- An optional `CRC32` may be appended to the serialization for integrity
+- An optional `CRC32C` may be appended to the serialization for integrity

[MEDIUM] Assumes a single root in general outline

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L40-L41

Description:
The outline implies a single root, while the spec supports multiple roots. Generalize to avoid confusion.

Suggestion:

--  List the cells from B in a chosen order: `c1, ..., cn` with `c1` being the root cell.
+-  List the cells from B in a chosen order: `c1, ..., cn` (with `c1, ..., c_k` as root cells).

Low (4)

Click to expand

[LOW] “indexes” vs “indices” inconsistency

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L31-L31

Description:
Uses “indexes” where “indices” is preferred for consistency with the rest of the document.

Suggestion:

- In the process of Boc serialization, the assignment of indexes of its cells plays an important role.
+ In the process of BoC serialization, the assignment of indices of its cells plays an important role.

[LOW] Missing newline at end of file

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L144-L144

Description:
The file lacks a trailing newline, which some tools expect and which avoids spurious diffs.

Suggestion:
Add a single newline at the end of the file.

[LOW] Unnecessary comma in opening sentence

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L6-L6

Description:
There is an unnecessary comma after “cells,” which interrupts flow.

Suggestion:

-[DAG](https://[REDACTED]/wiki/Directed_acyclic_graph) of cells, by identifying identical cells in the
+[DAG](https://[REDACTED]/wiki/Directed_acyclic_graph) of cells by identifying identical cells in the

[LOW] Acronym casing and wording in SDK comment

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/babdad40614a3b7fabd997f158c08a61ec65619f/tvm/serialization/boc.mdx?plain=1#L133-L135

Description:
The comment should use “indices” and uppercase “CRC32,” and present tense reads better.

Suggestion:

- // opt: { idx: boolean, crc32: boolean }. Two flags indicating whether indexes and crc32 will be included in serialization
+ // opt: { idx: boolean, crc32: boolean }. Two flags indicating whether indices and CRC32 are included in serialization

[anton-trunov]

let's make the lengths of the code lines shorter, so everything would fit on the screen without the need to scroll horizontally

[pyAndr3w]

The serialization specification is correct.
However, the article reads too terse and compressed—similar to Nikolai Durov’s original PDFs—which is not ideal for documentation.

The cell serialization duplicates “/tvm/serialization/cells”; it might be better to keep it in one place and link from the other.
The topic “What are multiroot BoC for?” is not covered.
There are no examples of deserialization, and serialization with hex output.

I would recommend balancing the dry text with visuals and examples, as was done in the old documentation.

[verytactical]

+1 to @pyAndr3w

I'd recommend to show the full serialization procedure on some example, i.e. with numbers and values.

[Karkarmath]

The serialization specification is correct. However, the article reads too terse and compressed—similar to Nikolai Durov’s original PDFs—which is not ideal for documentation.

The cell serialization duplicates “/tvm/serialization/cells”; it might be better to keep it in one place and link from the other. The topic “What are multiroot BoC for?” is not covered. There are no examples of deserialization, and serialization with hex output.

I would recommend balancing the dry text with visuals and examples, as was done in the old documentation.

---

The mentioned topic I shortly mentioned in Intro: bag of cells could be a forest, so, as I know, It is just convenient to send a serialization of more than one tree of cells in some situations. If you know more clear reason to use them, please, let me know.

Yes, it is good idea and I just put a link to cell serialization.

I also port the example of manual serialization from old docs and add code examples related mentioned issues.

[Karkarmath]

and serialization with hex output

To be honest, I did not see such an option.

[anton-trunov]

@Karkarmath ping

[hacker-volodya]

Want to move this from TVM to Foundations
@verytactical

[hacker-volodya]

Want to have this described formally, in TL-B and/or C-like structures, both outer boc structure and cell serialization. It is hard to understand informal structure as in tblkch.pdf.

[github-actions]

To fix the formatting issues:

1. Install necessary dependencies: npm ci
2. Then, run this command:

npx remark -o --silent --silently-ignore tvm/serialization/boc.mdx 

[github-actions]

To fix the formatting issues:

1. Install necessary dependencies: npm ci
2. Then, run this command:

npx remark -o --silent --silently-ignore tvm/serialization/boc.mdx 

[github-actions]

To fix the formatting issues:

1. Install necessary dependencies: npm ci
2. Then, run this command:

npx remark -o --silent --silently-ignore tvm/serialization/boc.mdx 

[github-actions]

To fix the formatting issues:

1. Install necessary dependencies: npm ci
2. Then, run this command:

npx remark -o --silent --silently-ignore tvm/serialization/boc.mdx 

[github-actions]

Thanks for the updates to the BoC documentation. A few high‑priority style‑guide corrections are needed to ensure anchors, callouts, and references render and resolve correctly.

Findings (4)

High (4)

[HIGH] Use <Aside> for callouts instead of <Note>

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/cf71f3587b6ff38d9ee28b48706da56958e2fa6a/`tvm/serialization/boc.mdx?plain=1#L40-L45`

Description:
This page renders a callout using <Note> rather than the standardized <Aside> component with an allowed type. The style guide requires using <Aside> with one of the supported types ("note", "tip", "caution", "danger") for consistent rendering and accessibility. The evidence is the <Note> block on these lines; the <Aside> import is also absent at the top of the file.

Suggestion:
Import <Aside> and replace the <Note> block with <Aside type="note">.

--- a/tvm/serialization/boc.mdx
+++ b/tvm/serialization/boc.mdx
@@
 ---
 title: "Bag of cells"
 ---
 
+import { Aside } from '/snippets/aside.jsx';
@@
-<Note>
+<Aside type="note">
   This and the following paragraphs provide a textual description of the Boc serialization process and the specifications of the TL-B schemas
   associated with it. The specific implementation of the serialization and TL-B schemes is left to the choice of developers.
 
   For a specific example of TL-B schema and pseudocode of related cell serialization, see [TL-B scheme](/tvm/serialization/boc#A-TL-B-scheme).
-</Note>
+</Aside>

[HIGH] Self-link anchor uses wrong case

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/cf71f3587b6ff38d9ee28b48706da56958e2fa6a/`tvm/serialization/boc.mdx?plain=1#L44-L44`

Description:
The in-page link points to “/tvm/serialization/boc#A-TL-B-scheme”, but the generated anchor from the heading “## A TL‑B scheme” resolves to lowercase “a-tl-b-scheme”. This case mismatch is likely to break the anchor because the slug generator produces lowercase IDs. The style guide treats broken/missing anchors as always HIGH priority (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L31-L31) and requires that internal anchors resolve correctly (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L786-L788).

Suggestion:
Update the anchor to match the generated lowercase form.

-  For a specific example of TL-B schema and pseudocode of related cell serialization, see [TL-B scheme](/tvm/serialization/boc#A-TL-B-scheme).
+  For a specific example of TL-B schema and pseudocode of related cell serialization, see [TL-B scheme](/tvm/serialization/boc#a-tl-b-scheme).

[HIGH] Fenced code block missing language tag

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/cf71f3587b6ff38d9ee28b48706da56958e2fa6a/`tvm/serialization/boc.mdx?plain=1#L225-L241`

Description:
The fenced code block that shows the BoC header fields is opened with triple backticks without a language tag. This violates the documented rule that “Fenced code blocks MUST specify a language,” which supports correct highlighting and downstream tooling. See https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L438-L438 for the requirement.

Suggestion:
Add a language identifier to the opening fence (e.g., text) to make the block compliant.

--- a/tvm/serialization/boc.mdx
+++ b/tvm/serialization/boc.mdx
@@
-```
+```text
 0xb5ee9c72                                 -> Tl-B id of the BoC structure

[HIGH] Link to moving target “main” instead of a stable permalink

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/cf71f3587b6ff38d9ee28b48706da56958e2fa6a/`tvm/serialization/boc.mdx?plain=1#L247-L247`

Description:
The GitHub URL references .../blob/main/..., which can drift as main evolves. For precision‑critical references to code, the style guide requires pinning links to a tag or commit to preserve reproducibility over time. This avoids future breakage or pointing to different content.

Suggestion:
Pin the link to a specific tag or commit.

-According to the TL-B scheme above there is the [SDK](https://github.com/ton-org/ton-core/blob/main/src/boc/cell/serialization.ts#L1)
+According to the TL-B scheme above there is the [SDK](https://github.com/ton-org/ton-core/blob/<TAG_OR_COMMIT>/src/boc/cell/serialization.ts#L1)