[taler-docs] branch master updated: Donau: charity history, links to taler exchange, first pass on keys, replace int with Integer

[gnunet]

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

pius-loosli pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new aacf89d4 Donau: charity history, links to taler exchange, first pass 
on keys, replace int with Integer
aacf89d4 is described below

commit aacf89d4c3b641eb6a4f5ca261445dd43ab1c4ee
Author: Pius Loosli <loosp2@bfh.ch>
AuthorDate: Tue Oct 10 12:08:57 2023 +0200

    Donau: charity history, links to taler exchange, first pass on keys, 
replace int with Integer
---
 core/api-donau.rst    | 180 ++++++++++++++++----------------------------------
 core/api-exchange.rst |   1 +
 2 files changed, 59 insertions(+), 122 deletions(-)

diff --git a/core/api-donau.rst b/core/api-donau.rst
index b8f33a0e..57a66603 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -155,44 +155,44 @@ should cache.
 
     }
 
-  .. ts:def:: DonauDonationUnitKeyGroup
+  .. ts:def:: DonationUnitKeyGroup
 
-    type DonauDonationUnitKeyGroup =
-      | DonauDonationUnitKeyGroupRsa
-      | DonauDonationUnitKeyGroupCs;
+    type DonationUnitKeyGroup =
+      | DonationUnitKeyGroupRsa
+      | DonationUnitKeyGroupCs;
 
-  .. ts:def:: DonauDonationUnitKeyGroupRsa
+  .. ts:def:: DonationUnitKeyGroupRsa
 
-    interface DonauDonationUnitKeyGroupRsa extends 
DonauDonationUnitKeyGroupCommon {
+    interface DonationUnitKeyGroupRsa extends DonationUnitKeyGroupCommon {
       cipher: "RSA";
 
       denoms: ({
         rsa_pub: RsaPublicKey;
-      } & DonauDonationUnitKeyCommon)[];
+      } & DonationUnitKeyCommon)[];
     }
 
-  .. ts:def:: DonauDonationUnitKeyGroupCs
+  .. ts:def:: DonationUnitKeyGroupCs
 
-    interface DonauDonationUnitKeyGroupCs extends 
DonauDonationUnitKeyGroupCommon {
+    interface DonationUnitKeyGroupCs extends DonationUnitKeyGroupCommon {
       cipher: "CS";
 
       denoms: ({
         cs_pub: Cs25519Point;
-      } & DonauDonationUnitKeyCommon)[];
+      } & DonationUnitKeyCommon)[];
     }
 
-  .. ts:def:: DonauDonationUnitKeyGroupCommon
+  .. ts:def:: DonationUnitKeyGroupCommon
 
-    // Common attributes for all denomination groups
-    interface DonauDonationUnitKeyGroupCommon {
+    // Common attributes for all donation unit groups
+    interface DonationUnitKeyGroupCommon {
       // How much was donated based on this donation receipt.
       value: Amount;
 
     }
 
-  .. ts:def:: DonauDonationUnitKeyCommon
+  .. ts:def:: DonationUnitKeyCommon
 
-    interface DonauDonationUnitKeyCommon {
+    interface DonationUnitKeyCommon {
 
       // For which year is this denomination unit key valid.
       year: Integer;
@@ -204,24 +204,24 @@ should cache.
       lost?: boolean;
     }
 
-  .. ts:def:: DonauDonationUnitKey
+  .. ts:def:: DonationUnitKey
 
-    type DonauDonationUnitKey =
-      | RsaDonauDonationUnitKey
-      | CSDonauDonationUnitKey;
+    type DonationUnitKey =
+      | RsaDonationUnitKey
+      | CSDonationUnitKey;
 
-  .. ts:def:: RsaDonauDonationUnitKey
+  .. ts:def:: RsaDonationUnitKey
 
-    interface RsaDonauDonationUnitKey {
+    interface RsaDonationUnitKey {
       cipher: "RSA";
 
       // RSA public key
       rsa_public_key: RsaPublicKey;
     }
 
-  .. ts:def:: CSDonauDonationUnitKey
+  .. ts:def:: CSDonationUnitKey
 
-    interface CSDonauDonationUnitKey {
+    interface CSDonationUnitKey {
       cipher: "CS";
 
       // Public key of the denomination.
@@ -255,7 +255,7 @@ should cache.
 Issue receipts
 ----------------------------------------
 
-Inspired by Taler's `Withdraw`.
+Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`.
 
 This API is used by the charity to obtain valid, attested donation receipts 
from the donau.
 Use the :ref:`charity GET route<donau_charity_get>` to see the remaining 
donation volume for the current year.
@@ -280,7 +280,7 @@ All incoming `BDID` are recorded under the corresponding 
charity_id by the donau
 
     interface IssueReceiptsRequest {
       charity_signature: EddsaSignature;
-      year: int;
+      year: Integer;
       bdids: BDID[];
     }
 
@@ -323,6 +323,8 @@ All incoming `BDID` are recorded under the corresponding 
charity_id by the donau
 -----------------------------
 Submit receipts (ex Deposit)
 -----------------------------
+Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
+
 
 .. http:POST:: /submit
   
@@ -341,7 +343,7 @@ Submit receipts (ex Deposit)
 
     interface SubmitRequest{
       taxnr_hashed: HashCode;
-      year: int;
+      year: Integer;
       donation_receipts: DonationReceipt[];
     }
 
@@ -419,11 +421,11 @@ Charity administration and status information
   .. ts:def:: Charity
 
     interface Charity{
-      charity_id: int,
+      charity_id: Integer;
       pub_key: RsaPublicKey;
       max_per_year: Amount;
       current_year: Amount; 
-      receipts_to_date: int;
+      receipts_to_date: Integer;
     }
 
 .. _donau_charity_get:
@@ -462,15 +464,27 @@ Charity administration and status information
       pub_key: RsaPublicKey;
       max_per_year: Amount;
       current_year: Amount; 
-      receipts_to_date: int;
+      receipts_to_date: Integer;
     }
 
   .. ts:def:: CharityResponse
 
     interface CharityResponse{
-      id: int;
+      id: Integer;
     }
   
+
+.. http:PATCH:: /charities/{id}
+
+  Modify a charity
+
+  **Request:** `CharityRequest`
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful.
+
 .. http:get:: /charities/$CHARITY_ID/history
 
   Request information about the history of a charity.
@@ -480,108 +494,30 @@ Charity administration and status information
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The Donau responds with a `CharityStatus` object; the charity was known to 
the Donau.
-  :http:statuscode:`403 Forbidden`:
-    The *TALER_SIGNATURE_CHARITY_HISTORY_REQUEST* is invalid.
-    This response comes with a standard `ErrorDetail` response.  
Alternatively, the provided timestamp is not close to the current time.
+    The Donau responds with a `CharityHistory` object; the charity was known 
to the Donau.
+  :http:statuscode:`400 Bad request`:
+    The charity id is malformed.
   :http:statuscode:`404 Not found`:
     The charity key does not belong to a charity known to the donau.
 
   **Details:**
 
-  .. ts:def:: CharityHistoryRequest
-
-    interface CharityHistoryRequest {
-      // Signature of type
-      // ``TALER_SIGNATURE_CHARITY_HISTORY_REQUEST``
-      // over a `TALER_CharityHistoryRequestSignaturePS`.
-      charity_sig: EddsaSignature;
+  .. ts:def:: CharityHistory
 
-      // Time when the client made the request.
-      // Timestamp must be reasonably close to the time of
-      // the donau, otherwise the donau may reject
-      // the request.
-      request_timestamp: Timestamp;
+    interface CharityHistory {
+      charityHistoryYears: CharityHistoryYear[];
+      donau_sig: EddsaSignature;
     }
 
-  .. ts:def:: CharityStatus
-
-    interface CharityStatus {
-      // Balance left in the charity.
-      balance: Amount;
-
-      // If set, gives the maximum age group that the client is required to set
-      // during withdrawal.
-      maximum_age_group: number;
-
-      // Transaction history for this charity.
-      // May be partial (!).
-      history: TransactionHistoryItem[];
-    }
-
-  Objects in the transaction history have the following format:
-
-  .. ts:def:: TransactionHistoryItem
-
-    // Union discriminated by the "type" field.
-    type TransactionHistoryItem =
-      | CharityWithdrawTransaction
-      | CharityCreditTransaction;
-
-  .. ts:def:: CharityWithdrawTransaction
-
-    interface CharityWithdrawTransaction {
-      type: "WITHDRAW";
+  .. ts:def:: CharityHistoryYear
 
-      // Amount withdrawn.
-      amount: Amount;
-
-      // Hash of the denomination public key of the receipt.
-      h_denom_pub: HashCode;
-
-      // Hash of the blinded receipt to be signed.
-      h_receipt_envelope: HashCode;
-
-      // Signature over a `TALER_WithdrawRequestPS`
-      // with purpose ``TALER_SIGNATURE_WALLET_CHARITY_WITHDRAW``
-      // created with the charity's private key.
-      charity_sig: EddsaSignature;
-
-      // Fee that is charged for withdraw.
-      withdraw_fee: Amount;
+    interface CharityHistoryYear {
+      year: Integer;
+      //pub_key: RsaPublicKey;
+      final_amout: Amount;
+      // for statistics
+      max_per_year: Amount;
      }
 
-  .. ts:def:: CharityCreditTransaction
-
-    interface CharityCreditTransaction {
-      type: "CREDIT";
-
-      // Amount deposited.
-      amount: Amount;
-
-      // Sender account ``payto://`` URL.
-      sender_account_url: string;
-
-      // Opaque identifier internal to the donau that
-      // uniquely identifies the wire transfer that credited the charity.
-      wire_reference: Integer;
-
-      // Timestamp of the incoming wire transfer.
-      timestamp: Timestamp;
-    }
-
-
-.. http:PATCH:: /charities/{id}
-  
-  Modify a charity
-
-  **Request:** `CharityRequest`
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `CharityResponse`.
-
-
 
 
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index a2826761..5bdebef0 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1591,6 +1591,7 @@ This part of the API is for the use by auditors 
interacting with the exchange.
 
     }
 
+.. _exchange-withdrawal:
 
 ----------
 Withdrawal

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