Merge pull request #164 from semiotic-ai/aasseman/issue163

refactor!: Replace "collateral" with "escrow"

Author: aasseman

tap_core/src/adapters/collateral_adapter.rs renamed to tap_core/src/adapters/escrow_adapter.rs

@@ -4,54 +4,51 @@
 use async_trait::async_trait;
 use ethereum_types::Address;
 
-/// `CollateralAdapter` defines a trait for adapters to handle collateral related operations.
+/// `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 collateral. The error handling is also
+/// 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_collateral` method should be used to retrieve the local accounting
-///  amount of available collateral for a specified gateway. Any errors during this operation
+/// The `get_available_escrow` method should be used to retrieve the local accounting
+///  amount of available escrow for a specified gateway. Any errors during this operation
 /// should be captured and returned in the `AdapterError` format.
 ///
-/// The `subtract_collateral` method is used to deduct a specified value from the local accounting
-/// of available collateral of a specified gateway. Any errors during this operation should be captured
+/// The `subtract_escrow` method is used to deduct a specified value from the local accounting
+/// of available escrow of a specified gateway. 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 collateral.
+/// operations for managing escrow.
 ///
 /// # Example
 ///
-/// For example code see [crate::adapters::collateral_adapter_mock]
+/// For example code see [crate::adapters::escrow_adapter_mock]
 
 #[async_trait]
-pub trait CollateralAdapter {
+pub trait EscrowAdapter {
     /// Defines the user-specified error type.
     ///
     /// 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 collateral for a specified gateway.
+    /// Retrieves the local accounting amount of available escrow for a specified gateway.
     ///
-    /// This method should be implemented to fetch the local accounting amount of available collateral for a
+    /// This method should be implemented to fetch the local accounting amount of available escrow for a
     /// specified gateway from your system. Any errors that occur during this process should
     /// be captured and returned as an `AdapterError`.
-    async fn get_available_collateral(
-        &self,
-        gateway_id: Address,
-    ) -> Result<u128, Self::AdapterError>;
+    async fn get_available_escrow(&self, gateway_id: Address) -> Result<u128, Self::AdapterError>;
 
-    /// Deducts a specified value from the local accounting of available collateral for a specified gateway.
+    /// Deducts a specified value from the local accounting of available escrow for a specified gateway.
     ///
     /// This method should be implemented to deduct a specified value from the local accounting of
-    /// available collateral of a specified gateway in your system. Any errors that occur during this
+    /// available escrow of a specified gateway in your system. Any errors that occur during this
     /// process should be captured and returned as an `AdapterError`.
-    async fn subtract_collateral(
+    async fn subtract_escrow(
         &self,
         gateway_id: Address,
         value: u128,

tap_core/src/adapters/mod.rs

@@ -8,21 +8,21 @@
 //! of use cases.
 //!
 //! The following adapters are defined:
-//! - `collateral_adapter`: An interface for checking and updating collateral availability.
+//! - `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.
 
-pub mod collateral_adapter;
+pub mod escrow_adapter;
 pub mod rav_storage_adapter;
 pub mod receipt_checks_adapter;
 pub mod receipt_storage_adapter;
 
 mod test;
 
-pub use test::collateral_adapter_mock;
+pub use test::escrow_adapter_mock;
 pub use test::rav_storage_adapter_mock;
 pub use test::receipt_checks_adapter_mock;
 pub use test::receipt_storage_adapter_mock;

tap_core/src/adapters/test/collateral_adapter_mock.rs

@@ -0,0 +1,83 @@
+// Copyright 2023-, Semiotic AI, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+use std::{collections::HashMap, sync::Arc};
+
+use async_trait::async_trait;
+use ethereum_types::Address;
+use tokio::sync::RwLock;
+
+use crate::adapters::escrow_adapter::EscrowAdapter;
+
+pub struct EscrowAdapterMock {
+    gateway_escrow_storage: Arc<RwLock<HashMap<Address, u128>>>,
+}
+
+use thiserror::Error;
+#[derive(Debug, Error)]
+pub enum AdpaterErrorMock {
+    #[error("something went wrong: {error}")]
+    AdapterError { error: String },
+}
+
+impl EscrowAdapterMock {
+    pub fn new(gateway_escrow_storage: Arc<RwLock<HashMap<Address, u128>>>) -> Self {
+        EscrowAdapterMock {
+            gateway_escrow_storage,
+        }
+    }
+    pub async fn escrow(&self, gateway_id: Address) -> Result<u128, AdpaterErrorMock> {
+        let gateway_escrow_storage = self.gateway_escrow_storage.read().await;
+        if let Some(escrow) = gateway_escrow_storage.get(&gateway_id) {
+            return Ok(*escrow);
+        }
+        Err(AdpaterErrorMock::AdapterError {
+            error: "No escrow exists for provided gateway ID.".to_owned(),
+        })
+    }
+
+    pub async fn increase_escrow(&mut self, gateway_id: Address, value: u128) {
+        let mut gateway_escrow_storage = self.gateway_escrow_storage.write().await;
+
+        if let Some(current_value) = gateway_escrow_storage.get(&gateway_id) {
+            let mut gateway_escrow_storage = self.gateway_escrow_storage.write().await;
+            gateway_escrow_storage.insert(gateway_id, current_value + value);
+        } else {
+            gateway_escrow_storage.insert(gateway_id, value);
+        }
+    }
+
+    pub async fn reduce_escrow(
+        &self,
+        gateway_id: Address,
+        value: u128,
+    ) -> Result<(), AdpaterErrorMock> {
+        let mut gateway_escrow_storage = self.gateway_escrow_storage.write().await;
+
+        if let Some(current_value) = gateway_escrow_storage.get(&gateway_id) {
+            let checked_new_value = current_value.checked_sub(value);
+            if let Some(new_value) = checked_new_value {
+                gateway_escrow_storage.insert(gateway_id, new_value);
+                return Ok(());
+            }
+        }
+        Err(AdpaterErrorMock::AdapterError {
+            error: "Provided value is greater than existing escrow.".to_owned(),
+        })
+    }
+}
+
+#[async_trait]
+impl EscrowAdapter for EscrowAdapterMock {
+    type AdapterError = AdpaterErrorMock;
+    async fn get_available_escrow(&self, gateway_id: Address) -> Result<u128, Self::AdapterError> {
+        self.escrow(gateway_id).await
+    }
+    async fn subtract_escrow(
+        &self,
+        gateway_id: Address,
+        value: u128,
+    ) -> Result<(), Self::AdapterError> {
+        self.reduce_escrow(gateway_id, value).await
+    }
+}

tap_core/src/adapters/test/escrow_adapter_mock.rs

@@ -2,22 +2,20 @@
 // SPDX-License-Identifier: Apache-2.0
 
 #[cfg(test)]
-mod collateral_adapter_unit_test {
+mod escrow_adapter_unit_test {
     use std::{collections::HashMap, sync::Arc};
 
     use ethers::signers::{coins_bip39::English, LocalWallet, MnemonicBuilder, Signer};
     use rstest::*;
     use tokio::sync::RwLock;
 
-    use crate::adapters::{
-        collateral_adapter::CollateralAdapter, collateral_adapter_mock::CollateralAdapterMock,
-    };
+    use crate::adapters::{escrow_adapter::EscrowAdapter, escrow_adapter_mock::EscrowAdapterMock};
 
     #[rstest]
     #[tokio::test]
-    async fn collateral_adapter_test() {
-        let collateral_storage = Arc::new(RwLock::new(HashMap::new()));
-        let mut collateral_adapter = CollateralAdapterMock::new(collateral_storage);
+    async fn escrow_adapter_test() {
+        let escrow_storage = Arc::new(RwLock::new(HashMap::new()));
+        let mut escrow_adapter = EscrowAdapterMock::new(escrow_storage);
 
         let wallet: LocalWallet = MnemonicBuilder::<English>::default()
          .phrase("abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about")
@@ -35,49 +33,49 @@ mod collateral_adapter_unit_test {
 
         let initial_value = 500u128;
 
-        collateral_adapter
-            .increase_collateral(gateway_id, initial_value)
+        escrow_adapter
+            .increase_escrow(gateway_id, initial_value)
             .await;
 
         // Check that gateway exists and has valid value through adapter
-        assert!(collateral_adapter
-            .get_available_collateral(gateway_id)
+        assert!(escrow_adapter
+            .get_available_escrow(gateway_id)
             .await
             .is_ok());
         assert_eq!(
-            collateral_adapter
-                .get_available_collateral(gateway_id)
+            escrow_adapter
+                .get_available_escrow(gateway_id)
                 .await
                 .unwrap(),
             initial_value
         );
 
         // Check that subtracting is valid for valid gateway, and results in expected value
-        assert!(collateral_adapter
-            .subtract_collateral(gateway_id, initial_value)
+        assert!(escrow_adapter
+            .subtract_escrow(gateway_id, initial_value)
             .await
             .is_ok());
-        assert!(collateral_adapter
-            .get_available_collateral(gateway_id)
+        assert!(escrow_adapter
+            .get_available_escrow(gateway_id)
             .await
             .is_ok());
         assert_eq!(
-            collateral_adapter
-                .get_available_collateral(gateway_id)
+            escrow_adapter
+                .get_available_escrow(gateway_id)
                 .await
                 .unwrap(),
             0
         );
 
-        // Check that subtracting to negative collateral results in err
-        assert!(collateral_adapter
-            .subtract_collateral(gateway_id, initial_value)
+        // Check that subtracting to negative escrow results in err
+        assert!(escrow_adapter
+            .subtract_escrow(gateway_id, initial_value)
             .await
             .is_err());
 
         // Check that accessing non initialized gateway results in err
-        assert!(collateral_adapter
-            .get_available_collateral(invalid_gateway_id)
+        assert!(escrow_adapter
+            .get_available_escrow(invalid_gateway_id)
             .await
             .is_err());
     }

tap_core/src/adapters/test/collateral_adapter_test.rs renamed to tap_core/src/adapters/test/escrow_adapter_test.rs

@@ -1,12 +1,12 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-pub mod collateral_adapter_test;
+pub mod escrow_adapter_test;
 pub mod rav_storage_adapter_test;
 pub mod receipt_checks_adapter_test;
 pub mod receipt_storage_adapter_test;
 
-pub mod collateral_adapter_mock;
+pub mod escrow_adapter_mock;
 pub mod rav_storage_adapter_mock;
 pub mod receipt_checks_adapter_mock;
 pub mod receipt_storage_adapter_mock;