Donau: Set meaningful titles, write API overview, move routes to correct chapters

1 files changed, 214 insertions, 236 deletions

diff --git a/core/api-donau.rst b/core/api-donau.rst
index c082ee85..6cc7b84e 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -29,38 +29,131 @@ defines all specific terms used in this section.
 ------------------------
 API Overview
 ------------------------
-.. http:POST:: /batch-sign
-  
-  Deposit BDR (collection) and ask the donau to sign them (used by charities)
+This is intended to provide a quick overview of the whole REST API. For a more detailed view of the protocol, see the protocol specification.
 
-.. http:POST:: /receipts
-  
-  Send in donation receipts for the past fiscal year, receive signed total back.
+The chapters group the families of requests frequently encountered when using the donau API:
 
-.. http:GET::  /charities   
+* :ref:`Key management<key-management>`
+* :ref:`Status information<donau_status>`: get the public keys of the donau, the donaus config or some entropy
+* :ref:`Attest/confirm receipts<donau_attest>`: Sign all the donation units inside a donation receipt signed by a recognized charity public key.
+* :ref:`Submit receipts<donau_submit>`: Receive the receipts and, if valid, add all of it's donation units to the donor total. Returns a signature on the total yearly donation amount, hash of taxid+salt and year.
+* :ref:`Charity administration and status information<donau_charity>`:
   
-  return all charities
+  * For use by administrators to add/modify a charity
+  * For use by charities to get their remaining donation volume
 
-.. http:GET::  /charities/{id}  
-  
-  return a charity
+.. include:: tos.rst
 
-.. http:POST:: /charities  
-  
-  Add a charity
+.. _key-management:
 
-.. http:PUT:: /charities/{id}
-  
-  Modify a charity
+------------------------------------------------
+Management operations authorized by master key
+------------------------------------------------
 
+.. http:get:: /management/keys
 
-.. include:: tos.rst
+  Get a list of future public keys to be used by the donau.  Only to be
+  used by the donau's offline key management team. Not useful for anyone
+  else (but also not secret, so access is public).
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The donau responds with a `FutureKeysResponse` object. This request should
+    virtually always be successful.
+
+  **Details:**
+
+  .. ts:def:: FutureKeysResponse
+
+    interface FutureKeysResponse {
+
+      // Future donation units to be offered by this donau
+      // (only those lacking a master signature).
+      future_denoms: FutureDonationUnit[];
+
+      // The donau's future signing keys (only those lacking a master signature).
+      future_signkeys: FutureSignKey[];
+
+      // Master public key expected by this donau (provided so that the
+      // offline signing tool can check that it has the right key).
+      master_pub: EddsaPublicKey;
+
+      // Public key of the denomination security module.
+      denom_secmod_public_key: EddsaPublicKey;
+
+      // Public key of the signkey security module.
+      signkey_secmod_public_key: EddsaPublicKey;
+
+    }
+
+  .. ts:def:: FutureDonationUnit
+
+    interface FutureDonationUnit {
+      // Name in the configuration file that defines this denomination.
+      section_name: string;
+
+      // How much are receipts of this denomination worth?
+      value: Amount;
+
+      // When does the denomination key become valid?
+      stamp_start: Timestamp;
+
+      // When is it no longer possible to withdraw receipts
+      // of this denomination?
+      stamp_expire_withdraw: Timestamp;
+
+      // When is it no longer possible to deposit receipts
+      // of this denomination?
+      stamp_expire_deposit: Timestamp;
+
+      // Timestamp indicating by when legal disputes relating to these receipts must
+      // be settled, as the donau will afterwards destroy its evidence relating to
+      // transactions involving this receipt.
+      stamp_expire_legal: Timestamp;
+
+      // Public key for the denomination.
+      denom_pub: DonauDontationUnitKey;
+
+      // Signature by the denomination security module
+      // over `TALER_DonationUnitKeyAnnouncementPS`
+      // for this denomination with purpose
+      // ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
+      denom_secmod_sig: EddsaSignature;
+
+    }
+
+  .. ts:def:: FutureSignKey
+
+    interface SignKey {
+      // The actual donau's EdDSA signing public key.
+      key: EddsaPublicKey;
+
+      // Initial validity date for the signing key.
+      stamp_start: Timestamp;
+
+      // Date when the donau will stop using the signing key, allowed to overlap
+      // slightly with the next signing key's validity to allow for clock skew.
+      stamp_expire: Timestamp;
+
+      // Date when all signatures made by the signing key expire and should
+      // henceforth no longer be considered valid in legal disputes.
+      stamp_end: Timestamp;
+
+      // Signature over `TALER_SigningKeyAnnouncementPS`
+      // for this signing key by the signkey security
+      // module using purpose ``TALER_SIGNATURE_SM_SIGNING_KEY``.
+      signkey_secmod_sig: EddsaSignature;
+    }
+
+
+.. http:post:: /management/keys
 
 .. _donau_status:
 
-------------------------
-Donau status information
-------------------------
+--------------------------------------------
+Donau public keys and status information
+--------------------------------------------
 
 This API is used by donors and charities to obtain global information about
 the Donau, such as online signing keys, available donation units and the fee
@@ -333,108 +426,7 @@ should cache.
 
 
 
-----------------------------------------------
-Management operations authorized by master key
-----------------------------------------------
-
-.. http:get:: /management/keys
-
-  Get a list of future public keys to be used by the donau.  Only to be
-  used by the donau's offline key management team. Not useful for anyone
-  else (but also not secret, so access is public).
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The donau responds with a `FutureKeysResponse` object. This request should
-    virtually always be successful.
-
-  **Details:**
-
-  .. ts:def:: FutureKeysResponse
-
-    interface FutureKeysResponse {
-
-      // Future donation units to be offered by this donau
-      // (only those lacking a master signature).
-      future_denoms: FutureDonationUnit[];
-
-      // The donau's future signing keys (only those lacking a master signature).
-      future_signkeys: FutureSignKey[];
-
-      // Master public key expected by this donau (provided so that the
-      // offline signing tool can check that it has the right key).
-      master_pub: EddsaPublicKey;
-
-      // Public key of the denomination security module.
-      denom_secmod_public_key: EddsaPublicKey;
-
-      // Public key of the signkey security module.
-      signkey_secmod_public_key: EddsaPublicKey;
-
-    }
-
-  .. ts:def:: FutureDonationUnit
-
-    interface FutureDonationUnit {
-      // Name in the configuration file that defines this denomination.
-      section_name: string;
-
-      // How much are receipts of this denomination worth?
-      value: Amount;
-
-      // When does the denomination key become valid?
-      stamp_start: Timestamp;
-
-      // When is it no longer possible to withdraw receipts
-      // of this denomination?
-      stamp_expire_withdraw: Timestamp;
-
-      // When is it no longer possible to deposit receipts
-      // of this denomination?
-      stamp_expire_deposit: Timestamp;
-
-      // Timestamp indicating by when legal disputes relating to these receipts must
-      // be settled, as the donau will afterwards destroy its evidence relating to
-      // transactions involving this receipt.
-      stamp_expire_legal: Timestamp;
-
-      // Public key for the denomination.
-      denom_pub: DonauDontationUnitKey;
-
-      // Signature by the denomination security module
-      // over `TALER_DonationUnitKeyAnnouncementPS`
-      // for this denomination with purpose
-      // ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
-      denom_secmod_sig: EddsaSignature;
-
-    }
-
-  .. ts:def:: FutureSignKey
-
-    interface SignKey {
-      // The actual donau's EdDSA signing public key.
-      key: EddsaPublicKey;
-
-      // Initial validity date for the signing key.
-      stamp_start: Timestamp;
-
-      // Date when the donau will stop using the signing key, allowed to overlap
-      // slightly with the next signing key's validity to allow for clock skew.
-      stamp_expire: Timestamp;
-
-      // Date when all signatures made by the signing key expire and should
-      // henceforth no longer be considered valid in legal disputes.
-      stamp_end: Timestamp;
-
-      // Signature over `TALER_SigningKeyAnnouncementPS`
-      // for this signing key by the signkey security
-      // module using purpose ``TALER_SIGNATURE_SM_SIGNING_KEY``.
-      signkey_secmod_sig: EddsaSignature;
-    }
-
 
-.. http:post:: /management/keys
 
   Provide master signatures for future public keys to be used by the Donau.
   Only to be used by the Donau's offline key management team. Not useful
@@ -491,10 +483,85 @@ Management operations authorized by master key
 
     }
 
+.. _donau_attest:
+
+----------------------------------------
+Attest/Confirm receipts(ex Withdrawal)
+----------------------------------------
+
+.. 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
+      }
+
+
+  
+  .. 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;
+      }
 
-----------
-Withdrawal
-----------
 
 This API is used by the wallet to obtain digital receipts.
 
@@ -790,9 +857,24 @@ Batch Withdraw
 
     }
 
--------
-Deposit
--------
+.. _donau_submit:
+
+-----------------------------
+Submit receipts (ex Deposit)
+-----------------------------
+
+.. http:POST:: /submit  
+  
+  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:**
 
 Deposit operations are requested f.e. by a merchant during a transaction or a
 bidder during an auction.
@@ -912,97 +994,11 @@ proof to the seller for the escrow of sufficient fund.
       donau_sig: EddsaSignature;
     }
 
+.. _donau_charity:
 
------
-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;
-      }
-
+----------------------------------------------
+Charity administration and status information
+----------------------------------------------
 .. http:GET::  /charities   
   
   return all charities
@@ -1076,21 +1072,3 @@ Design overview
   :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?