taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

api-common.rst (78521B)


      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero Public License as published by the Free Software
      7   Foundation; either version 3.0, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 
     16   @author Christian Grothoff
     17   @author Marcello Stanisci
     18   @author Özgür Kesim
     19 
     20 .. _http-common:
     21 
     22 ==================================
     23 Conventions for Taler RESTful APIs
     24 ==================================
     25 
     26 -------------------------
     27 HTTP Request and Response
     28 -------------------------
     29 
     30 Certain response formats are common for all requests. They are documented here
     31 instead of with each individual request.  Furthermore, we note that clients may
     32 theoretically fail to receive any response.  In this case, the client should
     33 verify that the Internet connection is working properly, and then proceed to
     34 handle the error as if an internal error (500) had been returned.
     35 
     36 .. http:any:: /*
     37 
     38 
     39   **Request:**
     40 
     41   Unless specified otherwise, HTTP requests that carry a message body must
     42   have the content type ``application/json``.
     43 
     44   :reqheader Content-Type: application/json
     45 
     46   **Response:**
     47 
     48   :resheader Content-Type: application/json
     49 
     50   :http:statuscode:`200 Ok`:
     51     The request was successful.
     52   :http:statuscode:`301 Moved permanently`:
     53     The server responsible for the reserve
     54     changed, the client MUST follow the link to the new location. If possible,
     55     the client SHOULD remember the new URL for the reserve for future
     56     requests.  Only applicable if the request method is GET.
     57   :http:statuscode:`302 Found`:
     58     The server responsible for the reserve changed, the
     59     client MUST follow the link to the new location, but MUST NOT retain the
     60     new URL for future requests.  Only applicable if the request method is GET.
     61   :http:statuscode:`307 Temporary redirect`:
     62     The server responsible for the reserve changed, the
     63     client MUST follow the link to the new location, but MUST NOT retain the
     64     new URL for future requests.
     65   :http:statuscode:`308 Permanent redirect`:
     66     The server responsible for the reserve
     67     changed, the client MUST follow the link to the new location. If possible,
     68     the client SHOULD remember the new URL for the reserve for future
     69     requests.
     70   :http:statuscode:`400 Bad request`:
     71     One of the arguments to the request is missing or malformed.
     72   :http:statuscode:`415 Unsupported Media Type`:
     73     The Content-Type header was not set, or it was set to an unsupported MIME type.
     74   :http:statuscode:`500 Internal server error`:
     75     This always indicates some serious internal operational error of the exchange,
     76     such as a program bug, database problems, etc., and must not be used for
     77     client-side problems.  When facing an internal server error, clients should
     78     retry their request after some delay.  We recommend initially trying after
     79     1s, twice more at randomized times within 1 minute, then the user should be
     80     informed and another three retries should be scheduled within the next 24h.
     81     If the error persists, a report should ultimately be made to the auditor,
     82     although the auditor API for this is not yet specified.  However, as internal
     83     server errors are always reported to the exchange operator, a good operator
     84     should naturally be able to address them in a timely fashion, especially
     85     within 24h.
     86 
     87   Unless specified otherwise, all error status codes (4xx and 5xx) have a message
     88   body with an `ErrorDetail` JSON object.
     89 
     90   **Details:**
     91 
     92   .. ts:def:: ErrorDetail
     93 
     94     interface ErrorDetail {
     95 
     96       // Numeric `error code <error-codes>` unique to the condition.
     97       // The other arguments are specific to the error value reported here.
     98       code: ErrorCode;
     99 
    100       // Human-readable description of the error, i.e. "missing parameter", "commitment violation", ...
    101       // Should give a human-readable hint about the error's nature. Optional, may change without notice!
    102       hint?: string;
    103 
    104       // Optional detail about the specific input value that failed. May change without notice!
    105       detail?: string;
    106 
    107       // Name of the parameter that was bogus (if applicable).
    108       parameter?: string;
    109 
    110       // Path to the argument that was bogus (if applicable).
    111       path?: string;
    112 
    113       // Offset of the argument that was bogus (if applicable).
    114       offset?: string;
    115 
    116       // Index of the argument that was bogus (if applicable).
    117       index?: string;
    118 
    119       // Name of the object that was bogus (if applicable).
    120       object?: string;
    121 
    122       // Name of the currency that was problematic (if applicable).
    123       currency?: string;
    124 
    125       // Expected type (if applicable).
    126       type_expected?: string;
    127 
    128       // Type that was provided instead (if applicable).
    129       type_actual?: string;
    130 
    131       // Extra information that doesn't fit into the above (if applicable).
    132       extra?: Object;
    133     }
    134 
    135   .. ts:def:: ErrorCode
    136 
    137     // Numeric `error code <error-codes>` unique to the condition.
    138     // The other arguments are specific to the error value reported here.
    139     type ErrorCode = Integer;
    140 
    141 -----------------------
    142 Protocol Version Ranges
    143 -----------------------
    144 
    145 Some of the Taler services (e.g. exchange, merchant, bank integration API)
    146 expose the range of API versions they support.  Clients in turn have an API
    147 version range they support.  These version ranges are written down in the
    148 `libtool version format <https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html>`__.
    149 
    150 A protocol version is a positive, non-zero integer.  A protocol version range consists of three components:
    151 
    152 1. The ``current`` version.  This is the latest version of the protocol supported by the client or service.
    153 2. The ``revision`` number.  This value should usually not be interpreted by the client/server, but serves
    154    purely as a comment.  Each time a service/client for a protocol is updated while supporting the same
    155    set of protocol versions, the revision should be increased.
    156    In rare cases, the revision number can be used to work around unintended breakage in deployed
    157    versions of a service.  This is discouraged and should only be used in exceptional situations.
    158 3. The ``age`` number.  This non-zero integer identifies with how many previous protocol versions this
    159    implementation is compatible.  An ``age`` of 0 implies that the implementation only supports
    160    the ``current`` protocol version.  The ``age`` must be less or equal than the ``current`` protocol version.
    161 
    162 To avoid confusion with semantic versions, the protocol version range is written down in the following format:
    163 
    164 .. code:: none
    165 
    166   current[:revision[:age]]
    167 
    168 The angle brackets mark optional components. If either ``revision`` or ``age`` are omitted, they default to 0.
    169 
    170 Examples:
    171 
    172 * "1" and "1" are compatible
    173 * "1" and "2" are **incompatible**
    174 * "2:0:1" and "1:0:0" are compatible
    175 * "2:5:1" and "1:10:0" are compatible
    176 * "4:0:1" and "2:0:0" are **incompatible**
    177 * "4:0:1" and "3:0:0" are compatible
    178 
    179 .. note::
    180 
    181   `Semantic versions <https://semver.org/>`__ are not a good tool for this job, as we concisely want to express
    182   that the client/server supports the last ``n`` versions of the protocol.
    183   Semantic versions don't support this, and semantic version ranges are too complex for this.
    184 
    185 .. warning::
    186 
    187   A client doesn't have one single protocol version range.  Instead, it has
    188   a protocol version range for each type of service it talks to.
    189 
    190 .. warning::
    191 
    192   For privacy reasons, the protocol version range of a client should not be
    193   sent to the service.  Instead, the client should just use the two version ranges
    194   to decide whether it will talk to the service.
    195 
    196 .. _error-codes:
    197 
    198 -----------
    199 Error Codes
    200 -----------
    201 
    202 All error codes used in GNU Taler are defined in
    203 `GANA <https://git.gnunet.org/gana.git/tree/gnu-taler-error-codes/>`__.
    204 
    205 This centralized registry also contains generators that create enumerations
    206 and mappings from error codes to HTTP status codes and human-readable error
    207 messages for various programming languages.
    208 
    209 All error codes have numeric values below 100 or above 1000, so as to never be
    210 confused with HTTP status codes.  A value of 0 is reserved for "no error" or
    211 "success".
    212 
    213 In C, the respective enumeration is the ``enum TALER_ErrorCode``.
    214 
    215 Developers may have to re-run ``bootstrap`` and/or update their Git
    216 submodules to ensure that they have the latest GANA registry.
    217 
    218 ---------------------
    219 Common query patterns
    220 ---------------------
    221 
    222 .. _row-id-pagination:
    223 
    224 Row ID pagination
    225 ^^^^^^^^^^^^^^^^^
    226 
    227 Some endpoints paginate elements identified by an opaque numeric identifier,
    228 referred to here as *row ID*. The semantics of the row ID (including its
    229 sorting order) are determined by the server and are completely opaque to the
    230 client.
    231 
    232 The list of returned elements is determined by a row ID *offset*
    233 and a non-zero signed integer *limit*:
    234 
    235 * If *limit* is positive, return a list of up to *limit* elements (all matching
    236   the filter criteria) strictly **after** the *offset*. The elements are sorted
    237   in **ascending** order of the row ID.
    238 * If *limit* is negative, return a list of up to *-limit* elements (all matching
    239   the filter criteria) strictly **before** the *offset*. The elements are sorted
    240   in **descending** order of the row ID.
    241 
    242 If *offset* is not explicitly given, it defaults to:
    243 
    244 * A value **smaller** than all other row IDs if *limit* is **positive**.
    245 * A value **larger** than all other row IDs if *limit* is **negative**.
    246 
    247 Row IDs of a history (for example the wire gateway's ``/history/incoming``
    248 and ``/history/outgoing``, and the revenue API's ``/history``) are assigned in
    249 the order in which their elements become visible: once a client has received
    250 an element with row ID *n*, no element with a row ID at or below *n* may
    251 appear later.  Clients rely on this: they store the row ID of the last element
    252 that they processed and continue strictly after it, so an element that became
    253 visible after one with a higher row ID would never reach them.  Row IDs may
    254 have gaps, and clients must not expect them to be consecutive.
    255 
    256 A database sequence alone does not give this order, because transactions can
    257 commit in another order than the one in which they drew their row IDs, and
    258 not even ``SERIALIZABLE`` isolation prevents that.  An implementation
    259 therefore lets only one transaction at a time draw row IDs of a history and
    260 holds that exclusion until the transaction has committed, for example with a
    261 table lock or an advisory lock taken just before the row ID is drawn.
    262 
    263 :query limit: *Optional.*
    264   At most return the given number of results. Negative for descending by row
    265   ID, positive for ascending by row ID.
    266 :query offset: *Optional.*
    267   Starting row ID for an iteration.
    268 
    269 .. _long-polling:
    270 
    271 Long polling
    272 ^^^^^^^^^^^^
    273 
    274 Endpoints can result in an empty response (pagination) or a negative response
    275 (uncompleted operation, etc). Some endpoints allow clients to perform a form of
    276 long polling by asking the server to wait until *timeout_ms* for a non-empty or
    277 positive result.
    278 
    279 In the case of pagination, the response is sent as soon as a matching element
    280 is found and, therefore, the response MAY contain fewer than *limit* elements.
    281 
    282 A client MUST never rely on this behavior, as a response can be sent
    283 immediately or after waiting only a fraction of *timeout_ms*.
    284 
    285 :query timeout_ms: *Optional.*
    286   Timeout in milliseconds to wait for the response to be non-empty or positive.
    287 
    288 .. _encodings-ref:
    289 
    290 ----------------
    291 Common encodings
    292 ----------------
    293 
    294 This section describes how certain types of values are represented throughout the API.
    295 
    296 .. _slug:
    297 
    298 Slugs
    299 ^^^^^
    300 
    301 Many objects are identified by short, mostly human-chosen labels, such as
    302 merchant instance, order, product, template or token family identifiers.
    303 Because these labels are used as path components of HTTP endpoint URLs (like
    304 ``$INSTANCE`` or ``$ORDER_ID``), they must be usable in a URL path segment
    305 without any escaping.  We call such an identifier a *slug*.
    306 
    307 .. ts:def:: Slug
    308 
    309   // Non-empty string that can be used as-is as a single path
    310   // component of a URL.  A slug must only use ASCII alphanumeric
    311   // characters ("A-Z", "a-z", "0-9") and the five punctuation
    312   // characters "-", ".", "_", ":" and "~".  Consequently a slug
    313   // never contains a "/" and never requires percent-encoding.
    314   // The strings "." and ".." are not valid slugs, as they have a
    315   // special meaning in URL paths.
    316   // Slugs are case-sensitive.  Individual endpoints may impose
    317   // additional restrictions on the slugs they accept; those are
    318   // documented with the respective endpoint or field.
    319   type Slug = string;
    320 
    321 A slug is thus the set of RFC 3986 *unreserved* characters, plus ``:``.  The
    322 character set is deliberately narrower than what RFC 3986 permits in a path
    323 segment: it excludes ``@`` and all sub-delimiters, which are legal in a URL
    324 path but cause trouble once a slug is embedded in other syntax, such as a
    325 shell command, a query string or a filename.
    326 
    327 Note that a slug is *not* the same as an opaque identifier that merely happens
    328 to be a string: identifiers that may contain arbitrary characters (and thus
    329 require percent-encoding when put into a URL) are documented as plain
    330 ``string``.
    331 
    332 .. _weburl:
    333 
    334 Web URLs
    335 ^^^^^^^^
    336 
    337 Many fields point at another service or at a Web resource, such as the base
    338 URL of an exchange, the URL of a webhook or the fulfillment URL of an order.
    339 We call such a value a *Web URL*.
    340 
    341 .. ts:def:: WebURL
    342 
    343   // Non-empty string with an absolute URL that begins with either
    344   // "http://" or "https://" (the scheme is matched
    345   // case-insensitively).  A Web URL must only use ASCII alphanumeric
    346   // characters ("A-Z", "a-z", "0-9") and the punctuation characters
    347   // "/", ":", ";", "&", "?", "-", ".", ",", "=", "_", "~", "%", "+"
    348   // and "#".  Any other character (in particular spaces and all
    349   // non-ASCII characters) must be percent-encoded.
    350   // Individual endpoints may impose additional restrictions on the
    351   // Web URLs they accept; those are documented with the respective
    352   // endpoint or field.
    353   type WebURL = string;
    354 
    355 Fields that are documented as a *base URL* are Web URLs that additionally
    356 must end with a slash (``/``), so that the name of an endpoint can simply be
    357 appended to obtain the URL of that endpoint.
    358 
    359 Note that URIs using other schemes are *not* Web URLs.  In particular,
    360 ``payto://``-URIs (see :ref:`below <payto>`) and the ``taler://``-URIs handed
    361 to wallets have their own types or are documented as plain ``string``.
    362 
    363 .. _payto:
    364 
    365 
    366 Payto URIs:
    367 ^^^^^^^^^^^
    368 
    369 RFC 8905 defines payto://-URIs which GNU Taler uses to identify bank
    370 accounts. In GNU Taler, we primarily distinguish three types of
    371 payto://-URIs:
    372 
    373 * First, a **normalized** payto-URI uniquely identifies a bank account (or
    374   wallet) and must be able to serve as a canonical representation of such a
    375   bank account.  Thus, optional arguments such as the *receiver-name* or
    376   optional path components such as the BIC must be removed and the account
    377   must be given in a canonical form for the wire method (for example,
    378   everything in lower-case).
    379 
    380 * Second, a **full** payto-URI is not expected to have a canonical form for
    381   a bank account (there can be many full payto-URIs for the same bank
    382   account) and must include at least the *receiver-name* but possibly also
    383   other (in RFC 8905 optional) arguments to identify the recipient, as
    384   those may be needed to do a wire transfer.
    385 
    386 * On occasion, we also use full payto://-URIs that additionally specify the
    387   *amount* and wire transfer *subject* and are actually intended to trigger
    388   a wire transfer.
    389 
    390 
    391 .. _base32:
    392 
    393 Binary Data
    394 ^^^^^^^^^^^
    395 
    396 .. ts:def:: Base32
    397 
    398   type Base32 = string;
    399 
    400 Binary data is generally encoded using Crockford's variant of Base32
    401 (http://www.crockford.com/wrmg/base32.html), except that "U" is not excluded
    402 but also decodes to "V" to make OCR easy. Also, in contrast to Crockford, we
    403 do *not* allow the use of "-" and also do *not* allow the (optional) checksum
    404 from Crockford's proposal. So we really only use the alphabet, plus "u".  We
    405 will still simply use the JSON type "base32" and the term "Crockford Base32"
    406 in the text to refer to the resulting encoding.  Encoders and decoders
    407 can be found in libgnunetutil.
    408 
    409 
    410 Hash codes
    411 ^^^^^^^^^^
    412 
    413 Hash codes are strings representing base32 encoding of the respective
    414 hashed data. See `base32`_.
    415 
    416 .. ts:def:: HashCode
    417 
    418   // 64-byte hash code.
    419   type HashCode = string;
    420 
    421 .. ts:def:: ShortHashCode
    422 
    423   // 32-byte hash code.
    424   type ShortHashCode = string;
    425 
    426 .. ts:def:: AccountAccessToken
    427 
    428   // 32-byte nonce.
    429   type AccountAccessToken = string;
    430 
    431 .. ts:def:: WireSalt
    432 
    433   // 16-byte salt.
    434   type WireSalt = string;
    435 
    436 .. ts:def:: SHA256HashCode
    437 
    438    type SHA256HashCode = ShortHashCode;
    439 
    440 .. ts:def:: SHA512HashCode
    441 
    442    type SHA512HashCode = HashCode;
    443 
    444 .. ts:def:: CSNonce
    445 
    446    // 32-byte nonce value, must only be used once.
    447    type CSNonce = string;
    448 
    449 .. ts:def:: RefreshMasterSeed
    450 
    451    // 32-byte nonce value, must only be used once.
    452    type RefreshMasterSeed = string;
    453 
    454 .. ts:def:: RefreshCommitmentHash
    455 
    456     // A refresh commitment corresponding to a call to /melt.
    457     // See `TALER_RefreshCommitmentP` for the data it is computed over.
    458     type RefreshCommitmentHash = HashCode;
    459 
    460 .. ts:def:: BlindingMasterSeed
    461 
    462    // 32-byte nonce value, must only be used once.
    463    type BlindingMasterSeed = string;
    464 
    465 .. ts:def:: Cs25519Point
    466 
    467    // 32-byte value representing a point on Curve25519.
    468    type Cs25519Point = string;
    469 
    470 .. ts:def:: Cs25519Scalar
    471 
    472    // 32-byte value representing a scalar multiplier
    473    // for scalar operations on points on Curve25519.
    474    type Cs25519Scalar = string;
    475 
    476 
    477 Safe Integers
    478 ^^^^^^^^^^^^^
    479 
    480 For easier browser-side processing, we restrict some integers to
    481 the range that is safely representable in JavaScript.
    482 
    483 .. ts:def:: SafeUint64
    484 
    485   // Subset of numbers:  Integers in the
    486   // inclusive range 0 .. (2^53 - 1).
    487   type SafeUint64 = Integer;
    488 
    489 Large numbers
    490 ^^^^^^^^^^^^^
    491 
    492 Large numbers such as RSA blinding factors and 256 bit keys, are transmitted
    493 as other binary data in Crockford Base32 encoding.
    494 
    495 Decimal numbers
    496 ^^^^^^^^^^^^^^^
    497 
    498 ..
    499   FIXME: explain the representation with strings.
    500 
    501 .. ts:def:: DecimalNumber
    502 
    503    // Number with at most 8 fractional digits.
    504    type DecimalNumber = string;
    505 
    506 Timestamps
    507 ^^^^^^^^^^
    508 
    509 Timestamps are represented by the following structure:
    510 
    511 .. ts:def:: Timestamp
    512 
    513   interface Timestamp {
    514     // Seconds since epoch, or the special
    515     // value "never" to represent an event that will
    516     // never happen.
    517     t_s: Integer | "never";
    518   }
    519 
    520 .. ts:def:: RelativeTime
    521 
    522   interface RelativeTime {
    523     // Duration in microseconds or "forever"
    524     // to represent an infinite duration. Numeric
    525     // values are capped at 2^53 - 1 inclusive.
    526     d_us: Integer | "forever";
    527   }
    528 
    529 
    530 .. _public\ key:
    531 
    532 
    533 Integers
    534 ^^^^^^^^
    535 
    536 .. ts:def:: Integer
    537 
    538   // JavaScript numbers restricted to integers.
    539   type Integer = number;
    540 
    541 Floats
    542 ^^^^^^
    543 
    544 .. ts:def:: Float
    545 
    546   // JavaScript numbers.
    547   type Float = number;
    548 
    549 Ages
    550 ^^^^
    551 
    552 .. ts:def:: Age
    553 
    554    // An age is an integer between 0 and 255 measured in years.
    555    type Age = Integer;
    556 
    557 
    558 .. ts:def:: AgeMask
    559 
    560     // Binary representation of the age groups.
    561     // The bits set in the mask mark the edges at the beginning of a next age
    562     // group.  F.e. for the age groups
    563     //     0-7, 8-9, 10-11, 12-13, 14-15, 16-17, 18-20, 21-*
    564     // the following bits are set:
    565     //
    566     //   31     24        16        8         0
    567     //   |      |         |         |         |
    568     //   oooooooo  oo1oo1o1  o1o1o1o1  ooooooo1
    569     //
    570     // A value of 0 means that the exchange does not support the extension for
    571     // age-restriction.
    572     type AgeMask = Integer;
    573 
    574 .. ts:def:: AgeCommitmentHash
    575 
    576     // SHA-512 hash over the age commitment of a coin, that is over the
    577     // vector of `Edx25519PublicKey` values, one per age group.
    578     // Crockford `Base32` encoded.
    579     type AgeCommitmentHash = string;
    580 
    581 
    582 Versions
    583 ^^^^^^^^
    584 
    585 We use the type `LibtoolVersion` in the design documents to refer to a string
    586 that represents a version with the semantic as defined by
    587 `libtool <https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html>`__.
    588 
    589 .. ts:def:: LibtoolVersion
    590 
    591    // Version information in libtool version format and semantics
    592    // current[:revision[:age]], f.e. "1", "2:0" or "3:1:2".
    593    // see https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html.
    594    type LibtoolVersion = string;
    595 
    596 We use the type `SemVer` to refer to a string that represents a version with
    597 the semantic as defined by `semantic versioning <https://semver.org/>`__.
    598 
    599 .. ts:def:: SemVer
    600 
    601    // Version information in semantic versioning format and semantics,
    602    // like "X.Z.Y", see https://semver.org/.
    603    type SemVer = string;
    604 
    605 Objects
    606 ^^^^^^^
    607 
    608 .. ts:def:: Object
    609 
    610   // JavaScript objects, no further restrictions.
    611   type Object = object;
    612 
    613 
    614 Contact details
    615 ^^^^^^^^^^^^^^^
    616 
    617 .. ts:def:: EmailAddress
    618 
    619   type EmailAddress = string;
    620 
    621 .. ts:def:: PhoneNumber
    622 
    623   type PhoneNumber = string;
    624 
    625 Phone numbers should start with the ``+`` symbol and the country code.
    626 
    627 Permissions
    628 ^^^^^^^^^^^
    629 
    630 This type expresses which permissions for a subject
    631 apply on a resource.
    632 
    633 .. ts:def:: LibeufinPermission
    634 
    635   interface LibeufinPermission {
    636     subjectType: string;
    637     subjectId: string;
    638     resourceType: string;
    639     resourceId: string;
    640     permissionName: string
    641   }
    642 
    643 
    644 Fetch params
    645 ^^^^^^^^^^^^
    646 
    647 .. _fetch-params:
    648 
    649 .. ts:def:: FetchParams
    650 
    651   interface FetchParams {
    652 
    653     // Because transactions are delivered by banks in "batches",
    654     // then every batch can have different qualities.  This value
    655     // lets the request specify which type of batch ought to be
    656     // returned.  Currently, the following two type are supported:
    657     //
    658     // 'report': typically includes only non booked transactions.
    659     // 'statement': typically includes only booked transactions.
    660     level: "report" | "statement" | "all";
    661 
    662     // This type indicates the time range of the query.
    663     // It allows the following values:
    664     //
    665     // 'latest': retrieves the last transactions from the bank.
    666     //           If there are older unread transactions, those will *not*
    667     //           be downloaded.
    668     //
    669     // 'all': retrieves all the transactions from the bank,
    670     //        until the oldest.
    671     //
    672     // 'previous-days': currently *not* implemented, it will allow
    673     //                  the request to download transactions from
    674     //                  today until N days before.
    675     //
    676     // 'since-last': retrieves all the transactions since the last
    677     //               time one was downloaded.
    678     //
    679     rangeType: "latest" | "all" | "previous-days" | "since-last";
    680   };
    681 
    682 
    683 Keys
    684 ^^^^
    685 
    686 .. ts:def:: ClaimToken
    687 
    688   // 16-byte access token used to authorize access.
    689   type ClaimToken = string;
    690 
    691 .. ts:def:: EddsaPublicKey
    692 
    693    // EdDSA and ECDHE public keys always point on Curve25519
    694    // and represented  using the standard 256 bits Ed25519 compact format,
    695    // converted to Crockford `Base32`.
    696    type EddsaPublicKey = string;
    697 
    698 .. ts:def:: EddsaPrivateKey
    699 
    700    // EdDSA and ECDHE public keys always point on Curve25519
    701    // and represented  using the standard 256 bits Ed25519 compact format,
    702    // converted to Crockford `Base32`.
    703    type EddsaPrivateKey = string;
    704 
    705 .. ts:def:: Edx25519PublicKey
    706 
    707    // Edx25519 public keys are points on Curve25519 and represented using the
    708    // standard 256 bits Ed25519 compact format converted to Crockford
    709    // `Base32`.
    710    type Edx25519PublicKey = string;
    711 
    712 .. ts:def:: Edx25519PrivateKey
    713 
    714    // Edx25519 private keys are always points on Curve25519
    715    // and represented using the standard 256 bits Ed25519 compact format,
    716    // converted to Crockford `Base32`.
    717    type Edx25519PrivateKey = string;
    718 
    719 .. ts:def:: EcdhePublicKey
    720 
    721    // EdDSA and ECDHE public keys always point on Curve25519
    722    // and represented  using the standard 256 bits Ed25519 compact format,
    723    // converted to Crockford `Base32`.
    724    type EcdhePublicKey = string;
    725 
    726 .. ts:def:: CSRPublic
    727 
    728    // Point on Curve25519 represented using the standard 256 bits Ed25519 compact format,
    729    // converted to Crockford `Base32`.
    730    type CSRPublic = string;
    731 
    732 .. ts:def:: EcdhePrivateKey
    733 
    734    // EdDSA and ECDHE public keys always point on Curve25519
    735    // and represented  using the standard 256 bits Ed25519 compact format,
    736    // converted to Crockford `Base32`.
    737    type EcdhePrivateKey = string;
    738 
    739 .. ts:def:: CoinPublicKey
    740 
    741    type CoinPublicKey = EddsaPublicKey;
    742 
    743 .. ts:def:: RsaPublicKey
    744 
    745    // RSA public key converted to Crockford `Base32`.
    746    type RsaPublicKey = string;
    747 
    748 .. ts:def:: PursePublicKey
    749 
    750    type PursePublicKey = EddsaPublicKey;
    751 
    752 
    753 .. _blinded-coin:
    754 
    755 Blinded coin
    756 ^^^^^^^^^^^^
    757 
    758 .. ts:def:: CoinEnvelope
    759 
    760   // The type of a coin's blinded envelope depends on the cipher that is used
    761   // for signing with a denomination key.
    762   type CoinEnvelope = RSACoinEnvelope | CSCoinEnvelope ;
    763 
    764 .. ts:def:: RSACoinEnvelope
    765 
    766   // For denomination signatures based on RSA, the planchet is just a blinded
    767   // coin's `public EdDSA key <eddsa-coin-pub>`.
    768   interface RSACoinEnvelope {
    769     cipher: "RSA" | "RSA+age_restricted";
    770     rsa_blinded_planchet: BlindedRsaSignature;
    771   }
    772 
    773 .. ts:def:: CSCoinEnvelope
    774 
    775   // For denomination signatures based on Blind Clause-Schnorr, the planchet
    776   // consists of the public nonce and two Curve25519 scalars which are two
    777   // blinded challenges in the Blinded Clause-Schnorr signature scheme.
    778   // See https://taler.net/papers/cs-thesis.pdf for details.
    779   interface CSCoinEnvelope {
    780     cipher: "CS" | "CS+age_restricted";
    781 
    782     // Session nonce, Crockford `Base32` encoded.  In a withdraw or melt
    783     // request it MUST be the nonce derived from the request's
    784     // ``blinding_seed`` for the coin's index i in ``denoms_h``:
    785     // HKDF (salt = i as 32-bit unsigned integer in network byte order,
    786     // ikm = "withdraw-n" for a withdrawal or "refresh-n" for a melt,
    787     // info = ``blinding_seed``), the same for every batch of the coin.
    788     // The exchange refuses an envelope with another nonce (400): the
    789     // exchange signs under the nonce of the envelope, and two different
    790     // blinded challenges signed under one nonce reveal the denomination's
    791     // private key.
    792     cs_nonce: string;
    793     cs_blinded_c0: string; // Crockford `Base32` encoded
    794     cs_blinded_c1: string; // Crockford `Base32` encoded
    795   }
    796 
    797 .. _unblinded-coin:
    798 
    799 Unblinded coin
    800 ^^^^^^^^^^^^^^
    801 
    802 .. ts:def:: UnblindedSignature
    803 
    804   // The type of a coin's unblinded signature depends on the cipher that was used
    805   // for signing with a denomination key.
    806   // Note that for now, only RSA is supported.
    807   type UnblindedSignature = RsaUnblindedSignature | CsUnblindedSignature;
    808 
    809 .. ts:def:: RsaUnblindedSignature
    810 
    811   interface RsaUnblindedSignature {
    812     cipher: "RSA";
    813     rsa_signature: RsaSignature;
    814   }
    815 
    816 .. ts:def:: CsUnblindedSignature
    817 
    818   // Note, this is here for the sake of completeness, but not yet supported
    819   interface CsUnblindedSignature {
    820     cipher: "CS";
    821 
    822     cs_signature_r: Cs25519Point;
    823     cs_signature_s: Cs25519Scalar;
    824   }
    825 
    826 
    827 .. _signature:
    828 
    829 Signatures
    830 ^^^^^^^^^^
    831 
    832 
    833 .. ts:def:: EddsaSignature
    834 
    835   // EdDSA signatures are transmitted as 64-bytes `base32`
    836   // binary-encoded objects with just the R and S values (base32_ binary-only).
    837   type EddsaSignature = string;
    838 
    839 .. ts:def:: Edx25519Signature
    840 
    841   // Edx25519 signatures are transmitted as 64-bytes `base32`
    842   // binary-encoded objects with just the R and S values (base32_ binary-only).
    843   type Edx25519Signature = string;
    844 
    845 .. ts:def:: RsaSignature
    846 
    847   // `base32` encoded RSA signature.
    848   type RsaSignature = string;
    849 
    850 .. ts:def:: BlindedRsaSignature
    851 
    852   // `base32` encoded RSA blinded signature.
    853   type BlindedRsaSignature = string;
    854 
    855 .. ts:def:: RsaBlindingKeySecret
    856 
    857   // `base32` encoded RSA blinding secret.
    858   type RsaBlindingKeySecret = string;
    859 
    860 .. ts:def:: DenominationBlindingKeySecret
    861 
    862   // Union, not (!) discriminated!
    863   type DenominationBlindingKeySecret =
    864     | RsaBlindingKeySecret
    865     | CsBlindingKeySecret;
    866 
    867 .. ts:def:: CsBlindingKeySecret
    868 
    869   // 32-byte secret from which the Clause-Schnorr blinding
    870   // scalars of a coin are derived, Crockford `Base32` encoded.
    871   type CsBlindingKeySecret = string;
    872 
    873 
    874 .. ts:def:: DenomCipher
    875 
    876    interface DenomCipher = {
    877      // specifier for the ciper
    878      cipher: string;
    879    }
    880 
    881 .. ts:def:: BlindedDenominationSignature
    882 
    883   type BlindedDenominationSignature = DenomCipher & (
    884     | RsaBlindedDenominationSignature
    885     | CSBlindedDenominationSignature
    886   )
    887 
    888 .. ts:def:: RsaBlindedDenominationSignature
    889 
    890   interface RsaBlindedDenominationSignature extends DenomCipher {
    891     cipher: "RSA";
    892 
    893     // (blinded) RSA signature
    894     blinded_rsa_signature: BlindedRsaSignature;
    895   }
    896 
    897 .. ts:def:: CSBlindedDenominationSignature
    898 
    899   interface CSBlindedDenominationSignature extends DenomCipher {
    900     cipher: "CS";
    901 
    902     // Signer chosen bit value, 0 or 1, used
    903     // in Clause Blind Schnorr to make the
    904     // ROS problem harder.
    905     b: Integer;
    906 
    907     // Blinded scalar calculated from c_b.
    908     s: Cs25519Scalar;
    909 
    910   }
    911 .. ts:def:: PurseContractSignature
    912 
    913    type PurseContractSignature = EddsaSignature
    914 
    915 
    916 .. _amount:
    917 
    918 Amounts
    919 ^^^^^^^
    920 
    921 Amounts of currency are always expressed in terms of a base value, a
    922 fractional value and the denomination of the currency.
    923 
    924 .. ts:def:: Amount
    925 
    926   type Amount = string;
    927 
    928 Amounts of currency are serialized as a string of the format
    929 ``<Currency>:<DecimalAmount>``.  Taler treats monetary amounts as
    930 fixed-precision numbers, with 8 decimal places.  Unlike floating point numbers,
    931 this allows accurate representation of monetary amounts.
    932 
    933 The following constraints apply for a valid amount:
    934 
    935 1. The ``<Currency>`` part must be at most 11 characters long and may only consist
    936    of ASCII letters (``a-zA-Z``).
    937 2. The integer part of ``<DecimalAmount>`` may be at most 2^52.
    938 3. The fractional part of ``<DecimalAmount>`` may contain at most 8 decimal digits.
    939 
    940 .. note::
    941 
    942   "EUR:1.50" and "EUR:10" are valid amounts.  These are all invalid amounts: "A:B:1.5", "EUR:4503599627370501.0", "EUR:1.", "EUR:.1".
    943 
    944 An amount that is prefixed with a ``+`` or ``-`` character is also used in certain contexts.
    945 When no sign is present, the amount is assumed to be positive.
    946 
    947 .. note::
    948 
    949   In some setups, when Libeufin-Bank offers cashouts towards traditional
    950   currencies like EUR for example, the fractional part gets restricted
    951   to at most 2 digits.
    952 
    953 .. ts:def:: SignedAmount
    954 
    955   type SignedAmount = string;
    956 
    957 .. sourcecode:: c
    958 
    959   struct TALER_AmountNBO {
    960     // Non-negative integer value in the currency (in network byte order),
    961     // can be at most 2^52.
    962     // Note that "1" here would correspond to 1 EUR or 1 USD,
    963     // depending on `currency`, not 1 cent.
    964     uint64_t value;
    965 
    966     // Unsigned 32 bit fractional value (in network byte order)
    967     // to be added to ``value`` representing
    968     // an additional currency fraction, in units of one hundred millionth (1e-8)
    969     // of the base currency value.  For example, a fraction
    970     // of 50,000,000 would correspond to 50 cents.
    971     uint32_t fraction;
    972 
    973     // Name of the currency, using either a three-character ISO 4217 currency
    974     // code, or a regional currency identifier between 4 and 11 characters,
    975     // consisting of ASCII alphabetic characters ("a-zA-Z").
    976     // Should be padded to 12 bytes with 0-characters.
    977     // Currency codes are compared case-insensitively.
    978     uint8_t currency_code[12];
    979   };
    980 
    981 
    982 Images
    983 ^^^^^^
    984 
    985 .. ts:def:: ImageDataUrl
    986 
    987   // The string must be a data URL according to RFC 2397
    988   // with explicit mediatype and base64 parameters.
    989   //
    990   //     ``data:<mediatype>;base64,<data>``
    991   //
    992   // Supported mediatypes are ``image/jpeg`` and ``image/png``.
    993   // Invalid strings will be rejected by the wallet.
    994   type ImageDataUrl = string;
    995 
    996 
    997 --------------
    998 Binary Formats
    999 --------------
   1000 
   1001 .. note::
   1002 
   1003    Due to the way of handling "big" numbers by some platforms (such as
   1004    JavaScript, for example), wherever the following specification mentions
   1005    a 64-bit value, the actual implementations are strongly advised to rely on
   1006    arithmetic up to 53 bits.
   1007 
   1008 .. note::
   1009 
   1010    Taler uses ``libgnunetutil`` for interfacing itself with the operating system,
   1011    doing crypto work, and other "low level" actions, therefore it is strongly
   1012    connected with the `GNUnet project <https://gnunet.org>`_.
   1013 
   1014 This section specifies the binary representation of messages used in Taler's
   1015 protocols. The message formats are given in a C-style pseudocode notation.
   1016 Padding is always specified explicitly, and numeric values are in network byte
   1017 order (big endian).
   1018 
   1019 
   1020 Time
   1021 ^^^^
   1022 
   1023 In signed messages, time is represented using 64-bit big-endian values,
   1024 denoting microseconds since the UNIX Epoch.  ``UINT64_MAX`` represents "never".
   1025 
   1026 .. sourcecode:: c
   1027 
   1028   struct GNUNET_TIME_Absolute {
   1029     uint64_t timestamp_us;
   1030   };
   1031   struct GNUNET_TIME_AbsoluteNBO {
   1032     uint64_t abs_value_us__;       // in network byte order
   1033   };
   1034 
   1035 .. sourcecode:: c
   1036 
   1037   struct GNUNET_TIME_Relative {
   1038     uint64_t timestamp_us;
   1039   };
   1040   struct GNUNET_TIME_RelativeNBO {
   1041     uint64_t rel_value_us__;       // in network byte order
   1042   };
   1043 
   1044 For certain statistics, we need to express relative time
   1045 in ways that correspond exactly to the calendar. So while
   1046 constants like ``GNUNET_TIME_UNIT_MONTH`` are defined to
   1047 mean 30 days, we cannot do this when tracking income for
   1048 a merchant over a calendar year. Thus, in this case,
   1049 we use the `StatisticBucketRange` when rounding time to
   1050 values that cannot be expressed as fixed multiples of
   1051 seconds:
   1052 
   1053 .. ts:def:: StatisticBucketRange
   1054 
   1055     type MerchantStatisticCounterByBucket =
   1056       "decade" | "year" | "quarter" | "month" | "week" | "day" | "hour" | "minute" | "second";
   1057 
   1058 .. _LegalTrouble:
   1059 
   1060 451 Responses
   1061 ^^^^^^^^^^^^^
   1062 
   1063 When KYC operations are required, various endpoints may respond with a
   1064 ``451 Unavailable for Legal Reasons`` status code and a `LegitimizationNeededResponse`
   1065 body.
   1066 
   1067 .. ts:def:: LegitimizationNeededResponse
   1068 
   1069   // Implemented in this style since exchange
   1070   // protocol **v20**.
   1071   interface LegitimizationNeededResponse {
   1072 
   1073     // Numeric `error code <error-codes>` unique to the condition.
   1074     // Should always be ``TALER_EC_EXCHANGE_GENERIC_KYC_REQUIRED``.
   1075     code: Integer;
   1076 
   1077     // Human-readable description of the error, i.e. "missing parameter",
   1078     // "commitment violation", ...  Should give a human-readable hint
   1079     // about the error's nature. Optional, may change without notice!
   1080     hint?: string;
   1081 
   1082     // Hash of the payto:// account URI for which KYC
   1083     // is required.
   1084     // The account holder can use the ``/kyc-check/$H_PAYTO``
   1085     // endpoint to check the KYC status or initiate the KYC process.
   1086     h_payto: NormalizedPaytoHash;
   1087 
   1088     // Public key associated with the account. The client must sign
   1089     // the initial request for the KYC status using the corresponding
   1090     // private key.  Will be either a reserve public key or a merchant
   1091     // (instance) public key.
   1092     //
   1093     // Absent if no public key is currently associated
   1094     // with the account and the client MUST thus first
   1095     // credit the exchange via an inbound wire transfer
   1096     // to associate a public key with the debited account.
   1097     account_pub?: EddsaPublicKey;
   1098 
   1099     // Identifies a set of measures that were triggered and that are
   1100     // now preventing this operation from proceeding.  Gives developers
   1101     // a starting point for understanding why the transaction was
   1102     // blocked and how to lift it.
   1103     // Can be zero (which means there is no requirement row),
   1104     // especially if ``bad_kyc_auth`` is set.
   1105     requirement_row: Integer;
   1106 
   1107     // True if the operation was denied because the
   1108     // KYC auth key does not match the merchant public
   1109     // key.  In this case, a KYC auth wire transfer
   1110     // with the merchant public key must be performed
   1111     // first.
   1112     // Since exchange protocol **v21**.
   1113     bad_kyc_auth?: boolean;
   1114 
   1115   }
   1116 
   1117 
   1118 Cryptographic primitives
   1119 ^^^^^^^^^^^^^^^^^^^^^^^^
   1120 
   1121 All elliptic curve operations are on Curve25519.  Public and private keys are
   1122 thus 32 bytes, and signatures 64 bytes.  For hashing, including HKDFs, Taler
   1123 uses 512-bit hash codes (64 bytes).
   1124 
   1125 .. _HashCode:
   1126 .. sourcecode:: c
   1127 
   1128    struct GNUNET_HashCode {
   1129      uint8_t hash[64];      // usually SHA-512
   1130    };
   1131 
   1132 .. sourcecode:: c
   1133 
   1134    struct TALER_DenominationHash {
   1135      struct GNUNET_HashCode hash;
   1136    };
   1137 
   1138 .. sourcecode:: c
   1139 
   1140    struct TALER_PrivateContractHash {
   1141      struct GNUNET_HashCode hash;
   1142    };
   1143 
   1144 .. sourcecode:: c
   1145 
   1146    struct TALER_ExtensionsPolicyHash {
   1147      struct GNUNET_HashCode hash;
   1148    };
   1149 
   1150 .. sourcecode:: c
   1151 
   1152    struct TALER_MerchantWireHash {
   1153      struct GNUNET_HashCode hash;
   1154    };
   1155 
   1156 .. _FullPaytoHash:
   1157 .. sourcecode:: c
   1158 
   1159    struct TALER_FullPaytoHash {
   1160      // Hash over a full payto://-URI, including receiver-name
   1161      // (and possibly BIC and other optional fields).
   1162      struct GNUNET_ShortHashCode hash;
   1163    };
   1164 
   1165 .. _NormalizedPaytoHash:
   1166 .. sourcecode:: c
   1167 
   1168    struct TALER_NormalizedPaytoHash {
   1169      // Hash over a normalized payto://-URI, including all optional
   1170      // fields and also with account-part canonicalized (so no BIC).
   1171      struct GNUNET_ShortHashCode hash;
   1172    };
   1173 
   1174 .. _BlindedCoinHash:
   1175 .. sourcecode:: c
   1176 
   1177    struct TALER_BlindedCoinHash {
   1178      // Hash over a) the hash of the denomination's public key,
   1179      // b) an enum value identifying the cipher, and
   1180      // c) cipher-dependant blinded information.
   1181      // See implementation of `TALER_coin_ev_hash`
   1182      // in libtalerexchange for details.
   1183      struct GNUNET_HashCode hash;
   1184    };
   1185 
   1186 .. sourcecode:: c
   1187 
   1188    struct TALER_CoinPubHash {
   1189      struct GNUNET_HashCode hash;
   1190    };
   1191 
   1192 .. sourcecode:: c
   1193 
   1194    struct TALER_OutputCommitmentHash {
   1195      struct GNUNET_HashCode hash;
   1196    };
   1197 
   1198 
   1199 .. _TALER_EcdhEphemeralPublicKeyP:
   1200 .. sourcecode:: c
   1201 
   1202    struct TALER_EcdhEphemeralPublicKeyP {
   1203      uint8_t ecdh_pub[32];
   1204    };
   1205 
   1206 .. _reserve-pub:
   1207 .. sourcecode:: c
   1208 
   1209    struct TALER_ReservePublicKeyP {
   1210      uint8_t eddsa_pub[32];
   1211    };
   1212 
   1213 .. _reserve-priv:
   1214 .. sourcecode:: c
   1215 
   1216    struct TALER_ReservePrivateKeyP {
   1217      uint8_t eddsa_priv[32];
   1218    };
   1219 
   1220    struct TALER_ReserveSignatureP {
   1221      uint8_t eddsa_signature[64];
   1222    };
   1223 
   1224 .. _merchant-pub:
   1225 .. sourcecode:: c
   1226 
   1227    struct TALER_MerchantPublicKeyP {
   1228      uint8_t eddsa_pub[32];
   1229    };
   1230 
   1231    struct TALER_MerchantPrivateKeyP {
   1232      uint8_t eddsa_priv[32];
   1233    };
   1234 
   1235    struct TALER_TransferPublicKeyP {
   1236      uint8_t ecdhe_pub[32];
   1237    };
   1238 
   1239    struct TALER_TransferPrivateKeyP {
   1240      uint8_t ecdhe_priv[32];
   1241    };
   1242 
   1243 
   1244 .. _AmlDecisionState:
   1245 .. sourcecode:: c
   1246 
   1247    enum TALER_AmlDecisionState {
   1248      NORMAL, PENDING, FROZEN
   1249    };
   1250 
   1251 .. _AmlOfficerPublicKeyP:
   1252 .. sourcecode:: c
   1253 
   1254    struct TALER_AmlOfficerPublicKeyP {
   1255      uint8_t eddsa_pub[32];
   1256    };
   1257 
   1258 .. _AmlOfficerPrivateKeyP:
   1259 .. sourcecode:: c
   1260 
   1261    struct TALER_AmlOfficerPrivateKeyP {
   1262      uint8_t eddsa_priv[32];
   1263    };
   1264 
   1265 .. _sign-key-pub:
   1266 .. sourcecode:: c
   1267 
   1268    struct TALER_ExchangePublicKeyP {
   1269      uint8_t eddsa_pub[32];
   1270    };
   1271 
   1272 .. _sign-key-priv:
   1273 .. sourcecode:: c
   1274 
   1275    struct TALER_ExchangePrivateKeyP {
   1276      uint8_t eddsa_priv[32];
   1277    };
   1278 
   1279 .. _eddsa-sig:
   1280 .. sourcecode:: c
   1281 
   1282    struct TALER_ExchangeSignatureP {
   1283      uint8_t eddsa_signature[64];
   1284    };
   1285 
   1286    struct TALER_MasterPublicKeyP {
   1287      uint8_t eddsa_pub[32];
   1288    };
   1289 
   1290    struct TALER_MasterPrivateKeyP {
   1291      uint8_t eddsa_priv[32];
   1292    };
   1293 
   1294     struct TALER_MasterSignatureP {
   1295      uint8_t eddsa_signature[64];
   1296    };
   1297 
   1298 .. _WireTransferIdentifierRawP:
   1299 .. sourcecode:: c
   1300 
   1301    struct WireTransferIdentifierRawP {
   1302      uint8_t raw[32];
   1303    };
   1304 
   1305 .. _UUID:
   1306 .. sourcecode:: c
   1307 
   1308    struct UUID {
   1309      uint32_t value[4];
   1310    };
   1311 
   1312 .. _WadId:
   1313 .. sourcecode:: c
   1314 
   1315    struct TALER_WadId wad_id {
   1316      uint32_t value[6];
   1317    };
   1318 
   1319 .. _eddsa-coin-pub:
   1320 .. sourcecode:: c
   1321 
   1322    union TALER_CoinSpendPublicKeyP {
   1323      uint8_t eddsa_pub[32];
   1324      uint8_t ecdhe_pub[32];
   1325    };
   1326 
   1327 .. _coin-priv:
   1328 .. sourcecode:: c
   1329 
   1330    union TALER_CoinSpendPrivateKeyP {
   1331      uint8_t eddsa_priv[32];
   1332      uint8_t ecdhe_priv[32];
   1333    };
   1334 
   1335    struct TALER_CoinSpendSignatureP {
   1336      uint8_t eddsa_signature[64];
   1337    };
   1338 
   1339    struct TALER_TransferSecretP {
   1340      uint8_t key[sizeof (struct GNUNET_HashCode)];
   1341    };
   1342 
   1343    struct TALER_EncryptedLinkSecretP {
   1344      uint8_t enc[sizeof (struct TALER_LinkSecretP)];
   1345    };
   1346 
   1347 .. _eddsa-token-pub:
   1348 .. sourcecode:: c
   1349 
   1350    union TALER_TokenPublicKeyP {
   1351      uint8_t eddsa_pub[32];
   1352      uint8_t ecdhe_pub[32];
   1353    };
   1354 
   1355 .. _account-pub:
   1356 .. sourcecode:: c
   1357 
   1358    union TALER_AccountPublicKeyP {
   1359      struct TALER_ReservePublicKeyP reserve_pub;
   1360      struct TALER_MerchantPublicKeyP merchant_pub;
   1361    };
   1362 
   1363 .. _Signatures:
   1364 
   1365 Signatures
   1366 ^^^^^^^^^^
   1367 
   1368 Any piece of signed data complies with the abstract data structure given below.
   1369 
   1370 .. sourcecode:: c
   1371 
   1372   struct Data {
   1373     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1374     type1_t payload1;
   1375     type2_t payload2;
   1376     ...
   1377   };
   1378 
   1379   /*From gnunet_crypto_lib.h*/
   1380   struct GNUNET_CRYPTO_EccSignaturePurpose {
   1381     /**
   1382      * This field equals the number of bytes being signed,
   1383      * namely 'sizeof (struct Data)'.
   1384      */
   1385     uint32_t size;
   1386     /**
   1387      * This field is used to express the context in
   1388      * which the signature is made, ensuring that a
   1389      * signature cannot be lifted from one part of the protocol
   1390      * to another. See `src/include/taler_signatures.h` within the
   1391      * exchange's codebase (git://taler.net/exchange).
   1392      */
   1393     uint32_t purpose;
   1394   };
   1395 
   1396 
   1397 The following list contains all the data structures that can be signed in
   1398 Taler. Their definition is typically found in ``src/include/taler_signatures.h``,
   1399 within the
   1400 `exchange's codebase <https://docs.taler.net/global-licensing.html#exchange-repo>`_.
   1401 
   1402 
   1403 
   1404 .. _TALER_HashPlanchetsP:
   1405 .. sourcecode:: c
   1406 
   1407   /**
   1408    * This is the running SHA512-hash over all
   1409    * `TALER_BlindedCoinHashP` values of an array of coins.
   1410    * Note that each `TALER_BlindedCoinHashP` itself
   1411    * captures the hash of the corresponding denomination's
   1412    * public key.
   1413    */
   1414   struct TALER_HashPlanchetsP {
   1415     struct GNUNET_HashCode hash;
   1416   };
   1417 
   1418 
   1419 .. _TALER_AgeMask:
   1420 .. sourcecode:: c
   1421 
   1422   /**
   1423    * Binary representation of the age groups.
   1424    * The bits set in the mask mark the edges at the beginning of a next age
   1425    * group.  F.e. for the age groups
   1426    *     0-7, 8-9, 10-11, 12-13, 14-15, 16-17, 18-20, 21-*
   1427    * the following bits are set:
   1428    *
   1429    *   31     24        16        8         0
   1430    *   |      |         |         |         |
   1431    *   oooooooo  oo1oo1o1  o1o1o1o1  ooooooo1
   1432    *
   1433    * A value of 0 means that the exchange does not support the extension for
   1434    * age-restriction.
   1435    */
   1436    struct TALER_AgeMask {
   1437        uint32_t mask;
   1438    };
   1439 
   1440 
   1441 
   1442 .. _TALER_WithdrawRequestPS:
   1443 .. sourcecode:: c
   1444 
   1445   /**
   1446    * Format used for to generate the signature on a request to withdraw
   1447    * coins from a reserve.
   1448    */
   1449   struct TALER_WithdrawRequestPS
   1450   {
   1451     /**
   1452      * Purpose is #TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
   1453      */
   1454     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1455     /**
   1456      * Amount to withdraw, excluding fees, i.e.
   1457      * the total sum of the denominations of the coins.
   1458      * Note that the reserve must have a value of at least amount+fee.
   1459      */
   1460     struct TALER_Amount amount;
   1461     /**
   1462      * Total fee for the withdrawal.
   1463      * Note that the reserve must have a value of at least amount+fee.
   1464      */
   1465     struct TALER_Amount fee;
   1466     /**
   1467      * If max_age was not set in the withdraw request, this is
   1468      * the running SHA512-hash over the n `TALER_BlindedCoinHashP`
   1469      * values of the coins, in the order of the request.
   1470      * Note that each `TALER_BlindedCoinHashP` itself
   1471      * captures the hash of the corresponding denomination's
   1472      * public key.
   1473      * If max_age was set in the withdraw request, the n*κ coins
   1474      * form κ batches of n coins each, the first n coins belonging
   1475      * to κ index=0, the next n to κ index=1 etc.  For each batch
   1476      * the running SHA512-hash over its n `TALER_BlindedCoinHashP`
   1477      * values is computed, and this value is the running
   1478      * SHA512-hash over the κ batch hashes:
   1479      * H( H(h[0][0]…h[0][n-1]) … H(h[κ-1][0]…h[κ-1][n-1]) ).
   1480      *
   1481      * Note also that this value is required for /recoup-withdraw and
   1482      * -- in case of a withdraw request with required age proof --
   1483      * in the subsequent call to /reveal-withdraw
   1484      */
   1485     struct TALER_HashPlanchetsP h_planchets;
   1486     /**
   1487      * The master seed that was used in the call to /blinding-prepare blinding,
   1488      * or all zeros, if no denomination of cipher type Clause-Schnorr is used.
   1489      */
   1490      struct TALER_BlindingMasterSecretP blinding_seed;
   1491     /**
   1492      * If age restriction proof is required, the maximum age _group_
   1493      * to commit to, 0 otherwise. Note that in this case, all
   1494      * denominations for all coins MUST support age restriction.
   1495      * Also note that this is not an age (in years), but the age group
   1496      * (an index) according to list of age groups in the configuration
   1497      * of the exchange.  See TALER_get_max_group() how to calculate
   1498      * the age group to a given age (in years).
   1499      */
   1500     uint32_t max_age_group;
   1501     /**
   1502      * The age groups as configured for the exchange, represented as a mask.
   1503      * If max_age_group is > 0, the mask MUST be non-zero, too.
   1504      */
   1505     struct TALER_AgeMask mask;
   1506   };
   1507 
   1508 .. _TALER_WithdrawConfirmationPS:
   1509 
   1510 .. sourcecode:: c
   1511 
   1512   struct TALER_WithdrawConfirmationPS
   1513   {
   1514     /**
   1515      * Purpose is #TALER_SIGNATURE_EXCHANGE_CONFIRM_WITHDRAW.
   1516      * Signed by a `struct TALER_ExchangePrivateKeyP` using EdDSA.
   1517      */
   1518     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1519 
   1520     /**
   1521      * Commitment made in the /withdraw request.
   1522      * Also needed for the /reveal-withdraw endpoint (in case
   1523      * of required proof of age restriction) and for /recoup-withdraw
   1524      */
   1525     struct TALER_HashBlindedPlanchetsP h_planchets;
   1526 
   1527     /**
   1528      * If proof of age restriction is not required for to this
   1529      * withdrawal, (i.e. max_age was not set during the request)
   1530      * MUST be 0xFFFFFFFF.
   1531      * Otherwise (i.e. proof of age restriction required):
   1532      * index that the client will not have to reveal, in NBO,
   1533      * MUST be smaller than #TALER_CNC_KAPPA.
   1534      */
   1535     uint32_t noreveal_index;
   1536 
   1537   };
   1538 
   1539 
   1540 .. _TALER_SingleWithdrawRequestPS:
   1541 .. sourcecode:: c
   1542 
   1543   struct TALER_SingleWithdrawRequestPS {
   1544     /**
   1545      * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
   1546      */
   1547     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1548     struct TALER_AmountNBO amount_with_fee;
   1549     struct TALER_DenominationHash h_denomination_pub;
   1550     struct TALER_BlindedCoinHash h_coin_envelope;
   1551   };
   1552 
   1553 
   1554 .. _taler_depositrequestps:
   1555 
   1556 .. sourcecode:: c
   1557 
   1558   struct TALER_DepositRequestPS {
   1559     /**
   1560      * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_DEPOSIT
   1561      */
   1562     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1563     struct TALER_PrivateContractHash h_contract_terms;
   1564     struct TALER_AgeCommitmentHash h_age_commitment;
   1565     struct TALER_ExtensionsPolicyHash h_policy;
   1566     struct TALER_MerchantWireHash h_wire;
   1567     struct TALER_DenominationHash h_denom_pub;
   1568     struct GNUNET_TIME_AbsoluteNBO timestamp;
   1569     struct GNUNET_TIME_AbsoluteNBO refund_deadline;
   1570     struct TALER_AmountNBO amount_with_fee;
   1571     struct TALER_AmountNBO deposit_fee;
   1572     struct TALER_MerchantPublicKeyP merchant;
   1573     struct GNUNET_HashCode wallet_data_hash;
   1574   };
   1575 
   1576 .. _TALER_DepositConfirmationPS:
   1577 
   1578 .. sourcecode:: c
   1579 
   1580   struct TALER_DepositConfirmationPS {
   1581     /**
   1582      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT
   1583      */
   1584     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1585     struct TALER_PrivateContractHash h_contract_terms;
   1586     struct TALER_MerchantWireHash h_wire;
   1587     struct TALER_ExtensionsPolicyHash h_policy;
   1588     struct GNUNET_TIME_AbsoluteNBO timestamp;
   1589     struct GNUNET_TIME_AbsoluteNBO refund_deadline;
   1590     struct TALER_AmountNBO amount_without_fee;
   1591     union TALER_CoinSpendPublicKeyP coin_pub;
   1592     struct TALER_MerchantPublicKeyP merchant;
   1593   };
   1594 
   1595 
   1596 .. _TALER_RefreshCommitmentP:
   1597 .. sourcecode:: c
   1598 
   1599   struct TALER_RefreshCommitmentP {
   1600     /**
   1601      * SHA-512 hash over the concatenation of:
   1602      *   1. the refresh_seed of the /melt request (64 bytes),
   1603      *   2. @since v45 (ignored for earlier protocol versions, see below):
   1604      *      the kappa * n transfer public keys of the /melt request
   1605      *      (32 bytes each), batch by batch:
   1606      *      [0][0..n), [1][0..n), ..., [kappa-1][0..n),
   1607      *   3. the blinding_seed of the /melt request (32 bytes) if one
   1608      *      of the fresh coins is of a Clause-Schnorr denomination,
   1609      *      otherwise 32 zero bytes,
   1610      *   4. the public key of the old coin (32 bytes),
   1611      *   5. the amount with fee, as `TALER_AmountNBO`,
   1612      *   6. kappa `TALER_HashPlanchetsP` (64 bytes each), one for each
   1613      *      batch k = 0..kappa-1, over the n `TALER_BlindedCoinHashP`
   1614      *      of the fresh coin candidates of the batch.
   1615      *
   1616      * Clients MUST include step 2 if the exchange announces protocol
   1617      * v45 or later in /config and /keys, and MUST NOT include it for
   1618      * exchanges of earlier protocol versions, which do not accept the
   1619      * transfer public keys in the commitment (even though clients
   1620      * since v32 send them in the /melt request).
   1621      *
   1622      * For compatibility with older clients, exchanges since v45 also
   1623      * accept the commitment without step 2.  A later protocol version
   1624      * will stop accepting it for new melts.
   1625      */
   1626      struct GNUNET_HashCode session_hash;
   1627  };
   1628 
   1629 .. _TALER_RefreshMeltCoinAffirmationPS:
   1630 .. sourcecode:: c
   1631 
   1632   struct TALER_RefreshMeltCoinAffirmationPS {
   1633     /**
   1634      * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_MELT
   1635      */
   1636     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1637     struct TALER_RefreshCommitmentP session_hash;
   1638     struct TALER_DenominationHash h_denom_pub;
   1639     struct TALER_AgeCommitmentHash h_age_commitment;
   1640     struct TALER_AmountNBO amount_with_fee;
   1641     struct TALER_AmountNBO melt_fee;
   1642   };
   1643 
   1644 .. _TALER_RefreshMeltConfirmationPS:
   1645 .. sourcecode:: c
   1646 
   1647   struct TALER_RefreshMeltConfirmationPS {
   1648     /**
   1649      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_MELT
   1650      */
   1651     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1652     struct TALER_RefreshCommitmentP session_hash;
   1653     // in network byte order
   1654     uint32_t noreveal_index;
   1655   };
   1656 
   1657 .. _TALER_ExchangeSigningKeyValidityPS:
   1658 .. sourcecode:: c
   1659 
   1660   struct TALER_ExchangeSigningKeyValidityPS {
   1661     /**
   1662      * purpose.purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY
   1663      */
   1664     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1665     struct GNUNET_TIME_AbsoluteNBO start;
   1666     struct GNUNET_TIME_AbsoluteNBO expire;
   1667     struct GNUNET_TIME_AbsoluteNBO end;
   1668     struct TALER_ExchangePublicKeyP signkey_pub;
   1669   };
   1670 
   1671 .. _TALER_ExchangeKeySetPS:
   1672 .. sourcecode:: c
   1673 
   1674   struct TALER_ExchangeKeySetPS {
   1675       /**
   1676        * purpose.purpose = TALER_SIGNATURE_EXCHANGE_KEY_SET
   1677        */
   1678       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1679       struct GNUNET_TIME_AbsoluteNBO list_issue_date;
   1680       struct GNUNET_HashCode hc;
   1681   };
   1682 
   1683 .. _TALER_DenominationKeyValidityPS:
   1684 .. sourcecode:: c
   1685 
   1686   struct TALER_DenominationKeyValidityPS {
   1687     /**
   1688      * purpose.purpose = TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY
   1689      */
   1690     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1691     struct TALER_MasterPublicKeyP master;
   1692     struct GNUNET_TIME_AbsoluteNBO start;
   1693     struct GNUNET_TIME_AbsoluteNBO expire_withdraw;
   1694     struct GNUNET_TIME_AbsoluteNBO expire_spend;
   1695     struct GNUNET_TIME_AbsoluteNBO expire_legal;
   1696     struct TALER_AmountNBO value;
   1697     struct TALER_AmountNBO fee_withdraw;
   1698     struct TALER_AmountNBO fee_deposit;
   1699     struct TALER_AmountNBO fee_refresh;
   1700     struct TALER_DenominationHash denom_hash;
   1701   };
   1702 
   1703 .. _TALER_MasterWireDetailsPS:
   1704 .. sourcecode:: c
   1705 
   1706   struct TALER_MasterWireDetailsPS {
   1707     /**
   1708      * purpose.purpose = TALER_SIGNATURE_MASTER_WIRE_DETAILS
   1709      */
   1710     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1711     struct TALER_FullPaytoHash h_wire_details;
   1712     struct GNUNET_HashCode h_conversion_url;
   1713     struct GNUNET_HashCode h_credit_restrictions;
   1714     struct GNUNET_HashCode h_debit_restrictions;
   1715   };
   1716 
   1717 .. _TALER_MasterWireFeePS:
   1718 .. sourcecode:: c
   1719 
   1720   struct TALER_MasterWireFeePS {
   1721     /**
   1722      * purpose.purpose = TALER_SIGNATURE_MASTER_WIRE_FEES
   1723      */
   1724     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1725     struct GNUNET_HashCode h_wire_method;
   1726     struct GNUNET_TIME_AbsoluteNBO start_date;
   1727     struct GNUNET_TIME_AbsoluteNBO end_date;
   1728     struct TALER_AmountNBO wire_fee;
   1729     struct TALER_AmountNBO closing_fee;
   1730   };
   1731 
   1732 .. _TALER_GlobalFeesPS:
   1733 .. sourcecode:: c
   1734 
   1735   struct TALER_GlobalFeesPS {
   1736     /**
   1737      * purpose.purpose = TALER_SIGNATURE_MASTER_GLOBAL_FEES
   1738      */
   1739     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1740     struct GNUNET_TIME_AbsoluteNBO start_date;
   1741     struct GNUNET_TIME_AbsoluteNBO end_date;
   1742     struct GNUNET_TIME_RelativeNBO purse_timeout;
   1743     struct GNUNET_TIME_RelativeNBO kyc_timeout;
   1744     struct GNUNET_TIME_RelativeNBO history_expiration;
   1745     struct TALER_AmountNBO history_fee;
   1746     struct TALER_AmountNBO kyc_fee;
   1747     struct TALER_AmountNBO account_fee;
   1748     struct TALER_AmountNBO purse_fee;
   1749     uint32_t purse_account_limit;
   1750   };
   1751 
   1752 .. _TALER_MasterDrainProfitPS:
   1753 .. sourcecode:: c
   1754 
   1755   struct TALER_MasterDrainProfitPS {
   1756     /**
   1757      * purpose.purpose = TALER_SIGNATURE_MASTER_DRAIN_PROFITS
   1758      */
   1759     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1760     struct TALER_WireTransferIdentifierRawP wtid;
   1761     struct GNUNET_TIME_AbsoluteNBO date;
   1762     struct TALER_AmountNBO amount;
   1763     struct GNUNET_HashCode h_section;
   1764     struct TALER_FullPaytoHashP h_payto;
   1765   };
   1766 
   1767 .. _TALER_DepositTrackPS:
   1768 .. sourcecode:: c
   1769 
   1770   struct TALER_DepositTrackPS {
   1771     /**
   1772      * purpose.purpose = TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION
   1773      */
   1774     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1775     struct TALER_PrivateContractHash h_contract_terms;
   1776     struct TALER_MerchantWireHash h_wire;
   1777     union TALER_CoinSpendPublicKeyP coin_pub;
   1778   };
   1779 
   1780 .. _TALER_WireDepositDetailP:
   1781 .. sourcecode:: c
   1782 
   1783   struct TALER_WireDepositDetailP {
   1784     struct TALER_PrivateContractHash h_contract_terms;
   1785     struct GNUNET_TIME_AbsoluteNBO execution_time;
   1786     union TALER_CoinSpendPublicKeyP coin_pub;
   1787     struct TALER_AmountNBO deposit_value;
   1788     struct TALER_AmountNBO deposit_fee;
   1789   };
   1790 
   1791 .. _TALER_WireDepositDataPS:
   1792 .. _TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT:
   1793 .. sourcecode:: c
   1794 
   1795   struct TALER_WireDepositDataPS {
   1796     /**
   1797      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT
   1798      */
   1799     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1800     struct TALER_AmountNBO total;
   1801     struct TALER_AmountNBO wire_fee;
   1802     struct TALER_MerchantPublicKeyP merchant_pub;
   1803     struct TALER_MerchantWireHash h_wire;
   1804     struct GNUNET_HashCode h_details;
   1805   };
   1806 
   1807 .. _TALER_ExchangeKeyValidityPS:
   1808 .. sourcecode:: c
   1809 
   1810   struct TALER_ExchangeKeyValidityPS {
   1811     /**
   1812      * purpose.purpose = TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS
   1813      */
   1814     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1815     struct GNUNET_HashCode auditor_url_hash;
   1816     struct TALER_MasterPublicKeyP master;
   1817     struct GNUNET_TIME_AbsoluteNBO start;
   1818     struct GNUNET_TIME_AbsoluteNBO expire_withdraw;
   1819     struct GNUNET_TIME_AbsoluteNBO expire_spend;
   1820     struct GNUNET_TIME_AbsoluteNBO expire_legal;
   1821     struct TALER_AmountNBO value;
   1822     struct TALER_AmountNBO fee_withdraw;
   1823     struct TALER_AmountNBO fee_deposit;
   1824     struct TALER_AmountNBO fee_refresh;
   1825     struct TALER_DenominationHash denom_hash;
   1826   };
   1827 
   1828 .. _TALER_PaymentResponsePS:
   1829 .. sourcecode:: c
   1830 
   1831   struct PaymentResponsePS {
   1832     /**
   1833      * purpose.purpose = TALER_SIGNATURE_MERCHANT_PAYMENT_OK
   1834      */
   1835     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1836     struct TALER_PrivateContractHash h_contract_terms;
   1837   };
   1838 
   1839 .. _TALER_ContractPS:
   1840 .. sourcecode:: c
   1841 
   1842   struct TALER_ContractPS {
   1843     /**
   1844      * purpose.purpose = TALER_SIGNATURE_MERCHANT_CONTRACT
   1845      */
   1846     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1847     struct TALER_PrivateContractHash h_contract_terms;
   1848   };
   1849 
   1850 .. _TALER_ConfirmWirePS:
   1851 .. _TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE:
   1852 .. sourcecode:: c
   1853 
   1854   struct TALER_ConfirmWirePS {
   1855     /**
   1856      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE
   1857      */
   1858     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1859     struct TALER_MerchantWireHash h_wire;
   1860     struct TALER_PrivateContractHash h_contract_terms;
   1861     struct TALER_WireTransferIdentifierRawP wtid;
   1862     union TALER_CoinSpendPublicKeyP coin_pub;
   1863     struct GNUNET_TIME_AbsoluteNBO execution_time;
   1864     struct TALER_AmountNBO coin_contribution;
   1865   };
   1866 
   1867 .. _TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND:
   1868 .. sourcecode:: c
   1869 
   1870    struct TALER_RefundConfirmationPS {
   1871      /**
   1872       * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND.
   1873       */
   1874      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1875      struct TALER_PrivateContractHash h_contract_terms;
   1876      union TALER_CoinSpendPublicKeyP coin_pub;
   1877      struct TALER_MerchantPublicKeyP merchant;
   1878      uint64_t rtransaction_id;
   1879      struct TALER_AmountNBO refund_amount;
   1880    };
   1881 
   1882 .. _TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION:
   1883 .. sourcecode:: c
   1884 
   1885     struct TALER_DepositTrackPS {
   1886       /**
   1887        * purpose.purpose = TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION.
   1888        */
   1889       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1890       struct TALER_PrivateContractHash h_contract_terms;
   1891       struct TALER_MerchantWireHash h_wire;
   1892       struct TALER_MerchantPublicKeyP merchant;
   1893       union TALER_CoinSpendPublicKeyP coin_pub;
   1894     };
   1895 
   1896 .. _TALER_RefundRequestPS:
   1897 .. sourcecode:: c
   1898 
   1899   struct TALER_RefundRequestPS {
   1900     /**
   1901      *  purpose.purpose = TALER_SIGNATURE_MERCHANT_REFUND
   1902      */
   1903     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1904     struct TALER_PrivateContractHash h_contract_terms;
   1905     union TALER_CoinSpendPublicKeyP coin_pub;
   1906     uint64_t rtransaction_id;
   1907     struct TALER_AmountNBO refund_amount;
   1908     struct TALER_AmountNBO refund_fee;
   1909   };
   1910 
   1911 .. _TALER_MerchantRefundConfirmationPS:
   1912 .. sourcecode:: c
   1913 
   1914   struct TALER_MerchantRefundConfirmationPS {
   1915     /**
   1916      *  purpose.purpose = TALER_SIGNATURE_MERCHANT_REFUND_OK
   1917      */
   1918     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1919     /**
   1920      * Hash of the order ID (a string), hashed without the 0-termination.
   1921      */
   1922     struct GNUNET_HashCode h_order_id;
   1923   };
   1924 
   1925 
   1926 .. _TALER_RecoupRequestPS:
   1927 .. sourcecode:: c
   1928 
   1929   struct TALER_RecoupRequestPS {
   1930     /**
   1931      *  purpose.purpose = TALER_SIGNATURE_WALLET_COIN_RECOUP
   1932      * or TALER_SIGNATURE_WALLET_COIN_RECOUP_REFRESH
   1933      */
   1934     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1935     struct TALER_DenominationHashP h_denom_pub;
   1936     union GNUNET_CRYPTO_BlindingSecretP coin_blind;
   1937   };
   1938 
   1939 .. _TALER_RecoupWithdrawBatchConfirmationPS:
   1940 .. sourcecode:: c
   1941 
   1942   /**
   1943    * Signed by the exchange in the response to /recoup-withdraw,
   1944    * affirming that it credited the reserve for all recouped coins
   1945    * of one request.
   1946    */
   1947   struct TALER_RecoupWithdrawBatchConfirmationPS {
   1948     /**
   1949      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_WITHDRAW_BATCH
   1950      */
   1951     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1952     struct GNUNET_TIME_TimestampNBO timestamp;
   1953     struct TALER_ReservePublicKeyP reserve_pub;
   1954     struct TALER_HashBlindedPlanchetsP planchets_h;
   1955     struct TALER_AmountNBO total_amount;
   1956     /**
   1957      * SHA-512 hash over the concatenation, in the order of the
   1958      * ``recoups`` array of the response, of the coin public key
   1959      * (32 bytes) followed by the recouped amount (as TALER_AmountNBO)
   1960      * of every recouped coin.
   1961      */
   1962     struct GNUNET_HashCode h_recoups;
   1963   };
   1964 
   1965 .. _TALER_RecoupRefreshBatchConfirmationPS:
   1966 .. sourcecode:: c
   1967 
   1968   /**
   1969    * Signed by the exchange in the response to /recoup-refresh,
   1970    * affirming that it credited the old coin for all recouped coins
   1971    * of one request.
   1972    */
   1973   struct TALER_RecoupRefreshBatchConfirmationPS {
   1974     /**
   1975      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH_BATCH
   1976      */
   1977     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1978     struct GNUNET_TIME_TimestampNBO timestamp;
   1979     struct TALER_CoinSpendPublicKeyP old_coin_pub;
   1980     struct TALER_RefreshCommitmentP rc;
   1981     struct TALER_AmountNBO total_amount;
   1982     /**
   1983      * SHA-512 hash over the concatenation, in the order of the
   1984      * ``recoups`` array of the response, of the coin public key
   1985      * (32 bytes) followed by the recouped amount (as TALER_AmountNBO)
   1986      * of every recouped coin.
   1987      */
   1988     struct GNUNET_HashCode h_recoups;
   1989   };
   1990 
   1991 .. _TALER_RecoupRefreshConfirmationPS:
   1992 .. sourcecode:: c
   1993 
   1994   struct TALER_RecoupRefreshConfirmationPS {
   1995     /**
   1996      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH
   1997      */
   1998     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   1999     struct GNUNET_TIME_AbsoluteNBO timestamp;
   2000     struct TALER_AmountNBO recoup_amount;
   2001     union TALER_CoinSpendPublicKeyP coin_pub;
   2002     union TALER_CoinSpendPublicKeyP old_coin_pub;
   2003   };
   2004 
   2005 .. _TALER_RecoupConfirmationPS:
   2006 .. sourcecode:: c
   2007 
   2008   struct TALER_RecoupConfirmationPS {
   2009     /**
   2010      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP
   2011      */
   2012     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2013     struct GNUNET_TIME_AbsoluteNBO timestamp;
   2014     struct TALER_AmountNBO recoup_amount;
   2015     union TALER_CoinSpendPublicKeyP coin_pub;
   2016     struct TALER_ReservePublicKeyP reserve_pub;
   2017   };
   2018 
   2019 
   2020 .. _TALER_DenominationUnknownAffirmationPS:
   2021 .. sourcecode:: c
   2022 
   2023   struct TALER_DenominationUnknownAffirmationPS {
   2024     /**
   2025      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_UNKNOWN
   2026      */
   2027     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2028     struct GNUNET_TIME_AbsoluteNBO timestamp;
   2029     struct TALER_DenominationHash h_denom_pub;
   2030   };
   2031 
   2032 
   2033 .. _TALER_DenominationExpiredAffirmationPS:
   2034 .. sourcecode:: c
   2035 
   2036   struct TALER_DenominationExpiredAffirmationPS {
   2037     /**
   2038      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_GENERIC_DENOMINATIN_EXPIRED
   2039      */
   2040     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2041     struct GNUNET_TIME_AbsoluteNBO timestamp;
   2042     char operation[8];
   2043     struct TALER_DenominationHash h_denom_pub;
   2044   };
   2045 
   2046 
   2047 .. _TALER_ReserveCloseConfirmationPS:
   2048 .. sourcecode:: c
   2049 
   2050   struct TALER_ReserveCloseConfirmationPS {
   2051     /**
   2052      * purpose.purpose = TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED
   2053      */
   2054     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2055     struct GNUNET_TIME_AbsoluteNBO timestamp;
   2056     struct TALER_AmountNBO closing_amount;
   2057     struct TALER_ReservePublicKeyP reserve_pub;
   2058     struct TALER_FullPaytoHash h_wire;
   2059   };
   2060 
   2061 .. _TALER_CoinLinkSignaturePS:
   2062 .. sourcecode:: c
   2063 
   2064   struct TALER_CoinLinkSignaturePS {
   2065     /**
   2066      * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_LINK
   2067      */
   2068     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2069     struct TALER_DenominationHash h_denom_pub;
   2070     union TALER_CoinSpendPublicKeyP old_coin_pub;
   2071     struct TALER_TransferPublicKeyP transfer_pub;
   2072     struct TALER_BlindedCoinHash coin_envelope_hash;
   2073   };
   2074 
   2075 .. _TALER_RefreshNonceSignaturePS:
   2076 .. sourcecode:: c
   2077 
   2078   struct TALER_RefreshNonceSignaturePS
   2079   {
   2080     /**
   2081      * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_LINK
   2082      */
   2083     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2084     struct TALER_PublicRefreshCoinNonceP nonce;
   2085   };
   2086 
   2087 
   2088 .. _TALER_ReserveStatusRequestSignaturePS:
   2089 .. sourcecode:: c
   2090 
   2091   struct TALER_ReserveStatusRequestSignaturePS {
   2092     /**
   2093      * purpose.purpose = TALER_SIGNATURE_RESERVE_STATUS_REQUEST
   2094      */
   2095     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2096     struct GNUNET_TIME_AbsoluteNBO request_timestamp;
   2097   };
   2098 
   2099 
   2100 .. _TALER_CoinHistoryRequestPS:
   2101 .. sourcecode:: c
   2102 
   2103   struct TALER_CoinHistoryRequestPS {
   2104     /**
   2105      * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_HISTORY
   2106      */
   2107     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2108     /**
   2109      * Value of the ``start`` query parameter, 0 if not given,
   2110      * in network byte order.
   2111      */
   2112     uint64_t start_off;
   2113   };
   2114 
   2115 
   2116 .. _TALER_ReserveHistoryRequestSignaturePS:
   2117 .. sourcecode:: c
   2118 
   2119   struct TALER_ReserveHistoryRequestSignaturePS {
   2120     /**
   2121      * purpose.purpose = TALER_SIGNATURE_RESERVE_HISTORY_REQUEST
   2122      */
   2123     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2124     struct TALER_AmountNBO history_fee;
   2125     struct GNUNET_TIME_AbsoluteNBO request_timestamp;
   2126   };
   2127 
   2128 
   2129 .. _TALER_PurseStatusRequestSignaturePS:
   2130 .. sourcecode:: c
   2131 
   2132   struct TALER_PurseStatusRequestSignaturePS {
   2133     /**
   2134      * purpose.purpose = TALER_SIGNATURE_PURSE_STATUS_REQUEST
   2135      */
   2136     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2137   };
   2138 
   2139 
   2140 .. _TALER_PurseStatusResponseSignaturePS:
   2141 .. sourcecode:: c
   2142 
   2143   struct TALER_PurseStatusResponseSignaturePS {
   2144     /**
   2145      * purpose.purpose = TALER_SIGNATURE_PURSE_STATUS_RESPONSE
   2146      */
   2147     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2148     struct TALER_AmountNBO total_purse_amount;
   2149     struct TALER_AmountNBO total_deposit_amount;
   2150     struct TALER_AmountNBO max_deposit_fees;
   2151     struct GNUNET_TIME_AbsoluteNBO purse_expiration;
   2152     struct GNUNET_TIME_AbsoluteNBO status_timestamp;
   2153     struct TALER_PrivateContractHash h_contract_terms;
   2154   };
   2155 
   2156 
   2157 .. _TALER_ReserveCloseRequestSignaturePS:
   2158 .. sourcecode:: c
   2159 
   2160   struct TALER_ReserveCloseRequestSignaturePS {
   2161     /**
   2162      * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_CLOSE
   2163      */
   2164     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2165   };
   2166 
   2167 
   2168 .. _TALER_PurseRequestSignaturePS:
   2169 .. sourcecode:: c
   2170 
   2171   struct TALER_PurseRequestSignaturePS {
   2172     /**
   2173      * purpose.purpose = TALER_SIGNATURE_WALLET_PURSE_CREATE
   2174      */
   2175     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2176     struct GNUNET_TIME_AbsoluteNBO purse_expiration;
   2177     struct TALER_AmountNBO merge_value_after_fees;
   2178     struct TALER_PrivateContractHashP h_contract_terms;
   2179     uint32_t min_age;
   2180   };
   2181 
   2182 
   2183 .. _TALER_PurseDepositSignaturePS:
   2184 .. sourcecode:: c
   2185 
   2186   struct TALER_PurseDepositSignaturePS {
   2187     /**
   2188      * purpose.purpose = TALER_SIGNATURE_PURSE_DEPOSIT
   2189      */
   2190     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2191     struct TALER_AmountNBO coin_contribution;
   2192     struct TALER_DenominationHash h_denom_pub;
   2193     struct TALER_AgeCommitmentHash h_age_commitment;
   2194     struct TALER_PursePublicKeyP purse_pub;
   2195     struct GNUNET_HashCode h_exchange_base_url;
   2196   };
   2197 
   2198 
   2199 .. _TALER_ReserveOpenDepositSignaturePS:
   2200 .. sourcecode:: c
   2201 
   2202   struct TALER_PurseDepositSignaturePS {
   2203     /**
   2204      * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_OPEN_DEPOSIT
   2205      */
   2206     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2207     struct TALER_ReserveSignatureP reserve_sig;
   2208     struct TALER_AmountNBO coin_contribution;
   2209   };
   2210 
   2211 
   2212 .. _TALER_PurseDepositConfirmedSignaturePS:
   2213 .. sourcecode:: c
   2214 
   2215   struct TALER_PurseDepositConfirmedSignaturePS {
   2216     /**
   2217      * purpose.purpose = TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED
   2218      */
   2219     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2220     struct TALER_AmountNBO total_purse_amount;
   2221     struct TALER_AmountNBO total_deposit_fees;
   2222     struct TALER_PursePublicKeyP purse_pub;
   2223     struct GNUNET_TIME_AbsoluteNBO purse_expiration;
   2224     struct TALER_PrivateContractHashP h_contract_terms;
   2225   };
   2226 
   2227 .. _TALER_PurseMergeSignaturePS:
   2228 .. sourcecode:: c
   2229 
   2230   struct TALER_PurseMergeSignaturePS {
   2231     /**
   2232      * purpose.purpose = TALER_SIGNATURE_WALLET_PURSE_MERGE
   2233      */
   2234     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2235     struct GNUNET_TIME_AbsoluteNBO merge_timestamp;
   2236     struct TALER_NormalizedPaytoHashP h_wire;
   2237   };
   2238 
   2239 
   2240 .. _TALER_AccountMergeSignaturePS:
   2241 .. sourcecode:: c
   2242 
   2243   struct TALER_AccountMergeSignaturePS {
   2244     /**
   2245      * purpose.purpose = TALER_SIGNATURE_WALLET_ACCOUNT_MERGE
   2246      */
   2247     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2248     struct TALER_ReservePublicKeyP reserve_pub;
   2249     struct TALER_PursePublicKeyP purse_pub;
   2250     struct TALER_AmountNBO merge_amount_after_fees;
   2251     struct GNUNET_TIME_AbsoluteNBO merge_timestamp;
   2252     struct GNUNET_TIME_AbsoluteNBO purse_expiration;
   2253     struct TALER_PrivateContractHashP h_contract_terms;
   2254     uint32_t min_age;
   2255   };
   2256 
   2257 .. _TALER_AccountSetupRequestSignaturePS:
   2258 .. sourcecode:: c
   2259 
   2260   struct TALER_AccountSetupRequestSignaturePS {
   2261     /**
   2262      * purpose.purpose = TALER_SIGNATURE_WALLET_ACCOUNT_SETUP
   2263      */
   2264     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2265     struct TALER_AmountNBO threshold;
   2266   };
   2267 
   2268 .. _TALER_PurseMergeSuccessSignaturePS:
   2269 .. sourcecode:: c
   2270 
   2271   struct TALER_PurseMergeSuccessSignaturePS {
   2272     /**
   2273      * purpose.purpose = TALER_SIGNATURE_PURSE_MERGE_SUCCESS
   2274      */
   2275     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2276     struct TALER_ReservePublicKeyP reserve_pub;
   2277     struct TALER_PursePublicKeyP purse_pub;
   2278     struct TALER_AmountNBO merge_amount_after_fees;
   2279     struct GNUNET_TIME_AbsoluteNBO contract_time;
   2280     struct TALER_PrivateContractHashP h_contract_terms;
   2281     struct TALER_NormalizedPaytoHashP h_wire;
   2282     uint32_t min_age;
   2283   };
   2284 
   2285 
   2286 .. _TALER_WadDataSignaturePS:
   2287 .. sourcecode:: c
   2288 
   2289   struct TALER_WadDataSignaturePS {
   2290     /**
   2291      * purpose.purpose = TALER_SIGNATURE_WAD_DATA
   2292      */
   2293     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2294     struct GNUNET_TIME_AbsoluteNBO wad_execution_time;
   2295     struct TALER_AmountNBO total_amount;
   2296     struct GNUNET_HashCode h_items;
   2297     struct TALER_WadId wad_id;
   2298   };
   2299 
   2300 .. _TALER_WadPartnerSignaturePS:
   2301 .. sourcecode:: c
   2302 
   2303   struct TALER_WadPartnerSignaturePS {
   2304     /**
   2305      * purpose.purpose = TALER_SIGNATURE_MASTER_PARTNER_DETAILS
   2306      */
   2307     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2308     struct GNUNET_HashCode h_partner_base_url;
   2309     struct TALER_MasterPublicKeyP master_public_key;
   2310     struct GNUNET_TIME_AbsoluteNBO start_date;
   2311     struct GNUNET_TIME_AbsoluteNBO end_date;
   2312     struct TALER_AmountNBO wad_fee;
   2313     struct GNUNET_TIME_RelativeNBO wad_frequency;
   2314   };
   2315 
   2316 
   2317 .. _TALER_P2PFeesPS:
   2318 .. sourcecode:: c
   2319 
   2320   struct TALER_P2PFeesPS {
   2321     /**
   2322      * purpose.purpose = TALER_SIGNATURE_P2P_FEES
   2323      */
   2324     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2325     struct GNUNET_TIME_AbsoluteNBO start_date;
   2326     struct GNUNET_TIME_AbsoluteNBO end_date;
   2327     struct TALER_AmountNBO kyc_fee;
   2328     struct TALER_AmountNBO purse_fee;
   2329     struct TALER_AmountNBO account_history_fee;
   2330     struct TALER_AmountNBO account_annual_fee;
   2331     struct GNUNET_TIME_RelativeNBO account_kyc_timeout;
   2332     struct GNUNET_TIME_RelativeNBO purse_timeout;
   2333     uint32_t purse_account_limit;
   2334   };
   2335 
   2336 
   2337 .. _TALER_SIGNATURE_EXCHANGE_CONFIRM_PURSE_REFUND:
   2338 .. sourcecode:: c
   2339 
   2340    struct TALER_CoinPurseRefundConfirmationPS {
   2341      /**
   2342       * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_PURSE_REFUND.
   2343       */
   2344      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2345      struct TALER_PursePublicKeyP purse_pub;
   2346      union TALER_CoinSpendPublicKeyP coin_pub;
   2347      struct TALER_AmountNBO refunded_amount;
   2348      struct TALER_AmountNBO refund_fee;
   2349    };
   2350 
   2351 
   2352 .. _TALER_DenominationKeyAnnouncementPS:
   2353 .. sourcecode:: c
   2354 
   2355    struct TALER_DenominationKeyAnnouncementPS {
   2356      /**
   2357       * purpose.purpose = TALER_SIGNATURE_SM_DENOMINATION_KEY
   2358       */
   2359       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2360       struct TALER_DenominationHash h_denom_pub;
   2361       struct GNUNET_HashCode h_section_name;
   2362       struct GNUNET_TIME_AbsoluteNBO anchor_time;
   2363       struct GNUNET_TIME_RelativeNBO duration_withdraw;
   2364     };
   2365 
   2366 
   2367 .. _TALER_SigningKeyAnnouncementPS:
   2368 .. sourcecode:: c
   2369 
   2370     struct TALER_SigningKeyAnnouncementPS {
   2371       /**
   2372        * purpose.purpose = TALER_SIGNATURE_SM_SIGNING_KEY .
   2373        */
   2374       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2375       struct TALER_ExchangePublicKeyP exchange_pub;
   2376       struct GNUNET_TIME_AbsoluteNBO anchor_time;
   2377       struct GNUNET_TIME_RelativeNBO duration;
   2378     };
   2379 
   2380 .. _TALER_MasterDenominationKeyRevocationPS:
   2381 .. sourcecode:: c
   2382 
   2383     struct TALER_MasterDenominationKeyRevocationPS {
   2384       /**
   2385        * purpose.purpose = TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED.
   2386        */
   2387       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2388       struct TALER_DenominationHash h_denom_pub;
   2389     };
   2390 
   2391 
   2392 .. _TALER_MasterSigningKeyRevocationPS:
   2393 .. sourcecode:: c
   2394 
   2395     struct TALER_MasterSigningKeyRevocationPS {
   2396       /**
   2397        * purpose.purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_REVOKED.
   2398        */
   2399       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2400       struct TALER_ExchangePublicKeyP exchange_pub;
   2401     };
   2402 
   2403 
   2404 .. _TALER_MasterAddAuditorPS:
   2405 .. sourcecode:: c
   2406 
   2407     struct TALER_MasterAddAuditorPS {
   2408       /**
   2409        * purpose.purpose = TALER_SIGNATURE_MASTER_ADD_AUDITOR
   2410        */
   2411        struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2412        struct GNUNET_TIME_AbsoluteNBO start_date;
   2413        struct TALER_AuditorPublicKeyP auditor_pub;
   2414        struct GNUNET_HashCode h_auditor_url;
   2415      };
   2416 
   2417 .. _TALER_MasterDelAuditorPS:
   2418 .. sourcecode:: c
   2419 
   2420     struct TALER_MasterDelAuditorPS {
   2421       /**
   2422        * purpose.purpose = TALER_SIGNATURE_MASTER_DEL_AUDITOR
   2423        */
   2424       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2425       struct GNUNET_TIME_AbsoluteNBO end_date;
   2426       struct TALER_AuditorPublicKeyP auditor_pub;
   2427     };
   2428 
   2429 .. _TALER_MasterAddWirePS:
   2430 .. sourcecode:: c
   2431 
   2432     struct TALER_MasterAddWirePS {
   2433       /**
   2434        * purpose.purpose = TALER_SIGNATURE_MASTER_ADD_WIRE.
   2435        */
   2436       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2437       struct GNUNET_TIME_AbsoluteNBO start_date;
   2438       struct TALER_FullPaytoHash h_wire;
   2439       struct GNUNET_HashCode h_conversion_url;
   2440       struct GNUNET_HashCode h_credit_restrictions;
   2441       struct GNUNET_HashCode h_debit_restrictions;
   2442     };
   2443 
   2444 .. _TALER_MasterDelWirePS:
   2445 .. sourcecode:: c
   2446 
   2447     struct TALER_MasterDelWirePS {
   2448       /**
   2449        * purpose.purpose = TALER_SIGNATURE_MASTER_DEL_WIRE.
   2450        */
   2451       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2452       struct GNUNET_TIME_AbsoluteNBO end_date;
   2453       struct TALER_FullPaytoHash h_wire;
   2454     };
   2455 
   2456 
   2457 .. _TALER_MasterAmlOfficerStatusPS:
   2458 .. sourcecode:: c
   2459 
   2460     struct TALER_MasterAmlOfficerStatusPS {
   2461       /**
   2462        * purpose.purpose = TALER_SIGNATURE_MASTER_AML_KEY
   2463        */
   2464       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2465       struct GNUNET_TIME_TimestampNBO change_date;
   2466       struct TALER_AmlOfficerPublicKeyP officer_pub;
   2467       struct GNUNET_HashCode h_officer_name GNUNET_PACKED;
   2468       uint32_t is_active GNUNET_PACKED;
   2469     };
   2470 
   2471 .. _TALER_AmlDecisionPS:
   2472 .. sourcecode:: c
   2473 
   2474     struct TALER_AmlDecisionPS {
   2475       /**
   2476        * purpose.purpose =TALER_SIGNATURE_AML_DECISION.
   2477        */
   2478       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2479       struct GNUNET_HashCode h_justification GNUNET_PACKED;
   2480       struct GNUNET_TIME_TimestampNBO decision_time;
   2481       struct TALER_AmountNBO new_threshold;
   2482       struct TALER_NormalizedPaytoHashP h_payto GNUNET_PACKED;
   2483       struct GNUNET_HashCode h_kyc_requirements;
   2484       uint32_t new_state GNUNET_PACKED;
   2485     };
   2486 
   2487 .. _TALER_PartnerConfigurationPS:
   2488 .. sourcecode:: c
   2489 
   2490     struct TALER_PartnerConfigurationPS {
   2491       /**
   2492        * purpose.purpose = TALER_SIGNATURE_MASTER_PARNTER_DETAILS
   2493        */
   2494       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2495       struct TALER_MasterPublicKeyP partner_pub;
   2496       struct GNUNET_TIME_TimestampNBO start_date;
   2497       struct GNUNET_TIME_TimestampNBO end_date;
   2498       struct GNUNET_TIME_RelativeNBO wad_frequency;
   2499       struct TALER_AmountNBO wad_fee;
   2500       struct GNUNET_HashCode h_url;
   2501     };
   2502 
   2503 .. _TALER_ReserveOpenPS:
   2504 .. sourcecode:: c
   2505 
   2506     struct TALER_ReserveOpenPS {
   2507       /**
   2508        * Purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_OPEN
   2509        */
   2510       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2511       struct TALER_AmountNBO reserve_payment;
   2512       struct GNUNET_TIME_TimestampNBO request_timestamp;
   2513       struct GNUNET_TIME_TimestampNBO reserve_expiration;
   2514       uint32_t purse_limit;
   2515     };
   2516 
   2517 .. _TALER_ReserveClosePS:
   2518 .. sourcecode:: c
   2519 
   2520     struct TALER_ReserveClosePS {
   2521       /**
   2522        * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_CLOSE
   2523        */
   2524       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2525       struct GNUNET_TIME_TimestampNBO request_timestamp;
   2526       struct TALER_FullPaytoHashP target_account_h_payto;
   2527     };
   2528 
   2529 .. _TALER_WalletReserveAttestRequestSignaturePS:
   2530 .. sourcecode:: c
   2531 
   2532     struct TALER_ReserveAttestRequestPS {
   2533       /**
   2534        * purpose.purpose = TALER_SIGNATURE_WALLET_ATTEST_REQUEST
   2535        */
   2536       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2537       struct GNUNET_TIME_TimestampNBO request_timestamp;
   2538       struct GNUNET_HashCode h_details;
   2539     };
   2540 
   2541 .. _TALER_ExchangeAttestPS:
   2542 .. sourcecode:: c
   2543 
   2544     struct TALER_ExchangeAttestPS {
   2545       /**
   2546        * purpose.purpose = TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS
   2547        */
   2548       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2549       struct GNUNET_TIME_TimestampNBO attest_timestamp;
   2550       struct GNUNET_TIME_TimestampNBO expiration_time;
   2551       struct TALER_ReservePublicKeyP reserve_pub;
   2552       struct GNUNET_HashCode h_attributes;
   2553     };
   2554 
   2555 .. _TALER_ExternKycDataImportBindingPS:
   2556 .. sourcecode:: c
   2557 
   2558   struct TALER_ExternKycDataImportBindingPS {
   2559     /**
   2560      * purpose.purpose = TALER_SIGNATURE_EXTERN_KYC_IMPORT_BINDING
   2561      */
   2562     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2563     struct GNUNET_TIME_AbsoluteNBO import_date;
   2564     union GNUNET_AccountPublicKeyP account_pub;
   2565     struct GNUNET_HashCode h_attributes;
   2566     struct GNUNET_HashCode h_customer_payto;
   2567   };
   2568 
   2569 
   2570 .. _TALER_ExternKycDataBulkBindingPS:
   2571 .. sourcecode:: c
   2572 
   2573   struct TALER_ExternKycDataBulkBindingPS {
   2574     /**
   2575      * purpose.purpose = TALER_SIGNATURE_EXTERN_KYC_BULK_BINDING
   2576      */
   2577     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
   2578     struct GNUNET_HashCode h_body;
   2579     struct GNUNET_HashCode h_customer_payto;
   2580   };
   2581 
   2582 .. _TALER_PreparedTransferRegisterPS:
   2583 .. sourcecode:: c
   2584 
   2585   struct TALER_PreparedTransferRegisterPS {
   2586     /**
   2587     * Purpose is #TALER_SIGNATURE_WALLET_PREPARED_TRANSFER_REGISTER
   2588     */
   2589     struct GNUNET_CRYPTO_SignaturePurpose purpose;
   2590     struct TALER_NormalizedPayto credit_account;
   2591     struct TALER_AmountNBO credit_amount;
   2592     /**
   2593     * 1: reserve, 2: kyc
   2594     */
   2595     uint32_t type;
   2596     /**
   2597     * 1: one-time, 2: recurrent
   2598     */
   2599     uint16_t recurrent;
   2600     /**
   2601     * 1: EdDSA
   2602     */
   2603     uint16_t alg;
   2604     union TALER_AccountPublicKeyP account_pub;
   2605   };
   2606 
   2607 .. _TALER_PreparedTransferUnregisterPS:
   2608 .. sourcecode:: c
   2609 
   2610   struct TALER_PreparedTransferUnregisterPS {
   2611     /**
   2612     * Purpose is #TALER_SIGNATURE_WALLET_PREPARED_TRANSFER_UNREGISTER
   2613     */
   2614     struct GNUNET_CRYPTO_SignaturePurpose purpose;
   2615     struct GNUNET_TIME_TimestampNBO timestamp;
   2616   };