get-leaf docs improvements

Author: elpiel

primitives/src/sentry.rs

@@ -722,7 +722,7 @@ pub struct ValidationErrorResponse {
     pub validation: Vec<String>,
 }
 
-/// Returns the merkle_proof for the spender/earner
+/// Get leaf response with the Merkle proof for the requested spender/earner.
 ///
 /// # Examples
 ///

sentry/src/routes.rs

@@ -1,5 +1,7 @@
 //! Sentry REST API documentation
 //!
+//! This module includes the documentation for all routes of the `Sentry`
+//! REST API and the corresponding requests, responses and parameters.
 //!
 //! All routes are listed below. Here is an overview and links to all of them:
 //! - [Channel](#channel) routes
@@ -236,39 +238,37 @@
 #![doc = include_str!("../../primitives/examples/channel_pay_request.rs")]
 //! ```
 //!
-//!
 //! #### GET `/v5/channel/:id/get-leaf
 //!
 //! This route gets the latest approved state ([`NewState`]/[`ApproveState`] pair),
-//! and finds the given `spender`/`earner` in the balances tree, and produce a merkle proof for it.
+//! finds the given `spender` or `earner` in the balances tree and produces a Merkle proof for it.
 //! This is useful for the Platform to verify if a spender leaf really exists.
 //!
 //! The route is handled by [`channel::get_leaf()`].
 //!
-//! Example Spender:
+//! Response: [`GetLeafResponse`](primitives::sentry::GetLeafResponse)
 //!
-//! `/get-leaf/spender/0xDd589B43793934EF6Ad266067A0d1D4896b0dff0`
+//! ##### Routes:
 //!
-//! Example Earner:
+//! - GET `/v5/channel/:id/get-leaf/spender/:addr`
+//! - GET `/v5/channel/:id/get-leaf/earner/:addr`
 //!
-//! `/get-leaf/earner/0xE882ebF439207a70dDcCb39E13CA8506c9F45fD9`
+//! ##### Examples:
 //!
-//! Response: [`GetLeafResponse`](primitives::sentry::GetLeafResponse)
+//! URI for retrieving leaf of a Spender:
 //!
-//! ##### Examples:
+//! `/v5/channel/0xf147fa3f1c5e5e06d359c15aa082442cc3e0380f306306022d1e9047c565a0f9/get-leaf/spender/0xDd589B43793934EF6Ad266067A0d1D4896b0dff0`
+//!
+//! URI for retrieving leaf of an Earner:
+//!
+//! `/v5/channel/0xf147fa3f1c5e5e06d359c15aa082442cc3e0380f306306022d1e9047c565a0f9/get-leaf/earner/0xE882ebF439207a70dDcCb39E13CA8506c9F45fD9`
 //!
 //! Response:
 //!
 //! ```
-#![doc = include_str!("../../primitives/examples/spender_response.rs")]
+#![doc = include_str!("../../primitives/examples/get_leaf_response.rs")]
 //! ```
 //!
-//! #### Subroutes:
-//! - GET `/v5/channel/:id/get-leaf/spender`
-//! - GET `/v5/channel/:id/get-leaf/earner`
-//!
-//! This module includes all routes for `Sentry` and the documentation of each Request/Response.
-//!
 //! #### POST `/v5/channel/dummy-deposit` (auth required)
 //!
 //! Set a deposit for a Channel and depositor (the authenticated address) in the Dummy adapter.

sentry/src/routes/channel.rs

@@ -504,11 +504,12 @@ pub async fn channel_payout<C: Locked + 'static>(
     Ok(Json(SuccessResponse { success: true }))
 }
 
-/// GET `/v5/channel/0xXXX.../get-leaf/` request
+/// GET `/v5/channel/0xXXX.../get-leaf` requests
 ///
-/// Subroutes:
-/// - /v5/channel/0xXXX.../get-leaf/spender
-/// - /v5/channel/0xXXX.../get-leaf/earner
+/// # Routes:
+///
+/// - GET `/v5/channel/:id/get-leaf/spender/:addr`
+/// - GET `/v5/channel/:id/get-leaf/earner/:addr`
 ///
 /// Response: [`GetLeafResponse`]
 pub async fn get_leaf<C: Locked + 'static>(
@@ -519,10 +520,9 @@ pub async fn get_leaf<C: Locked + 'static>(
 ) -> Result<Json<GetLeafResponse>, ResponseError> {
     let channel = channel_context.context;
 
-    let approve_state = match latest_approve_state(&app.pool, &channel).await? {
-        Some(approve_state) => approve_state,
-        None => return Err(ResponseError::NotFound),
-    };
+    let approve_state = latest_approve_state(&app.pool, &channel)
+        .await?
+        .ok_or(ResponseError::NotFound)?;
 
     let state_root = approve_state.msg.state_root.clone();
 
@@ -566,9 +566,9 @@ pub async fn get_leaf<C: Locked + 'static>(
 
     let signable_state_root = get_signable_state_root(channel.id().as_bytes(), &merkle_tree.root());
 
-    let res = hex::encode(signable_state_root);
+    let merkle_proof = hex::encode(signable_state_root);
 
-    Ok(Json(GetLeafResponse { merkle_proof: res }))
+    Ok(Json(GetLeafResponse { merkle_proof }))
 }
 
 /// POST `/v5/channel/dummy-deposit` request