espresso_api/v1/
availability.rs

1use std::ops::Range;
2
3use async_trait::async_trait;
4use espresso_types::{
5    NamespaceProofQueryData, SeqTypes, StateCertQueryDataV1, StateCertQueryDataV2,
6    v0_3::AvidMIncorrectEncodingNsProof,
7};
8use futures::stream::BoxStream;
9use hotshot_query_service_types::{
10    Header,
11    availability::{
12        BlockQueryData, BlockSummaryQueryData, LeafQueryData, Limits, PayloadQueryData,
13        TransactionQueryData, TransactionWithProofQueryData, VidCommonQueryData,
14    },
15};
16use hotshot_types::simple_certificate::Certificate2;
17
18#[derive(Debug, Clone)]
19pub enum BlockId {
20    Height(u64),
21    Hash(String),
22    PayloadHash(String),
23}
24
25#[derive(Debug, Clone)]
26pub enum LeafId {
27    Height(u64),
28    Hash(String),
29}
30
31#[derive(Debug, Clone)]
32pub enum PayloadId {
33    Height(u64),
34    Hash(String),
35    BlockHash(String),
36}
37
38#[async_trait]
39pub trait AvailabilityApi {
40    async fn get_namespace_proof(
41        &self,
42        block_id: BlockId,
43        namespace: u32,
44    ) -> anyhow::Result<NamespaceProofQueryData>;
45
46    async fn get_namespace_proof_range(
47        &self,
48        from: u64,
49        until: u64,
50        namespace: u32,
51    ) -> anyhow::Result<Vec<NamespaceProofQueryData>>;
52
53    async fn stream_namespace_proofs(
54        &self,
55        from: usize,
56        namespace: u32,
57    ) -> anyhow::Result<BoxStream<'static, NamespaceProofQueryData>>;
58
59    async fn get_incorrect_encoding_proof(
60        &self,
61        block_id: BlockId,
62        namespace: u32,
63    ) -> anyhow::Result<AvidMIncorrectEncodingNsProof>;
64
65    async fn get_state_cert(&self, epoch: u64) -> anyhow::Result<StateCertQueryDataV1<SeqTypes>>;
66
67    async fn get_state_cert_v2(&self, epoch: u64)
68    -> anyhow::Result<StateCertQueryDataV2<SeqTypes>>;
69}
70
71/// HotShot core availability API: mirrors the hotshot-query-service availability endpoints.
72///
73/// Each method corresponds to a hotshot-query-service route, with no path or output changes.
74#[async_trait]
75pub trait HotShotAvailabilityApi {
76    async fn get_leaf(&self, id: LeafId) -> anyhow::Result<LeafQueryData<SeqTypes>>;
77    async fn get_leaf_range(
78        &self,
79        from: usize,
80        until: usize,
81    ) -> anyhow::Result<Vec<LeafQueryData<SeqTypes>>>;
82
83    async fn get_header(&self, id: BlockId) -> anyhow::Result<Header<SeqTypes>>;
84    async fn get_header_range(
85        &self,
86        from: usize,
87        until: usize,
88    ) -> anyhow::Result<Vec<Header<SeqTypes>>>;
89
90    async fn get_block(&self, id: BlockId) -> anyhow::Result<BlockQueryData<SeqTypes>>;
91    async fn get_block_range(
92        &self,
93        from: usize,
94        until: usize,
95    ) -> anyhow::Result<Vec<BlockQueryData<SeqTypes>>>;
96
97    async fn get_payload(&self, id: PayloadId) -> anyhow::Result<PayloadQueryData<SeqTypes>>;
98    async fn get_payload_range(
99        &self,
100        from: usize,
101        until: usize,
102    ) -> anyhow::Result<Vec<PayloadQueryData<SeqTypes>>>;
103
104    async fn get_vid_common(&self, id: BlockId) -> anyhow::Result<VidCommonQueryData<SeqTypes>>;
105    async fn get_vid_common_range(
106        &self,
107        from: usize,
108        until: usize,
109    ) -> anyhow::Result<Vec<VidCommonQueryData<SeqTypes>>>;
110
111    /// The objects for a set of half-open height ranges, which must be ascending and disjoint.
112    ///
113    /// These carry a fragmented set of heights in one request, for peers catching up. Like the
114    /// range endpoints they answer in full or not at all: a height the node lacks is fetched from
115    /// its own peers, and a 404 means at least one was not available in time.
116    async fn get_leaf_ranges(
117        &self,
118        ranges: Vec<Range<u64>>,
119    ) -> anyhow::Result<Vec<LeafQueryData<SeqTypes>>>;
120    async fn get_block_ranges(
121        &self,
122        ranges: Vec<Range<u64>>,
123    ) -> anyhow::Result<Vec<BlockQueryData<SeqTypes>>>;
124    async fn get_vid_common_ranges(
125        &self,
126        ranges: Vec<Range<u64>>,
127    ) -> anyhow::Result<Vec<VidCommonQueryData<SeqTypes>>>;
128
129    async fn get_transaction_by_position(
130        &self,
131        height: u64,
132        index: u64,
133    ) -> anyhow::Result<TransactionQueryData<SeqTypes>>;
134    async fn get_transaction_by_hash(
135        &self,
136        hash: String,
137    ) -> anyhow::Result<TransactionQueryData<SeqTypes>>;
138
139    async fn get_transaction_proof_by_position(
140        &self,
141        height: u64,
142        index: u64,
143    ) -> anyhow::Result<TransactionWithProofQueryData<SeqTypes>>;
144    async fn get_transaction_proof_by_hash(
145        &self,
146        hash: String,
147    ) -> anyhow::Result<TransactionWithProofQueryData<SeqTypes>>;
148
149    async fn get_block_summary(
150        &self,
151        height: usize,
152    ) -> anyhow::Result<BlockSummaryQueryData<SeqTypes>>;
153    async fn get_block_summary_range(
154        &self,
155        from: usize,
156        until: usize,
157    ) -> anyhow::Result<Vec<BlockSummaryQueryData<SeqTypes>>>;
158
159    async fn get_limits(&self) -> anyhow::Result<Limits>;
160
161    async fn get_cert2(&self, height: u64) -> anyhow::Result<Option<Certificate2<SeqTypes>>>;
162
163    async fn stream_leaves(
164        &self,
165        from: usize,
166    ) -> anyhow::Result<BoxStream<'static, LeafQueryData<SeqTypes>>>;
167
168    async fn stream_headers(
169        &self,
170        from: usize,
171    ) -> anyhow::Result<BoxStream<'static, Header<SeqTypes>>>;
172
173    async fn stream_blocks(
174        &self,
175        from: usize,
176    ) -> anyhow::Result<BoxStream<'static, BlockQueryData<SeqTypes>>>;
177
178    async fn stream_payloads(
179        &self,
180        from: usize,
181    ) -> anyhow::Result<BoxStream<'static, PayloadQueryData<SeqTypes>>>;
182
183    async fn stream_vid_common(
184        &self,
185        from: usize,
186    ) -> anyhow::Result<BoxStream<'static, VidCommonQueryData<SeqTypes>>>;
187
188    async fn stream_transactions(
189        &self,
190        from: usize,
191        namespace: Option<u32>,
192    ) -> anyhow::Result<BoxStream<'static, TransactionQueryData<SeqTypes>>>;
193}
espresso_api/v1/availability.rs

espresso_api/v1/
availability.rs
