espresso_api/v1/
light_client.rs

1//! V1 light-client API.
2
3use std::{collections::HashMap, ops::Range};
4
5use async_trait::async_trait;
6use espresso_types::v0_3::StakeTableEvent;
7use light_client::consensus::{
8    header::HeaderProof, leaf::LeafProof, namespace::NamespaceProof, payload::PayloadProof,
9};
10
11#[derive(Debug, Clone)]
12pub enum LeafQuery {
13    Height(u64),
14    Hash(String),
15    BlockHash(String),
16    PayloadHash(String),
17}
18
19#[derive(Debug, Clone)]
20pub enum HeaderQuery {
21    Height(u64),
22    Hash(String),
23    PayloadHash(String),
24}
25
26#[async_trait]
27pub trait LightClientApi {
28    async fn get_leaf_proof(
29        &self,
30        query: LeafQuery,
31        finalized: Option<u64>,
32    ) -> anyhow::Result<LeafProof>;
33
34    async fn get_header_proof(
35        &self,
36        root: u64,
37        requested: HeaderQuery,
38    ) -> anyhow::Result<HeaderProof>;
39
40    async fn get_light_client_stake_table(
41        &self,
42        epoch: u64,
43    ) -> anyhow::Result<Vec<StakeTableEvent>>;
44
45    async fn get_payload_proof(&self, height: u64) -> anyhow::Result<PayloadProof>;
46
47    async fn get_payload_proof_range(
48        &self,
49        start: u64,
50        end: u64,
51    ) -> anyhow::Result<Vec<PayloadProof>>;
52
53    /// Payload proofs for a set of `(from, until)` half-open height ranges, which need not be
54    /// contiguous.
55    ///
56    /// A node catching up over a fragmented set of heights would otherwise pay a round trip per
57    /// run. The proofs are the same ones the range endpoint returns, in ascending height order.
58    async fn get_payload_proof_ranges(
59        &self,
60        ranges: Vec<Range<u64>>,
61    ) -> anyhow::Result<Vec<PayloadProof>>;
62
63    async fn get_lc_namespace_proof(
64        &self,
65        height: u64,
66        namespace: u64,
67    ) -> anyhow::Result<NamespaceProof>;
68
69    async fn get_lc_namespace_proof_range(
70        &self,
71        start: u64,
72        end: u64,
73        namespace: u64,
74    ) -> anyhow::Result<Vec<NamespaceProof>>;
75
76    /// `namespaces` is the raw `TaggedBase64`-encoded path segment produced by the light-client
77    /// client (tag `NS`, wrapping a JSON `Vec<u64>`); decoding it is left to the implementation
78    /// so this crate does not need a `tagged-base64` dependency.
79    async fn get_lc_namespaces_proof_range(
80        &self,
81        start: u64,
82        end: u64,
83        namespaces: String,
84    ) -> anyhow::Result<Vec<HashMap<u64, NamespaceProof>>>;
85}
espresso_api/v1/light_client.rs

espresso_api/v1/
light_client.rs
