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
9/// Reward API trait - returns internal types
10///
11/// Uses associated types to avoid importing espresso-types in this crate.
12/// Types must be Serialize for JSON responses, but don't need JsonSchema.
13#[async_trait]
14pub trait RewardApi {
15    /// Type for reward claim input data (must be serializable to JSON)
16    type RewardClaimInput: Serialize + Send + Sync;
17
18    /// Type for reward balance queries (must be serializable to JSON)
19    type RewardBalance: Serialize + Send + Sync;
20
21    /// Type for reward account proof queries (must be serializable to JSON)
22    type RewardAccountQueryData: Serialize + Send + Sync;
23
24    /// Type for paginated reward amounts (must be serializable to JSON)
25    type RewardAmounts: Serialize + Send + Sync;
26
27    /// Type for raw merkle tree snapshots (must be serializable to JSON)
28    type RewardMerkleTreeData: Serialize + Send + Sync;
29
30    /// Get reward claim input for L1 contract submission
31    ///
32    /// Returns all data needed to call the claimRewards function on the L1 contract,
33    /// including lifetime rewards and the Merkle proof.
34    ///
35    /// # Arguments
36    /// * `block_height` - Must match the height finalized in the Light Client contract
37    /// * `address` - Ethereum address to query rewards for (hex format)
38    async fn get_reward_claim_input(
39        &self,
40        block_height: u64,
41        address: String,
42    ) -> anyhow::Result<Self::RewardClaimInput>;
43
44    /// Get reward balance at a specific height
45    ///
46    /// # Arguments
47    /// * `height` - Block height to query
48    /// * `address` - Ethereum address to query rewards for
49    async fn get_reward_balance(
50        &self,
51        height: u64,
52        address: String,
53    ) -> anyhow::Result<Self::RewardBalance>;
54
55    /// Get latest reward balance at the most recent finalized height
56    ///
57    /// # Arguments
58    /// * `address` - Ethereum address to query rewards for
59    async fn get_latest_reward_balance(
60        &self,
61        address: String,
62    ) -> anyhow::Result<Self::RewardBalance>;
63
64    /// Get Merkle proof for a reward account at a specific height
65    ///
66    /// Returns complete query data with balance and expanded merkle proof
67    ///
68    /// # Arguments
69    /// * `height` - Block height to query
70    /// * `address` - Ethereum address to query proof for
71    async fn get_reward_account_proof(
72        &self,
73        height: u64,
74        address: String,
75    ) -> anyhow::Result<Self::RewardAccountQueryData>;
76
77    /// Get Merkle proof for a reward account at the latest finalized height
78    ///
79    /// Returns complete query data with balance and expanded merkle proof
80    ///
81    /// # Arguments
82    /// * `address` - Ethereum address to query proof for
83    async fn get_latest_reward_account_proof(
84        &self,
85        address: String,
86    ) -> anyhow::Result<Self::RewardAccountQueryData>;
87
88    /// Get paginated list of reward amounts at a specific height
89    ///
90    /// # Arguments
91    /// * `height` - Block height to query
92    /// * `offset` - Starting index for pagination
93    /// * `limit` - Maximum number of results (≤ 10000)
94    async fn get_reward_amounts(
95        &self,
96        height: u64,
97        offset: u64,
98        limit: u64,
99    ) -> anyhow::Result<Self::RewardAmounts>;
100
101    /// Get raw RewardMerkleTreeV2 snapshot at a given height
102    ///
103    /// Returns the serialized merkle tree data
104    ///
105    /// # Arguments
106    /// * `height` - Block height to query
107    async fn get_reward_merkle_tree_v2(
108        &self,
109        height: u64,
110    ) -> anyhow::Result<Self::RewardMerkleTreeData>;
111}
espresso_api/v1/reward_state_v2.rs

espresso_api/v1/
reward_state_v2.rs
