Skip to main content

Client

Struct Client 

Source
pub struct Client { /* private fields */ }
Expand description

A connection to a single TON liteserver.

A Client owns one ADNL channel to one liteserver and serves reads over it.

Reads come in two kinds and the return type says which. A ServerReported value is the server’s word, believed because the server said so. A Verified value was checked against a block hash the caller supplied, and could not have been produced any other way. Nothing converts one into the other.

A Client serializes its queries: overlapping calls on the same client run one after another over the single channel, because each takes &mut self. Open more than one client for real concurrency.

Implementations§

Source§

impl Client

Source

pub async fn connect(config: &Config) -> Result<Self, Error>

Connects to a liteserver from the config and completes the ADNL handshake.

Tries the config’s liteservers in turn until one connects and completes a handshake. Nothing is proved yet: the client has no anchor until sync establishes one.

§Errors

Returns Error::Transport if no liteserver is reachable, or Error::Handshake if the last one reached rejects the handshake.

Source

pub async fn connect_from( config: &Config, anchor: &BlockIdExt, ) -> Result<Self, Error>

Connects and starts the walk from a block the caller already trusts.

anchor must be a masterchain key block. It is the client’s root of trust: everything the client goes on to believe is derived from it, so it is worth exactly what the storage it came from is worth. Anything that can write to where a caller keeps one can choose what this client believes.

A block from a previous run’s anchor makes this sync short, which is the whole reason the anchor is handed back.

§Errors

As connect, plus Error::Sync if the server cannot prove a chain from anchor, and Error::Stale if what it leads to is too old.

Source

pub fn anchor(&self) -> Option<&BlockIdExt>

The key block the client’s trust currently rests on, if a sync has run.

Saving this and handing it to connect_from on a later run makes that run’s sync short. It is a public block identity and holds no secret, but it is a root of trust, so where it is kept is a decision the caller’s own threat model makes. This library stores nothing and picks no location.

Source

pub async fn sync(&mut self) -> Result<SyncReport, Error>

Walks the anchor forward to the network’s current head.

Without an anchor the walk starts at the config’s init block, which is a first sync and costs a run over every key block published since that block: about a couple of minutes and fifty megabytes against mainnet in July 2026. With one it is a few links.

The head in the returned SyncReport is proved and then the client forgets it. What the client keeps is the last key block on the way, because that is the only kind of block a later chain can continue from. Read anchor after this to save it.

§Errors

Returns Error::Config if there is neither an anchor nor an init block, Error::Sync if the proof chain does not check out or the server will not finish it, Error::Stale if the head it leads to is older than the config’s freshness bound, or the transport errors.

Source

pub async fn masterchain_info( &mut self, ) -> Result<ServerReported<MasterchainInfo>, Error>

Reads the liteserver’s current masterchain head.

The returned MasterchainInfo is fully decoded from the wire. It is not proof-verified.

§Errors

Returns Error::Timeout if the query does not complete in time, Error::LiteServer if the server returns an error, Error::Decode if the response does not decode, or Error::Transport on a socket failure.

Source

pub async fn account( &mut self, address: &Address, ) -> Result<Verified<Account>, Error>

Reads an account and proves it against a block this client established itself.

Walks the chain to a current head, reads the account there, and checks the proofs against it. Nothing in the result rests on a hash the caller supplied, which is what separates this from account_at: the block it proves against was derived from the key block the config pins, one validator signature set at a time.

Every call walks. After the first that is a link or two, but it is not free, so a caller reading many accounts should sync once and pass the head to account_at rather than pay it per account.

§Errors

Returns Error::Config if there is nothing to start a walk from, Error::Sync if the chain does not check out, Error::Stale if the head it reaches is too old, Error::Proof if the account does not bind to that head, or the transport errors.

Source

pub async fn account_reported( &mut self, address: &Address, ) -> Result<ServerReported<Account>, Error>

Reads an account at the current masterchain head without checking anything.

Reads the head first, then the account at that block. The value is the server’s word: the proofs it sent are carried along unchecked. It is named for what it is because after this release the proven read is the one a caller lands on without choosing, and this is the exception.

§Errors

Returns Error::Timeout if a query does not complete in time, Error::LiteServer if the server returns an error, Error::Decode if a response does not decode, Error::Cell if the account state does not read as an account, or Error::Transport on a socket failure. Never Error::Proof: this call checks no proof, so it has none to fail.

Source

pub async fn account_state( &mut self, address: &Address, block: &BlockIdExt, ) -> Result<ServerReported<AccountState>, Error>

Reads an account’s raw state and proofs at a given block.

The bytes come back as the server sent them, unchecked and undecoded. This is the way out for a caller who wants to keep the proofs, check them elsewhere, or check them against an anchor obtained later.

§Errors

Returns Error::Timeout if the query does not complete in time, Error::LiteServer if the server returns an error, Error::Decode if the response does not decode, or Error::Transport on a socket failure.

Source

pub async fn account_at( &mut self, address: &Address, trusted: &BlockIdExt, ) -> Result<Verified<Account>, Error>

Reads an account at a block the caller names, and proves it belongs to that block.

The proofs are checked against trusted’s root hash: for an account outside the masterchain the shard block holding it is derived from the masterchain state rather than taken from what the server named, and the state bytes are bound to the account the proof carries. An account the block’s state does not hold comes back as AccountStatus::Nonexistent, which is a proved answer rather than a failure. An account the proof declines to cover is a failure.

trusted is taken on faith, so where it came from is the whole question. Taking it from masterchain_info on this same client proves nothing: that only shows the server agrees with itself. The two sources that do mean something are a block this client proved, from sync or anchor, and a block the caller trusts independently.

Reading many accounts at one proved block is what this is for now: account walks the chain on every call, so a caller who wants a consistent snapshot syncs once and passes the head here.

§Errors

Returns Error::Proof if trusted is not a masterchain block, if a proof does not check out, or if the account does not bind to trusted, or Error::Timeout, Error::LiteServer, Error::Decode, or Error::Transport as the read fails.

Trait Implementations§

Source§

impl Debug for Client

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.