espresso_api/v1/reward_state_v2.rs
1//! Reward State V2 API trait for v1
2//!
3//! Returns internal espresso-types (legacy, no OpenAPI docs).
4//! Uses associated types to avoid importing espresso-types in this crate.
5
6use async_trait::async_trait;
7use serde::Serialize;
8
9use crate::v1::merklized_state::Snapshot;
10
11/// Reward API trait - returns internal types
12///
13/// Uses associated types to avoid importing espresso-types in this crate.
14/// Types must be Serialize for JSON responses, but don't need JsonSchema.
15#[async_trait]
16pub trait RewardApi {
17 /// Type for reward claim input data (must be serializable to JSON)
18 type RewardClaimInput: Serialize + Send + Sync;
19
20 /// Type for reward balance queries (must be serializable to JSON)
21 type RewardBalance: Serialize + Send + Sync;
22
23 /// Type for reward account proof queries (must be serializable to JSON)
24 type RewardAccountQueryData: Serialize + Send + Sync;
25
26 /// Type for paginated reward amounts (must be serializable to JSON)
27 type RewardAmounts: Serialize + Send + Sync;
28
29 /// Type for raw merkle tree snapshots (must be serializable to JSON)
30 type RewardMerkleTreeData: Serialize + Send + Sync;
31
32 /// Type for reward account proof queries against the V1 (RewardMerkleTreeV1) tree
33 type RewardAccountQueryDataV1: Serialize + Send + Sync;
34
35 /// Type for a raw Merkle path into the reward-state (RewardMerkleTreeV1) tree
36 type RewardStatePathV1: Serialize + Send + Sync;
37
38 /// Type for a raw Merkle path into the reward-state-v2 (RewardMerkleTreeV2) tree
39 type RewardStatePathV2: Serialize + Send + Sync;
40
41 /// Get the height of the last persisted reward-state-v1 merklized state snapshot
42 async fn get_reward_state_height(&self) -> anyhow::Result<u64>;
43
44 /// Get the height of the last persisted reward-state-v2 merklized state snapshot
45 async fn get_reward_state_v2_height(&self) -> anyhow::Result<u64>;
46
47 /// Get Merkle proof for a reward account against the V1 (RewardMerkleTreeV1) tree
48 ///
49 /// # Arguments
50 /// * `height` - Block height to query
51 /// * `address` - Ethereum address to query proof for
52 async fn get_reward_account_proof_v1(
53 &self,
54 height: u64,
55 address: String,
56 ) -> anyhow::Result<Self::RewardAccountQueryDataV1>;
57
58 /// Get reward claim input for L1 contract submission
59 ///
60 /// Returns all data needed to call the claimRewards function on the L1 contract,
61 /// including lifetime rewards and the Merkle proof.
62 ///
63 /// # Arguments
64 /// * `block_height` - Must match the height finalized in the Light Client contract
65 /// * `address` - Ethereum address to query rewards for (hex format)
66 async fn get_reward_claim_input(
67 &self,
68 block_height: u64,
69 address: String,
70 ) -> anyhow::Result<Self::RewardClaimInput>;
71
72 /// Get reward balance at a specific height
73 ///
74 /// # Arguments
75 /// * `height` - Block height to query
76 /// * `address` - Ethereum address to query rewards for
77 async fn get_reward_balance(
78 &self,
79 height: u64,
80 address: String,
81 ) -> anyhow::Result<Self::RewardBalance>;
82
83 /// Get latest reward balance at the most recent finalized height
84 ///
85 /// # Arguments
86 /// * `address` - Ethereum address to query rewards for
87 async fn get_latest_reward_balance(
88 &self,
89 address: String,
90 ) -> anyhow::Result<Self::RewardBalance>;
91
92 /// Get Merkle proof for a reward account at a specific height
93 ///
94 /// Returns complete query data with balance and expanded merkle proof
95 ///
96 /// # Arguments
97 /// * `height` - Block height to query
98 /// * `address` - Ethereum address to query proof for
99 async fn get_reward_account_proof(
100 &self,
101 height: u64,
102 address: String,
103 ) -> anyhow::Result<Self::RewardAccountQueryData>;
104
105 /// Get Merkle proof for a reward account at the latest finalized height
106 ///
107 /// Returns complete query data with balance and expanded merkle proof
108 ///
109 /// # Arguments
110 /// * `address` - Ethereum address to query proof for
111 async fn get_latest_reward_account_proof(
112 &self,
113 address: String,
114 ) -> anyhow::Result<Self::RewardAccountQueryData>;
115
116 /// Get paginated list of reward amounts at a specific height
117 ///
118 /// # Arguments
119 /// * `height` - Block height to query
120 /// * `offset` - Starting index for pagination
121 /// * `limit` - Maximum number of results (≤ 10000)
122 async fn get_reward_amounts(
123 &self,
124 height: u64,
125 offset: u64,
126 limit: u64,
127 ) -> anyhow::Result<Self::RewardAmounts>;
128
129 /// Get raw RewardMerkleTreeV2 snapshot at a given height
130 ///
131 /// Returns the serialized merkle tree data
132 ///
133 /// # Arguments
134 /// * `height` - Block height to query
135 async fn get_reward_merkle_tree_v2(
136 &self,
137 height: u64,
138 ) -> anyhow::Result<Self::RewardMerkleTreeData>;
139
140 /// Get the Merkle path for a key in the reward-state (RewardMerkleTreeV1) tree
141 ///
142 /// Mirrors the legacy `merklized_state` `get_path`, inherited by the reward-state mount
143 /// from `hotshot-query-service`'s merklized-state base routes (same as block-state/fee-state).
144 ///
145 /// # Arguments
146 /// * `snapshot` - Height or commitment identifying the tree snapshot
147 /// * `key` - Reward account address to query
148 async fn get_reward_state_path_v1(
149 &self,
150 snapshot: Snapshot,
151 key: String,
152 ) -> anyhow::Result<Self::RewardStatePathV1>;
153
154 /// Get the Merkle path for a key in the reward-state-v2 (RewardMerkleTreeV2) tree
155 ///
156 /// # Arguments
157 /// * `snapshot` - Height or commitment identifying the tree snapshot
158 /// * `key` - Reward account address to query
159 async fn get_reward_state_path_v2(
160 &self,
161 snapshot: Snapshot,
162 key: String,
163 ) -> anyhow::Result<Self::RewardStatePathV2>;
164}