ton_net/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-net: a direct client for the TON network.
20//!
21//! This crate connects to a TON liteserver over ADNL and reads chain state without an
22//! HTTP indexer in the path. It speaks the wire protocols directly: the TL codec, the
23//! ADNL transport, and the liteserver query layer.
24//!
25//! # Verification status
26//!
27//! Every read says in its type whether it was proved.
28//!
29//! A [`ServerReported`] value is the liteserver's word, returned without checking the
30//! proofs that came with it. A [`Verified`] value was checked: its Merkle proofs were
31//! recomputed against a block hash the caller supplied, and the account was bound to that
32//! block's state. There is no way to turn the first into the second.
33//!
34//! What [`Verified`] does not settle on its own is where the block hash came from.
35//! Passing [`Client::account_at`] a head read from the same liteserver shows only that the
36//! server agrees with itself, which a server making things up can also manage.
37//!
38//! [`Client::sync`] is what closes that. It walks from the key block the config pins to
39//! the network's current head, checking a validator signature set at every step, and
40//! leaves the client holding a block it proved rather than one a server named. The block
41//! it starts from is the one thing still taken on trust from the chain's side, and it
42//! comes from the file that already decides which network a client is on.
43//!
44//! The other trusted input is the local clock. A proof establishes that a block is real
45//! and was committed; it says nothing about when it was handed over, so a server
46//! replaying a genuine chain from last year passes every other check here. The clock is
47//! what catches that, which means a client whose clock is wrong has a weaker freshness
48//! guarantee than one whose clock is right. A clock far enough behind is reported rather
49//! than obeyed, so the check never silently stops running.
50//!
51//! [`Client::account`] reads against that block, so it is the read to reach for.
52//! [`Client::account_at`] proves against a block the caller names, and
53//! [`Client::account_reported`] checks nothing at all. The safe one is the one with the
54//! plain name.
55//!
56//! # Example
57//!
58//! ```no_run
59//! use ton_net::{Address, Client, Config};
60//!
61//! # async fn run() -> Result<(), ton_net::Error> {
62//! let config = Config::mainnet();
63//! let mut client = Client::connect(&config).await?;
64//! let elector = Address::parse("-1:3333333333333333333333333333333333333333333333333333333333333333")?;
65//!
66//! // Proved against a block the client walked to itself. The first call pays for the
67//! // walk; save `client.anchor()` and hand it to `connect_from` next time.
68//! let account = client.account(&elector).await?;
69//! println!("proved balance: {}", account.value().balance);
70//!
71//! // The server's word, for a caller who asks for it by name.
72//! let reported = client.account_reported(&elector).await?;
73//! println!("reported balance: {}", reported.value().balance);
74//! # Ok(())
75//! # }
76//! ```
77#![forbid(unsafe_code)]
78#![warn(missing_docs)]
79#![deny(rustdoc::broken_intra_doc_links)]
80
81mod address;
82mod client;
83mod codec;
84mod config;
85mod error;
86mod proof;
87mod sync;
88mod verified;
89
90/// Which set of things this build will accept as proven.
91///
92/// A version number answers "is this API compatible". It cannot answer the question a
93/// caller of a verifier actually has, which is whether an upgrade changed what the
94/// library believes. Those are different questions: the accept and reject boundary can
95/// move while every signature stays byte-identical, and it can stay fixed across a
96/// breaking API change.
97///
98/// So this is a separate number. It rises when a new kind of proof is accepted, when an
99/// acceptance condition tightens or loosens, when the rule for validator signature weight
100/// changes, or when a freshness default changes. It does not move for wording, for
101/// performance, or for anything a caller cannot observe in an accept or reject.
102///
103/// A caller that recorded a result can compare the epoch it was verified under against
104/// this one and decide whether to check again. Nothing else in the API answers that.
105///
106/// ```
107/// # let cached_epoch = ton_net::VERIFY_EPOCH;
108/// if cached_epoch < ton_net::VERIFY_EPOCH {
109/// // this build accepts a different set of things; verify again rather than trust
110/// // a result an older set of rules produced
111/// }
112/// ```
113///
114/// The number is meaningless across libraries and is not a version. It only ever
115/// increases, and each increase is recorded in the changelog as the delta in what is
116/// accepted and what is refused.
117pub const VERIFY_EPOCH: u32 = 2;
118
119pub use address::Address;
120pub use client::Client;
121pub use config::Config;
122pub use error::{Error, ErrorCode};
123pub use proof::verify_account;
124pub use sync::SyncReport;
125pub use verified::Verified;
126
127/// The read response types, defined in ton-net-lite and surfaced here.
128pub use ton_net_lite::{AccountState, BlockIdExt, MasterchainInfo, ServerReported};
129
130/// The decoded chain structures, defined in ton-net-block and surfaced here.
131pub use ton_net_block::{Account, AccountRead, AccountStatus, Coins};
132
133/// The cell model a decoded account carries, defined in ton-net-cell and surfaced here.
134///
135/// The list is the closure of one rule over the cell model: a type a method on a
136/// re-exported cell type answers with is nameable here, or that method is unusable
137/// through the facade. An [`Account`] carries its code and data as [`Cell`]s, and from a
138/// [`Cell`] the answers this reaches are a [`Slice`] from [`Cell::parse`], an
139/// [`Identity`] from [`Cell::identity`], a [`Builder`] from [`Cell::to_builder`], and a
140/// [`CellError`] from every read that can fail. Types a cell answers with that need no
141/// name of their own, a `Vec<u8>` from [`Cell::to_boc`] and a `String` from
142/// [`Cell::dump`], are outside it. A
143/// [`Slice`] adds the [`Dict`] that [`Slice::load_dict`] answers with, the [`Lookup`],
144/// [`DictEntry`] and [`DictIter`] that a dictionary is read through, and the
145/// [`MsgAddress`] that [`Slice::load_address`] reads.
146///
147/// [`MsgAddress`] is the wire form an address takes inside a message, which is not
148/// [`Address`]: that one is the form a person writes and a caller parses.
149///
150/// The block layer is not closed the same way. [`Account::decode`] answers with a
151/// `BlockError`, which is not nameable here, so a caller reads that failure through the
152/// `From` conversion into [`Error`] rather than by naming it. Closing that is a separate
153/// decision about which layer's error a consumer sees.
154///
155/// What the rule does not pull in stays out. The augmented and prefix dictionaries, the
156/// proof builders, and the streaming readers are reachable from no method on a type this
157/// crate returns, so a consumer whose need is the cell engine on its own depends on
158/// ton-net-cell rather than finding half of it here.
159pub use ton_net_cell::{
160 Builder, Cell, CellError, CellType, Dict, DictEntry, DictIter, Identity, Lookup, MsgAddress,
161 Slice,
162};
163
164/// The bag-of-cells codec, defined in ton-net-cell and surfaced here.
165///
166/// [`Client::account_state`] hands a proof and a state back as raw bag bytes, and
167/// [`AccountState`] documents them as such, so a facade with [`Cell::to_boc`] and no
168/// [`parse_boc`] can write a bag out and cannot read one in. [`MAX_CELLS`] and
169/// [`MAX_DEPTH`] are the bounds a parse refuses past; [`MAX_BITS`] and [`MAX_REFS`] are
170/// the bounds one cell holds within.
171pub use ton_net_cell::{parse_boc, serialize_boc, MAX_BITS, MAX_CELLS, MAX_DEPTH, MAX_REFS};
172
173// The README ships to crates.io and cannot be replaced once a version is published,
174// so its examples are compiled here rather than trusted. Doc-only: this does not
175// appear in the rendered documentation.
176#[cfg(doctest)]
177#[doc = include_str!("../README.md")]
178struct Readme;