Documentation for channel accounting

Author: simzzz

primitives/Cargo.toml

@@ -20,6 +20,9 @@ postgres = ["bytes", "tokio-postgres", "deadpool-postgres"]
 # All Addresses and keystore files exist in the ganache-cli setup for testing with the EthereumAdapter
 test-util = []
 
+[[example]]
+name = "accounting_response"
+
 [[example]]
 name = "analytics_query"
 

primitives/examples/accounting_response.rs

@@ -0,0 +1,31 @@
+use primitives::{sentry::AccountingResponse, balances::CheckedState};
+use serde_json::{from_value, json};
+
+fn main() {
+
+
+    // Empty balances
+    {
+        let json = json!({
+            "earners": {},
+            "spenders": {},
+          });
+        assert!(from_value::<AccountingResponse::<CheckedState>>(json).is_ok());
+    }
+
+    // Non-empty balances
+    {
+        // earners sum and spenders sum should always match since balances are CheckedState
+        let json = json!({
+            "earners": {
+                "0x0000000000000000000000000000000000000000": "10000000000",
+                "0x1111111111111111111111111111111111111111": "20000000000",
+                "0x2222222222222222222222222222222222222222": "30000000000",
+            },
+            "spenders": {
+                "0x7777777777777777777777777777777777777777": "60000000000",
+            },
+        });
+        assert!(from_value::<AccountingResponse::<CheckedState>>(json).is_ok());
+    }
+}

primitives/src/sentry.rs

@@ -24,6 +24,12 @@ pub use event::{Event, EventType, CLICK, IMPRESSION};
 #[serde(rename_all = "camelCase")]
 /// Channel Accounting response
 /// A collection of all `Accounting`s for a specific `Channel`
+///
+/// # Examples
+///
+/// ```
+#[doc = include_str!("../examples/accounting_response.rs")]
+/// ```
 pub struct AccountingResponse<S: BalancesState> {
     #[serde(flatten, bound = "S: BalancesState")]
     pub balances: Balances<S>,

sentry/src/routes.rs

@@ -59,9 +59,15 @@
 //!
 //! #### GET `/v5/channel/:id/accounting`
 //!
+//! Gets all of the accounting entries for a channel from the database and checks the balances.
+//!
 //! The route is handled by [`channel::get_accounting_for_channel()`].
 //!
-//! Response: [`AccountingResponse::<CheckedState>`](primitives::sentry::AccountingResponse)
+//! Response:
+//!
+//! ```
+#![doc = include_str!("../../primitives/examples/accounting_response.rs")]
+//! ```
 //!
 //! #### GET `/v5/channel/:id/spender/:addr` (auth required)
 //!