docs: add tracker docs

Signed-off-by: Gustavo Inacio <[email protected]>

Author: gusinacio

crates/tap-agent/src/tracker.rs

@@ -1,6 +1,19 @@
 // Copyright 2023-, Edge & Node, GraphOps, and Semiotic Labs.
 // SPDX-License-Identifier: Apache-2.0
 
+//! # tracker
+//!
+//! This is the heart of tap-agent, every decision depends on these trackers.
+//!
+//! There are two main trackers: [SimpleFeeTracker] [SenderFeeTracker].
+//! Each of them enable certain methods that allows fine-grained control over what are the
+//! algorithm that selects the biggest allocation.
+//!
+//! The tracker contains a tricky feature called buffer that is used to count know the counter of
+//! any key in X amount of seconds ago. This is important since, receipt timestamp_ns is provided
+//! by senders, we want to have a tolerance buffer where we still accept receipts with timestamp
+//! older than our current clock.
+
 pub use extra_data::{DefaultFromExtra, DurationInfo, NoExtraData};
 use generic_tracker::GenericTracker;
 pub use sender_fee_stats::SenderFeeStats;
@@ -16,14 +29,34 @@ pub use generic_tracker::GlobalFeeTracker;
 
 use crate::agent::unaggregated_receipts::UnaggregatedReceipts;
 
+/// Simple Tracker used for just `u128` fees and no extra blocking or unblocking feature
+///
+/// It's mainly used for Invalid Receipts and Ravs, since they only need to store and retrieve the
+/// total amount of all allocations combined
 pub type SimpleFeeTracker = GenericTracker<u128, u128, NoExtraData, u128>;
+/// SenderFeeTracker used for more complex features.
+///
+/// It uses [UnaggregatedReceipts] instead of [u128], contains a buffer for selection, and contains
+/// more logic about if an allocation is available for selection or not.
 pub type SenderFeeTracker =
     GenericTracker<GlobalFeeTracker, SenderFeeStats, DurationInfo, UnaggregatedReceipts>;
 
+/// Stats trait used by the Counter of a given allocation.
+///
+/// This is the data that goes in the Value side of the Map inside our Tracker
 pub trait AllocationStats<U> {
+    /// updates its value with a new one
     fn update(&mut self, v: U);
+    /// Returns if an allocation is allows to trigger a rav request
     fn is_allowed_to_trigger_rav_request(&self) -> bool;
+    /// Get the stats U given
     fn get_stats(&self) -> U;
+    /// Returns the total fee (validated and pending)
     fn get_total_fee(&self) -> u128;
+    /// Returns only ravable fees (no pending fees) that is used for triggering
+    ///
+    /// Pending fees are usually fees that not eligible to trigger a RAV,
+    /// for example, you don't want to trigger a Rav Request if your only allocation is currently
+    /// requesting, so this should return a value that don't contains that allocation
     fn get_valid_fee(&mut self) -> u128;
 }

crates/tap-agent/src/tracker/extra_data.rs

@@ -3,15 +3,19 @@
 
 use std::time::Duration;
 
+/// Default values for a given extra data E
 pub trait DefaultFromExtra<E> {
+    /// Generates a new default Self given some extra data
     fn default_from_extra(extra: &E) -> Self;
 }
 
+/// Buffer information
 #[derive(Debug, Clone)]
 pub struct DurationInfo {
     pub(super) buffer_duration: Duration,
 }
 
+/// No Extra Data struct
 #[derive(Debug, Clone, Default)]
 pub struct NoExtraData;
 

crates/tap-agent/src/tracker/generic_tracker.rs

@@ -14,6 +14,10 @@ use super::{
 };
 use crate::agent::unaggregated_receipts::UnaggregatedReceipts;
 
+/// Global Fee Tracker used inside SenderFeeTracker
+///
+/// This allows to keep a simple O(1) instead of looping over all allocations to get the total
+/// amount
 #[derive(Debug, Clone, Copy, Default, PartialEq)]
 pub struct GlobalFeeTracker {
     pub(super) requesting: u128,

crates/tap-agent/src/tracker/sender_fee_stats.rs

@@ -9,20 +9,24 @@ use std::{
 use super::{AllocationStats, DefaultFromExtra, DurationInfo};
 use crate::{agent::unaggregated_receipts::UnaggregatedReceipts, backoff::BackoffInfo};
 
+/// Stats for a given allocation
 #[derive(Debug, Clone, Default)]
 pub struct SenderFeeStats {
+    /// sum of all fees in the tracker
     pub(super) total_fee: u128,
+    /// counter of receipts
     pub(super) count: u64,
-    // there are some allocations that we don't want it to be
-    // heaviest allocation, because they are already marked for finalization,
-    // and thus requesting RAVs on their own in their `post_stop` routine.
+    /// there are some allocations that we don't want it to be
+    /// heaviest allocation, because they are already marked for finalization,
+    /// and thus requesting RAVs on their own in their `post_stop` routine.
     pub(super) blocked: bool,
+    /// amount of fees that are currently being requested
     pub(super) requesting: u128,
 
-    // Buffer info
+    /// Buffer info
     pub(super) buffer_info: BufferInfo,
 
-    // Backoff info
+    /// Backoff info
     pub(super) backoff_info: BackoffInfo,
 }