\section{Additional Details -- Implementation}\label{app-impl}

This appendix describes the remaining implementation details such as APIs.

\subsection{REST API}

The detailed REST API specification of the Donau back-end is publicly
available and will be submitted as artifact.
The following are
the main API endpoints:

\subsubsection{\texttt{/keys}}
The \texttt{GET /keys} request returns all valid donation unit public keys
offered by the Donau, as well as the Donau's current EdDSA public signing key.
The following is an example response of a \texttt{curl 127.0.0.1:8080/keys}
command. Some parts of the following example responses are truncated (denoted by
the three dots '\texttt{...}') to make them more readable.

\begin{verbatim}
{
"version": "0:0:0",
"base_url": "http://localhost:8080/",
"currency": "EUR",
"signkeys": [
  {
    "stamp_start": {
      "t_s": 1717069556
    },
    "stamp_expire": {
      "t_s": 1718279156
    },
    "key": "CFV2PY8164E231XZSQK30K8R6CBQ..."
  },
  {
  ...
  }
  ],
  "donation_units": [
  {
    "donation_unit_pub": {
      "cipher": "RSA",
      "rsa_public_key": "020000YC7XK99S..."
    },
    "year": 2024,
    "lost": false,
    "value": "EUR:5"
  },
  {
    "donation_unit_pub": {
      "cipher": "CS",
      "cs_public_key": "7SKRQGBSEPBG24..."
    },
    "year": 2024,
    "lost": false,
    "value": "EUR:1"
  },
  {
  ...
  }
  ]
}
\end{verbatim}

\subsubsection{\texttt{/charities}}

The following is an example response of a \texttt{curl 127.0.0.1:8080/charities} command.
There is only one charity named \texttt{example} registered with a donation limit of 10 euros.

\begin{verbatim}
{
"charities": [
  {
    "charity_pub": "ABETNXT9ZF606FRF3WD5...",
    "url": "example.com",
    "name": "example",
    "max_per_year": "EUR:10",
    "receipts_to_date": "EUR:0",
    "current_year": 2024
  }
]
}
\end{verbatim}

To insert a charity a \texttt{POST} request can be sent using
\texttt{curl -d @charity.json -X POST http://127.0.0.1:8080/charities}.

The following is an example of a
\texttt{charity.json} entry

\begin{verbatim}
{
"charity_pub": "ABETNXT9ZF606FRF3WD5...",
"charity_name": "mycharity",
"charity_url": "mycharity.example.com",
"max_per_year": "EUR:1000",
"receipts_to_date": "EUR:0",
"current_year": 2024
}
\end{verbatim}

The response consists of the charity ID generated by the database.
\begin{verbatim}
{
"charity-id": 1
}
\end{verbatim}


\subsubsection{\texttt{/batch-issue}}

The following is an example response of a \\
\texttt{curl -d @issue.json -X POST http://127.0.0.1:8080/batch-issue/1}
request showing a \texttt{issue.json} entry.
The number at the end of the URL is the charity ID.



\begin{verbatim}
{
"budikeypairs": [
{
  "h_donaton_unit_pub": "130C2KDHTAFDQFB8XED...",
  "blinded_udi": {
  "cipher": "RSA",
  "rsa_blinded_identifier": "AXPTEE24W28S9XN..."
  }
}
],
"charity_sig": "JEJ0QMDXD416XKSK1SG0DETJEH...",
"year": 2024
}
\end{verbatim}

\begin{verbatim}
{
"blind_signatures": [
  {
   "blinded_signature": {
   "cipher": "RSA",
   "blinded_rsa_signature": "16XHNWSCDRVKHF..."
    }
  }
],
"issued_amount: "EUR:15"
}
\end{verbatim}

\subsubsection{\texttt{/batch-submit}}

\begin{verbatim}
{
"h_donor_tax_id": "N2NYR2SFNGZSS388R2SB0VK...",
"donation_year": 2024,
"donation_receipts": [
{
  "h_donaton_unit_pub": "130C2KDHTAFDQFB8X...",
  "nonce": "JEQC39G",
  "donation_unit_sig":
  {
  "cipher": "RSA",
  "rsa_signature":  "GQBXPNE4JT5W53T3CVP6E..."
  }
}
]
}
\end{verbatim}

\subsubsection{\texttt{/donation-statement}}
To obtain the donation statement, the donor submits a GET request for a specified year and taxpayer ID.

The following is an example response of a \\
\texttt{curl http://127.0.0.1:8080/donation-statement/$\backslash$} \\
\hspace*{0.5cm} \ \texttt{2024/N2NYR2SFNGZSS388R2SB...} \\
request.

The last parameter of the URL is the \DI.

\begin{verbatim}
{
"total": "EUR:15",
"donation_statement": "C1JVDP25AR001W5AHMAZ...",
"donau_pub": "63f62b7901311c2187bfcde6304d1..."
}
\end{verbatim}
