Merge pull request #217 from semiotic-ai/gusinacio/documentation

docs!: create docs and readme.

Author: gusinacio

README.md

@@ -1 +1,71 @@
 # Timeline Aggregation Protocol (TAP)
+
+## Overview
+
+The TAP (Timeline Aggregation Protocol) facilitates a series of payments from a 
+sender to a receiver (TAP Receipts), who aggregates these payments into a single 
+payment (a Receipt Aggregate Voucher, or RAV). 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:** A service managed by the sender that aggregates receipts 
+on the receiver's request into a signed RAV.
+- **EscrowAccount:** An account created in the blockchain to hold funds for 
+the sender-receiver pair.
+
+## Security Measures
+
+- The protocol uses asymmetric cryptography (ECDSA secp256k1) 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 new 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 that need unidirectional, parallel 
+micro-payments that are too expensive to redeem individually on-chain. By 
+aggregating operations off-chain and redeeming them in one transaction, costs 
+are drastically 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](https://github.com/semiotic-ai/timeline-aggregation-protocol/blob/main/CONTRIBUTING.md).

tap_core/src/error.rs

@@ -11,54 +11,73 @@ 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,10 @@
 // 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.
+#![doc = include_str!("../../README.md")]
+//! ## 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 +17,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 +29,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,62 +7,41 @@ 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 {
     /// Defines the user-specified error type.
     ///
-    /// This error type should implement the `Error` and `Debug` traits from the standard library.
+    /// This error type should implement the `Error` and `Debug` traits from
+    /// the standard library.
     /// Errors of this type are returned to the user when an operation fails.
     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 +66,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,12 @@
 // 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.
+//! 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.
 
 mod escrow;
 mod rav;

tap_core/src/manager/adapters/rav.rs

@@ -5,73 +5,46 @@ use async_trait::async_trait;
 
 use crate::rav::SignedRAV;
 
-/// `RAVStore` defines a trait for write storage adapters to handle `SignedRAV` data.
-///
-/// This trait is designed to be implemented by users of this library who want to
-/// customize the write storage behavior of `SignedRAV` data. The error handling is also
-/// customizable by defining an `AdapterError` type, which must implement both `Error`
-/// and `Debug` from the standard library.
-///
-/// # Usage
-///
-/// The `update_last_rav` method should be used to update the last validated `SignedRAV`
-/// in the storage managed by the adapter. Errors during this operation should be
-/// captured and returned in the `AdapterError` format.
-///
-/// This trait is utilized by [crate::tap_manager], which relies on these
-/// operations for working with `SignedRAV` data.
+/// Stores the latest RAV in the storage.
 ///
 /// # Example
 ///
-/// For example code see [crate::adapters::rav_storage_adapter_mock]
+/// For example code see [crate::manager::context::memory::RAVStorage]
 
 #[async_trait]
 pub trait RAVStore {
     /// Defines the user-specified error type.
     ///
-    /// This error type should implement the `Error` and `Debug` traits from the standard library.
+    /// This error type should implement the `Error` and `Debug` traits from
+    /// the standard library.
     /// Errors of this type are returned to the user when an operation fails.
     type AdapterError: std::error::Error + std::fmt::Debug + Send + Sync + 'static;
 
     /// Updates the storage with the latest validated `SignedRAV`.
     ///
-    /// This method should be implemented to store the most recent validated `SignedRAV` into your chosen storage system.
-    /// Any errors that occur during this process should be captured and returned as an `AdapterError`.
+    /// This method should be implemented to store the most recent validated
+    /// `SignedRAV` into your chosen storage system. Any errors that occur
+    /// during this process should be captured and returned as an `AdapterError`.
     async fn update_last_rav(&self, rav: SignedRAV) -> Result<(), Self::AdapterError>;
 }
 
-/// `RAVRead` defines a trait for read storage adapters to handle `SignedRAV` data.
-///
-/// This trait is designed to be implemented by users of this library who want to
-/// customize the read storage behavior of `SignedRAV` data. The error handling is also
-/// customizable by defining an `AdapterError` type, which must implement both `Error`
-/// and `Debug` from the standard library.
-///
-/// # Usage
-///
-/// The `last_rav` method is designed to fetch the latest `SignedRAV` from the storage.
-/// If there is no `SignedRAV` available, it should return `None`. 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 working with `SignedRAV` data.
+/// Reads the RAV from storage
 ///
 /// # Example
 ///
-/// For example code see [crate::adapters::rav_storage_adapter_mock]
+/// For example code see [crate::manager::context::memory::RAVStorage]
 
 #[async_trait]
 pub trait RAVRead {
     /// Defines the user-specified error type.
     ///
-    /// This error type should implement the `Error` and `Debug` traits from the standard library.
+    /// This error type should implement the `Error` and `Debug` traits from
+    /// the standard library.
     /// Errors of this type are returned to the user when an operation fails.
     type AdapterError: std::error::Error + std::fmt::Debug + Send + Sync + 'static;
 
     /// Retrieves the latest `SignedRAV` from the storage.
     ///
-    /// This method should be implemented to fetch the latest `SignedRAV` from your storage system.
     /// If no `SignedRAV` is available, this method should return `None`.
-    /// Any errors that occur during this process should be captured and returned as an `AdapterError`.
     async fn last_rav(&self) -> Result<Option<SignedRAV>, Self::AdapterError>;
 }