[taler-docs] branch master updated: merging deposit confirmations and other small fixes

[gnunet]

This is an automated email from the git hooks/post-receive script.

nic-eigel pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new c699abab merging deposit confirmations and other small fixes
c699abab is described below

commit c699ababe7f5876788f8c4d1d6f8ede2238aa92c
Author: Nic <nic@eigel.ch>
AuthorDate: Wed Jan 10 23:44:04 2024 +0100

    merging deposit confirmations and other small fixes
---
 core/api-auditor.rst | 269 +++++++++++++--------------------------------------
 1 file changed, 67 insertions(+), 202 deletions(-)

diff --git a/core/api-auditor.rst b/core/api-auditor.rst
index 117e1c78..3d465ed3 100644
--- a/core/api-auditor.rst
+++ b/core/api-auditor.rst
@@ -139,184 +139,12 @@ This API is used by auditor to obtain a list of all 
exchanges signing keys to be
     This API is still experimental (and is not yet implemented at the
     time of this writing).
 
-.. _purses-list:
-
------------------------
-Obtaining Purses List
------------------------
-
-This API is used by auditor to obtain a list of all the purses and their 
respective balances that the auditor is aware of.
-
-.. http:get:: /purses
-
-  Get a list of all purses and their respective balances known by the auditor.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The auditor responds with a :ts:type:`PursesList` object.
-
-  :http:statuscode:`204 No content`:
-    No purses found.
-
-  **Details:**
-
-  .. ts:def:: PursesList
-
-    interface PursesList {
-      // Purse known by the auditor.
-      purse: PurseEntry[];
-    }
-
-  .. ts:def:: PurseEntry
-
-    interface PurseEntry {
-
-      // Public online signing key of the exchange.
-      purse_pub: EddsaPublicKey;
-
-         // Time when online signing key will first be use.
-      balance: taler_amount;
-
-         // Time when this online signing key will no longer be used.
-      target: taler_amount;
-
-         // Time when this online signing key legally expires.
-      expiration_date: Timestamp;
-    }
-
-  .. note::
-
-    This API is still experimental (and is not yet implemented at the
-    time of this writing).
-
-.. _purses-list:
-
------------------------
-Obtaining Reserves List
------------------------
-
-This API is used by auditor to obtain a list of all the customer reserves and 
their respective balances that the auditor is aware of.
-
-.. http:get:: /reserves
-
-  Get a list of all the reserves and their respective balances known by the 
auditor.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The auditor responds with a :ts:type:`ReservesList` object.
-
-  :http:statuscode:`204 No content`:
-    No reserves found.
-
-  **Details:**
-
-  .. ts:def:: ReservesList
-
-    interface ReservesList {
-      // Reserve known by the auditor.
-      reserve: ReserveEntry[];
-    }
-
-  .. ts:def:: ReserveEntry
-
-    interface ReserveEntry {
-
-      // Public online signing key of the reserve
-      reserve_pub: EddsaPublicKey;
-
-         // Balance of respective reserve.
-      reserve_balance: taler_amount;
-
-         // Loss of respective reserve.
-      reserve_loss: taler_amount;
-
-         // Withdraw fee balance.
-      withdraw_fee_balance: taler_amount;
-
-         // Closing fee balance.
-      close_fee_balance: taler_amount;
-
-         // Purse fee balance.
-      purse_fee_balance: taler_amount;
-
-         // Open fee balance.
-      open_fee_balance: taler_amount;
-
-         // Time when this online signing key will no longer be used.
-      history_fee_balance: taler_amount;
-
-         // Time when this reserve expires.
-      expiration_date: Timestamp;
-    }
-
-  .. note::
-
-    This API is still experimental (and is not yet implemented at the
-    time of this writing).
-
-.. deposit-confirmation-list:
+.. _deposit-confirmation:
 
 -----------------------
-Obtaining list of deposit confirmations to check
+Deposit Confirmations
 -----------------------
 
-This API is used by the auditor to obtain a list of all deposit confirmations 
that need to be audited by
-this auditor.
-
-.. http:get:: /deposit-confirmation
-
-  Get a list of all deposit confirmations to be manually audited.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The auditor responds with a :ts:type:`DepositConfirmationList` object. 
This request should
-    virtually always be successful.
-
-  **Details:**
-
-  .. ts:def:: DepositConfirmationList
-
-    interface DepositConfirmationList {
-      // Deposit confirmations to be audited.
-      deposit-confirmations: DepositConfirmation[];
-    }
-
-  .. ts:def:: DepositConfirmation
-
-    interface DepositConfirmation {
-
-         // Database row id of entry
-         row_id: Integer;
-
-      // Time when the deposit confirmation confirmation was generated.
-      timestamp: Timestamp;
-
-      // How much time does the merchant have to issue a refund
-      // request?  Zero if refunds are not allowed.
-      refund_deadline: Timestamp;
-
-      // By what time does the exchange have to wire the funds?
-      wire_deadline: Timestamp;
-
-      // Amount to be deposited, excluding fee.  Calculated from the
-      // amount with fee and the fee from the deposit request.
-      amount_without_fee: Amount;
-    }
-
-  .. note::
-
-    This API is still experimental (and is not yet implemented at the
-    time of this writing).
-
-.. _deposit-confirmation:
-
---------------------------------
-Submitting deposit confirmations
---------------------------------
-
 Merchants should probabilistically submit some of the deposit
 confirmations they receive from the exchange to auditors to ensure
 that the exchange does not lie about recording deposit confirmations
@@ -418,17 +246,61 @@ paid out first.
     time of this writing). A key open question is whether the auditor
     should sign the response information.
 
-.. delete-deposit-confirmation:
+This API is used by the auditor to obtain a list of all deposit confirmations 
that the auditor
+did not receive by the exchange, only by the merchant.
 
------------------------
-Delete audited deposit confirmation
------------------------
+.. http:get:: /deposit-confirmation
+
+  Get a list of all deposit confirmations that were not received by the 
auditor from the exchange to be manually audited.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The auditor responds with a :ts:type:`DepositConfirmationList` object.
+  :http:statuscode:`204 No Content`:
+    No missing deposit confirmations found.
+
+  **Details:**
+
+  .. ts:def:: DepositConfirmationList
+
+    interface DepositConfirmationList {
+      // Deposit confirmations to be audited.
+      deposit-confirmations: DepositConfirmation[];
+    }
+
+  .. ts:def:: DepositConfirmation
+
+    interface DepositConfirmation {
+
+         // Database row id of entry
+         row_id: Integer;
+
+      // Time when the deposit confirmation confirmation was generated.
+      timestamp: Timestamp;
+
+      // How much time does the merchant have to issue a refund
+      // request?  Zero if refunds are not allowed.
+      refund_deadline: Timestamp;
+
+      // By what time does the exchange have to wire the funds?
+      wire_deadline: Timestamp;
+
+      // Amount to be deposited, excluding fee.  Calculated from the
+      // amount with fee and the fee from the deposit request.
+      amount_without_fee: Amount;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing).
 
 This API is used by the auditor to delete an audited deposit confirmation.
 
-.. http:delete:: /deposit-confirmation/$rowid
+.. http:delete:: /deposit-confirmation/$SERIAL_ID
 
-  Delete deposit confirmation entry with given row id.
+  Delete deposit confirmation entry with given serial_id.
 
   **Response:**
 
@@ -439,10 +311,7 @@ This API is used by the auditor to delete an audited 
deposit confirmation.
     Unauthorized request.
 
   :http:statuscode:`404 Not found`:
-    The deposit confirmation was already unknown.
-
-  :http:statuscode:`409 Conflict`:
-  The deposit confirmation cannot be deleted anymore.
+    The deposit confirmation was unknown.
 
   .. note::
 
@@ -452,45 +321,41 @@ This API is used by the auditor to delete an audited 
deposit confirmation.
 .. balances-list:
 
 -----------------------
-Obtaining list of auditor balances to check
+Obtaining list of auditor balances
 -----------------------
 
-This API is used by the auditor to obtain a list of all balances that need to 
be audited by
-this auditor.
+This API is used to obtain a list of all the balances that are stored by the 
auditor.
 
 .. http:get:: /balances
 
-  Get a list of all auditor balances.
+  Get a list of all balances stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The auditor responds with a :ts:type:`BalanceList` object. This request 
should
-    virtually always be successful.
+    The auditor responds with a :ts:type:`BalanceList` object.
+
+  :http:statuscode:`409 Conflict`:
+    Balance missing or other error occured.
 
   **Details:**
 
-  .. ts:def:: BalanceList
+  .. ts:def:: Balances
 
     interface BalanceList {
-      // Balances of the auditor.
-      balance: Balance[];
-    }
-
-  .. ts:def:: Balance
+      // Total amount reported
+      auditor_total_reported_balance: taler_amount;
 
-    interface Balance {
-         // By what time does the exchange have to wire the funds?
-      balance_key: string;
+      // Amount potentially missing
+      auditor_missing_balance: taler_amount;
 
-      // amount with fee and the fee from the deposit request.
-      balance_value: taler_amount;
+      //...
     }
 
   .. note::
 
     This API is still experimental (and is not yet implemented at the
-    time of this writing).
+    time of this writing). The API will be further developed as needed.
 
 .. denominations-pending-list:
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.