Skip to main content

Crate ton_net_cell

Crate ton_net_cell 

Source
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.
AugDictIter
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 X over n-bit keys.
DictEntry
Where a lookup landed: the cell holding the leaf, and where its contents start.
DictIter
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.
ParseOptions
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.
PfxDictIter
A walk over every entry of a prefix dictionary, in ascending key order.
PfxMatch
Where a lookup_prefix landed: 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.
UsageTree
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.
CellError
A failure parsing a bag of cells or reading a cell.
CellType
The kind of a cell.
Lookup
How a lookup ended.
MsgAddress
An account address, as a message carries it.
Traverse
What a traverse_extra visitor asks for at each node.

Constants§

MAX_BITS
The most data bits a cell may hold.
MAX_CELLS
The most cells parse_boc will read from one bag.
MAX_DEPTH
The longest chain of references parse_boc will 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 cell stands above level zero, the mark a proof leaves on what it covers.
may_apply
Applies a Merkle update if base is the tree it transforms, otherwise returns None.
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 cell over refs in 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.

Type Aliases§

AugItem
A key and the augmented entry stored under it, the pair an AugDict query returns.
ForkExtra
A dictionary fork’s key prefix and the summary it carries.