taler-docs

commit 991232458a33150b2171bc2f72723009c5401bda
parent e32431b9b3c699d2009ea371d7f8ea394147716b
Author: Pius Loosli <loosp2@bfh.ch>
Date:   Tue, 17 Oct 2023 14:45:40 +0200

Donau: Use DonationSignature, minor other corrections

Diffstat:
M
core/api-donau.rst
 | 
63
++++++++++++++++++++++++++++++++++++++++-----------------------

1 file changed, 40 insertions(+), 23 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -266,7 +266,7 @@ All incoming `BDID` are recorded under the corresponding charity_id by the Donau
 
 .. http:POST:: /batch-issue/$CHARITY_ID
   
-  Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained `DonationUnit`.
+  Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained `BDID`.
 
   **Request:** `IssueReceiptsRequest`
 
@@ -342,12 +342,12 @@ All incoming `BDID` are recorded under the corresponding charity_id by the Donau
   .. ts:def:: BlindedDonationReceiptSignature
 
     type BlindedDonationReceiptSignature =
-      | RsaBlindedDonationReceiptSignature
+      | RSABlindedDonationReceiptSignature
       | CSBlindedDonationReceiptSignature;
 
-  .. ts:def:: BlindedDonationReceiptSignature
+  .. ts:def:: RSABlindedDonationReceiptSignature
 
-    interface RsaBlindedDonationReceiptSignature {
+    interface RSABlindedDonationReceiptSignature {
       cipher: "RSA";
 
       // (blinded) RSA signature
@@ -422,7 +422,7 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
   
   Send in donation receipts for the past fiscal year, receive signed total back.
 
-  **Request:** `SubmitRequest`
+  **Request:** `SubmitDonationReceiptsRequest`
 
   **Response:**
 
@@ -432,16 +432,14 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
     One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
-  :http:statuscode:`409 Conflict`:
-    The submit operation has failed because a unique donor id was already submitted. Comes with a `DonationReceiptDoubleSpendError`.
   :http:statuscode:`410 Gone`:
     The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.  FIXME: text does not match our use case well.
 
   **Details:**
 
-  .. ts:def:: SubmitRequest // Bad name
+  .. ts:def:: SubmitDonationReceiptsRequest
 
-    interface SubmitRequest{
+    interface SubmitDonationReceiptsRequest{
       // hashed taxpayer ID plus salt 
       taxnr_hashed: HashCode;
       // All donation receipts must be for this year.
@@ -455,25 +453,46 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
     interface DonationReceipt{
       donation_unit_pub_hash: HashCode;
       nonce: string;
-      donau_sig: RsaDonationSignature | CSDonationSignature; // There is a data type for this (without |), see DenoninationSignaure, better: DonationSignature
+      donau_sig: DonationSignature
     }
 
+  .. ts:def:: DonationSignature
+
+    type DonationSignature =
+      RsaDonationSignature | CSDonationSignature;
+
+  .. ts:def:: RsaDonationSignature
+
+    interface RsaDonationSignature {
+      cipher: "RSA";
+
+      // RSA signature
+      rsa_signature: RsaSignature;
+    }
+
+  .. ts:def:: CSDonationSignature
+    
+    interface CSDonationSignature {
+      type: "CS";
+
+      // R value component of the signature.
+      cs_signature_r: Cs25519Point;
+
+      // s value component of the signature.
+      cs_signature_s: Cs25519Scalar:
+    }
+
+
+
   .. ts:def:: SubmitResponse
 
     interface SubmitResponse{
+      // *accepted* total
       total: Amount;
       // signature over taxid_hashed, total, year
       signature: EddsaSignature;
     }
 
-  // Consider removing, always return SubmitResponse over *accepted* total.
-  .. ts:def:: DonationReceiptDoubleSpendError
-
-    interface DonationReceiptDoubleSpendError{
-      doubleSpent: DonationReceipt[];
-    }
-
-
 .. _donau_charity:
 
 ---------------------------------------------
@@ -488,8 +507,6 @@ The administration requests require an authorized bearer token to be set in the 
 
   **Request:**
 
-  FIXME: Authentication header? authorization? 
-
   **Reponse:**
 
   :http:statuscode:`200 OK`:
@@ -556,7 +573,7 @@ The administration requests require an authorized bearer token to be set in the 
   :http:statuscode:`201 Created`:
     The request was successful, and the response is a `CharityResponse`.
 
-  :http:statuscode: `403 Forbidden`:
+  :http:statuscode:`403 Forbidden`:
     The request did not contain an accepted administrator bearer token in it's header.
 
   .. ts:def:: CharityRequest
@@ -585,7 +602,7 @@ The administration requests require an authorized bearer token to be set in the 
   :http:statuscode:`200 OK`:
     The request was successful.
 
-  :http:statuscode: `403 Forbidden`:
+  :http:statuscode:`403 Forbidden`:
     The request did not contain an accepted administrator bearer token in it's header.
 
 
@@ -600,5 +617,5 @@ The administration requests require an authorized bearer token to be set in the 
   :http:statuscode:`200 OK`:
     The request was successful.
 
-  :http:statuscode: `403 Forbidden`:
+  :http:statuscode:`403 Forbidden`:
     The request did not contain an accepted administrator bearer token in it's header.
 \ No newline at end of file