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
impl Client
Sourcepub async fn connect(config: &Config) -> Result<Self, Error>
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.
Sourcepub async fn connect_from(
config: &Config,
anchor: &BlockIdExt,
) -> Result<Self, Error>
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.
Sourcepub fn anchor(&self) -> Option<&BlockIdExt>
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.
Sourcepub async fn sync(&mut self) -> Result<SyncReport, Error>
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.
Sourcepub async fn masterchain_info(
&mut self,
) -> Result<ServerReported<MasterchainInfo>, Error>
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.
Sourcepub async fn account(
&mut self,
address: &Address,
) -> Result<Verified<Account>, Error>
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.
Sourcepub async fn account_reported(
&mut self,
address: &Address,
) -> Result<ServerReported<Account>, Error>
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.
Sourcepub async fn account_state(
&mut self,
address: &Address,
block: &BlockIdExt,
) -> Result<ServerReported<AccountState>, Error>
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.
Sourcepub async fn account_at(
&mut self,
address: &Address,
trusted: &BlockIdExt,
) -> Result<Verified<Account>, Error>
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.