[taler-docs] branch master updated: REST API overview & merge

[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 4d36a0fe REST API overview & merge
4d36a0fe is described below

commit 4d36a0fe73ef662738af8d7b8604565b35b1fb49
Author: Pius Loosli <pius.loosli@students.bfh.ch>
AuthorDate: Tue Sep 26 17:33:05 2023 +0200

    REST API overview & merge
---
 core/api-donau.rst | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 197 insertions(+)

diff --git a/core/api-donau.rst b/core/api-donau.rst
index ff7c3475..f4a61ffa 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -82,6 +82,7 @@ should cache.
 
     }
 
+
 .. http:get:: /keys
 
   Get a list of all donation units keys offered by the Donau,
@@ -190,6 +191,10 @@ should cache.
       // How much are receipts of this denomination worth?
       value: Amount;
 
+      // XOR of all the SHA-512 hash values of the denominations' public keys
+      // in this group.  Note that for hashing, the binary format of the
+      // public keys is used, and not their base32 encoding.
+      hash: HashCode;
     }
 
   .. ts:def:: DonauDonationUnitKeyCommon
@@ -506,6 +511,13 @@ donau.
       // Balance left in the charity.
       balance: Amount;
 
+      // If set, age restriction is required to be set for each coin to this
+      // value during the withdrawal from this reserve. The client then MUST
+      // use a denomination with support for age restriction enabled for the
+      // withdrawal.
+      // The value represents a valid age group from the list of permissible
+      // age groups as defined by the donau's output to /keys.
+      maximum_age_group?: number;
     }
 
 
@@ -587,6 +599,8 @@ donau.
       // created with the charity's private key.
       charity_sig: EddsaSignature;
 
+      // Fee that is charged for withdraw.
+      withdraw_fee: Amount;
      }
 
   .. ts:def:: CharityCreditTransaction
@@ -738,6 +752,7 @@ Batch Withdraw
 
     }
 
+
   .. ts:def:: BatchWithdrawResponse
 
     interface BatchWithdrawResponse {
@@ -869,3 +884,185 @@ proof to the seller for the escrow of sufficient fund.
       donau_sig: EddsaSignature;
     }
 
+
+-----
+Design overview
+-----
+
+.. _overview:
+
+.. http:POST:: /batch-sign
+  
+  Deposit BDR (collection) and ask the donau to sign them (used by charities)
+
+  **Request:** `BlindedDonationReceipts`
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `SignedBDRs`.
+
+  **Details:**
+
+  .. ts:def:: BDRsRequest
+
+    interface BlindedDonationRequests {
+
+      blinded_donation_receipts: BlindedDonationReceipt[];
+
+    }
+
+
+  .. ts:def:: SignedBDRs
+
+    interface SignedBDRs {
+
+      blinded_donation_receipts: BlindedDonationReceipt[];
+
+    }
+
+  .. ts:def:: BlindedDonationReceipt
+
+      interface BlindedDonationReceipt{
+        // TODO
+      }
+
+.. http:POST:: /receipts  
+  
+  Send in donation receipts for the past fiscal year, receive signed total 
back.
+
+  **Request:** `ReceiptsRequest`
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `FiscalYearResponse`.
+
+  **Details:**
+  
+  .. ts:def:: ReceiptsRequest
+
+    interface {
+      //TODO
+      taxnr_hashed: HashCode
+      salt: WireSalt
+      year: int;
+      receipts: DonationReceipt[];
+    }
+
+  .. ts:def:: DonationReceipt
+
+    interface DonationReceipt{
+    //TODO
+      amount: Amount;
+      taxnr_hashed: HashCode
+      salt: WireSalt
+      year: int; 
+      donau_sig:
+    }
+
+  .. ts:def:: FiscalYearResponse
+
+    interface FiscalYearResponse{
+      total: Amount;
+      signature: YearTotalSignature
+    }
+
+  .. ts:def:: FiscalYearSignature
+
+      interface YearTotalSignature{
+        // signature over taxnr_hashed, total, year
+        fiscal_year_sig: EddsaSignature;
+      }
+
+.. http:GET::  /charities   
+  
+  return all charities
+
+  **Request:** 
+
+  **Reponse:** 
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `Charities`.  
+
+  **Details:**
+
+  .. ts:def:: Charities
+
+    interface Charities{
+      charities: Charity[];
+    }
+
+  .. ts:def:: Charity
+
+    interface Charity{
+      charity_id: int,
+      pub_key: RsaPublicKey;
+      max_per_year: Amount;
+      current_year: Amount; 
+      receipts_to_date: int;
+    }
+
+.. http:GET::  /charities/{id}
+  
+  return a charity
+
+
+.. http:POST:: /charities
+
+  Add a charity
+
+  **Request:** `CharityRequest`
+
+  **Response:**
+
+  **Details:**
+
+  :http:statuscode:`201 Created`:
+    The request was successful, and the response is a `CharityResponse`.
+
+  .. ts:def:: CharityRequest
+  
+    interface CharityRequest{
+      pub_key: RsaPublicKey;
+      max_per_year: Amount;
+      current_year: Amount; 
+      receipts_to_date: int;
+    }
+
+  .. ts:def:: CharityResponse
+
+    interface CharityResponse{
+      id: int;
+    }
+  
+.. http:PUT:: /charities/{id}
+  
+  Modify a charity
+
+  **Request:** `CharityRequest`
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `CharityResponse`.
+
+
+
+.. http:GET::  /keys
+  
+(adapt existing)     return DONAU keys
+
+
+
+**Delete following**:
+
+- Withdraw
+
+- /config "largely for the SPA for AML officers"
+
+
+**questions:**
+
+/reserves      only useful for withdrawal of taler coins, no use in donau?

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