Donau: submit and issue routes

1 files changed, 170 insertions, 509 deletions

diff --git a/core/api-donau.rst b/core/api-donau.rst
index d299122c..a009b601 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -33,7 +33,6 @@ This is intended to provide a quick overview of the whole REST API. For a more d
 
 The chapters group the families of requests frequently encountered when using the donau API:
 
-* :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.
@@ -44,111 +43,6 @@ The chapters group the families of requests frequently encountered when using th
 
 .. include:: tos.rst
 
-.. _key-management:
-
-------------------------------------------------
-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
-
 .. _donau_status:
 
 --------------------------------------------
@@ -156,8 +50,7 @@ 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
-structure.  This is typically the first call any Donau client makes, as it
+the Donau, such as online signing keys and available donation units.  This is typically the first call any Donau client makes, as it
 returns information required to process all of the other interactions with the
 Donau.  The returned information is secured by signature(s) from the Donau,
 especially the long-term offline signing key of the Donau, which clients
@@ -207,7 +100,7 @@ should cache.
 .. http:get:: /keys
 
   Get a list of all donation units keys offered by the Donau,
-  as well as the Donau's current online signing key.
+  as well as the Donau's current online signing key (used for donation statements).
 
   **Request:**
 
@@ -359,92 +252,185 @@ should cache.
 .. _donau_attest:
 
 ----------------------------------------
-Attest/Confirm receipts(ex Withdrawal)
+Issue receipts
 ----------------------------------------
 
-.. http:POST:: /batch-attest
+Inspired by Taler's `Withdraw`.
+
+This API is used by the charity to obtain valid, attested donation receipts from the donau.
+Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year.
+
+
+All incoming `BDID` are recorded under the corresponding charity_id by the donau.
+
+.. http:POST:: /batch-issue/$CHARITY_ID
   
-  Deposit a `SignedDonationReceipt` and ask the donau to sign all it's contained `DonationUnit`s.
+  Send in a `IssueReceiptsRequest` and ask the donau to sign all it's contained `DonationUnit`.
 
-  **Request:** `SignedDonationReceipt`
+  **Request:** `IssueReceiptsRequest`
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `AttestedDonationReceipt`.
+    The request was successful, and the response is a `BSDonationReceipts`.
 
   **Details:**
 
-  .. ts:def:: SignedDonationReceipt
+  .. ts:def:: IssueReceiptsRequest
 
-    interface SignedDonationReceipt {
+    interface IssueReceiptsRequest {
       charity_signature: EddsaSignature;
       year: int;
-      donation_units: DonationUnit[];
+      bdids: BDID[];
     }
 
-  .. ts:def:: DonationUnit
+  .. ts:def:: BDID
 
-    interface DonationUnit {
+    interface BDID {
       donau_pub_hash: HashCode;
       taxid_hashed: HashCode;
       nonce: string;
     }
 
-  .. ts:def:: AttestedDonationReceipt
-
-    interface AttestedDonationReceipt {
+  .. ts:def:: BSDonationReceipts
 
-      blindsigned_donation_units: BlindsignedDonationUnit[];
-
-    }
-
-  .. ts:def:: BlindsignedDonationUnit
-
-    interface BlindsignedDonationUnit{
-      donau_pub_hash: HashCode;
-      donation_unit_ev: DonationUnitEnvelope;
+    interface DonationReceipts {
+      blind_signed_receipt_signatures: DonationReceiptEnvelope[];
     }
 
-  .. ts:def:: DonationUnitEnvelope
+  .. ts:def:: DonationReceiptEnvelope
     
-    type DonationUnitEnvelope = RSADonationUnitEnvelope | CSDonationUnitEnvelope ;
+    type DonationReceiptEnvelope = RSADonationReceiptEnvelope | CSDonationReceiptEnvelope ;
 
-  .. ts:def:: RSADonationUnitEnvelope
+  .. ts:def:: RSADonationReceiptEnvelope
 
-    interface RSADonationUnitEnvelope {
+    interface RSADonationReceiptEnvelope {
       cipher: "RSA";
-      rsa_blinded_donation_unit: string;          // Crockford Base32 encoded
+      rsa_blinded_donation_receipt_sig: string;          // Crockford Base32 encoded
     }
 
-  .. ts:def:: CSDonationUnitEnvelope
+  .. ts:def:: CSDonationReceiptEnvelope
 
-    interface CSDonationUnitEnvelope {
+    interface CSDonationReceiptEnvelope {
       cipher: "CS";
       cs_nonce: string;      // Crockford Base32 encoded
       cs_blinded_c0: string; // Crockford Base32 encoded
       cs_blinded_c1: string; // Crockford Base32 encoded
     }
 
+-----------------------------
+Submit receipts (ex Deposit)
+-----------------------------
 
-This API is used by the wallet to obtain digital receipts.
+.. http:POST:: /submit
+  
+  Send in donation receipts for the past fiscal year, receive signed total back.
 
-When transferring money to the donau such as via SEPA transfers, the donau creates
-a *charity*, which keeps the money from the customer.  The customer must
-specify an EdDSA charity public key as part of the transfer, and can then
-withdraw digital receipts using the corresponding private key.  All incoming and
-outgoing transactions are recorded under the corresponding public key by the
-donau.
+  **Request:** `SubmitRequest`
 
-.. note::
+  **Response:**
 
-   Eventually the donau will need to advertise a policy for how long it will
-   keep transaction histories for inactive or even fully drained charitys.  We
-   will therefore need some additional handler similar to ``/keys`` to
-   advertise those terms of service.
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `SubmitResponse`.
 
+  **Details:**
 
-.. http:get:: /charitys/$CHARITY_PUB
+  .. ts:def:: SubmitRequest
+
+    interface SubmitRequest{
+      taxnr_hashed: HashCode;
+      year: int;
+      donation_receipts: DonationReceipt[];
+    }
+
+  .. ts:def:: DonationReceipt
+
+    interface DonationReceipt{
+      donation_unit_pub_hash: HashCode;
+      nonce: string;
+      taxid_hashed: HashCode;
+      donau_sig: RsaSignature | Edx25519Signature
+    }
+
+  .. ts:def:: SubmitResponse
+
+    interface SubmitResponse{
+      total: Amount;
+      // signature over taxid_hashed, total, year
+      signature: EddsaSignature;
+    }
+..   :http:statuscode:`200 OK`:
+..     The operation succeeded, the donau confirms that no double-spending took
+..     place.  The response will include a `BatchDepositSuccess` object.
+..   :http:statuscode:`403 Forbidden`:
+..     One of the signatures is invalid.
+..     This response comes with a standard `ErrorDetail` response.
+..   :http:statuscode:`404 Not found`:
+..     Either one of the denomination keys is not recognized (expired or invalid),
+..     or the wire type is not recognized.
+..     If a denomination key is unknown, the response will be
+..     a `DonationUnitUnknownMessage`.
+..   :http:statuscode:`409 Conflict`:
+..     The deposit operation has either failed because a receipt has insufficient
+..     residual value, or because the same public key of a receipt has been
+..     previously used with a different denomination.
+..     Which case it is
+..     can be decided by looking at the error code
+..     (``TALER_EC_DONAU_DEPOSIT_CONFLICTING_CONTRACT`` (same receipt used in different ways),
+..     ``TALER_EC_DONAU_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient) or
+..     ``TALER_EC_DONAU_GENERIC_RECEIPT_CONFLICTING_DENOMINATION_KEY``
+..     (same receipt public key, but different denomination)).
+..     The fields of the response are still evolving (see bug 7267),
+..     for now the format of the response is a `DepositDoubleSpendError`.
+..     The request should not be repeated again with this receipt.
+..   :http:statuscode:`410 Gone`:
+..     The requested denomination 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.
+
+.. _donau_charity:
+
+----------------------------------------------
+Charity administration and status information
+----------------------------------------------
+.. 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
+
+.. _donau_charity_get:
+
+.. http:get:: /charitys/$CHARITY_ID
 
   Request information about a charity.
 
@@ -480,7 +466,36 @@ donau.
     }
 
 
-.. http:post:: /charitys/$CHARITY_PUB/history
+
+.. 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:post:: /charitys/$CHARITY_ID/history
 
   Request information about the history of a charity.
 
@@ -583,371 +598,17 @@ donau.
 
 
 
-Withdraw
-~~~~~~~~
-
-.. http:post:: /csr-withdraw
-
-  Obtain donau-side input values in preparation for a
-  withdraw step for certain denomination cipher types,
-  specifically at this point for Clause-Schnorr blind
-  signatures.
-
-  **Request:** The request body must be a `WithdrawPrepareRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `WithdrawPrepareResponse`.  Note that repeating exactly the same request
-    will again yield the same response (assuming none of the denomination is expired).
-  :http:statuscode:`404 Not found`:
-    The denomination key is not known to the donau.
-  :http:statuscode:`410 Gone`:
-    The requested denomination 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.
-
-  **Details:**
-
-  .. ts:def:: WithdrawPrepareRequest
-
-    interface WithdrawPrepareRequest {
-
-      // Nonce to be used by the donau to derive
-      // its private inputs from. Must not have ever
-      // been used before.
-      nonce: CSNonce;
-
-      // Hash of the public key of the denomination the
-      // request relates to.
-      denom_pub_hash: HashCode;
-
-    }
-
-  .. ts:def:: WithdrawPrepareResponse
-
-    type WithdrawPrepareResponse =
-      | DonauWithdrawValue;
-
-  .. ts:def:: DonauWithdrawValue
-
-    type DonauWithdrawValue =
-      | DonauRsaWithdrawValue
-      | DonauCsWithdrawValue;
-
-  .. ts:def:: DonauRsaWithdrawValue
-
-    interface DonauRsaWithdrawValue {
-      cipher: "RSA";
-    }
-
-  .. ts:def:: DonauCsWithdrawValue
-
-    interface DonauCsWithdrawValue {
-      cipher: "CS";
-
-      // CSR R0 value
-      r_pub_0: CsRPublic;
-
-      // CSR R1 value
-      r_pub_1: CsRPublic;
-    }
-
-
-Batch Withdraw
-~~~~~~~~~~~~~~
-
-
-.. http:post:: /charitys/$CHARITY_PUB/batch-withdraw
-
-  Withdraw multiple receipts from the same charity.  Note that the client should
-  commit all of the request details, including the private key of the receipts and
-  the blinding factors, to disk *before* issuing this request, so that it can
-  recover the information if necessary in case of transient failures, like
-  power outage, network outage, etc.
-
-  **Request:** The request body must be a `BatchWithdrawRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `BatchWithdrawResponse`.
-    Note that repeating exactly the same request will again yield the same
-    response, so if the network goes down during the transaction or before the
-    client can commit the receipt signature to disk, the receipt is not lost.
-  :http:statuscode:`403 Forbidden`:
-    A signature is invalid.
-    This response comes with a standard `ErrorDetail` response.
-  :http:statuscode:`404 Not found`:
-    A denomination key or the charity are not known to the donau.  If the
-    denomination key is unknown, this suggests a bug in the wallet as the
-    wallet should have used current denomination keys from ``/keys``.
-    In this case, the response will be a `DonationUnitUnknownMessage`.
-    If the charity is unknown, the wallet should not report a hard error yet, but
-    instead simply wait for up to a day, as the wire transaction might simply
-    not yet have completed and might be known to the donau in the near future.
-    In this case, the wallet should repeat the exact same request later again
-    using exactly the same blinded receipt.
-  :http:statuscode:`409 Conflict`:
-    The balance of the charity is not sufficient to withdraw the receipts of the
-    indicated donation units.  
-  :http:statuscode:`410 Gone`:
-    A requested denomination 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.
-
-  **Details:**
-
-  .. ts:def:: BatchWithdrawRequest
-
-    interface BatchWithdrawRequest {
-      // Array of requests for the individual receipts to withdraw.
-      planchets: WithdrawRequest[];
-
-    }
-
-
-  .. ts:def:: BatchWithdrawResponse
-
-    interface BatchWithdrawResponse {
-      // Array of blinded signatures, in the same order as was
-      // given in the request.
-      ev_sigs: WithdrawResponse[];
-
-    }
-
-.. _donau_submit:
-
------------------------------
-Submit receipts (ex Deposit)
------------------------------
-
-.. http:POST:: /submit
+.. http:PATCH:: /charities/{id}
   
-  Send in donation receipts for the past fiscal year, receive signed total back.
-
-  **Request:** `SubmitRequest`
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    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.
-
-For the deposit operation during purchase, the merchant has to obtain the
-deposit permission for a receipt from their customer who owns the receipt.  When
-depositing a receipt, the merchant is credited an amount specified in the deposit
-permission, possibly a fraction of the total receipt's value, minus the deposit
-fee as specified by the receipt's denomination.
-
-For auctions, a bidder performs an deposit operation and provides all relevant
-information for the auction policy (such as timeout and public key as bidder)
-and can use the ``donau_sig`` field from the `DepositSuccess` message as a
-proof to the seller for the escrow of sufficient fund.
-
-
-.. _deposit:
-
-.. http:POST:: /batch-deposit
-
-  Deposit multiple receipts and ask the donau to transfer the given :ref:`amount`
-  into the merchant's bank account.  This API is used by the merchant to redeem
-  the digital receipts.
-
-  **Request:**
-
-  The request body must be a `BatchDepositRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The operation succeeded, the donau confirms that no double-spending took
-    place.  The response will include a `BatchDepositSuccess` object.
-  :http:statuscode:`403 Forbidden`:
-    One of the signatures is invalid.
-    This response comes with a standard `ErrorDetail` response.
-  :http:statuscode:`404 Not found`:
-    Either one of the denomination keys is not recognized (expired or invalid),
-    or the wire type is not recognized.
-    If a denomination key is unknown, the response will be
-    a `DonationUnitUnknownMessage`.
-  :http:statuscode:`409 Conflict`:
-    The deposit operation has either failed because a receipt has insufficient
-    residual value, or because the same public key of a receipt has been
-    previously used with a different denomination.
-    Which case it is
-    can be decided by looking at the error code
-    (``TALER_EC_DONAU_DEPOSIT_CONFLICTING_CONTRACT`` (same receipt used in different ways),
-    ``TALER_EC_DONAU_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient) or
-    ``TALER_EC_DONAU_GENERIC_RECEIPT_CONFLICTING_DENOMINATION_KEY``
-    (same receipt public key, but different denomination)).
-    The fields of the response are still evolving (see bug 7267),
-    for now the format of the response is a `DepositDoubleSpendError`.
-    The request should not be repeated again with this receipt.
-  :http:statuscode:`410 Gone`:
-    The requested denomination 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.
-
-  **Details:**
-
-  .. ts:def:: BatchDepositRequest
-
-    interface BatchDepositRequest {
-
-      // The list of receipts that are going to be deposited with this Request.
-      receipts: BatchDepositRequestReceipt[];
-
-      // FIXME: maybe add tax year?
-      
-      // Hash of the salted tax payer identification number.
-      h_donor: DonorTaxDataHash;
-    }
-
-  .. ts:def:: BatchDepositRequestReceipt
-
-    interface BatchDepositRequestReceipt {
-      // EdDSA public key of the receipt being deposited.
-      receipt_pub: EddsaPublicKey;
-
-      // Hash of denomination RSA key with which the receipt is signed.
-      denom_pub_hash: HashCode;
-
-      // Donau's unblinded RSA signature of the receipt.
-      ub_sig: DonationUnitSignature;
-
-      // Signature over `TALER_DonauDepositRequestPS`, made by the customer with the
-      // `receipt's private key <receipt-priv>`.
-      receipt_sig: EddsaSignature;
-    }
-
-  The deposit operation succeeds if the receipt is valid for making a deposit and
-  has enough residual value that has not already been deposited or melted.
-
-  .. ts:def:: BatchDepositSuccess
-
-     interface BatchDepositSuccess {
-      // FIXME: maybe add tax year instead?
-      donau_timestamp: Timestamp;
-
-      // FIXME: maybe add total amount?
-
-      // `Public EdDSA key of the donau <sign-key-pub>` that was used to
-      // generate the signature.
-      // Should match one of the donau's signing keys from ``/keys``.  It is given
-      // explicitly as the client might otherwise be confused by clock skew as to
-      // which signing key was used.
-      donau_pub: EddsaPublicKey;
-
-      // Final tax receipt signature from the donau.
-      // The EdDSA signature of `TALER_DonauTaxDeductionConfirmationPS` using a current
-      // `signing key of the donau <sign-key-priv>` affirming the successful
-      // deposit and that the donau will transfer the funds after the refund
-      // deadline, or as soon as possible if the refund deadline is zero.
-      donau_sig: EddsaSignature;
-    }
-
-.. _donau_charity:
-
-----------------------------------------------
-Charity administration and status information
-----------------------------------------------
-.. 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
+  Modify a charity
 
   **Request:** `CharityRequest`
 
   **Response:**
 
-  **Details:**
-
-  :http:statuscode:`201 Created`:
+  :http:statuscode:`200 OK`:
     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`.