vote_commitment_tree/
sync_api.rs

1//! Communication boundary between server and client.
2//!
3//! The [`TreeSyncApi`] trait defines the contract for fetching tree data.
4//! In the POC: in-process trait object.
5//! In production: maps to Cosmos SDK gRPC/REST endpoints.
6
7use pasta_curves::Fp;
8
9use crate::hash::MerkleHashVote;
10
11// ---------------------------------------------------------------------------
12// Types
13// ---------------------------------------------------------------------------
14
15/// Response from `get_block_commitments`: leaves appended in a single block.
16#[derive(Clone, Debug)]
17pub struct BlockCommitments {
18    /// Block height.
19    pub height: u32,
20    /// Index of the first leaf in this block.
21    pub start_index: u64,
22    /// Leaves appended in this block (in append order).
23    pub leaves: Vec<MerkleHashVote>,
24    /// Commitment tree root after this block's leaves.
25    pub root: Fp,
26}
27
28/// Paginated response from `get_block_commitments`.
29#[derive(Clone, Debug)]
30pub struct BlockCommitmentsPage {
31    /// Blocks returned in this page.
32    pub blocks: Vec<BlockCommitments>,
33    /// Next height to request, or zero when the sync range is complete.
34    pub next_from_height: u32,
35}
36
37/// Current state of the server tree.
38#[derive(Clone, Debug)]
39pub struct TreeState {
40    /// Next leaf index (= number of leaves appended so far).
41    pub next_index: u64,
42    /// Current Merkle root.
43    pub root: Fp,
44    /// Latest checkpointed block height.
45    pub height: u32,
46}
47
48// ---------------------------------------------------------------------------
49// TreeSyncApi trait
50// ---------------------------------------------------------------------------
51
52/// The contract between server and client.
53///
54/// In the POC: in-process (server implements this directly).
55/// In production: maps to Cosmos SDK gRPC/REST endpoints:
56/// - `get_block_commitments` → custom compact-block endpoint or Tendermint block queries
57/// - `get_root_at_height` → `GET /zally/v1/commitment-tree/{height}`
58/// - `get_tree_state` → `GET /zally/v1/commitment-tree/latest`
59pub trait TreeSyncApi {
60    type Error: std::fmt::Debug;
61
62    /// Fetch commitments per block in a height range (primary sync method).
63    ///
64    /// Returns blocks in ascending height order. Empty blocks (no appends) may
65    /// be omitted from the result.
66    fn get_block_commitments(
67        &self,
68        from_height: u32,
69        to_height: u32,
70    ) -> Result<BlockCommitmentsPage, Self::Error>;
71
72    /// Fetch tree root at a checkpoint height (anchor verification).
73    ///
74    /// Maps to: `GET /zally/v1/commitment-tree/{height}`
75    fn get_root_at_height(&self, height: u32) -> Result<Option<Fp>, Self::Error>;
76
77    /// Fetch current tree state (next_index, root, latest height).
78    ///
79    /// Maps to: `GET /zally/v1/commitment-tree/latest`
80    fn get_tree_state(&self) -> Result<TreeState, Self::Error>;
81}
vote_commitment_tree/sync_api.rs

vote_commitment_tree/
sync_api.rs
