Storage

utxo/docs/65cdd331-aa64-48bf-9224-0e1e13c68e41.md

@@ -0,0 +1,91 @@
+# Verax
+
+## Theory
+
+Verax's data model is heavily inspired by Bitcoin's model. It is a data model where transactions are primarily by a set of `payments` that are going to be spend, and a set of new `payments` to be created.
+
+Each `payment` is a data structure with this information
+
+```
+struct Payment {
+  created_by_transaction: TransactionId,
+	amount: Amount,
+	destination: Address,
+	spend_by: Option<TransactionId>
+}
+```
+
+Any `payment` that has `spend_by: None` is part of the active balance of each address. Any other payment is not longer part of the active balance, but part of the historial record. These spent payments are read-only from that point forward.
+
+Every `payment` is created from a transaction, no exception.
+
+### Transactions
+
+```mermaid
+flowchart LR
+    UserA --> |1000 USD| B{Transfer}
+    B --> |1000 USD| UserB
+```
+
+After this simple transction, `UserA` cannot longer spend their `1000 USD` and balance, and `UserB` can spend `1000 USD` more.
+
+This data model does not care how many payments are being spend or created, as long as the amounts are the same on both ends.
+
+In the following example UserA transfer `1000 USD` to `UserB`, but `1 USD` is deducted from the transfer by the system and that is being transfer to the `FeeManager` account.
+
+```mermaid
+flowchart LR
+    UserA --> |1000 USD| B{Transfer}
+    B --> |999 USD| UserB
+    B --> |1 USD| FeeManager
+```
+
+### Multi-step transactions
+
+As mentioned before, the transaction can spend multiple payments and can create multiple as well. As long as the amounts are equal on both ends (in this case `1000 USD, 980 EUR` is equal to `999USD + 1 USD, 979EUR + 1EUR`), the transaction will be valid.
+
+```mermaid
+flowchart LR
+    UserA' --> |1000 USD| B{Transfer}
+    UserB' --> |980 EUR| B
+    B --> |999 USD| UserB
+    B --> |979 EUR| UserA
+    B --> |1 USD| FeeManager
+    B --> |1 EUR| FeeManager
+```
+
+When the transaction will be attempted to be persisted, the storage layer will make sure to flag `UserA'` and `UserB'` payments. If that operation fails, the whole transaction creation fails.
+
+## Concurrency model
+
+Because Verax is heavily inspired in Bitcoin's model, the concurrency model is quite simple. When a new transaction is commited into the database, each payment in `input` section is attempted to be spent (altering their `spend_by` field from `None` to `Some(new_transaction_id)`). If any `payment is already spent, or not valid, the whole transaction creation fails and a rollback is issued upper stream. The storage layer ensures that transaction creation and updates are atomic and updates.
+
+```mermaid
+sequenceDiagram
+    Transaction->>+ DB: 
+    critical Spend each input
+        loop Spend Inputs
+            Transaction ->>+ DB: Spend input
+            DB ->>+ Transaction: OK
+        end 
+        DB ->>+  Transaction: OK
+        loop Output
+            Transaction ->>+ DB: Creates new output
+        end
+    option Success
+        Transaction ->>+ DB: Commit
+        DB ->>+  Transaction: OK
+    option Failure
+        DB ->>- Transaction: Error
+        Transaction ->>+ DB: Rollback
+    end
+    
+ 
+```
+
+Because of the `input` and `output` model, there is no need to check if the account has enough balance, and there is no need to enforce any locking mechanism, as long as each selected `payment` can be spendable at transaction storing time, the transaction will be created atomically. Each payment in the `inputs` must spendable, or else the whole operation fails, because every update is atomic, ensured by the storage layer.
+
+The conditions for a payment ot be spendable are:
+
+* It must be unspent: Payments are spendable once.
+* It must be finalized: This means that the transaction which created this new `payment` is settled. Any other state is not acceptable and will render this payment not usable.

utxo/src/storage.rs

@@ -436,23 +436,67 @@ pub mod test {
         T: Storage<'a, B>,
         B: Batch<'a>,
     {
-        let account: AccountId = "alice".parse().expect("account");
+        let account1: AccountId = "alice1".parse().expect("account");
+        let account2: AccountId = "alice2".parse().expect("account");
+        let account3: AccountId = "alice3".parse().expect("account");
         let deposit = Transaction::new_external_deposit(
             "test reference".to_owned(),
             Status::Settled,
             vec![(
-                account.clone(),
+                account1.clone(),
                 assets
                     .human_amount_by_name("USD", "100.99")
                     .expect("valid amount"),
             )],
         )
         .expect("valid tx");
-        let mut storing = storage.begin().await.expect("valid tx");
-        storing.store_transaction(&deposit).await;
-        storing
-            .relate_account_to_transaction(&deposit, &account)
+
+        let mut batch = storage.begin().await.expect("valid tx");
+        batch.store_transaction(&deposit).await;
+        batch
+            .relate_account_to_transaction(&deposit, &account1)
             .await
             .expect("relationship");
+        batch
+            .relate_account_to_transaction(&deposit, &account2)
+            .await
+            .expect("relationship");
+
+        batch.commit().await.expect("valid commit");
+
+        assert_eq!(
+            1,
+            storage
+                .get_transactions(&account1, vec![Type::Deposit])
+                .await
+                .expect("valid tx")
+                .len()
+        );
+        assert_eq!(
+            1,
+            storage
+                .get_transactions(&account2, vec![Type::Deposit])
+                .await
+                .expect("valid tx")
+                .len()
+        );
+        assert_eq!(
+            0,
+            storage
+                .get_transactions(&account3, vec![Type::Deposit])
+                .await
+                .expect("valid tx")
+                .len()
+        );
+        for account in &[account1, account2, account3] {
+            assert_eq!(
+                0,
+                storage
+                    .get_transactions(&account, vec![Type::Withdrawal])
+                    .await
+                    .expect("valid tx")
+                    .len()
+            );
+        }
     }
 }

utxo/src/transaction/typ.rs

@@ -16,7 +16,7 @@ pub enum Type {
     Withdrawal,
     /// Transaction
     Transaction,
-    /// Internal / Exchange Transactiojn
+    /// Internal / Exchange Transaction
     Exchange,
 }