Expand description
The TON cell model and bag-of-cells codec for ton-net.
A Cell is TON’s universal container: up to 1023 bits of data and up to four
references to other cells, forming a directed acyclic graph. Every structure on TON,
an account, a block, a contract’s code, is a tree of cells. A cell is either
ordinary or one of four exotic kinds the cell model gives a
meaning, which is what makes Merkle proofs possible.
parse_boc reads the serialized form, a bag of cells, into the root cells it
holds, and serialize_boc writes one back. Cell::parse opens a Slice, a
cursor that reads typed values out of a cell’s bits and references, and Builder
is the way back: outside this crate a cell comes from parsing or from a builder and
from nowhere else.
A bag and a hash travel as text more often than as bytes, so base64_encode and
hex_encode write one down and base64_decode and hex_decode read it back.
What each reader takes beyond what its own encoder writes is stated on the reader:
base64 takes that one spelling and nothing else, hex takes either case.
Dict is TON’s dictionary, a radix tree over fixed-width keys that carries almost
everything a block holds. It sits here rather than above the block types because it
belongs to the cell model: the virtual machine has opcodes for it, and a wallet needs
one without needing to know what a block is. AugDict is the same tree with a
summary of every subtree kept in the node above it, which is the form a shard’s
accounts and a block’s transactions take.
§Identity and proofs
A cell’s identity is its representation hash, returned by Cell::hash. The hash is
computed when the cell is built, following the level rules that give exotic cells
their meaning: at level zero a pruned branch answers with the hash of the subtree it
replaced, so a pruned copy of a tree hashes to the same value as the full tree. That
substitution is what makes a Merkle proof checkable, and Cell::hash_at reaches
the other levels. virtualize reads the tree a Merkle proof stands for,
create_proof builds one, and a UsageTree records the cells a read touches so
UsageTree::prove builds a proof of just those.
§Untrusted input
A bag of cells arrives from a liteserver, which this client does not trust, and a
Merkle proof is attacker-shaped by design. Parsing therefore never panics and never
allocates on a declared size it has not checked: it returns CellError instead,
and refuses a bag past MAX_CELLS or MAX_DEPTH, a reference that does not
point strictly forward, or a cell whose descriptors and data disagree.
This is an internal crate of the ton-net client.
§Examples
use ton_net_cell::parse_boc;
// A bag of cells holding one cell of eight bits.
let bytes = [0xb5, 0xee, 0x9c, 0x72, 0x01, 0x01, 0x01, 0x01, 0x00, 0x03, 0x00,
0x00, 0x02, 0xab];
let roots = parse_boc(&bytes)?;
let mut slice = roots[0].parse();
assert_eq!(slice.load_uint(8)?, 0xab);Structs§
- AugDict
- An augmented dictionary: TON’s
HashmapAug n X Y. - AugDict
Iter - A walk over every entry of an augmented dictionary, in ascending key order.
- AugEntry
- Where a lookup landed in an augmented dictionary.
- BocChunks
- A bag of cells yielded a chunk at a time, built by
serialize_boc_chunks. - BocOptions
- What to write into a bag of cells beyond the cells themselves.
- BocView
- A bag of cells read only as far as its header.
- Builder
- Accumulates the bits and references of a cell under construction.
- Cell
- A TON cell: up to 1023 bits of data and up to four references.
- Dict
- A dictionary: TON’s
HashmapE n Xovern-bit keys. - Dict
Entry - Where a lookup landed: the cell holding the leaf, and where its contents start.
- Dict
Iter - A walk over every entry of a dictionary, in ascending key order.
- Identity
- A cell’s identity: one representation hash and depth per level its mask makes significant.
- LazyBoc
- A bag of cells read once, with its cells built on demand and kept.
- Parse
Options - What a caller allows one parse to take, where that is narrower than the crate’s own bounds.
- PfxDict
- A prefix dictionary: TON’s
PfxHashmapE n X. - PfxDict
Iter - A walk over every entry of a prefix dictionary, in ascending key order.
- PfxMatch
- Where a
lookup_prefixlanded: the stored key that is a prefix of the query, by its length in bits and the value under it. - Slice
- A cursor that reads typed values out of one cell.
- Usage
Tree - A record of the cells a read touched, over the tree it read.
Enums§
- AugNode
- A node a directed augmented walk visits: an interior fork, or a leaf.
- Cell
Error - A failure parsing a bag of cells or reading a cell.
- Cell
Type - The kind of a cell.
- Lookup
- How a lookup ended.
- MsgAddress
- An account address, as a message carries it.
- Traverse
- What a
traverse_extravisitor asks for at each node.
Constants§
- MAX_
BITS - The most data bits a cell may hold.
- MAX_
CELLS - The most cells
parse_bocwill read from one bag. - MAX_
DEPTH - The longest chain of references
parse_bocwill read. - MAX_
REFS - The most references a cell may hold.
Traits§
- Augmentation
- How a caller reads, writes and combines the summaries an augmented dictionary carries.
Functions§
- apply_
update - Applies a Merkle update to the base it transforms, returning the new tree.
- base64_
decode - Reads standard-alphabet base64, in its canonical form only.
- base64_
encode - Writes bytes as standard-alphabet base64, padded to a whole number of quanta.
- combine_
updates - Combines two chained Merkle updates into one that carries the whole change.
- create_
proof - Builds a Merkle proof standing for
content. - create_
update - Builds a Merkle update from an old tree to a new one.
- file_
hash - The SHA-256 of a serialized bag, the hash a block or state is named by.
- hex_
decode - Reads hex into its bytes, in either case.
- hex_
encode - Writes bytes as lowercase hex, two characters for every byte.
- is_
virtualized - Whether
cellstands above level zero, the mark a proof leaves on what it covers. - may_
apply - Applies a Merkle update if
baseis the tree it transforms, otherwise returnsNone. - parse_
boc - Parses a bag of cells and returns its root cells.
- parse_
boc_ with - Parses a bag of cells under bounds the caller has narrowed.
- rebuild_
with_ refs - Rebuilds an ordinary
celloverrefsin place of its own references, keeping its data. - serialize_
boc - Serializes a cell graph as a bag of cells, with a checksum.
- serialize_
boc_ chunks - Serializes a bag of cells as a stream of byte chunks, the streaming form of
serialize_boc. - serialize_
boc_ chunks_ with - Serializes a bag as a stream of chunks, choosing what to write beyond the cells.
- serialize_
boc_ with - Serializes a cell graph as a bag of cells, choosing what to write beyond the cells.
- validate_
update - Checks a Merkle update stands consistently for the two trees attached to it.
- virtualize
- Reads the tree a Merkle proof stands for.