docs: add tap docs

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

Author: gusinacio

crates/tap-agent/src/tap/context.rs

@@ -35,6 +35,11 @@ use tonic::{transport::Channel, Code, Status};
 /// multiple matches. This way we can keep the code separated and we
 /// can easily add or remove network versions.
 pub trait NetworkVersion: Send + Sync + 'static {
+    /// Sol struct returned from an aggregation
+    ///
+    /// Usually this is wrapped around a [Eip712SignedMessage].
+    ///
+    /// We provide all the trait bounds here to evict it spreading across other modules
     type Rav: SolStruct
         + Aggregate<TapReceipt>
         + Serialize
@@ -45,6 +50,7 @@ pub trait NetworkVersion: Send + Sync + 'static {
         + std::fmt::Debug
         + PartialEq;
 
+    /// gRPC client type used to process an aggregation request
     type AggregatorClient: Send + Sync;
 
     /// Takes the aggregator client, a list of receipts and the previous rav
@@ -158,6 +164,7 @@ pub struct TapAgentContext<T> {
 
 /// Allow any [NetworkVersion] to create a new context
 impl<T: NetworkVersion> TapAgentContext<T> {
+    /// Creates a TapContext
     pub fn new(
         pgpool: PgPool,
         allocation_id: Address,

crates/tap-agent/src/tap/context/checks.rs

@@ -1,6 +1,12 @@
 // Copyright 2023-, Edge & Node, GraphOps, and Semiotic Labs.
 // SPDX-License-Identifier: Apache-2.0
 
+//! # Receipt Checks
+//!
+//! Some additional receipt checks are done before an aggregation request.
+//! This allows us to have two layers of checks that allows some relieve in the performance
+//! critical part of the system in indexer-service
+
 mod allocation_id;
 mod signature;
 

crates/tap-agent/src/tap/context/checks/allocation_id.rs

@@ -13,12 +13,16 @@ use tokio::sync::watch::Receiver;
 
 use crate::tap::{CheckingReceipt, TapReceipt};
 
+/// AllocationId check
+///
+/// Verifies if the allocation is already redeemed.
 pub struct AllocationId {
     tap_allocation_redeemed: Receiver<bool>,
     allocation_id: Address,
 }
 
 impl AllocationId {
+    /// Creates a new allocation id check
     pub async fn new(
         indexer_address: Address,
         escrow_polling_interval: Duration,

crates/tap-agent/src/tap/context/checks/signature.rs

@@ -9,12 +9,18 @@ use tokio::sync::watch::Receiver;
 
 use crate::tap::{CheckingReceipt, TapReceipt};
 
+/// Signature check
+///
+/// Verifies if the signatures are signed correctly by the list of provided signers.
+/// This is an important step since [tap_core] doesn't verify signatures by default and RavRequests
+/// may fail if any of those are wrong.
 pub struct Signature {
     domain_separator: Eip712Domain,
     escrow_accounts: Receiver<EscrowAccounts>,
 }
 
 impl Signature {
+    /// Creates a new signature check
     pub fn new(domain_separator: Eip712Domain, escrow_accounts: Receiver<EscrowAccounts>) -> Self {
         Self {
             domain_separator,

crates/tap-agent/src/tap/context/error.rs

@@ -3,36 +3,61 @@
 
 use thegraph_core::alloy::primitives::Address;
 
+/// AdapterError.
+///
+/// This is used to provide good error messages for indexers
 #[derive(Debug, thiserror::Error)]
 pub enum AdapterError {
+    /// Error in case it could not get escrow accounts
     #[error("Could not get escrow accounts from eventual")]
-    EscrowEventualError { error: String },
+    EscrowEventualError {
+        /// Error message
+        error: String,
+    },
 
+    /// Error in case couldn't get the available escrow for a sender
     #[error("Could not get available escrow for sender")]
     AvailableEscrowError(#[from] indexer_monitor::EscrowAccountsError),
 
+    /// Overflow error
     #[error("Sender {sender} escrow balance is too large to fit in u128, could not get available escrow.")]
-    BalanceTooLarge { sender: Address },
-
-    #[error("Sender {sender} does not have enough escrow to subtract {fees} from {balance}.")]
-    NotEnoughEscrow {
+    BalanceTooLarge {
+        /// Sender address
         sender: Address,
-        fees: u128,
-        balance: u128,
     },
 
+    /// Database error while storing rav
     #[error("Error in while storing Ravs: {error}")]
-    RavStore { error: String },
+    RavStore {
+        /// Error message
+        error: String,
+    },
 
+    /// Database error while reading receipt
     #[error("Error in while reading Ravs: {error}")]
-    RavRead { error: String },
+    RavRead {
+        /// Error message
+        error: String,
+    },
 
+    /// Database error while deleting receipt
     #[error("Error while deleting receipts: {error}")]
-    ReceiptDelete { error: String },
+    ReceiptDelete {
+        /// Error message
+        error: String,
+    },
 
+    /// Database error while reading receipt
     #[error("Error while reading receipts: {error}")]
-    ReceiptRead { error: String },
+    ReceiptRead {
+        /// Error message
+        error: String,
+    },
 
-    #[error("Error while validating receipts: {error}")]
-    ValidationError { error: String },
+    /// Error validating signer for Ravs
+    #[error("Error while validating rav signature: {error}")]
+    ValidationError {
+        /// Error message
+        error: String,
+    },
 }

crates/tap-agent/src/tap/mod.rs

@@ -1,15 +1,24 @@
 // Copyright 2023-, Edge & Node, GraphOps, and Semiotic Labs.
 // SPDX-License-Identifier: Apache-2.0
 
+//! # tap
+//!
+//! This module implements all traits and functions necessary for a context in a
+//! [tap_core::manager::Manager] as well as receipt checks used to verify if receipts are valid.
+
 pub use ::indexer_receipt::TapReceipt;
 use indexer_monitor::EscrowAccounts;
 use tap_core::receipt::{state::Checking, ReceiptWithState};
 use thegraph_core::alloy::{hex::ToHexExt, primitives::Address};
 use tokio::sync::watch::Receiver;
+
+/// [TapReceipt] wrapped around a [Checking] state.
 pub type CheckingReceipt = ReceiptWithState<Checking, TapReceipt>;
 
+/// Context implmentation
 pub mod context;
 
+/// Helper function used to get a list of all signers in [String] for a given `sender`.
 pub async fn signers_trimmed(
     escrow_accounts_rx: Receiver<EscrowAccounts>,
     sender: Address,