commit 4d36a0fe73ef662738af8d7b8604565b35b1fb49
parent f760071851adeefc78a7405ed13305ac8596284c
Author: Pius Loosli <pius.loosli@students.bfh.ch>
Date: Tue, 26 Sep 2023 17:33:05 +0200
REST API overview & merge
Diffstat:
| M | core/api-donau.rst | | | 197 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 197 insertions(+), 0 deletions(-)
diff --git 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?
