Struct LightClient 

pub struct LightClient<P, S> {
    db: P,
    server: S,
    opt: LightClientOptions,
    chain_id: ChainId,
    epoch_height: u64,
    first_epoch_with_dynamic_stake_table: EpochNumber,
    genesis_stake_table: Arc<StakeTable>,
    stake_tables: RwLock<BTreeMap<EpochNumber, Arc<StakeTable>>>,
}

Client-side state required to implement the light client interface.

A LightClient can always be created from scratch, with no state, since ultimately all data is fetched and verified from external query nodes. However, having some persistent state can make it more efficient to use a LightClient over a long period of time, as important artifacts can be cached locally, avoiding the need to frequently re-fetch and verify them.

Fields

db: P

server: S

opt: LightClientOptions

chain_id: ChainId

epoch_height: u64

first_epoch_with_dynamic_stake_table: EpochNumber

genesis_stake_table: Arc<StakeTable>

stake_tables: RwLock<BTreeMap<EpochNumber, Arc<StakeTable>>>

Implementations

impl<P, S> LightClient<P, S>

pub fn into_storage(self) -> P

pub fn storage(&self) -> &P

pub fn into_inner(self) -> S

pub fn inner(&self) -> &S

impl<P, S> LightClient<P, S>

where P: Storage, S: Client,

pub fn from_genesis(db: P, server: S, genesis: Genesis) -> Self

Create a light client from scratch, with no state.

State will automatically be populated as queries are made. The provided genesis becomes the root of trust for verifying all state that is subsequently loaded by the light client. If the genesis is not correct (i.e. matching the genesis used by honest HotShot nodes) the light client may verify incorrect data, or fail to verify correct data.

pub fn from_genesis_with_options( db: P, server: S, genesis: Genesis, opt: LightClientOptions, ) -> Self

Create a light client from scratch, with no state, using the given options.

State will automatically be populated as queries are made. The provided genesis becomes the root of trust for verifying all state that is subsequently loaded by the light client. If the genesis is not correct (i.e. matching the genesis used by honest HotShot nodes) the light client may verify incorrect data, or fail to verify correct data.

pub fn genesis(&self) -> Genesis

pub async fn block_height(&self) -> Result<u64>

Get the number of known blocks in the chain.

This is equivalent to one more than the block number of the latest known block. The latest known block may come either from the local light client database or from an untrusted query service (in which case the corresponding leaf is fetched and verified to ensure there is in fact such a block). Note however that it is always possible that neither this light client nor the connected server is aware of the true latest block, and so in rare cases the result of this method may be an underestimate.

pub async fn fetch_leaf( &self, id: LeafId<SeqTypes>, ) -> Result<LeafQueryData<SeqTypes>>

Fetch and verify the requested leaf.

async fn fetch_leaf_with_quorum<Q>( &self, id: LeafId<SeqTypes>, quorum: impl Send + FnOnce(EpochNumber) -> Q, ) -> Result<LeafQueryData<SeqTypes>>

where Q: Send + Quorum,

pub async fn fetch_leaves_in_range( &self, start_height: usize, end_height: usize, ) -> Result<Vec<LeafQueryData<SeqTypes>>>

Fetches leaves in range [start_height, end_height)

pub async fn fetch_leaves_in_range_uncached( &self, start_height: usize, end_height: usize, ) -> Result<Vec<LeafQueryData<SeqTypes>>>

fetch_leaves_in_range for a caller that needs each leaf once, such as the state loop replaying history.

Only the proven last leaf goes into the cache. Writing the others costs one transaction per leaf, more than fetching the whole range, and a range longer than the cache would evict every leaf other callers keep there as anchors.

async fn fetch_leaves_in_range_with( &self, start_height: usize, end_height: usize, cache: CacheLeaves, ) -> Result<Vec<LeafQueryData<SeqTypes>>>

pub async fn fetch_headers_in_range( &self, start_height: usize, end_height: usize, ) -> Result<Vec<Header>>

Fetches headers in range [start_height, end_height)

pub async fn fetch_certificate2( &self, height: u64, ) -> Result<Option<Certificate2<SeqTypes>>>

Fetch and verify the Certificate2 at the given block height.

Returns Ok(None) if the server reports that no cert2 exists at this height

pub async fn fetch_certificate2_for_header( &self, header: &Header, ) -> Result<Option<Certificate2<SeqTypes>>>

fetch_certificate2 for a caller that already holds the verified header of the block, which saves fetching it again.

async fn verify_certificate2( &self, cert2: Certificate2<SeqTypes>, header: &Header, ) -> Result<Certificate2<SeqTypes>>

async fn fetch_leaves_in_range_from_server( &self, start_height: usize, end_height: usize, known_finalized: &LeafQueryData<SeqTypes>, cache: CacheLeaves, ) -> Result<Vec<LeafQueryData<SeqTypes>>>

Fetches leaves from the server in range [start_height, end_height) and verifies them by walking backwards from the known finalized leaf, ensuring each leaf’s hash matches the parent commitment of the subsequent leaf.

async fn verify_leaf_chain( &self, leaves: &[LeafQueryData<SeqTypes>], known_finalized: &LeafQueryData<SeqTypes>, cache: CacheLeaves, ) -> Result<()>

Verify unproven leaves by chaining them to a leaf already known to be finalized.

leaves must be consecutive and end just below known_finalized, which the caller has verified. Each leaf is then pinned by the parent commitment of the one above it, so the whole run inherits the anchor’s finality without a proof of its own.

pub async fn fetch_leaves_for_ranges( &self, ranges: &[Range<u64>], ) -> Result<Vec<LeafQueryData<SeqTypes>>>

Fetch and verify the leaves in a set of height ranges.

The bulk of the leaves come from one ranges request, which is what a fragmented set of heights is worth batching for. Verification is still per contiguous run: each run needs one leaf whose finality is proven, and the rest of the run chains to it. A run of a single height is therefore just a proof fetch, with nothing left for the ranges request to carry.

pub async fn fetch_header(&self, id: BlockId<SeqTypes>) -> Result<Header>

Fetch and verify the requested header.

async fn fetch_header_with_quorum<Q>( &self, id: BlockId<SeqTypes>, quorum: impl Send + FnOnce(EpochNumber) -> Q, ) -> Result<Header>

where Q: Send + Quorum,

pub async fn fetch_payload( &self, id: BlockId<SeqTypes>, ) -> Result<PayloadQueryData<SeqTypes>>

Fetch and verify the requested payload.

pub async fn fetch_payload_for_header( &self, header: Header, ) -> Result<PayloadQueryData<SeqTypes>>

Fetch and verify the full payload with the requested header.

pub async fn fetch_block( &self, id: BlockId<SeqTypes>, ) -> Result<BlockQueryData<SeqTypes>>

Fetch and verify the requested block.

pub async fn fetch_block_for_header( &self, header: Header, ) -> Result<BlockQueryData<SeqTypes>>

Fetch and verify the full block with the requested header.

pub async fn fetch_vid_common( &self, id: BlockId<SeqTypes>, ) -> Result<VidCommonQueryData<SeqTypes>>

Fetch and verify the VID common data for the requested block.

pub async fn fetch_vid_common_for_header( &self, header: Header, ) -> Result<VidCommonQueryData<SeqTypes>>

Fetch and verify the VID common data for the requested header.

pub async fn fetch_block_and_vid_common( &self, id: BlockId<SeqTypes>, ) -> Result<(BlockQueryData<SeqTypes>, VidCommonQueryData<SeqTypes>)>

Fetch and verify the requested payload and the associated VID common data.

pub async fn fetch_block_and_vid_common_for_header( &self, header: Header, ) -> Result<(BlockQueryData<SeqTypes>, VidCommonQueryData<SeqTypes>)>

Fetch and verify the payload corresponding to header, and the associated VID common data.

pub async fn fetch_blocks_in_range( &self, start: usize, end: usize, ) -> Result<Vec<BlockQueryData<SeqTypes>>>

Fetch and verify the blocks in the height range [start, end).

pub async fn fetch_vid_common_in_range( &self, start: usize, end: usize, ) -> Result<Vec<VidCommonQueryData<SeqTypes>>>

Fetch and verify the VID common data for blocks in the height range [start, end).

pub async fn fetch_blocks_and_vid_common_in_range( &self, start: usize, end: usize, ) -> Result<Vec<(BlockQueryData<SeqTypes>, VidCommonQueryData<SeqTypes>)>>

Fetch and verify the blocks and VID common data in the height range [start, end).

pub async fn fetch_blocks_and_vid_common_for_ranges( &self, ranges: &[Range<u64>], ) -> Result<Vec<(BlockQueryData<SeqTypes>, VidCommonQueryData<SeqTypes>)>>

Fetch and verify the blocks and VID common data for a set of height ranges.

One request for the proofs covering every range, rather than one per range. Each proof is still verified against its own header, so batching changes only how they arrive.

pub async fn fetch_namespace( &self, id: BlockId<SeqTypes>, namespace: NamespaceId, ) -> Result<Vec<Transaction>>

Fetch and verify the transactions in the given namespace of the requested block.

pub async fn fetch_namespace_for_header( &self, header: &Header, namespace: NamespaceId, ) -> Result<Vec<Transaction>>

Fetch and verify the transactions in the given namespace of the requested header.

pub async fn fetch_namespaces_in_range( &self, start_height: usize, end_height: usize, namespace: NamespaceId, ) -> Result<Vec<Vec<Transaction>>>

Fetch and verify the transactions in the given namespace of blocks in the range [start_height, end_height).

pub async fn fetch_all_namespaces_in_range( &self, start_height: usize, end_height: usize, namespaces: &[NamespaceId], ) -> Result<Vec<HashMap<NamespaceId, Vec<Transaction>>>>

Fetch and verify the transactions in the given namespaces of blocks in the range [start_height, end_height).

For each block, the result maps a namespace ID to its verified transactions, including only those requested namespaces that are actually present in that block.

pub async fn quorum_for_epoch( &self, epoch: EpochNumber, ) -> Result<Arc<StakeTable>>

Fetch and verify the stake table for the requested epoch.

fn fetch_leaf_from_server<'a, 'b, Q>( &'a self, id: impl Send + Into<LeafRequest> + 'a, known_finalized: Option<&'b Leaf2>, make_quorum: impl 'a + Send + FnOnce(EpochNumber) -> Q, ) -> impl 'b + Send + Future<Output = Result<LeafQueryData<SeqTypes>>>

where Q: Send + Quorum, 'a: 'b,

async fn cache_stake_table( &self, epoch: EpochNumber, stake_table: Arc<StakeTable>, ) -> Arc<StakeTable>

fn decaf(&self) -> bool

Trait Implementations

impl<P: Debug, S: Debug> Debug for LightClient<P, S>

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

Formats the value using the given formatter.

impl<P, S> Provider<SeqTypes, BlockRangeRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: BlockRangeRequest, ) -> Pin<Box<dyn Future<Output = Option<NonEmptyRange<BlockQueryData<SeqTypes>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, BlockRangesRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: BlockRangesRequest, ) -> Pin<Box<dyn Future<Output = Option<BlockRangesResponse<SeqTypes>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, Certificate2Request> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: Certificate2Request, ) -> Pin<Box<dyn Future<Output = Option<Option<Certificate2<SeqTypes>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, LeafRangeRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: LeafRangeRequest, ) -> Pin<Box<dyn Future<Output = Option<NonEmptyRange<LeafQueryData<SeqTypes>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, LeafRangesRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: LeafRangesRequest, ) -> Pin<Box<dyn Future<Output = Option<Vec<LeafQueryData<SeqTypes>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, LeafRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: LeafRequest, ) -> Pin<Box<dyn Future<Output = Option<LeafQueryData<SeqTypes>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, PayloadRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: PayloadRequest, ) -> Pin<Box<dyn Future<Output = Option<Payload>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, VidCommonRangeRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: VidCommonRangeRequest, ) -> Pin<Box<dyn Future<Output = Option<NonEmptyRange<VidCommonQueryData<SeqTypes>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, VidCommonRangesRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: VidCommonRangesRequest, ) -> Pin<Box<dyn Future<Output = Option<Vec<VidCommonQueryData<SeqTypes>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.

impl<P, S> Provider<SeqTypes, VidCommonRequest> for LightClient<P, S>

where P: Storage, S: Client,

fn fetch<'life0, 'async_trait>( &'life0 self, req: VidCommonRequest, ) -> Pin<Box<dyn Future<Output = Option<VidCommon>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch a resource.