Skip to main content

ton_net_cell/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: 2026 Nirapod Labs
3
4// A library that decodes bytes from a peer it does not trust must fail by returning, not
5// by unwinding: a panic in a decoder is a denial of service in whatever process embedded
6// it. The lints sit on the library because a test is the opposite case, where an unwrap
7// is the assertion. Arithmetic is deliberately not in the set: every count these formats
8// carry is bounded before it is used, and each subtraction sits within a few lines of the
9// guard that makes it safe, so denying it would bury the real bounds under checked_sub.
10#![deny(
11    clippy::unwrap_used,
12    clippy::expect_used,
13    clippy::panic,
14    clippy::unreachable,
15    clippy::todo,
16    clippy::indexing_slicing
17)]
18
19//! The TON cell model and bag-of-cells codec for ton-net.
20//!
21//! A [`Cell`] is TON's universal container: up to 1023 bits of data and up to four
22//! references to other cells, forming a directed acyclic graph. Every structure on TON,
23//! an account, a block, a contract's code, is a tree of cells. A cell is either
24//! [ordinary](CellType::Ordinary) or one of four exotic kinds the cell model gives a
25//! meaning, which is what makes Merkle proofs possible.
26//!
27//! [`parse_boc`] reads the serialized form, a bag of cells, into the root cells it
28//! holds, and [`serialize_boc`] writes one back. [`Cell::parse`] opens a [`Slice`], a
29//! cursor that reads typed values out of a cell's bits and references, and [`Builder`]
30//! is the way back: outside this crate a cell comes from parsing or from a builder and
31//! from nowhere else.
32//!
33//! A bag and a hash travel as text more often than as bytes, so [`base64_encode`] and
34//! [`hex_encode`] write one down and [`base64_decode`] and [`hex_decode`] read it back.
35//! What each reader takes beyond what its own encoder writes is stated on the reader:
36//! base64 takes that one spelling and nothing else, hex takes either case.
37//!
38//! [`Dict`] is TON's dictionary, a radix tree over fixed-width keys that carries almost
39//! everything a block holds. It sits here rather than above the block types because it
40//! belongs to the cell model: the virtual machine has opcodes for it, and a wallet needs
41//! one without needing to know what a block is. [`AugDict`] is the same tree with a
42//! summary of every subtree kept in the node above it, which is the form a shard's
43//! accounts and a block's transactions take.
44//!
45//! # Identity and proofs
46//!
47//! A cell's identity is its representation hash, returned by [`Cell::hash`]. The hash is
48//! computed when the cell is built, following the level rules that give exotic cells
49//! their meaning: at level zero a pruned branch answers with the hash of the subtree it
50//! replaced, so a pruned copy of a tree hashes to the same value as the full tree. That
51//! substitution is what makes a Merkle proof checkable, and [`Cell::hash_at`] reaches
52//! the other levels. [`virtualize`] reads the tree a Merkle proof stands for,
53//! [`create_proof`] builds one, and a [`UsageTree`] records the cells a read touches so
54//! [`UsageTree::prove`] builds a proof of just those.
55//!
56//! # Untrusted input
57//!
58//! A bag of cells arrives from a liteserver, which this client does not trust, and a
59//! Merkle proof is attacker-shaped by design. Parsing therefore never panics and never
60//! allocates on a declared size it has not checked: it returns [`CellError`] instead,
61//! and refuses a bag past [`MAX_CELLS`] or [`MAX_DEPTH`], a reference that does not
62//! point strictly forward, or a cell whose descriptors and data disagree.
63//!
64//! This is an internal crate of the ton-net client.
65//!
66//! # Examples
67//!
68//! ```
69//! use ton_net_cell::parse_boc;
70//!
71//! // A bag of cells holding one cell of eight bits.
72//! let bytes = [0xb5, 0xee, 0x9c, 0x72, 0x01, 0x01, 0x01, 0x01, 0x00, 0x03, 0x00,
73//!              0x00, 0x02, 0xab];
74//! let roots = parse_boc(&bytes)?;
75//! let mut slice = roots[0].parse();
76//! assert_eq!(slice.load_uint(8)?, 0xab);
77//! # Ok::<(), ton_net_cell::CellError>(())
78//! ```
79#![forbid(unsafe_code)]
80#![warn(missing_docs)]
81#![deny(rustdoc::broken_intra_doc_links)]
82
83mod boc;
84mod builder;
85mod cell;
86mod codec;
87mod dict;
88mod error;
89mod merkle;
90mod slice;
91mod usage;
92
93// Building a cell goes through a crate-private constructor, deliberately: outside this
94// crate a cell can only come from parsing. So the properties over generated trees have
95// to sit inside the crate rather than in `tests/`.
96#[cfg(test)]
97mod proptests;
98
99#[cfg(feature = "compress")]
100pub use boc::compress;
101pub use boc::{
102    file_hash, parse_boc, parse_boc_with, serialize_boc, serialize_boc_chunks,
103    serialize_boc_chunks_with, serialize_boc_with, BocChunks, BocOptions, BocView, LazyBoc,
104    ParseOptions, MAX_CELLS, MAX_DEPTH,
105};
106pub use builder::Builder;
107#[cfg(feature = "json")]
108pub use cell::json;
109pub use cell::{Cell, CellType, Identity, MAX_BITS, MAX_REFS};
110pub use codec::{base64_decode, base64_encode, hex_decode, hex_encode};
111pub use dict::{
112    AugDict, AugDictIter, AugEntry, AugItem, AugNode, Augmentation, Dict, DictEntry, DictIter,
113    ForkExtra, Lookup, PfxDict, PfxDictIter, PfxMatch, Traverse,
114};
115pub use error::CellError;
116pub use merkle::{
117    apply_update, combine_updates, create_proof, create_update, is_virtualized, may_apply,
118    rebuild_with_refs, validate_update, virtualize,
119};
120pub use slice::{MsgAddress, Slice};
121pub use usage::UsageTree;
122
123// The README ships to crates.io and cannot be replaced once a version is published,
124// so its examples are compiled here rather than trusted. Doc-only: this does not
125// appear in the rendered documentation.
126#[cfg(doctest)]
127#[doc = include_str!("../README.md")]
128struct Readme;