Skip to main content

ton_net_block/
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//! TON block and account structures, decoded from cells, for ton-net.
20//!
21//! This crate turns the cells a liteserver returns into values a reader can use. It
22//! reads the account structure into an [`Account`], walks the fragments of a block and a
23//! shard state that an account read and its proof depend on, and reads a block's
24//! [`BlockHeader`] and the [`ValidatorSet`] a key block names.
25//!
26//! It decodes only what a read or a proof needs. A shard state carries message queues
27//! and libraries, and a block carries its whole transaction set; none of that is read
28//! here.
29//!
30//! # Trust
31//!
32//! Decoding and checking are separate here, and the types say which is which. An
33//! [`Account`] from [`Account::decode`] is bytes a server sent, believed because the
34//! server said so. The same type from [`proof::verify_account`] was checked against a
35//! block hash the caller trusts. Nothing about the value records the difference, so the
36//! caller keeps track of which call produced it; the facade above this crate is where
37//! that distinction is carried in the type.
38//!
39//! This is an internal crate of the ton-net client.
40//!
41//! # Examples
42//!
43//! ```
44//! use ton_net_block::{Account, AccountStatus};
45//!
46//! // A liteserver reports an address nothing has been stored under as empty bytes.
47//! let account = Account::decode(&[])?;
48//! assert_eq!(account.status, AccountStatus::Nonexistent);
49//! assert_eq!(account.balance.nanotons(), 0);
50//! # Ok::<(), ton_net_block::BlockError>(())
51//! ```
52#![forbid(unsafe_code)]
53#![warn(missing_docs)]
54#![deny(rustdoc::broken_intra_doc_links)]
55
56mod account;
57mod block;
58pub mod chain;
59mod coins;
60mod error;
61pub mod proof;
62mod shard;
63pub mod signature;
64pub mod validators;
65
66pub use account::{Account, AccountStatus};
67pub use block::{Block, BlockHeader};
68pub use chain::{verify_chain, ProvenBlock};
69pub use coins::Coins;
70pub use error::BlockError;
71pub use proof::{verify_account, AccountRead};
72pub use shard::{McStateExtra, ShardAccountEntry, ShardDescr, ShardState};
73pub use validators::{Validator, ValidatorSet};
74
75/// How a dictionary lookup ended, re-exported from ton-net-cell because this crate's
76/// own reads answer with it.
77pub use ton_net_cell::Lookup;
78
79/// The block identity and proof-chain types [`verify_chain`] reads, re-exported from
80/// ton-net-tl so a caller need not name that crate to check a chain.
81pub use ton_net_tl::lite::{BlockIdExt, BlockLink, PartialBlockProof};
82
83// The README ships to crates.io and cannot be replaced once a version is published,
84// so its examples are compiled here rather than trusted. Doc-only: this does not
85// appear in the rendered documentation.
86#[cfg(doctest)]
87#[doc = include_str!("../README.md")]
88struct Readme;