docs!: create docs and readme.

update the modules for better visibility and documentation

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

Author: gusinacio

README.md

@@ -1 +1,48 @@
 # Timeline Aggregation Protocol (TAP)
+
+## Overview
+
+The TAP (Timeline Aggregation Protocol) facilitates a series of payments from a sender to a receiver, who aggregates these payments into a single payment. This aggregate payment can then be verified on-chain by a payment verifier, reducing the number of transactions and simplifying the payment process.
+
+## Key Components
+
+- **Sender:** Initiates the payment.
+- **Receiver:** Receives the payment.
+- **Signers:** Multiple signers authorized by the sender to sign receipts.
+- **State Channel:** A one-way channel opened by the sender with the receiver for sending receipts.
+- **Receipt:** A record of payment sent by the sender to the receiver.
+- **ReceiptAggregateVoucher (RAV):** A signed message containing the aggregate value of the receipts.
+- **tap_aggregator:** An entity managed by the sender that signs RAV requests.
+- **EscrowAccount:** An account created in the blockchain to hold funds for the sender-receiver pair.
+
+## Security Measures
+
+- The protocol uses asymmetric cryptography to sign and verify messages, ensuring the integrity of receipts and RAVs.
+
+## Process
+
+1. **Opening a State Channel:** A state channel is opened via a blockchain contract, creating an EscrowAccount for the sender-receiver pair.
+2. **Sending Receipts:** The sender sends receipts to the receiver through the state channel.
+3. **Storing Receipts:** The receiver stores the receipts and tracks the aggregate payment.
+4. **Creating a RAV Request:** A RAV request consists of a list of receipts and, optionally, the previous RAV.
+5. **Signing the RAV:** The receiver sends the RAV request to the tap_aggregator, which signs it into a RAV.
+6. **Tracking Aggregate Value:** The receiver tracks the aggregate value and new receipts since the last RAV.
+7. **Requesting a New RAV:** The receiver sends new receipts and the last RAV to the tap_aggregator for a new RAV.
+8. **Closing the State Channel:** When the allocation period ends, the receiver can send the last RAV to the blockchain and receive payment from the EscrowAccount.
+
+## Performance Considerations
+
+- The primary performance limitations are the time required to verify receipts and network limitations for sending requests to the tap_aggregator.
+
+## Use Cases
+
+- The TAP protocol is suitable for systems with sequential operations that are too expensive to redeem individually on-chain. By aggregating operations and redeeming them in one transaction, costs can be reduced.
+
+## Compatibility
+
+- The current implementation is for EVM-compatible blockchains, with most of the system being off-chain.
+
+## Contributing
+
+Contributions are welcome! Please submit a pull request or open an issue to discuss potential changes.
+Also, make sure to follow the [Contributing Guide](CONTRIBUTING.md).

tap_core/src/error.rs

@@ -11,54 +11,75 @@ use ethers_core::types::SignatureError;
 use std::result::Result as StdResult;
 use thiserror::Error as ThisError;
 
+/// Error type for the TAP protocol
 #[derive(ThisError, Debug)]
 pub enum Error {
+    /// Error when trying to aggregate receipts and the result overflows
     #[error("Aggregating receipt results in overflow")]
     AggregateOverflow,
-    #[error("Failed to encode to EIP712 hash:\n{source_error_message}")]
-    EIP712EncodeError { source_error_message: String },
-    #[error(
-        "Unexpected check: \"{check_string}\". Only checks provided in initial checklist are valid"
-    )]
-    InvalidCheckError { check_string: String },
-    #[error("The requested action is invalid for current receipt state: {state}")]
-    InvalidStateForRequestedAction { state: String },
+    /// 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 },
+    /// `ethers` wallet error
     #[error(transparent)]
     WalletError(#[from] WalletError),
+    /// Error when signature verification fails
     #[error(transparent)]
     SignatureError(#[from] SignatureError),
-    #[error("Recovered sender address invalid {address}")]
-    InvalidRecoveredSigner { address: Address },
+
+    /// Error when the received RAV does not match the expected RAV
     #[error("Received RAV does not match expexted RAV")]
     InvalidReceivedRAV {
         received_rav: ReceiptAggregateVoucher,
         expected_rav: ReceiptAggregateVoucher,
     },
+    /// Generic error from the adapter
     #[error("Error from adapter.\n Caused by: {source_error}")]
     AdapterError { source_error: anyhow::Error },
+    /// Error when no valid receipts are found for a RAV request
     #[error("Failed to produce rav request, no valid receipts")]
     NoValidReceiptsForRAVRequest,
+
+    /// Error when the previous RAV allocation id does not match the allocation id from the new receipt
     #[error("Previous RAV allocation id ({prev_id}) doesn't match the allocation id from the new receipt ({new_id}).")]
     RavAllocationIdMismatch { prev_id: String, new_id: String },
+
+    /// Error when all receipts do not have the same allocation id
+    ///
+    /// Used in tap_aggregator
     #[error("All receipts should have the same allocation id, but they don't")]
     RavAllocationIdNotUniform,
+    /// Error when the receipt signature is duplicated.
+    ///
+    /// Used in tap_aggregator
     #[error("Duplicate receipt signature: {0}")]
     DuplicateReceiptSignature(String),
     #[error(
         "Receipt timestamp ({receipt_ts}) is less or equal than previous rav timestamp ({rav_ts})"
     )]
     ReceiptTimestampLowerThanRav { rav_ts: u64, receipt_ts: u64 },
+
+
+    /// Error when the min timestamp is greater than the max timestamp
+    /// Used by [`crate::manager::Manager::create_rav_request()`]
     #[error("Timestamp range error: min_timestamp_ns: {min_timestamp_ns}, max_timestamp_ns: {max_timestamp_ns}. Adjust timestamp buffer.")]
     TimestampRangeError {
         min_timestamp_ns: u64,
         max_timestamp_ns: u64,
     },
 
+    /// Error on the receipt side
     #[error("Receipt error: {0}")]
     ReceiptError(#[from] ReceiptError),
 
+
+    /// Error when the recovered signer address is invalid
+    /// Used by [`crate::manager::adapters::EscrowHandler`]
+    #[error("Recovered sender address invalid {address}")]
+    InvalidRecoveredSigner { address: Address },
+
+    /// Indicates a failure while verifying the signer
+    /// Used by [`crate::manager::adapters::EscrowHandler`]
     #[error("Failed to check the signer: {0}")]
     FailedToVerifySigner(String),
 }

tap_core/src/lib.rs

@@ -1,10 +1,74 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-//! The Timeline Aggregation Protocol (TAP) is a micro-trust
-//! state channel payment solution allowing one-way payments
-//! from a payment sender to be aggregated then cheaply
-//! verified on-chain by a payment receiver.
+
+//! # Timeline Aggregation Protocol
+//!
+//! ## Overview
+//!
+//! The TAP (Timeline Aggregation Protocol) facilitates a series of payments from
+//! a sender to a receiver, who aggregates these payments into a single payment.
+//! This aggregate payment can then be verified on-chain by a payment verifier,
+//! reducing the number of transactions and simplifying the payment process.
+//!
+//! ## Key Components
+//!
+//! - **Sender:** Initiates the payment.
+//! - **Receiver:** Receives the payment.
+//! - **Signers:** Multiple signers authorized by the sender to sign receipts.
+//! - **State Channel:** A one-way channel opened by the sender with the receiver
+//! for sending receipts.
+//! - **Receipt:** A record of payment sent by the sender to the receiver.
+//! - **ReceiptAggregateVoucher (RAV):** A signed message containing the aggregate
+//! value of the receipts.
+//! - **tap_aggregator:** An entity managed by the sender that signs RAV requests.
+//! - **EscrowAccount:** An account created in the blockchain to hold funds for
+//! the sender-receiver pair.
+//!
+//! ## Security Measures
+//!
+//! - The protocol uses asymmetric cryptography to sign and verify messages,
+//! ensuring the integrity of receipts and RAVs.
+//!
+//! ## Process
+//!
+//! 1. **Opening a State Channel:** A state channel is opened via a blockchain
+//! contract, creating an EscrowAccount for the sender-receiver pair.
+//! 2. **Sending Receipts:** The sender sends receipts to the receiver through
+//! the state channel.
+//! 3. **Storing Receipts:** The receiver stores the receipts and tracks the
+//! aggregate payment.
+//! 4. **Creating a RAV Request:** A RAV request consists of a list of receipts
+//! and, optionally, the previous RAV.
+//! 5. **Signing the RAV:** The receiver sends the RAV request to the
+//! tap_aggregator, which signs it into a RAV.
+//! 6. **Tracking Aggregate Value:** The receiver tracks the aggregate value and
+//! new receipts since the last RAV.
+//! 7. **Requesting a New RAV:** The receiver sends new receipts and the last
+//! RAV to the tap_aggregator for a new RAV.
+//! 8. **Closing the State Channel:** When the allocation period ends, the receiver
+//! can send the last RAV to the blockchain and receive payment from the EscrowAccount.
+//!
+//! ## Performance Considerations
+//!
+//! - The primary performance limitations are the time required to verify receipts
+//! and network limitations for sending requests to the tap_aggregator.
+//!
+//! ## Use Cases
+//!
+//! - The TAP protocol is suitable for systems with sequential operations that
+//! are too expensive to redeem individually on-chain. By aggregating operations
+//! and redeeming them in one transaction, costs can be reduced.
+//!
+//! ## Compatibility
+//!
+//! - The current implementation is for EVM-compatible blockchains, with most
+//! of the system being off-chain.
+//!
+//! ## Getting started
+//!
+//! To get started with the TAP protocol, take a look on the [`manager`] module
+//! to see how to manage the state channel and implement the needed adapters.
 
 use std::time::{SystemTime, UNIX_EPOCH};
 
@@ -17,7 +81,8 @@ pub mod rav;
 pub mod receipt;
 pub mod signed_message;
 
-pub use error::{Error, Result};
+pub use error::Error;
+use error::Result;
 
 fn get_current_timestamp_u64_ns() -> Result<u64> {
     Ok(SystemTime::now()
@@ -28,6 +93,21 @@ fn get_current_timestamp_u64_ns() -> Result<u64> {
         .as_nanos() as u64)
 }
 
+/// The EIP712 domain separator builder for the TAP protocol.
+///
+/// This is the current domain separator that is used for the [EIP712](https://eips.ethereum.org/EIPS/eip-712) signature scheme.
+///
+///
+/// It's used to validate the signature of the `ReceiptAggregateVoucher` and `Receipt` structs.
+///
+/// You can take a look on deployed [TAPVerfiers](https://github.com/semiotic-ai/timeline-aggregation-protocol-contracts/blob/4dc87fc616680c924b99dbaf285bdd449c777261/src/TAPVerifier.sol)
+/// contracts [here](https://github.com/semiotic-ai/timeline-aggregation-protocol-contracts/blob/4dc87fc616680c924b99dbaf285bdd449c777261/addresses.json)
+///
+/// The domain separator is defined as:
+/// - `name`: "TAP"
+/// - `version`: "1"
+/// - `chain_id`: The chain ID of the chain where the domain separator is deployed.
+/// - `verifying_contract`: The address of the contract that is verifying the signature.
 pub fn tap_eip712_domain(
     chain_id: u64,
     verifying_contract_address: alloy_primitives::Address,

tap_core/src/manager/adapters/escrow.rs

@@ -7,33 +7,15 @@ use async_trait::async_trait;
 
 use crate::{
     rav::SignedRAV,
-    receipt::{AwaitingReserve, ReceiptError, ReceiptResult, ReceiptWithState},
+    receipt::{state::AwaitingReserve, ReceiptError, ReceiptResult, ReceiptWithState},
     Error,
 };
 
-/// `EscrowAdapter` defines a trait for adapters to handle escrow related operations.
-///
-/// This trait is designed to be implemented by users of this library who want to
-/// customize the management of local accounting for available escrow. The error handling is also
-/// customizable by defining an `AdapterError` type, which must implement both `Error`
-/// and `Debug` from the standard library.
-///
-/// # Usage
-///
-/// The `get_available_escrow` method should be used to retrieve the local accounting
-///  amount of available escrow for a specified sender. Any errors during this operation
-/// should be captured and returned in the `AdapterError` format.
-///
-/// The `subtract_escrow` method is used to deduct a specified value from the local accounting
-/// of available escrow of a specified sender. Any errors during this operation should be captured
-/// and returned as an `AdapterError`.
-///
-/// This trait is utilized by [crate::tap_manager], which relies on these
-/// operations for managing escrow.
+/// Manages the escrow operations
 ///
 /// # Example
 ///
-/// For example code see [crate::adapters::escrow_adapter_mock]
+/// For example code see [crate::manager::context::memory::EscrowStorage]
 
 #[async_trait]
 pub trait EscrowHandler: Send + Sync {
@@ -44,25 +26,21 @@ pub trait EscrowHandler: Send + Sync {
     type AdapterError: std::error::Error + std::fmt::Debug + Send + Sync + 'static;
 
     /// Retrieves the local accounting amount of available escrow for a specified sender.
-    ///
-    /// This method should be implemented to fetch the local accounting amount of available escrow for a
-    /// specified sender from your system. Any errors that occur during this process should
-    /// be captured and returned as an `AdapterError`.
     async fn get_available_escrow(&self, sender_id: Address) -> Result<u128, Self::AdapterError>;
 
     /// Deducts a specified value from the local accounting of available escrow for a specified sender.
-    ///
-    /// This method should be implemented to deduct a specified value from the local accounting of
-    /// available escrow of a specified sender in your system. Any errors that occur during this
-    /// process should be captured and returned as an `AdapterError`.
     async fn subtract_escrow(
         &self,
         sender_id: Address,
         value: u128,
     ) -> Result<(), Self::AdapterError>;
 
+    /// Verifies the signer of the receipt
+    ///
+    /// Used by [`Self::check_rav_signature`] to verify the signer of the receipt
     async fn verify_signer(&self, signer_address: Address) -> Result<bool, Self::AdapterError>;
 
+    /// Checks and reserves escrow for the received receipt
     async fn check_and_reserve_escrow(
         &self,
         received_receipt: &ReceiptWithState<AwaitingReserve>,
@@ -87,6 +65,7 @@ pub trait EscrowHandler: Send + Sync {
         Ok(())
     }
 
+    /// Checks the signature of the RAV
     async fn check_rav_signature(
         &self,
         signed_rav: &SignedRAV,

tap_core/src/manager/adapters/mod.rs

@@ -1,19 +1,11 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-//! The adapters module provides interfaces that allow flexibility in storing and verifying TAP components.
+//! Context adapters for the TAP manager.
 //!
 //! Each adapter should be defined by the user of the library based on their specific storage and verification requirements. This modular design
 //! allows for easy integration with various storage solutions and verification procedures, thereby making the library adaptable to a wide range
 //! of use cases.
-//!
-//! The following adapters are defined:
-//! - `escrow_adapter`: An interface for checking and updating escrow availability.
-//! - `rav_storage_adapter`: An interface for storing and retrieving/replacing RAVs.
-//! - `receipt_checks_adapter`: An interface for verifying TAP receipts.
-//! - `receipt_storage_adapter`: An interface for storing, retrieving, updating, and removing TAP receipts.
-//!
-//! In addition, this module also includes mock implementations of each adapter for testing and example purposes.
 
 mod escrow;
 mod rav;