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}
25
26/// Current state of the server tree.
27#[derive(Clone, Debug)]
28pub struct TreeState {
29    /// Next leaf index (= number of leaves appended so far).
30    pub next_index: u64,
31    /// Current Merkle root.
32    pub root: Fp,
33    /// Latest checkpointed block height.
34    pub height: u32,
35}
36
37// ---------------------------------------------------------------------------
38// TreeSyncApi trait
39// ---------------------------------------------------------------------------
40
41/// The contract between server and client.
42///
43/// In the POC: in-process (server implements this directly).
44/// In production: maps to Cosmos SDK gRPC/REST endpoints:
45/// - `get_block_commitments` → custom compact-block endpoint or Tendermint block queries
46/// - `get_root_at_height` → `GET /zally/v1/commitment-tree/{height}`
47/// - `get_tree_state` → `GET /zally/v1/commitment-tree/latest`
48pub trait TreeSyncApi {
49    type Error: std::fmt::Debug;
50
51    /// Fetch commitments per block in a height range (primary sync method).
52    ///
53    /// Returns blocks in ascending height order. Empty blocks (no appends) may
54    /// be omitted from the result.
55    fn get_block_commitments(
56        &self,
57        from_height: u32,
58        to_height: u32,
59    ) -> Result<Vec<BlockCommitments>, Self::Error>;
60
61    /// Fetch tree root at a checkpoint height (anchor verification).
62    ///
63    /// Maps to: `GET /zally/v1/commitment-tree/{height}`
64    fn get_root_at_height(&self, height: u32) -> Result<Option<Fp>, Self::Error>;
65
66    /// Fetch current tree state (next_index, root, latest height).
67    ///
68    /// Maps to: `GET /zally/v1/commitment-tree/latest`
69    fn get_tree_state(&self) -> Result<TreeState, Self::Error>;
70}
vote_commitment_tree/sync_api.rs

vote_commitment_tree/
sync_api.rs
