docs: add new crates doc

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

Author: gusinacio

tap_core/src/rav_request.rs

@@ -1,6 +1,8 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Request to Tap Aggregator
+
 use alloy::sol_types::SolStruct;
 use tap_receipt::rav::AggregationError;
 

tap_core/src/receipt.rs

@@ -1,4 +1,23 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
-//
+
+//! # Receipts states and checks
+//!
+//! Receipts are used as single transaction promise of payment. A payment sender
+//! creates a receipt and ECDSA signs it, then sends it to a payment receiver.
+//! The payment receiver would verify the received receipt and store it to be
+//! accumulated with other received receipts in the future.
+//!
+//! A list of checks are performed on the received receipts to ensure they are valid.
+//! The checks are performed when storing the receipt and when aggregating the receipts
+//! into a Receipt Aggregate Voucher (RAV).
+//!
+//! Each receipt is wrapped into a State Machine that can be in one of the following states:
+//! - `Checking`: The receipt is being checked.
+//! - `Failed`: The receipt has failed a check or validation.
+//! - `AwaitingReserve`: The receipt has passed all checks and is awaiting escrow reservation.
+//! - `Reserved`: The receipt has successfully reserved escrow.
+//!
+//!
+
 pub use ::tap_receipt::*;

tap_core/src/signed_message.rs

@@ -1,4 +1,25 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+//! # EIP712 message and signatures
+//!
+//! This module contains the `EIP712SignedMessage` struct which is used to sign and verify messages
+//! using EIP712 standard.
+//!
+//! # Example
+//! ```rust
+//! # use alloy::{dyn_abi::Eip712Domain, primitives::Address, signers::local::PrivateKeySigner};
+//! # let domain_separator = Eip712Domain::default();
+//! use tap_eip712_message::EIP712SignedMessage;
+//! # let wallet = PrivateKeySigner::random();
+//! # let wallet_address = wallet.address();
+//! # let message = msg::Receipt::new(Address::from([0x11u8; 20]), 100).unwrap();
+//!
+//! let signed_message = EIP712SignedMessage::new(&domain_separator, message, &wallet).unwrap();
+//! let signer = signed_message.recover_signer(&domain_separator).unwrap();
+//!
+//! assert_eq!(signer, wallet_address);
+//! ```
+//!
+
 pub use ::tap_eip712_message::*;

tap_eip712_message/src/lib.rs

@@ -1,9 +1,9 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-//! # EIP712 message and signature
+//! # EIP712 signed message
 //!
-//! This module contains the `EIP712SignedMessage` struct which is used to sign and verify messages
+//! This crate contains the `EIP712SignedMessage` struct which is used to sign and verify messages
 //! using EIP712 standard.
 //!
 //! # Example
@@ -30,6 +30,7 @@ use alloy::{
 };
 use serde::{Deserialize, Serialize};
 
+/// Errors returned by creation of messages and verify signature
 #[derive(thiserror::Error, Debug)]
 pub enum Eip712Error {
     /// `alloy` wallet error
@@ -50,9 +51,11 @@ pub struct Eip712SignedMessage<M: SolStruct> {
     pub signature: Signature,
 }
 
+/// Signature that can be used in a HashSet
 #[derive(Debug, Hash, PartialEq, Eq, PartialOrd, Ord)]
 pub struct SignatureBytes([u8; 65]);
 
+/// Extension for Signature to return [SignatureBytes]
 pub trait SignatureBytesExt {
     fn get_signature_bytes(&self) -> SignatureBytes;
 }

tap_graph/src/lib.rs

@@ -1,26 +1,13 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-use std::time::{SystemTime, UNIX_EPOCH};
+//! # The Graph TAP structs
+//!
+//! These structs are used for communication between The Graph systems.
+//!
 
 mod rav;
 mod receipt;
 
 pub use rav::{ReceiptAggregateVoucher, SignedRav};
 pub use receipt::{Receipt, SignedReceipt};
-
-#[derive(Debug, thiserror::Error)]
-pub enum Error {
-    /// Error when Rust fails to get the current system time
-    #[error("Failed to get current system time: {source_error_message} ")]
-    InvalidSystemTime { source_error_message: String },
-}
-
-fn get_current_timestamp_u64_ns() -> Result<u64, Error> {
-    Ok(SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map_err(|err| Error::InvalidSystemTime {
-            source_error_message: err.to_string(),
-        })?
-        .as_nanos() as u64)
-}

tap_graph/src/rav.rs

@@ -50,11 +50,11 @@ use tap_receipt::{
 
 use crate::{receipt::Receipt, SignedReceipt};
 
-/// EIP712 signed message for ReceiptAggregateVoucher
+/// A Rav wrapped in an Eip712SignedMessage
 pub type SignedRav = Eip712SignedMessage<ReceiptAggregateVoucher>;
 
 sol! {
-    /// Holds information needed for promise of payment signed with ECDSA
+    /// ReceiptAggregateVoucher struct sent to Arbitrum to redeem payments
     ///
     /// We use camelCase for field names to match the Ethereum ABI encoding
     #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)]

tap_graph/src/receipt.rs

@@ -8,17 +8,19 @@
 //! The payment receiver would verify the received receipt and store it to be
 //! accumulated with other received receipts in the future.
 
+use std::time::{SystemTime, SystemTimeError, UNIX_EPOCH};
+
 use alloy::{primitives::Address, sol};
 use rand::{thread_rng, Rng};
 use serde::{Deserialize, Serialize};
 use tap_eip712_message::Eip712SignedMessage;
 use tap_receipt::WithValueAndTimestamp;
 
-/// A signed receipt message
+/// A Receipt wrapped in an Eip712SignedMessage
 pub type SignedReceipt = Eip712SignedMessage<Receipt>;
 
 sol! {
-    /// Holds information needed for promise of payment signed with ECDSA
+    /// Receipt struct used to pay for an off-chain service
     #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)]
     struct Receipt {
         /// Unique allocation id this receipt belongs to
@@ -32,10 +34,14 @@ sol! {
     }
 }
 
+fn get_current_timestamp_u64_ns() -> Result<u64, SystemTimeError> {
+    Ok(SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos() as u64)
+}
+
 impl Receipt {
     /// Returns a receipt with provided values
-    pub fn new(allocation_id: Address, value: u128) -> Result<Self, crate::Error> {
-        let timestamp_ns = crate::get_current_timestamp_u64_ns()?;
+    pub fn new(allocation_id: Address, value: u128) -> Result<Self, SystemTimeError> {
+        let timestamp_ns = get_current_timestamp_u64_ns()?;
         let nonce = thread_rng().gen::<u64>();
         Ok(Self {
             allocation_id,

tap_receipt/src/lib.rs

@@ -33,13 +33,16 @@ use tap_eip712_message::{Eip712SignedMessage, SignatureBytes, SignatureBytesExt}
 /// Result type for receipt
 pub type ReceiptResult<T> = Result<T, ReceiptError>;
 
+/// Extra information for [checks::Check]
 pub type Context = anymap3::Map<dyn std::any::Any + Send + Sync>;
 
+/// Extension that allows TAP Aggregation for any SolStruct receipt
 pub trait WithValueAndTimestamp {
     fn value(&self) -> u128;
     fn timestamp_ns(&self) -> u64;
 }
 
+/// Extension that allows UniqueCheck for any SolStruct receipt
 pub trait WithUniqueId {
     type Output: Eq + std::hash::Hash;
     fn unique_id(&self) -> Self::Output;

tap_receipt/src/rav.rs

@@ -1,6 +1,8 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Aggregation of Receipts
+
 use alloy::sol_types::SolStruct;
 use tap_eip712_message::Eip712SignedMessage;