Donau: skeleton for /batch-attest and /submit

1 files changed, 55 insertions, 49 deletions

diff --git a/core/api-donau.rst b/core/api-donau.rst
index 6cc7b84e..f1f84de1 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -489,78 +489,69 @@ should cache.
 Attest/Confirm receipts(ex Withdrawal)
 ----------------------------------------
 
-.. http:POST:: /batch-sign
+.. http:POST:: /batch-attest
   
-  Deposit BDR (collection) and ask the donau to sign them (used by charities)
+  Deposit a `SignedDonationReceipt` and ask the donau to sign all it's contained `DonationUnit`s.
 
-  **Request:** `BlindedDonationReceipts`
+  **Request:** `SignedDonationReceipt`
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `SignedBDRs`.
+    The request was successful, and the response is a `AttestedDonationReceipt`.
 
   **Details:**
 
-  .. ts:def:: BDRsRequest
-
-    interface BlindedDonationRequests {
-
-      blinded_donation_receipts: BlindedDonationReceipt[];
+  .. ts:def:: SignedDonationReceipt
 
+    interface SignedDonationReceipt {
+      charity_signature: EddsaSignature;
+      year: int;
+      donation_units: DonationUnit[];
     }
 
+  .. ts:def:: DonationUnit
 
-  .. ts:def:: SignedBDRs
-
-    interface SignedBDRs {
-
-      blinded_donation_receipts: BlindedDonationReceipt[];
-
+    interface DonationUnit {
+      donau_pub_hash: HashCode;
+      taxid_hashed: HashCode;
+      nonce: string;
     }
 
-  .. ts:def:: BlindedDonationReceipt
+  .. ts:def:: AttestedDonationReceipt
 
-      interface BlindedDonationReceipt{
-        // TODO
-      }
+    interface AttestedDonationReceipt {
 
+      blindsigned_donation_units: BlindsignedDonationUnit[];
 
-  
-  .. ts:def:: ReceiptsRequest
-
-    interface {
-      //TODO
-      taxnr_hashed: HashCode
-      salt: WireSalt
-      year: int;
-      receipts: DonationReceipt[];
     }
 
-  .. ts:def:: DonationReceipt
+  .. ts:def:: BlindsignedDonationUnit
 
-    interface DonationReceipt{
-    //TODO
-      amount: Amount;
-      taxnr_hashed: HashCode
-      salt: WireSalt
-      year: int; 
-      donau_sig:
+    interface BlindsignedDonationUnit{
+      donau_pub_hash: HashCode;
+      donation_unit_ev: DonationUnitEnvelope;
     }
 
-  .. ts:def:: FiscalYearResponse
+  .. ts:def:: DonationUnitEnvelope
+    
+    type DonationUnitEnvelope = RSADonationUnitEnvelope | CSDonationUnitEnvelope ;
 
-    interface FiscalYearResponse{
-      total: Amount;
-      signature: YearTotalSignature
+  .. ts:def:: RSADonationUnitEnvelope
+
+    interface RSADonationUnitEnvelope {
+      cipher: "RSA";
+      rsa_blinded_donation_unit: string;          // Crockford Base32 encoded
     }
 
-  .. ts:def:: FiscalYearSignature
+  .. ts:def:: CSDonationUnitEnvelope
 
-      interface YearTotalSignature{
-        // signature over taxnr_hashed, total, year
-        fiscal_year_sig: EddsaSignature;
-      }
+    interface CSDonationUnitEnvelope {
+      cipher: "CS";
+      cs_nonce: string;      // Crockford Base32 encoded
+      cs_blinded_c0: string; // Crockford Base32 encoded
+      cs_blinded_c1: string; // Crockford Base32 encoded
+    }
 
 
 This API is used by the wallet to obtain digital receipts.
@@ -792,7 +783,6 @@ Withdraw
     }
 
 
-
 Batch Withdraw
 ~~~~~~~~~~~~~~
 
@@ -863,19 +853,35 @@ Batch Withdraw
 Submit receipts (ex Deposit)
 -----------------------------
 
-.. http:POST:: /submit  
+.. http:POST:: /submit
   
   Send in donation receipts for the past fiscal year, receive signed total back.
 
-  **Request:** `ReceiptsRequest`
+  **Request:** `SubmitRequest`
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `FiscalYearResponse`.
+    The request was successful, and the response is a `SubmitResponse`.
 
   **Details:**
 
+  .. ts:def:: SubmitRequest
+
+    interface SubmitRequest{
+      taxnr_hashed: HashCode;
+      year: int;
+      donation_units: DonationUnit[];
+    }
+
+  .. ts:def:: FiscalYearResponse
+
+    interface SubmitResponse{
+      total: Amount;
+      // signature over taxid_hashed, total, year
+      signature: EddsaSignature;
+    }
+
 Deposit operations are requested f.e. by a merchant during a transaction or a
 bidder during an auction.