path: root/core/api-donau.rst

..
  This file is part of GNU TALER.
  Copyright (C) 2014-2023 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Christian Grothoff

=====================
The Donau RESTful API
=====================

The API specified here follows the :ref:`general conventions <http-common>`
for all details not specified in the individual requests.
The `glossary <https://docs.taler.net/glossary.html#glossary>`_
defines all specific terms used in this section.

.. contents:: Table of Contents

------------------------
API Overview
------------------------
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.

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.
* :ref:`Charity administration and status information<donau_charity>`:
  
  * For use by administrators to add/modify a charity
  * For use by charities to get their remaining donation volume

.. 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:

--------------------------------------------
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
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
should cache.


.. http:get:: /seed

  Return an entropy seed. The Donau will return a high-entropy
  value that will differ for every call.  The response is NOT in
  JSON, but simply high-entropy binary data in the HTTP body.
  This API should be used by wallets to guard themselves against
  running on low-entropy (bad PRNG) hardware. Naturally, the entropy
  returned MUST be mixed with locally generated entropy.


.. http:get:: /config

  Return the protocol version, financial domain and currency supported by this
  Donau backend.

  **Response:**

  :http:statuscode:`200 OK`:
    The body is a `VersionResponse`.

  .. ts:def:: DonauVersionResponse

    interface DonauVersionResponse {
      // libtool-style representation of the Donau protocol version, see
      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
      // The format is "current:revision:age".
      version: string;

      // Name of the protocol.
      name: "taler-donau";

      // Currency supported by this donau.
      currency: string;

      // Financial domain by this donau.
      domain: string;

    }


.. 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.

  **Request:**

  :query last_issue_date: Optional argument specifying the maximum value of
                          any of the ``stamp_start`` members of the
                          donation unit keys of a ``/keys`` response that is
                          already known to the client. Allows the Donau to
                          only return keys that have changed since that
                          timestamp.  The given value must be an unsigned
                          64-bit integer representing seconds after 1970.  If
                          the timestamp does not exactly match the
                          ``stamp_start`` of one of the denomination keys, all
                          keys are returned.

  **Response:**

  :http:statuscode:`200 OK`:
    The Donau responds with a `DonauKeysResponse` object. This request should
    virtually always be successful. It only fails if the Donau is misconfigured or
    has not yet been provisioned with key signatures via ``taler-donau-offline``.

  **Details:**

  .. ts:def:: DonauKeysResponse

    interface DonauKeysResponse {
      // libtool-style representation of the Donau protocol version, see
      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
      // The format is "current:revision:age".
      version: string;

      // Financial domain this donau operates for.
      domain: string;

      // The donau's base URL.
      base_url: string;

      // The donau's currency.
      currency: string;

      // How many digits should the amounts be rendered
      // with by default. Small capitals should
      // be used to render fractions beyond the number
      // given here (like on gas stations).
      currency_fraction_digits: Integer;

      // EdDSA master public key of the donau, used to sign entries
      // in ``denoms`` and ``signkeys``.
      master_public_key: EddsaPublicKey;

      // Donation Units offered by this donau
      donation_units: DonationUnitKeyGroup[];

      // The date when the denomination keys were last updated.
      list_issue_date: Timestamp;

      // The Donau's signing keys.
      signkeys: SignKey[];

      // Compact EdDSA `signature` (binary-only) over the list "donation units".
      // Signature of `TALER_DonauKeySetPS`
      exchange_sig: EddsaSignature;

      // Public EdDSA key of the Donau that was used to generate the exchange_sig.
      // 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.
      exchange_pub: EddsaPublicKey;

    }

  .. ts:def:: DonauDonationUnitKeyGroup

    type DonauDonationUnitKeyGroup =
      | DonauDonationUnitKeyGroupRsa
      | DonauDonationUnitKeyGroupCs;

  .. ts:def:: DonauDonationUnitKeyGroupRsa

    interface DonauDonationUnitKeyGroupRsa extends DonauDonationUnitKeyGroupCommon {
      cipher: "RSA";

      denoms: ({
        rsa_pub: RsaPublicKey;
      } & DonauDonationUnitKeyCommon)[];
    }

  .. ts:def:: DonauDonationUnitKeyGroupCs

    interface DonauDonationUnitKeyGroupCs extends DonauDonationUnitKeyGroupCommon {
      cipher: "CS";

      denoms: ({
        cs_pub: Cs25519Point;
      } & DonauDonationUnitKeyCommon)[];
    }

  .. ts:def:: DonauDonationUnitKeyGroupCommon

    // Common attributes for all denomination groups
    interface DonauDonationUnitKeyGroupCommon {
      // 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

    interface DonauDonationUnitKeyCommon {
      // Signature of `TALER_DonauDonationUnitKeyValidityPS`.
      master_sig: EddsaSignature;

      // When does the denomination key become valid?
      stamp_start: Timestamp;

      // When is it no longer possible to deposit receipts
      // of this denomination?
      stamp_expire_withdraw: 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;

      // Set to 'true' if the Donau somehow "lost" the private key. The donation unit was not
      // revoked, but still cannot be used to withdraw receipts at this time (theoretically,
      // the private key could be recovered in the future; receipts signed with the private key
      // remain valid).
      lost?: boolean;
    }

  .. ts:def:: DonauDonationUnit

    interface DonauDonationUnit {
      // How much are donation receipts of this denomination worth?
      value: Amount;

      // When does the denomination key become valid?
      stamp_start: Timestamp;

      // When is it no longer possible to deposit receipts
      // of this denomination?
      stamp_expire_withdraw: 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: DonauDonationUnitKey;

      // Signature of `TALER_DonauDonationUnitKeyValidityPS`.
      master_sig: EddsaSignature;
    }

  .. ts:def:: DonauDonationUnitKey

    type DonauDonationUnitKey =
      | RsaDonauDonationUnitKey
      | CSDonauDonationUnitKey;

  .. ts:def:: RsaDonauDonationUnitKey

    interface RsaDonauDonationUnitKey {
      cipher: "RSA";

      // RSA public key
      rsa_public_key: RsaPublicKey;
    }

  .. ts:def:: CSDonauDonationUnitKey

    interface CSDonauDonationUnitKey {
      cipher: "CS";

      // Public key of the denomination.
      cs_public_key: Cs25519Point;

    }

  A signing key in the ``signkeys`` list is a JSON object with the following fields:

  .. ts:def:: SignKey

    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 ``key`` and ``stamp_expire`` by the donau master key.
      // Signature of `TALER_DonauSigningKeyValidityPS`.
      // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
      master_sig: EddsaSignature;
    }


  .. note::

    Both the individual donation units *and* the denomination list is signed,
    allowing customers to prove that they received an inconsistent list.





  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
  for anyone else.

  **Request:** The request body must be a `MasterSignatures` object.

  **Response:**

  :http:statuscode:`204 No content`:
    The request was successfully processed.
  :http:statuscode:`403 Forbidden`:
    A provided signature is invalid.
  :http:statuscode:`404 Not found`:
    One of the keys for which a signature was provided is unknown to the Donau.

  **Details:**

  .. ts:def:: MasterSignatures

    interface MasterSignatures {

      // Provided master signatures for future denomination keys.
      denom_sigs: DonationUnitSignature[];

      // Provided master signatures for future online signing keys.
      signkey_sigs: SignKeySignature[];

    }

  .. ts:def:: DonationUnitSignature

    interface DonationUnitSignature {

      // Hash of the public key of the donation unit key.
      h_denom_pub: HashCode;

      // Signature over `TALER_DonationUnitKeyValidityPS`.
      // Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY``
      master_sig: EddsaSignature;

    }

  .. ts:def:: SignKeySignature

    interface SignKeySignature {
      // The actual donau's EdDSA signing public key.
      key: EddsaPublicKey;

      // Signature by the donau master key over
      // `TALER_DonauSigningKeyValidityPS`.
      // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
      master_sig: EddsaSignature;

    }

.. _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;
      }


This API is used by the wallet to obtain digital receipts.

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.

.. note::

   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:get:: /charitys/$CHARITY_PUB

  Request information about a charity.

  **Request:**

  :query timeout_ms=MILLISECONDS: *Optional.* If specified, the donau will
                                  wait up to MILLISECONDS for incoming funds
                                  before returning a 404 if the charity does
                                  not yet exist.

  **Response:**

  :http:statuscode:`200 OK`:
    The donau responds with a `CharitySummary` object; the charity was known to the donau.
  :http:statuscode:`404 Not found`:
    The charity key does not belong to a charity known to the donau.

  **Details:**

  .. ts:def:: CharitySummary

    interface CharitySummary {
      // 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;
    }


.. http:post:: /charitys/$CHARITY_PUB/history

  Request information about the history of a charity.

  **Request:**

  The request body must be a `CharityHistoryRequest` object.

  **Response:**

  :http:statuscode:`200 OK`:
    The Donau responds with a `CharityStatus` object; the charity was known to the Donau.
  :http:statuscode:`403 Forbidden`:
    The *TALER_SIGNATURE_CHARITY_HISTORY_REQUEST* is invalid.
    This response comes with a standard `ErrorDetail` response.  Alternatively, the provided timestamp is not close to the current time.
  :http:statuscode:`404 Not found`:
    The charity key does not belong to a charity known to the donau.

  **Details:**

  .. ts:def:: CharityHistoryRequest

    interface CharityHistoryRequest {
      // Signature of type
      // ``TALER_SIGNATURE_CHARITY_HISTORY_REQUEST``
      // over a `TALER_CharityHistoryRequestSignaturePS`.
      charity_sig: EddsaSignature;

      // Time when the client made the request.
      // Timestamp must be reasonably close to the time of
      // the donau, otherwise the donau may reject
      // the request.
      request_timestamp: Timestamp;
    }

  .. ts:def:: CharityStatus

    interface CharityStatus {
      // Balance left in the charity.
      balance: Amount;

      // If set, gives the maximum age group that the client is required to set
      // during withdrawal.
      maximum_age_group: number;

      // Transaction history for this charity.
      // May be partial (!).
      history: TransactionHistoryItem[];
    }

  Objects in the transaction history have the following format:

  .. ts:def:: TransactionHistoryItem

    // Union discriminated by the "type" field.
    type TransactionHistoryItem =
      | CharityWithdrawTransaction
      | CharityCreditTransaction;

  .. ts:def:: CharityWithdrawTransaction

    interface CharityWithdrawTransaction {
      type: "WITHDRAW";

      // Amount withdrawn.
      amount: Amount;

      // Hash of the denomination public key of the receipt.
      h_denom_pub: HashCode;

      // Hash of the blinded receipt to be signed.
      h_receipt_envelope: HashCode;

      // Signature over a `TALER_WithdrawRequestPS`
      // with purpose ``TALER_SIGNATURE_WALLET_CHARITY_WITHDRAW``
      // created with the charity's private key.
      charity_sig: EddsaSignature;

      // Fee that is charged for withdraw.
      withdraw_fee: Amount;
     }

  .. ts:def:: CharityCreditTransaction

    interface CharityCreditTransaction {
      type: "CREDIT";

      // Amount deposited.
      amount: Amount;

      // Sender account ``payto://`` URL.
      sender_account_url: string;

      // Opaque identifier internal to the donau that
      // uniquely identifies the wire transfer that credited the charity.
      wire_reference: Integer;

      // Timestamp of the incoming wire transfer.
      timestamp: Timestamp;
    }



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  
  
  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.

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

  **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`.