[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [taler-docs] branch master updated: The big doc refactoring
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] [taler-docs] branch master updated: The big doc refactoring |
|
Date: |
Fri, 27 Sep 2019 00:57:05 +0200 |
This is an automated email from the git hooks/post-receive script.
dold pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 3df802c The big doc refactoring
3df802c is described below
commit 3df802c19af277bcf46586909de2cbb41f34b962
Author: Florian Dold <address@hidden>
AuthorDate: Fri Sep 27 00:55:41 2019 +0200
The big doc refactoring
Use new ts:def directive for TypeScript definitions and use ``foo`` for
literal text. The form `foo` is an interpreted role. Also, only use
the interpreted role form for references in TS definition comments.
---
core/api-auditor.rst | 28 ++--
core/api-bank.rst | 276 ++++++++++++++++++++++-----------------
core/api-common.rst | 164 +++++++++++++++--------
core/api-error.rst | 1 +
core/api-exchange.rst | 351 +++++++++++++++++++++++---------------------------
core/api-merchant.rst | 318 ++++++++++++++++++++-------------------------
core/api-sync.rst | 14 +-
core/taler-uri.rst | 16 +--
core/wireformats.rst | 4 +-
onboarding.rst | 18 +--
10 files changed, 604 insertions(+), 586 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
index 957b1c0..03a26f7 100644
--- a/core/api-auditor.rst
+++ b/core/api-auditor.rst
@@ -21,7 +21,7 @@ The Auditor RESTful JSON API
The API specified here follows the :ref:`general conventions <http-common>`
for all details not specified in the individual requests.
-The `glossary <https://docs.taler.net/glossary.html#glossary>`
+The `glossary <https://docs.taler.net/glossary.html#glossary>`_
defines all specific terms used in this section.
.. _auditor-version:
@@ -54,10 +54,10 @@ know-your-customer (KYC) registration before issuing
contracts.
//
https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
// The format is "current:revision:age". Note that the auditor
// protocol is versioned independently of the exchange's protocol.
- version: String;
+ version: string;
// Return which currency this auditor is auditing for.
- currency: String;
+ currency: string;
// EdDSA master public key of the auditor
auditor_public_key: EddsaPublicKey;
@@ -86,21 +86,19 @@ know-your-customer (KYC) registration before issuing
contracts.
**Response:**
:status 200 OK:
- The auditor responds with a `ExchangeList`_ object. This request should
+ The auditor responds with a :ts:type:`ExchangeList` object. This request
should
virtually always be successful.
**Details:**
- .. _ExchangeList:
- .. code-block:: tsref
+ .. ts:def:: ExchangeList
interface ExchangeList {
// Exchanges audited by this auditor
exchanges: ExchangeEntry[];
}
- .. _tsref-type-Denom:
- .. code-block:: tsref
+ .. ts:def:: ExchangeEntry
interface ExchangeEntry {
@@ -134,28 +132,24 @@ paid out first.
.. http:put:: /deposit-confirmation
- Submits a `DepositConfirmation`_ to the exchange. Should succeed
+ Submits a `DepositConfirmation` to the exchange. Should succeed
unless the signature provided is invalid or the exchange is not
audited by this auditor.
**Response:**
- :status 200: The auditor responds with a `DepositAudited`_ object.
+ :status 200: The auditor responds with a `DepositAudited` object.
This request should virtually always be successful.
**Details:**
- .. _DepositAudited:
- .. _tsref-type-DepositAudited:
- .. code-block:: tsref
+ .. ts:def:: DepositAudited
interface DepositAudited {
- // TODO: do we care for the auditor to sign this?
+ // TODO: do we care for the auditor to sign this?
}
- .. _DepositConfirmation:
- .. _tsref-type-DepositConfirmation:
- .. code-block:: tsref
+ .. ts:def:: DepositConfirmation
interface DepositConfirmation {
diff --git a/core/api-bank.rst b/core/api-bank.rst
index a3c8953..2ef4961 100644
--- a/core/api-bank.rst
+++ b/core/api-bank.rst
@@ -26,18 +26,23 @@ This API provides programmatic user registration at the
bank.
.. _bank-register:
.. http:post:: /register
-**Request** The body of this request must have the format of a
`BankRegistrationRequest`_.
+ **Request** The body of this request must have the format of a
+ `BankRegistrationRequest`.
-**Response**
+ **Response**
-:status 200 OK: The new user has been correctly registered.
-:status 409 Conflict: the username requested by the client is not available
anymore
-:status 406 Not Acceptable: unacceptable characters were given for the
username. See
https://docs.djangoproject.com/en/2.2/ref/contrib/auth/#django.contrib.auth.models.User.username
for the accepted character set.
+ :status 200 OK:
+ The new user has been correctly registered.
+ :status 409 Conflict:
+ The username requested by the client is not available anymore.
+ :status 406 Not Acceptable:
+ Unacceptable characters were given for the username. See
+
https://docs.djangoproject.com/en/2.2/ref/contrib/auth/#django.contrib.auth.models.User.username
+ for the accepted character set.
**Details**
-.. _BankRegistrationRequest:
-.. code-block:: tsref
+.. ts:def:: BankRegistrationRequest
interface BankRegistrationRequest {
@@ -58,18 +63,17 @@ bank account to the exchange's.
.. _bank-withdraw:
.. http:post:: /taler/withdraw
-**Request** The body of this request must have the format of a
`BankTalerWithdrawRequest`_.
+**Request** The body of this request must have the format of a
`BankTalerWithdrawRequest`.
**Response**
-:status 200 OK: The withdrawal was correctly initiated, therefore the exchange
received the payment. A `BankTalerWithdrawResponse`_ object is returned.
+:status 200 OK: The withdrawal was correctly initiated, therefore the exchange
received the payment. A `BankTalerWithdrawResponse` object is returned.
:status 406 Not Acceptable: the user does not have sufficient credit to
fulfill their request.
:status 404 Not Found: The exchange wire details did not point to any valid
bank account.
**Details**
-.. _BankTalerWithdrawRequest:
-.. code-block:: tsref
+.. ts:def:: BankTalerWithdrawRequest
interface BankTalerWithdrawRequest {
@@ -89,8 +93,7 @@ bank account to the exchange's.
exchange_wire_details: string;
}
-.. _BankTalerWithdrawResponse:
-.. code-block:: tsref
+.. ts:def:: BankTalerWithdrawResponse
interface BankTalerWithdrawResponse {
@@ -109,93 +112,90 @@ request.
.. _bank-deposit:
.. http:post:: /admin/add/incoming
-**Request:** The body of this request must have the format of a
`BankDepositRequest`_.
-
-**Response:**
-
-:status 200 OK: The request has been correctly handled, so the funds have been
transferred to the recipient's account. The body is a `BankDepositDetails`_.
-:status 400 Bad Request: The bank replies a `BankError`_ object.
-:status 406 Not Acceptable: The request had wrong currency; the bank replies a
`BankError`_ object.
+ **Request:** The body of this request must have the format of a
`BankDepositRequest`.
-**Details:**
+ **Response:**
-.. _BankDepositDetails:
-.. code-block:: tsref
+ :status 200 OK:
+ The request has been correctly handled, so the funds have been transferred
to
+ the recipient's account. The body is a `BankDepositDetails`
+ :status 400 Bad Request: The bank replies a `BankError` object.
+ :status 406 Not Acceptable: The request had wrong currency; the bank replies
a `BankError` object.
- interface BankDepositDetails {
+ **Details:**
- // Timestamp related to the transaction being made.
- timestamp: Timestamp;
-
- // Row id number identifying the transaction in the bank's
- // database.
- row_id: number;
- }
+ .. ts:def:: BankDepositDetails
-.. _BankDepositRequest:
-.. code-block:: tsref
+ interface BankDepositDetails {
- interface BankDepositRequest {
+ // Timestamp related to the transaction being made.
+ timestamp: Timestamp;
- // Authentication method used
- auth: BankAuth;
+ // Row id number identifying the transaction in the bank's
+ // database.
+ row_id: number;
+ }
- // JSON 'amount' object. The amount the caller wants to transfer
- // to the recipient's count
- amount: Amount;
+ .. ts:def:: BankDepositRequest
- // Exchange base URL, used to perform tracking requests against the
- // wire transfer ID. Note that in the actual bank wire transfer,
- // the schema may have to be encoded differently, i.e.
- // "https://exchange.com/"; may become "https exchange.com" due to
- // character set restrictions. It is the responsibility of the
- // wire transfer adapter to properly encode/decode the URL.
- // Payment service providers must ensure that their URL is short
- // enough to fit together with the wire transfer identifier into
- // the wire transfer subject of their respective banking system.
- exchange_url: string;
+ interface BankDepositRequest {
- // The subject of this wire transfer.
- subject: string;
+ // Authentication method used
+ auth: BankAuth;
- // The sender's account identificator. NOTE, in the current stage
- // of development this field is _ignored_, as it's always the bank account
- // of the logged user that plays as the "debit account".
- // In future releases, a logged user may specify multiple bank accounts
- // of her/his as the debit account.
- debit_account: number;
+ // JSON 'amount' object. The amount the caller wants to transfer
+ // to the recipient's count
+ amount: Amount;
+
+ // Exchange base URL, used to perform tracking requests against the
+ // wire transfer ID. Note that in the actual bank wire transfer,
+ // the schema may have to be encoded differently, i.e.
+ // "https://exchange.com/"; may become "https exchange.com" due to
+ // character set restrictions. It is the responsibility of the
+ // wire transfer adapter to properly encode/decode the URL.
+ // Payment service providers must ensure that their URL is short
+ // enough to fit together with the wire transfer identifier into
+ // the wire transfer subject of their respective banking system.
+ exchange_url: string;
+
+ // The subject of this wire transfer.
+ subject: string;
+
+ // The sender's account identificator. NOTE, in the current stage
+ // of development this field is _ignored_, as it's always the bank
account
+ // of the logged user that plays as the "debit account".
+ // In future releases, a logged user may specify multiple bank accounts
+ // of her/his as the debit account.
+ debit_account: number;
- // The recipient's account identificator
- credit_account: number;
+ // The recipient's account identificator
+ credit_account: number;
- }
+ }
-.. _BankAuth:
-.. _tsref-type-BankAuth:
-.. code-block:: tsref
+ .. ts:def:: BankAuth
- interface BankAuth {
+ interface BankAuth {
- // authentication type. At this stage of development,
- // only value "basic" is accepted in this field.
- // The credentials must be indicated in the following HTTP
- // headers: "X-Taler-Bank-Username" and "X-Taler-Bank-Password".
- type: string;
- }
+ // authentication type. At this stage of development,
+ // only value "basic" is accepted in this field.
+ // The credentials must be indicated in the following HTTP
+ // headers: "X-Taler-Bank-Username" and "X-Taler-Bank-Password".
+ type: string;
+ }
-.. _BankError:
-.. code-block:: tsref
+ .. ts:def:: BankError
- interface BankError {
+ interface BankError {
- // Human readable explanation of the failure.
- error: string;
+ // Human readable explanation of the failure.
+ error: string;
- // Numeric Taler error code (`enum TALER_ErrorCode`)
- ec: number;
+ // Numeric Taler error code (`TALER_ErrorCode`)
+ ec: number;
- }
+ }
.. http:put:: /reject
@@ -207,14 +207,20 @@ request.
This API is used when the exchange receives a wire transfer with an invalid
wire
transfer subject that fails to decode to a public key.
- **Request** The body of this request must have the format of a
`BankCancelRequest`_.
+ **Request** The body of this request must have the format of a
`BankCancelRequest`.
- :query auth: authentication method used. At this stage of development, only
value `basic` is accepted. Note that username and password need to be given as
request's headers. The dedicated headers are: `X-Taler-Bank-Username` and
`X-Taler-Bank-Password`.
+ :query auth:
+ authentication method used. At this stage of development, only
+ value ``"basic"`` is accepted. Note that username and password need to be
+ given as request's headers.
+ The dedicated headers are: ``X-Taler-Bank-Username`` and
``X-Taler-Bank-Password``.
:query row_id: row identifier of the transaction that should be cancelled.
- :query account_number: bank account for which the incoming transfer was made
and for which `auth` provides the authentication data. *Currently ignored*, as
multiple bank accounts per user are not implemented yet.
+ :query account_number:
+ bank account for which the incoming transfer was made and
+ for which ``auth`` provides the authentication data.
+ **Currently ignored**, as multiple bank accounts per user are not
implemented yet.
- .. _BankCancelRequest:
- .. code-block:: tsref
+ .. ts:def:: BankCancelRequest
interface BankCancelRequest {
@@ -229,31 +235,50 @@ request.
}
- **Response** In case of an error, the body is a `BankError`_ object.
+ **Response** In case of an error, the body is a `BankError` object.
:status 204 No Content: The request has been correctly handled, so the
original transaction was voided. The body is empty.
- :status 400 Bad Request: The bank replies a `BankError`_ object.
+ :status 400 Bad Request: The bank replies a `BankError` object.
:status 404 Not Found: The bank does not know this rowid for this account.
.. http:get:: /history-range
- Filters and returns the list of transactions in the time range specified by
`start` and `end`
+ Filters and returns the list of transactions in the time range specified by
+ ``start`` and ``end``
**Request**
- :query auth: authentication method used. At this stage of development, only
value `basic` is accepted. Note that username and password need to be given as
request's headers. The dedicated headers are: `X-Taler-Bank-Username` and
`X-Taler-Bank-Password`.
- :query start: unix timestamp indicating the oldest transaction accepted in
the result.
- :query end: unix timestamp indicating the youngest transaction accepted in
the result.
- :query direction: argument taking values `debit` or `credit`, according to
the caller willing to receive both incoming and outgoing, only outgoing, or
only incoming records. Use `both` to return both directions.
- :query cancelled: argument taking values `omit` or `show` to filter out
rejected transactions
- :query account_number: bank account whose history is to be returned.
*Currently ignored*, as multiple bank accounts per user are not implemented yet.
- :query ordering: can be `descending` or `ascending` and regulates whether
the row are returned youger-to-older or vice versa. Defaults to `descending`.
+ :query auth:
+ authentication method used. At this stage of development, only
+ value ``"basic"`` is accepted. Note that username and password need to be
+ given as request's headers. The dedicated headers are:
+ ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``.
+ :query start:
+ unix timestamp indicating the oldest transaction accepted in
+ the result.
+ :query end:
+ unix timestamp indicating the youngest transaction accepted in
+ the result.
+ :query direction:
+ argument taking values ``debit`` or ``credit``, according to
+ the caller willing to receive both incoming and outgoing, only outgoing, or
+ only incoming records. Use ``both`` to return both directions.
+ :query cancelled:
+ argument taking values ``omit`` or ``show`` to filter out rejected
+ transactions
+ :query account_number:
+ bank account whose history is to be returned. *Currently ignored*, as
+ multiple bank accounts per user are not implemented yet.
+ :query ordering:
+ can be ``descending`` or ``ascending`` and regulates whether
+ the row are returned youger-to-older or vice versa. Defaults to
+ ``descending``.
**Response**
- :status 200 OK: JSON object whose field `data` is an array of type
`BankTransaction`_.
+ :status 200 OK: JSON object whose field ``data`` is an array of type
`BankTransaction`.
:status 204 No content: in case no records exist for the targeted user.
@@ -263,22 +288,39 @@ request.
**Request**
- :query auth: authentication method used. At this stage of development, only
value `basic` is accepted. Note that username and password need to be given as
request's headers. The dedicated headers are: `X-Taler-Bank-Username` and
`X-Taler-Bank-Password`.
- :query delta: returns the first `N` records younger (older) than `start` if
`+N` (`-N`) is specified.
- :query start: according to `delta`, only those records with row id strictly
greater (lesser) than `start` will be returned. This argument is optional; if
not given, it defaults to "MAX_UINT64".
- :query direction: argument taking values `debit` or `credit`, according to
the caller willing to receive both incoming and outgoing, only outgoing, or
only incoming records. Use `both` to return both directions.
- :query cancelled: argument taking values `omit` or `show` to filter out
rejected transactions
- :query account_number: bank account whose history is to be returned.
*Currently ignored*, as multiple bank accounts per user are not implemented yet.
- :query ordering: can be `descending` or `ascending` and regulates whether
the row are returned youger-to-older or vice versa. Defaults to `descending`.
+ :query auth:
+ authentication method used. At this stage of development, only
+ value ``basic`` is accepted. Note that username and password need to be
given
+ as request's headers. The dedicated headers are:
``X-Taler-Bank-Username`` and
+ ``X-Taler-Bank-Password``.
+ :query delta:
+ returns the first ``N`` records younger (older) than ``start`` if
+ ``+N`` (``-N``) is specified.
+ :query start:
+ according to ``delta``, only those records with row id strictly
+ greater (lesser) than ``start`` will be returned. This argument is
optional;
+ if not given, it defaults to "MAX_UINT64".
+ :query direction:
+ argument taking values ``debit`` or ``credit``, according
+ to the caller willing to receive both incoming and outgoing, only outgoing,
+ or only incoming records. Use ``both`` to return both directions.
+ :query cancelled:
+ argument taking values ``omit`` or ``show`` to filter out rejected
transactions
+ :query account_number:
+ bank account whose history is to be returned.
+ *Currently ignored*, as multiple bank accounts per user are not implemented
+ yet.
+ :query ordering:
+ can be ``descending`` or ``ascending`` and regulates whether the
+ row are returned youger-to-older or vice versa. Defaults to
``descending``.
**Response**
- :status 200 OK: JSON object whose field `data` is an array of type
`BankTransaction`_.
+ :status 200 OK: JSON object whose field ``data`` is an array of type
`BankTransaction`.
:status 204 No content: in case no records exist for the targeted user.
-.. _BankTransaction:
-.. code-block:: tsref
+.. ts:def:: BankTransaction
interface BankTransaction {
@@ -338,26 +380,30 @@ wallet is *not* installed. This special page will hide
any element of
the class ``taler-install-show``; it can be downloaded at the following
URL: ``git://taler.net/web-common/taler-fallback.css``.
-Withdrawing coins.
-^^^^^^^^^^^^^^^^^^
+Withdrawing coins
+^^^^^^^^^^^^^^^^^
-After the user confirms the withdrawal, the bank must return a `202 Accepted`
response,
+After the user confirms the withdrawal, the bank must return a ``202
Accepted`` response,
along with the following HTTP headers:
* ``X-Taler-Operation: create-reserve``
* ``X-Taler-Callback-Url: <callback_url>``; this URL will be automatically
visited by the wallet after the user confirms the exchange.
* ``X-Taler-Wt-Types: '["test"]'``; stringified JSON list of supported wire
transfer types (only 'test' supported so far).
* ``X-Taler-Amount: <amount_string>``; stringified Taler-style JSON
:ref:`amount <amount>`.
-* ``X-Taler-Sender-Wire: <wire_details>``; stringified WireDetails_.
-* ``X-Taler-Suggested-Exchange: <URL>``; this header is optional, and
``<URL>`` is the suggested exchange URL as given in the `SUGGESTED_EXCHANGE`
configuration option.
+* ``X-Taler-Sender-Wire: <wire_details>``; stringified `WireDetails`.
+* ``X-Taler-Suggested-Exchange: <URL>``; this header is optional, and
``<URL>`` is the suggested exchange URL as given in the ``SUGGESTED_EXCHANGE``
configuration option.
-.. _WireDetails:
-.. code-block:: tsref
+.. ts:def:: WireDetails
interface WireDetails {
- type: string; // Only 'test' value admitted so far.
- bank_uri: URL of the bank.
- account_number: bank account number of the user attempting to withdraw.
+ // Only 'test' value admitted so far.
+ type: string;
+
+ // URL of the bank.
+ bank_uri: string;
+
+ // bank account number of the user attempting to withdraw.
+ account_number: number;
}
After the user confirms the exchange to withdraw coins from, the wallet will
@@ -381,7 +427,7 @@ The callback URL implements the following API.
:query amount_currency: currency of the amount to be withdrawn.
:query exchange: base URL of the exchange where the reserve is to be created.
:query reserve_pub: public key of the reserve to create.
- :query exchange_wire_details: stringification of the chosen exchange's
WireDetails_.
+ :query exchange_wire_details: stringification of the chosen exchange's
`WireDetails`.
**Response**
diff --git a/core/api-common.rst b/core/api-common.rst
index 8f3ae37..eb40a62 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -36,7 +36,7 @@ handle the error as if an internal error (500) had been
returned.
**Request:**
Unless specified otherwise, HTTP requests that carry a message body must
- have the content type `application/json`.
+ have the content type ``application/json``.
:reqheader Content-Type: application/json
@@ -60,17 +60,15 @@ handle the error as if an internal error (500) had been
returned.
:status 400 Bad Request: One of the arguments to the request is missing or
malformed.
Unless specified otherwise, all error status codes (4xx and 5xx) have a
message
- body with an `ErrorDetail`_ JSON object.
+ body with an `ErrorDetail` JSON object.
**Details:**
- .. _ErrorDetail:
- .. _tsref-type-ErrorDetail:
- .. code-block:: tsref
+ .. ts:def:: ErrorDetail
interface ErrorDetail {
- // Numeric `error code <error-codes>`_ unique to the condition.
+ // Numeric `error code <error-codes>` unique to the condition.
code: number;
// Human-readable description of the error, i.e. "missing parameter",
"commitment violation", ...
@@ -115,69 +113,105 @@ Common encodings
This section describes how certain types of values are represented throughout
the API.
.. _base32:
-.. _tsref-type-Base32:
Binary Data
^^^^^^^^^^^
+.. ts:def:: foobase
+
+ type Base32 = string;
+
Binary data is generally encoded using Crockford's variant of Base32
(http://www.crockford.com/wrmg/base32.html), except that "U" is not excluded
but also decodes to "V" to make OCR easy. We will still simply use the JSON
type "base32" and the term "Crockford Base32" in the text to refer to the
resulting encoding.
-.. _tsref-type-HashCode:
-
Hash codes
^^^^^^^^^^
Hashcodes are strings representing base32 encoding of the respective hashed
data. See `base32`_.
+.. ts:def:: HashCode
+
+ type HashCode = string;
+
Large numbers
^^^^^^^^^^^^^
Large numbers such as RSA blinding factors and 256 bit keys, are transmitted
as other binary data in Crockford Base32 encoding.
-
-.. _tsref-type-Timestamp:
-
Timestamps
^^^^^^^^^^
-Timestamps are represented in JSON as a string literal `"\\/Date(x)\\/"`,
-where `x` is the decimal representation of the number of seconds past the
-Unix Epoch (January 1, 1970). The escaped slash (`\\/`) is interpreted in
+Timestamps are represented in JSON as a string literal ``"\\/Date(x)\\/"``,
+where ``x`` is the decimal representation of the number of seconds past the
+Unix Epoch (January 1, 1970). The escaped slash (``\\/``) is interpreted in
JSON simply as a normal slash, but distinguishes the timestamp from a normal
string literal. We use the type "date" in the documentation below.
-Additionally, the special strings "\\/never\\/" and "\\/forever\\/" are
+Additionally, the special strings ``"\\/never\\/"`` and ``"\\/forever\\/"`` are
recognized to represent the end of time.
+.. ts:def:: Timestamp
+
+ type Timestamp = string;
+
+
+.. ts:def:: RelativeTime
+
+ type RelativeTime = string;
+
.. _public\ key:
+
+Integers
+^^^^^^^^
+
+.. ts:def:: Integer
+
+ // JavaScript numbers restricted to integers
+ type Integer = number;
+
Keys
^^^^
-.. _`tsref-type-EddsaPublicKey`:
-.. _`tsref-type-EcdhePublicKey`:
-.. _`tsref-type-EcdhePrivateKey`:
-.. _`tsref-type-EddsaPrivateKey`:
-.. _`tsref-type-CoinPublicKey`:
-
-.. code-block:: tsref
+.. ts:def:: EddsaPublicKey
// EdDSA and ECDHE public keys always point on Curve25519
// and represented using the standard 256 bits Ed25519 compact format,
- // converted to Crockford `Base32`_.
+ // converted to Crockford `Base32`.
type EddsaPublicKey = string;
+
+.. ts:def:: EddsaPrivateKey
+
+ // EdDSA and ECDHE public keys always point on Curve25519
+ // and represented using the standard 256 bits Ed25519 compact format,
+ // converted to Crockford `Base32`.
type EddsaPrivateKey = string;
-.. _`tsref-type-RsaPublicKey`:
+.. ts:def:: EcdhePublicKey
+
+ // EdDSA and ECDHE public keys always point on Curve25519
+ // and represented using the standard 256 bits Ed25519 compact format,
+ // converted to Crockford `Base32`.
+ type EcdhePublicKey = string;
+
+.. ts:def:: EcdhePrivateKey
+
+ // EdDSA and ECDHE public keys always point on Curve25519
+ // and represented using the standard 256 bits Ed25519 compact format,
+ // converted to Crockford `Base32`.
+ type EcdhePrivateKey = string;
+
+.. ts:def:: CoinPublicKey
+
+ type CoinPublicKey = EddsaPublicKey;
-.. code-block:: tsref
+.. ts:def:: RsaPublicKey
- // RSA public key converted to Crockford `Base32`_.
+ // RSA public key converted to Crockford `Base32`.
type RsaPublicKey = string;
.. _blinded-coin:
@@ -185,11 +219,9 @@ Keys
Blinded coin
^^^^^^^^^^^^
-.. _`tsref-type-CoinEnvelope`:
+.. ts:def:: CoinEnvelope
-.. code-block:: tsref
-
- // Blinded coin's `public EdDSA key <eddsa-coin-pub>`_, `base32`_ encoded
+ // Blinded coin's `public EdDSA key <eddsa-coin-pub>`, `base32` encoded
type CoinEnvelope = string;
.. _signature:
@@ -197,45 +229,46 @@ Blinded coin
Signatures
^^^^^^^^^^
-.. _`tsref-type-EddsaSignature`:
-.. code-block:: tsref
+.. ts:def:: EddsaSignature
- // EdDSA signatures are transmitted as 64-bytes `base32`_
+ // EdDSA signatures are transmitted as 64-bytes `base32`
// binary-encoded objects with just the R and S values (base32_ binary-only)
type EddsaSignature = string;
+.. ts:def:: RsaSignature
-.. _`tsref-type-RsaSignature`:
-
-.. code-block:: tsref
-
- // `base32`_ encoded RSA signature
+ // `base32` encoded RSA signature
type RsaSignature = string;
-.. _`tsref-type-BlindedRsaSignature`:
+.. ts:def:: BlindedRsaSignature
-.. code-block:: tsref
-
- // `base32`_ encoded RSA blinded signature
+ // `base32` encoded RSA blinded signature
type BlindedRsaSignature = string;
+.. ts:def:: RsaBlindingKeySecret
+
+ // `base32` encoded RSA blinding secret
+ type RsaBlindingKeySecret = string;
+
.. _amount:
Amounts
^^^^^^^
-.. _`tsref-type-Amount`:
+.. ts:def:: Amount
-Amounts of currency are serialized as a string of the format
`<Currency>:<DecimalAmount>`.
+ type Amount = string;
+
+Amounts of currency are serialized as a string of the format
``<Currency>:<DecimalAmount>``.
Taler treats monetary amounts as fixed-precision numbers. Unlike floating
point numbers,
this allows accurate representation of monetary amounts.
The following constrains apply for a valid amount:
-1. The `<Currency>` part must be at most 12 characters long and may not
contain a colon (`:`).
-2. The integer part of `<DecimalAmount>` may be at most 2^52
-3. the fractional part of `<DecimalAmount>` may contain at most 8 decimal
digits.
+1. The ``<Currency>`` part must be at most 12 characters long and may not
contain a colon (``:``).
+2. The integer part of ``<DecimalAmount>`` may be at most 2^52
+3. the fractional part of ``<DecimalAmount>`` may contain at most 8 decimal
digits.
Internally, amounts are parsed into the following object:
@@ -243,7 +276,7 @@ Internally, amounts are parsed into the following object:
"EUR:1.50" and "EUR:10" are is a valid amounts. These are all invalid
amounts: "A:B:1.5", "EUR:4503599627370501.0", "EUR:1.", "EUR:.1"
-.. code-block:: tsref
+.. ts:def:: ParsedAmount
interface ParsedAmount {
// name of the currency using either a three-character ISO 4217 currency
@@ -256,7 +289,7 @@ Internally, amounts are parsed into the following object:
// correspond to 1 EUR or 1 USD, depending on `currency`, not 1 cent.
value: number;
- // unsigned 32 bit fractional value to be added to `value` representing
+ // unsigned 32 bit fractional value to be added to ``value`` representing
// an additional currency fraction, in units of one millionth (1e-6)
// of the base currency value. For example, a fraction
// of 500,000 would correspond to 50 cents.
@@ -270,14 +303,14 @@ Binary Formats
.. note::
- Due to the way of handling `big` numbers by some platforms (such as
- `JavaScript`, for example), wherever the following specification mentions
+ Due to the way of handling "big" numbers by some platforms (such as
+ JavaScript, for example), wherever the following specification mentions
a 64-bit value, the actual implementations are strongly advised to rely on
arithmetic up to 53 bits.
.. note::
- Taler uses `libgnunetutil` for interfacing itself with the operating
system,
+ Taler uses ``libgnunetutil`` for interfacing itself with the operating
system,
doing crypto work, and other "low level" actions, therefore it is strongly
connected with the `GNUnet project <https://gnunet.org>`_.
@@ -310,7 +343,7 @@ Time
^^^^
In signed messages, time is represented using 64-bit big-endian values,
-denoting microseconds since the UNIX Epoch. `UINT64_MAX` represents "never".
+denoting microseconds since the UNIX Epoch. ``UINT64_MAX`` represents "never".
.. sourcecode:: c
@@ -472,7 +505,7 @@ Any piece of signed data, complies to the abstract data
structure given below.
The following list contains all the data structure that can be signed in
-Taler. Their definition is typically found in `src/include/taler_signatures.h`,
+Taler. Their definition is typically found in
``src/include/taler_signatures.h``,
within the
`exchange's codebase
<https://docs.taler.net/global-licensing.html#exchange-repo>`_.
@@ -526,6 +559,11 @@ within the
struct TALER_MerchantPublicKeyP merchant;
};
+.. _TALER_RefreshCommitmentP:
+.. sourcecode:: c
+
+ // FIXME: put definition here
+
.. _TALER_RefreshMeltCoinAffirmationPS:
.. sourcecode:: c
@@ -650,6 +688,7 @@ within the
.. _TALER_WireDepositDataPS:
+.. _TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT:
.. sourcecode:: c
struct TALER_WireDepositDataPS {
@@ -711,6 +750,7 @@ within the
};
.. _TALER_ConfirmWirePS:
+.. _TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE:
.. sourcecode:: c
struct TALER_ConfirmWirePS {
@@ -726,6 +766,16 @@ within the
struct TALER_AmountNBO coin_contribution;
};
+.. _TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND:
+.. sourcecode:: c
+
+ // FIXME: put definition here
+
+.. _TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION:
+.. sourcecode:: c
+
+ // FIXME: put definition here
+
.. _TALER_RefundRequestPS:
.. sourcecode:: c
@@ -767,6 +817,10 @@ within the
struct TALER_DenominationBlindingKeyP coin_blind;
};
+.. _TALER_PaybackRefreshConfirmationPS:
+.. sourcecode:: c
+
+ // FIXME: put definition here
.. _TALER_PaybackConfirmationPS:
.. sourcecode:: c
diff --git a/core/api-error.rst b/core/api-error.rst
index 61716b7..d460c7a 100644
--- a/core/api-error.rst
+++ b/core/api-error.rst
@@ -26,6 +26,7 @@ The following list shows error codes defined in
`<EXCHANGE-REPO>/src/include/taler_error_codes.h
<https://git.taler.net/exchange.git/tree/src/include/taler_error_codes.h>`_
.. _error-codes:
+.. _TALER_ErrorCode:
.. code-block:: c
/**
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 1d03dae..4c04f1f 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -21,7 +21,7 @@ The Exchange RESTful JSON API
The API specified here follows the :ref:`general conventions <http-common>`
for all details not specified in the individual requests.
-The `glossary <https://docs.taler.net/glossary.html#glossary>`
+The `glossary <https://docs.taler.net/glossary.html#glossary>`_
defines all specific terms used in this section.
.. _keys:
@@ -53,21 +53,20 @@ possibly by using HTTPS.
**Response:**
:status 200 OK:
- The exchange responds with a `ExchangeKeysResponse`_ object. This request
should
+ The exchange responds with a `ExchangeKeysResponse` object. This request
should
virtually always be successful.
**Details:**
- .. _ExchangeKeysResponse:
- .. code-block:: tsref
+ .. ts:def:: ExchangeKeysResponse
interface ExchangeKeysResponse {
// libtool-style representation of the Taler protocol version, see
//
https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
// The format is "current:revision:age".
- version: String;
+ version: string;
- // EdDSA master public key of the exchange, used to sign entries in
`denoms` and `signkeys`
+ // EdDSA master public key of the exchange, used to sign entries in
'denoms' and 'signkeys'
master_public_key: EddsaPublicKey;
// Relative duration until inactive reserves are closed; not signed,
expressed as
@@ -89,11 +88,11 @@ possibly by using HTTPS.
// The exchange's signing keys.
signkeys: SignKey[];
- // compact EdDSA `signature`_ (binary-only) over the SHA-512 hash of the
+ // compact EdDSA `signature` (binary-only) over the SHA-512 hash of the
// concatenation of all SHA-512 hashes of the RSA denomination public
keys
- // in `denoms` in the same order as they were in `denoms`. Note that for
+ // in ``denoms`` in the same order as they were in ``denoms``. Note
that for
// hashing, the binary format of the RSA public keys is used, and not
their
- // `base32 encoding <base32>`_. Wallets cannot do much with this
signature by itself;
+ // `base32 encoding <base32>`. Wallets cannot do much with this
signature by itself;
// it is only useful when multiple clients need to establish that the
exchange
// is sabotaging end-user anonymity by giving disjoint denomination keys
to
// different users. If a exchange were to do this, this signature
allows the
@@ -107,8 +106,7 @@ possibly by using HTTPS.
eddsa_pub: EddsaPublicKey;
}
- .. _tsref-type-Denom:
- .. code-block:: tsref
+ .. ts:def:: Denom
interface Denom {
// How much are coins of this denomination worth?
@@ -141,18 +139,17 @@ possibly by using HTTPS.
// Fee charged by the exchange for refunding a coin of this denomination
fee_refund: Amount;
- // Signature of `TALER_DenominationKeyValidityPS`_
+ // Signature of `TALER_DenominationKeyValidityPS`
master_sig: EddsaSignature;
}
Fees for any of the operations can be zero, but the fields must still be
- present. The currency of the `fee_deposit`, `fee_refresh` and `fee_refund`
must match the
- currency of the `value`. Theoretically, the `fee_withdraw` could be in a
+ present. The currency of the ``fee_deposit``, ``fee_refresh`` and
``fee_refund`` must match the
+ currency of the ``value``. Theoretically, the ``fee_withdraw`` could be in a
different currency, but this is not currently supported by the
implementation.
- .. _tsref-type-Payback:
- .. code-block:: tsref
+ .. ts:def:: Payback
interface Payback {
// hash of the public key of the denomination that is being revoked under
@@ -166,10 +163,9 @@ possibly by using HTTPS.
// denomination keys listed here.
}
- A signing key in the `signkeys` list is a JSON object with the following
fields:
+ A signing key in the ``signkeys`` list is a JSON object with the following
fields:
- .. _tsref-type-SignKey:
- .. code-block:: tsref
+ .. ts:def:: SignKey
interface SignKey {
// The actual exchange's EdDSA signing public key.
@@ -186,15 +182,14 @@ possibly by using HTTPS.
// henceforth no longer be considered valid in legal disputes.
stamp_end: Timestamp;
- // Signature over `key` and `stamp_expire` by the exchange master key.
+ // Signature over ``key`` and ``stamp_expire`` by the exchange master
key.
// Must have purpose TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY.
master_sig: EddsaSignature;
}
- An entry in the `auditors` list is a JSON object with the following fields:
+ An entry in the ``auditors`` list is a JSON object with the following fields:
- .. _tsref-type-Auditor:
- .. code-block:: tsref
+ .. ts:def:: Auditor
interface Auditor {
// The auditor's EdDSA signing public key.
@@ -210,17 +205,16 @@ possibly by using HTTPS.
denomination_keys: DenominationKey[];
}
- .. _tsref-type-DenominationKey:
- .. code-block:: tsref
+ .. ts:def:: DenominationKey
interface DenominationKey {
// hash of the public RSA key used to sign coins of the respective
// denomination. Note that the auditor's signature covers more than just
- // the hash, but this other information is already provided in `denoms`
and
+ // the hash, but this other information is already provided in
``denoms`` and
// thus not repeated here.
denom_pub_h: HashCode;
- // Signature of `TALER_ExchangeKeyValidityPS`_
+ // Signature of `TALER_ExchangeKeyValidityPS`
auditor_sig: EddsaSignature;
}
@@ -247,13 +241,11 @@ Obtaining wire-transfer information
**Response:**
- :status 200: The exchange responds with a `WireResponse`_ object. This
request should virtually always be successful.
+ :status 200: The exchange responds with a `WireResponse` object. This
request should virtually always be successful.
**Details:**
- .. _WireResponse:
- .. _tsref-type-WireResponse:
- .. code-block:: tsref
+ .. ts:def:: WireResponse
interface WireResponse {
@@ -268,9 +260,7 @@ Obtaining wire-transfer information
The specification for the account object is:
- .. _WireAccouunt:
- .. _tsref-type-WireAccount:
- .. code-block:: tsref
+ .. ts:def:: WireAccount
interface WireAccount {
// payto:// URL identifying the account and wire method
@@ -286,12 +276,10 @@ Obtaining wire-transfer information
Aggregate wire transfer fees representing the fees the exchange
charges per wire transfer to a merchant must be specified as an
- array in all wire transfer response objects under `fees`. The
+ array in all wire transfer response objects under ``fees``. The
respective array contains objects with the following members:
- .. _AggregateTransferFee:
- .. _tsref-type-AggregateTransferFee:
- .. code-block:: tsref
+ .. ts:def:: AggregateTransferFee
interface AggregateTransferFee {
// Per transfer wire transfer fee.
@@ -310,7 +298,7 @@ Obtaining wire-transfer information
// any of the denomination keys are valid without overlap.
end_date: Timestamp;
- // Signature of `TALER_MasterWireFeePS`_ with purpose
TALER_SIGNATURE_MASTER_WIRE_FEES
+ // Signature of `TALER_MasterWireFeePS` with purpose
TALER_SIGNATURE_MASTER_WIRE_FEES
sig: EddsaSignature;
}
@@ -329,7 +317,7 @@ exchange.
.. note::
- Eventually the exchange will need to advertise a policy for how long it
will keep transaction histories for inactive or even fully drained reserves.
We will therefore need some additional handler similar to `/keys` to advertise
those terms of service.
+ Eventually the exchange will need to advertise a policy for how long it
will keep transaction histories for inactive or even fully drained reserves.
We will therefore need some additional handler similar to ``/keys`` to
advertise those terms of service.
.. http:get:: /reserve/status
@@ -352,13 +340,12 @@ exchange.
**Response:**
:status 200 OK:
- The exchange responds with a `ReserveStatus`_ object; the reserve was
known to the exchange,
+ The exchange responds with a `ReserveStatus` object; the reserve was
known to the exchange,
:status 404 Not Found: The reserve key does not belong to a reserve known to
the exchange.
**Details:**
- .. _ReserveStatus:
- .. code-block:: tsref
+ .. ts:def:: ReserveStatus
interface ReserveStatus {
// Balance left in the reserve.
@@ -370,8 +357,7 @@ exchange.
Objects in the transaction history have the following format:
- .. _tsref-type-TransactionHistoryItem:
- .. code-block:: tsref
+ .. ts:def:: TransactionHistoryItem
interface TransactionHistoryItem {
// Either "WITHDRAW", "DEPOSIT", "PAYBACK", or "CLOSING"
@@ -383,13 +369,14 @@ exchange.
// Hash of the denomination public key of the coin, if
// type is "WITHDRAW".
- h_denom_pub?: base32;
+ h_denom_pub?: Base32;
// Hash of the blinded coin to be signed, if
// type is "WITHDRAW".
- h_coin_envelope?: base32;
+ h_coin_envelope?: Base32;
- // Signature of `TALER_WithdrawRequestPS`_ created with the `reserves's
private key <reserve-priv>`_. Only present if type is "WITHDRAW".
+ // Signature of 'TALER_WithdrawRequestPS' created with the `reserves's
+ // private key <reserve-priv>`. Only present if type is "WITHDRAW".
reserve_sig?: EddsaSignature;
// The fee that was charged for "WITHDRAW".
@@ -399,7 +386,7 @@ exchange.
closing_fee?: Amount;
// Sender account payto://-URL, only present if type is "DEPOSIT".
- sender_account_url?: String;
+ sender_account_url?: string;
// Receiver account details, only present if type is "PAYBACK".
receiver_account_details?: any;
@@ -415,20 +402,27 @@ exchange.
// Hash of the wire account into which the funds were
// returned to, present if type is "CLOSING".
- h_wire?: base32;
-
- // If `type` is "PAYBACK", this is a signature over a `struct
TALER_PaybackConfirmationPS` with purpose
TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK.
- // If `type` is "CLOSING", this is a signature over a `struct
TALER_ReserveCloseConfirmationPS` with purpose
TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED.
- // Not present for other values of `type`.
+ h_wire?: Base32;
+
+ // If ``type`` is "PAYBACK", this is a signature over
+ // a struct `TALER_PaybackConfirmationPS` with purpose
+ // TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK.
+ // If ``type`` is "CLOSING", this is a signature over a
+ // struct `TALER_ReserveCloseConfirmationPS` with purpose
+ // TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED.
+ // Not present for other values of ``type``.
exchange_sig?: EddsaSignature;
- // Public key used to create `exchange_sig`, only present if
`exchange_sig` is present.
+ // Public key used to create ``exchange_sig``, only present if
+ // ``exchange_sig`` is present.
exchange_pub?: EddsaPublicKey;
// Public key of the coin that was paid back; only present if type is
"PAYBACK".
coin_pub?: CoinPublicKey;
- // Timestamp when the exchange received the /payback or executed the
wire transfer. Only present if `type` is "DEPOSIT", "PAYBACK" or "CLOSING".
+ // Timestamp when the exchange received the /payback or executed the
+ // wire transfer. Only present if ``type`` is "DEPOSIT", "PAYBACK" or
+ // "CLOSING".
timestamp?: Timestamp;
}
@@ -441,7 +435,7 @@ exchange.
recover the information if necessary in case of transient failures, like
power outage, network outage, etc.
- **Request:** The request body must be a `WithdrawRequest`_ object.
+ **Request:** The request body must be a `WithdrawRequest` object.
**Response:**
@@ -454,7 +448,7 @@ exchange.
:status 404 Not Found:
The denomination key or the reserve are not known to the exchange. If the
denomination key is unknown, this suggests a bug in the wallet as the
- wallet should have used current denomination keys from `/keys`. If the
+ wallet should have used current denomination keys from ``/keys``. If the
reserve is unknown, the wallet should not report a hard error yet, but
instead simply wait for up to a day, as the wire transaction might simply
not yet have completed and might be known to the exchange in the near
future.
@@ -462,13 +456,12 @@ exchange.
using exactly the same blinded coin.
:status 403 Forbidden:
The balance of the reserve is not sufficient to withdraw a coin of the
indicated denomination.
- The response is `WithdrawError`_ object.
+ The response is `WithdrawError` object.
**Details:**
- .. _WithdrawRequest:
- .. code-block:: tsref
+ .. ts:def:: WithdrawRequest
interface WithdrawRequest {
// Hash of a denomination public key (RSA), specifying the type of coin
the client
@@ -479,27 +472,25 @@ exchange.
// denomination private key
coin_ev: CoinEnvelope;
- // `public (EdDSA) key <reserve-pub>`_ of the reserve from which the
coin should be
+ // `public (EdDSA) key <reserve-pub>` of the reserve from which the coin
should be
// withdrawn. The total amount deducted will be the coin's value plus
the
// withdrawal fee as specified with the denomination information.
reserve_pub: EddsaPublicKey;
- // Signature of `TALER_WithdrawRequestPS`_ created with the `reserves's
private key <reserve-priv>`_
+ // Signature of `TALER_WithdrawRequestPS` created with the `reserves's
private key <reserve-priv>`
reserve_sig: EddsaSignature;
}
- .. _WithdrawResponse:
- .. code-block:: tsref
+ .. ts:def:: WithdrawResponse
interface WithdrawResponse {
- // The blinded RSA signature over the `coin_ev`, affirms the coin's
+ // The blinded RSA signature over the ``coin_ev``, affirms the coin's
// validity after unblinding.
ev_sig: BlindedRsaSignature;
}
- .. _WithdrawError:
- .. code-block:: tsref
+ .. ts:def:: WithdrawError
interface WithdrawError {
// Constant "Insufficient funds"
@@ -535,26 +526,26 @@ denomination.
the digital coins. The request should contain a JSON object with the
following fields:
- **Request:** The request body must be a `DepositRequest`_ object.
+ **Request:** The request body must be a `DepositRequest` object.
**Response:**
:status 200 Ok:
- The operation succeeded, the exchange confirms that no double-spending
took place. The response will include a `DepositSuccess`_ object.
+ The operation succeeded, the exchange confirms that no double-spending took
+ place. The response will include a `DepositSuccess` object.
:status 401 Unauthorized:
One of the signatures is invalid.
:status 403 Forbidden:
The deposit operation has failed because the coin has insufficient
residual value; the request should not be repeated again with this coin.
- In this case, the response is a `DepositDoubleSpendError`_.
+ In this case, the response is a `DepositDoubleSpendError`.
:status 404 Not Found:
Either the denomination key is not recognized (expired or invalid) or
the wire type is not recognized.
**Details:**
- .. _DepositRequest:
- .. code-block:: tsref
+ .. ts:def:: DepositRequest
interface DepositRequest {
// Amount to be deposited, can be a fraction of the
@@ -563,10 +554,10 @@ denomination.
// The merchant's account details. This must be a JSON object whose
format
// must correspond to one of the supported wire transfer formats of the
exchange.
- // See `wireformats`_.
- wire: Object;
+ // See `wireformats`.
+ wire: object;
- // SHA-512 hash of the merchant's payment details from `wire`. Although
+ // SHA-512 hash of the merchant's payment details from ``wire``.
Although
// strictly speaking redundant, this helps detect inconsistencies.
// TODO: change to 'h_wire'.
H_wire: HashCode;
@@ -575,7 +566,7 @@ denomination.
// details are never disclosed to the exchange.
h_contract_terms: HashCode;
- // `coin's public key <eddsa-coin-pub>`_, both ECDHE and EdDSA.
+ // `coin's public key <eddsa-coin-pub>`, both ECDHE and EdDSA.
coin_pub: CoinPublicKey;
// Hash of denomination RSA key with which the coin is signed
@@ -594,7 +585,7 @@ denomination.
// the merchant, in case of successful payment.
wire_deadline: Timestamp;
- // EdDSA `public key of the merchant <merchant-pub>`_, so that the
client can identify the
+ // EdDSA `public key of the merchant <merchant-pub>`, so that the client
can identify the
// merchant for refund requests.
merchant_pub: EddsaPublicKey;
@@ -602,29 +593,27 @@ denomination.
// exchange, possibly zero if refunds are not allowed.
refund_deadline: Timestamp;
- // Signature of `TALER_DepositRequestPS`_, made by the customer with the
`coin's private key <coin-priv>`_
+ // Signature of `TALER_DepositRequestPS`, made by the customer with the
+ // `coin's private key <coin-priv>`
coin_sig: EddsaSignature;
}
The deposit operation succeeds if the coin is valid for making a deposit and
has enough residual value that has not already been deposited or melted.
-
- .. _`tsref-type-DepositSuccess`:
- .. _DepositSuccess:
- .. code-block:: tsref
+ .. ts:def:: DepositSuccess
interface DepositSuccess {
// The string constant "DEPOSIT_OK"
status: string;
- // the EdDSA signature of `TALER_DepositConfirmationPS`_ using a current
- // `signing key of the exchange <sign-key-priv>`_ affirming the
successful
+ // the EdDSA signature of `TALER_DepositConfirmationPS` using a current
+ // `signing key of the exchange <sign-key-priv>` affirming the successful
// deposit and that the exchange will transfer the funds after the refund
// deadline, or as soon as possible if the refund deadline is zero.
sig: EddsaSignature;
- // `public EdDSA key of the exchange <sign-key-pub>`_ that was used to
+ // `public EdDSA key of the exchange <sign-key-pub>` that was used to
// generate the signature.
// Should match one of the exchange's signing keys from /keys. It is
given
// explicitly as the client might otherwise be confused by clock skew as
to
@@ -632,8 +621,7 @@ denomination.
pub: EddsaPublicKey;
}
- .. _DepositDoubleSpendError:
- .. code-block:: tsref
+ .. ts:def:: DepositDoubleSpendError
interface DepositDoubleSpendError {
// The string constant "insufficient funds"
@@ -644,16 +632,15 @@ denomination.
history: CoinSpendHistoryItem[];
}
- .. _`tsref-type-CoinSpendHistoryItem`:
- .. _CoinSpendHistoryItem:
- .. code-block:: tsref
+ .. ts:def:: CoinSpendHistoryItem
interface CoinSpendHistoryItem {
// Either "DEPOSIT", "MELT", "REFUND", "PAYBACK",
// "OLD-COIN-PAYBACK" or "PAYBACK-REFRESH"
type: string;
- // The total amount of the coin's value absorbed (or restored in the
case of a refund) by this transaction.
+ // The total amount of the coin's value absorbed (or restored in the
+ // case of a refund) by this transaction.
// Note that for deposit and melt this means the amount given includes
// the transaction fee, while for refunds the amount given excludes
// the transaction fee. The current coin value can thus be computed by
@@ -676,7 +663,7 @@ denomination.
// exchange, possibly zero if refunds are not allowed. Only for
"DEPOSIT" operations.
refund_deadline?: Timestamp;
- // Signature by the coin, only present if `type` is "DEPOSIT" or "MELT"
+ // Signature by the coin, only present if ``type`` is "DEPOSIT" or "MELT"
coin_sig?: EddsaSignature;
// Deposit fee in case of type "MELT".
@@ -686,7 +673,7 @@ denomination.
rc?: TALER_RefreshCommitmentP;
// Hash of the bank account from where we received the funds,
- // only present if `type` is "DEPOSIT"
+ // only present if ``type`` is "DEPOSIT"
h_wire?: HashCode;
// Deposit fee in case of type "REFUND".
@@ -694,36 +681,37 @@ denomination.
// Hash over the proposal data of the contract that
// is being paid (if type is "DEPOSIT") or refunded (if
- // `type` is "REFUND"); otherwise absent.
+ // ``type`` is "REFUND"); otherwise absent.
h_contract_terms?: HashCode;
- // Refund transaction ID. Only present if `type` is
+ // Refund transaction ID. Only present if ``type`` is
// "REFUND"
- rtransaction_id?: integer;
+ rtransaction_id?: Integer;
- // `EdDSA Signature <eddsa-sig>`_ authorizing the REFUND. Made with
- // the `public key of the merchant <merchant-pub>`_.
- // Only present if `type` is "REFUND"
+ // `EdDSA Signature <eddsa-sig>` authorizing the REFUND. Made with
+ // the `public key of the merchant <merchant-pub>`.
+ // Only present if ``type`` is "REFUND"
merchant_sig?: EddsaSignature;
// public key of the reserve that will receive the funds, for "PAYBACK"
operations.
reserve_pub?: EddsaPublicKey;
- // Signature by the exchange, only present if `type` is "PAYBACK",
+ // Signature by the exchange, only present if ``type`` is "PAYBACK",
// "OLD-COIN-PAYBACK" or "PAYBACK-REFRESH". Signature is
// of type TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK for "PAYBACK",
// and of type TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK_REFRESH
otherwise.
exchange_sig?: EddsaSignature;
- // public key used to sign `exchange_sig`, only present if
`exchange_sig` present.
+ // public key used to sign ``exchange_sig``,
+ // only present if ``exchange_sig`` present.
exchange_pub?: EddsaPublicKey;
// Blinding factor of the revoked new coin,
- // only present if `type` is "REFRESH_PAYBACK".
+ // only present if ``type`` is "REFRESH_PAYBACK".
new_coin_blinding_secret: RsaBlindingKeySecret;
// Blinded public key of the revoked new coin,
- // only present if `type` is "REFRESH_PAYBACK".
+ // only present if ``type`` is "REFRESH_PAYBACK".
new_coin_ev: RsaBlindingKeySecret;
}
@@ -731,7 +719,7 @@ denomination.
Refreshing
----------
-Refreshing creates `n` new coins from `m` old coins, where the sum of
+Refreshing creates ``n`` new coins from ``m`` old coins, where the sum of
denominations of the new coins must be smaller than the sum of the old coins'
denominations plus melting (refresh) and withdrawal fees charged by the
exchange.
The refreshing API can be used by wallets to melt partially spent coins, making
@@ -747,19 +735,19 @@ the API during normal operation.
.. http:post:: /refresh/melt
"Melts" coins. Invalidates the coins and prepares for exchangeing of fresh
- coins. Taler uses a global parameter `kappa` for the cut-and-choose
+ coins. Taler uses a global parameter ``kappa`` for the cut-and-choose
component of the protocol, for which this request is the commitment. Thus,
- various arguments are given `kappa`-times in this step. At present `kappa`
+ various arguments are given ``kappa``-times in this step. At present
``kappa``
is always 3.
:status 401 Unauthorized:
One of the signatures is invalid.
:status 200 OK:
- The request was succesful. The response body is `MeltResponse`_ in this
case.
+ The request was succesful. The response body is `MeltResponse` in this
case.
:status 403 Forbidden:
The operation is not allowed as at least one of the coins has insufficient
funds. The response
- is `MeltForbiddenResponse`_ in this case.
+ is `MeltForbiddenResponse` in this case.
:status 404:
the exchange does not recognize the denomination key as belonging to the
exchange,
or it has expired
@@ -767,20 +755,20 @@ the API during normal operation.
**Details:**
- .. code-block:: tsref
+ .. ts:def:: MeltRequest
interface MeltRequest {
- // `Coin public key <eddsa-coin-pub>`_, uniquely identifies the coin to
be melted
+ // `Coin public key <eddsa-coin-pub>`, uniquely identifies the coin to
be melted
coin_pub: string;
// Hash of the denomination public key, to determine total coin value.
denom_pub_hash: HashCode;
- // Signature over the `coin public key <eddsa-coin-pub>`_ by the
denomination.
+ // Signature over the `coin public key <eddsa-coin-pub>` by the
denomination.
denom_sig: RsaSignature;
- // Signature by the `coin <coin-priv>`_ over the melt commitment.
+ // Signature by the `coin <coin-priv>` over the melt commitment.
confirm_sig: EddsaSignature;
// Amount of the value of the coin that should be melted as part of
@@ -788,7 +776,7 @@ the API during normal operation.
value_with_fee: Amount;
// Melt commitment. Hash over the various coins to be withdrawn.
- // See also `TALER_refresh_get_commitment()`
+ // See also ``TALER_refresh_get_commitment()``
rc: TALER_RefreshCommitmentP;
}
@@ -796,21 +784,19 @@ the API during normal operation.
For details about the HKDF used to derive the new coin private keys and
the blinding factors from ECDHE between the transfer public keys and
the private key of the melted coin, please refer to the
- implementation in `libtalerutil`.
+ implementation in ``libtalerutil``.
- .. _tsref-type-MeltResponse:
- .. _MeltResponse:
- .. code-block:: tsref
+ .. ts:def:: MeltResponse
interface MeltResponse {
- // Which of the `kappa` indices does the client not have to reveal.
+ // Which of the ``kappa`` indices does the client not have to reveal.
noreveal_index: number;
- // Signature of `TALER_RefreshMeltConfirmationPS`_ whereby the exchange
- // affirms the successful melt and confirming the `noreveal_index`
+ // Signature of `TALER_RefreshMeltConfirmationPS` whereby the exchange
+ // affirms the successful melt and confirming the ``noreveal_index``
exchange_sig: EddsaSignature;
- // `public EdDSA key <sign-key-pub>`_ of the exchange that was used to
generate the signature.
+ // `public EdDSA key <sign-key-pub>` of the exchange that was used to
generate the signature.
// Should match one of the exchange's signing keys from /keys. Again
given
// explicitly as the client might otherwise be confused by clock skew as
to
// which signing key was used.
@@ -818,9 +804,7 @@ the API during normal operation.
}
- .. _tsref-type-MeltForbiddenResponse:
- .. _MeltForbiddenResponse:
- .. code-block:: tsref
+ .. ts:def:: MeltForbiddenResponse
interface MeltForbiddenResponse {
// Always "insufficient funds"
@@ -848,50 +832,50 @@ the API during normal operation.
.. http:post:: /refresh/reveal
Reveal previously commited values to the exchange, except for the values
- corresponding to the `noreveal_index` returned by the /exchange/melt step.
+ corresponding to the ``noreveal_index`` returned by the /exchange/melt step.
Errors such as failing to do proper arithmetic when it comes to calculating
the total of the coin values and fees are simply reported as bad requests.
This includes issues such as melting the same coin twice in the same session,
which is simply not allowed. However, theoretically it is possible to melt a
- coin twice, as long as the `value_with_fee` of the two melting operations is
+ coin twice, as long as the ``value_with_fee`` of the two melting operations
is
not larger than the total remaining value of the coin before the melting
operations. Nevertheless, this is not really useful.
:status 200 OK:
The transfer private keys matched the commitment and the original request
was well-formed.
- The response body is a `RevealResponse`_
+ The response body is a `RevealResponse`
:status 409 Conflict:
There is a problem between the original commitment and the revealed private
keys. The returned information is proof of the missmatch, and therefore
rather verbose, as it includes most of the original /refresh/melt request,
but of course expected to be primarily used for diagnostics.
- The response body is a `RevealConflictResponse`_.
+ The response body is a `RevealConflictResponse`.
**Details:**
Request body contains a JSON object with the following fields:
- .. code-block:: tsref
+ .. ts:def:: RevealRequest
interface RevealRequest {
- // Array of `n` new hash codes of denomination public keys to order.
+ // Array of ``n`` new hash codes of denomination public keys to order.
new_denoms_h: HashCode[];
- // Array of `n` entries with blinded coins,
- // matching the respective entries in `new_denoms`.
+ // Array of ``n`` entries with blinded coins,
+ // matching the respective entries in ``new_denoms``.
coin_evs: CoinEnvelope[];
- // `kappa - 1` transfer private keys (ephemeral ECDHE keys)
+ // ``kappa - 1`` transfer private keys (ephemeral ECDHE keys)
transfer_privs: EddsaPrivateKey[];
- // transfer public key at the `noreveal_index`.
+ // transfer public key at the ``noreveal_index``.
transfer_pub: EddsaPublicKey;
- // Array of `n` signatures made by the wallet using the old coin's
private key,
+ // Array of ``n`` signatures made by the wallet using the old coin's
private key,
// used later to verify the /refresh/link response from the exchange.
- // Signs over a `TALER_CoinLinkSignaturePS`_
+ // Signs over a `TALER_CoinLinkSignaturePS`
link_sigs: EddsaSignature[];
// The original commitment, used to match the /refresh/reveal
@@ -900,8 +884,7 @@ the API during normal operation.
}
- .. _RevealResponse:
- .. code-block:: tsref
+ .. ts:def:: RevealResponse
interface RevealResponse {
// List of the exchange's blinded RSA signatures on the new coins. Each
@@ -911,15 +894,14 @@ the API during normal operation.
}
- .. _RevealConflictResponse:
- .. code-block:: tsref
+ .. ts:def:: RevealConflictResponse
interface RevealConflictResponse {
// Constant "commitment violation"
error: string;
// Detailed error code
- code: integer;
+ code: Integer;
// Commitment as calculated by the exchange from the revealed data.
rc_expected: HashCode;
@@ -947,11 +929,10 @@ the API during normal operation.
**Details:**
- .. _tsref-type-LinkResponse:
- .. code-block:: tsref
+ .. ts:def:: LinkResponse
interface LinkResponse {
- // transfer ECDHE public key corresponding to the `coin_pub`, used to
+ // transfer ECDHE public key corresponding to the ``coin_pub``, used to
// compute the blinding factor and private key of the fresh coins.
transfer_pub: EcdhePublicKey;
@@ -960,8 +941,7 @@ the API during normal operation.
new_coins: NewCoinInfo[];
}
- .. _tsref-type-NewCoinInfo:
- .. code-block:: tsref
+ .. ts:def:: NewCoinInfo
interface NewCoinInfo {
// RSA public key of the exchangeed coin.
@@ -975,7 +955,7 @@ the API during normal operation.
coin_ev: CoinEnvelope;
// Signature made by the old coin over the refresh request.
- // Signs over a `TALER_CoinLinkSignaturePS`_
+ // Signs over a `TALER_CoinLinkSignaturePS`
link_sig: EddsaSignature;
}
@@ -994,15 +974,15 @@ part of the /keys response. If and only if this has
happened,
coins that were signed with those denomination keys can be cashed
in using this API.
- .. note::
+.. note::
- This is a proposed API, we are implementing it as bug #3887.
+ This is a proposed API, we are implementing it as bug #3887.
.. http:post:: /payback
Demand that a coin be refunded via wire transfer to the original owner.
- **Request:** The request body must be a `PaybackRequest`_ object.
+ **Request:** The request body must be a `PaybackRequest` object.
**Response:**
:status 200 OK:
@@ -1013,7 +993,7 @@ in using this API.
coin is not lost.
:status 401 Unauthorized: The coin's signature is invalid.
:status 403 Forbidden: The coin was already used for payment.
- The response is a `DepositDoubleSpendError`_.
+ The response is a `DepositDoubleSpendError`.
:status 404 Not Found:
The denomination key is not in the set of denomination
keys where emergency pay back is enabled, or the blinded
@@ -1021,15 +1001,14 @@ in using this API.
**Details:**
- .. _PaybackRequest:
- .. code-block:: tsref
+ .. ts:def:: PaybackRequest
interface PaybackRequest {
// Hash of denomination public key (RSA), specifying the type of coin
the client
// would like the exchange to pay back.
denom_pub_hash: HashCode;
- // Signature over the `coin public key <eddsa-coin-pub>`_ by the
denomination.
+ // Signature over the `coin public key <eddsa-coin-pub>` by the
denomination.
denom_sig: RsaSignature;
// coin's public key
@@ -1038,7 +1017,7 @@ in using this API.
// coin's blinding factor
coin_blind_key_secret: RsaBlindingKeySecret;
- // Signature of `TALER_PaybackRequestPS`_ created with the `coin's
private key <coin-priv>`_
+ // Signature of `TALER_PaybackRequestPS` created with the `coin's
private key <coin-priv>`
coin_sig: EddsaSignature;
// Was the coin refreshed (and thus the payback should go to the old
coin)?
@@ -1047,8 +1026,7 @@ in using this API.
}
- .. _PaybackConfirmation:
- .. code-block:: tsref
+ .. ts:def:: PaybackConfirmation
interface PaybackConfirmation {
// public key of the reserve that will receive the payback,
@@ -1066,9 +1044,9 @@ in using this API.
// Time by which the exchange received the /payback request.
timestamp: Timestamp;
- // the EdDSA signature of `TALER_PaybackConfirmationPS`_ (refreshed
false)
- // or `TALER_PaybackRefreshConfirmationPS_` (refreshed true) using a
current
- // `signing key of the exchange <sign-key-priv>`_ affirming the
successful
+ // the EdDSA signature of `TALER_PaybackConfirmationPS` (refreshed false)
+ // or `TALER_PaybackRefreshConfirmationPS` (refreshed true) using a
current
+ // `signing key of the exchange <sign-key-priv>` affirming the successful
// payback request, and that the exchange promises to transfer the funds
// by the date specified (this allows the exchange delaying the transfer
// a bit to aggregate additional payback requests into a larger one).
@@ -1125,13 +1103,11 @@ typically also view the balance.)
:status 200 OK:
The wire transfer is known to the exchange, details about it follow in the
body.
- The body of the response is a `TrackTransferResponse`_.
+ The body of the response is a `TrackTransferResponse`.
:status 404 Not Found:
The wire transfer identifier is unknown to the exchange.
- .. _TrackTransferResponse:
- .. _tsref-type-TrackTransferResponse:
- .. code-block:: tsref
+ .. ts:def:: TrackTransferResponse
interface TrackTransferResponse {
// Total amount transferred
@@ -1163,8 +1139,7 @@ typically also view the balance.)
exchange_pub: EddsaSignature;
}
- .. _tsref-type-TrackTransferDetail:
- .. code-block:: tsref
+ .. ts:def:: TrackTransferDetail
interface TrackTransferDetail {
// SHA-512 hash of the contact of the merchant with the customer.
@@ -1185,26 +1160,24 @@ typically also view the balance.)
Provide the wire transfer identifier associated with an (existing) deposit
operation.
- **Request:** The request body must be a `TrackTransactionRequest`_ JSON
object.
+ **Request:** The request body must be a `TrackTransactionRequest` JSON
object.
**Response:**
:status 200 OK:
The deposit has been executed by the exchange and we have a wire transfer
identifier.
- The response body is a `TrackTransactionResponse`_ object.
+ The response body is a `TrackTransactionResponse` object.
:status 202 Accepted:
The deposit request has been accepted for processing, but was not yet
executed. Hence the exchange does not yet have a wire transfer
identifier. The
merchant should come back later and ask again.
- The response body is a `TrackTransactionAcceptedResponse`_.
+ The response body is a `TrackTransactionAcceptedResponse`.
:status 401 Unauthorized: The signature is invalid.
:status 404 Not Found: The deposit operation is unknown to the exchange
**Details:**
- .. _tsref-type-TrackTransactionRequest:
- .. _TrackTransactionRequest:
- .. code-block:: tsref
+ .. ts:def:: TrackTransactionRequest
interface TrackTransactionRequest {
// SHA-512 hash of the merchant's payment details.
@@ -1227,9 +1200,7 @@ typically also view the balance.)
}
- .. _tsref-type-TrackTransactionResponse:
- .. _TrackTransactionResponse:
- .. code-block:: tsref
+ .. ts:def:: TrackTransactionResponse
interface TrackTransactionResponse {
// raw wire transfer identifier of the deposit.
@@ -1255,9 +1226,7 @@ typically also view the balance.)
exchange_pub: EddsaPublicKey;
}
- .. _tsref-type-TrackTransactionAcceptedResponse:
- .. _TrackTransactionAcceptedResponse:
- .. code-block:: tsref
+ .. ts:def:: TrackTransactionAcceptedResponse
interface TrackTransactionAcceptedResponse {
// time by which the exchange currently thinks the deposit will be
executed.
@@ -1274,12 +1243,12 @@ Refunds
Undo deposit of the given coin, restoring its value.
- **Request:** The request body must be a `RefundRequest`_ object.
+ **Request:** The request body must be a `RefundRequest` object.
**Response:**
:status 200 Ok:
- The operation succeeded, the exchange confirms that the coin can now be
refreshed. The response will include a `RefundSuccess`_ object.
+ The operation succeeded, the exchange confirms that the coin can now be
refreshed. The response will include a `RefundSuccess` object.
:status 401 Unauthorized:
Merchant signature is invalid.
:status 404 Not found:
@@ -1289,8 +1258,7 @@ Refunds
**Details:**
- .. _RefundRequest:
- .. code-block:: tsref
+ .. ts:def:: RefundRequest
interface RefundRequest {
@@ -1320,8 +1288,7 @@ Refunds
}
- .. _RefundSuccess:
- .. code-block:: tsref
+ .. ts:def:: RefundSuccess
interface RefundSuccess {
// The string constant "REFUND_OK"
@@ -1355,9 +1322,9 @@ binary-compatible with the implementation of the exchange.
**Request:**
- .. code-block:: tsref
+ .. ts:def:: TestBase32Request
- {
+ interface TestBase32Request {
// some base32-encoded value
input: Base32;
}
@@ -1380,10 +1347,10 @@ binary-compatible with the implementation of the
exchange.
.. code-block:: tsref
{
- // Some `base32`_-encoded value
+ // Some `base32`-encoded value
input: Base32;
- // some `base32`_-encoded hash that is used to derive the symmetric key
and
+ // some `base32`-encoded hash that is used to derive the symmetric key
and
// initialization vector for the encryption using the HKDF with "skey"
and
// "iv" as the salt.
key_hash: Base32;
@@ -1409,7 +1376,7 @@ binary-compatible with the implementation of the exchange.
.. code-block:: tsref
{
- // Some `base32`_-encoded value
+ // Some `base32`-encoded value
input: Base32;
}
@@ -1513,7 +1480,7 @@ binary-compatible with the implementation of the exchange.
.. code-block:: tsref
{
- // Blind RSA signature over the `blind_ev` using the private key
+ // Blind RSA signature over the ``blind_ev`` using the private key
// corresponding to the RSA public key returned by /test/rsa/get.
rsa_blind_sig: BlindedRsaSignature;
}
@@ -1530,7 +1497,7 @@ binary-compatible with the implementation of the exchange.
// Private transfer key
trans_priv: string;
- // `Coin public key <eddsa-coin-pub>`_
+ // `Coin public key._
coin_pub: EddsaPublicKey;
}
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 35483f3..5605476 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -35,7 +35,7 @@ Receiving Payments
Create a new order that a customer can pay for.
- This request is **not** idempotent unless an `order_id` is explicitly
specified.
+ This request is **not** idempotent unless an ``order_id`` is explicitly
specified.
.. note::
@@ -46,16 +46,15 @@ Receiving Payments
**Request:**
- The request must be a `PostOrderRequest`_.
+ The request must be a `PostOrderRequest`.
**Response**
:status 200 OK:
The backend has successfully created the proposal. The response is a
- `PostOrderResponse`_.
+ :ts:type:`PostOrderResponse`.
- .. _PostOrderRequest:
- .. code-block:: tsref
+ .. ts:def:: PostOrderRequest
interface PostOrderRequest {
// The order must at least contain the minimal
@@ -64,13 +63,11 @@ Receiving Payments
}
The following fields must be specified in the ``order`` field of the
request. Other fields from
- `ContractTerms`_ are optional, and will override the defaults in the
merchant configuration.
+ `ContractTerms` are optional, and will override the defaults in the merchant
configuration.
- .. _MinimalOrderDetail:
- .. _tsref-type-MinimalOrderDetail:
- .. code-block:: tsref
+ .. ts:def:: MinimalOrderDetail
- interface MinimalOrderRequest {
+ interface MinimalOrderDetail {
// Amount to be paid by the customer
amount: Amount
@@ -83,8 +80,7 @@ Receiving Payments
fulfillment_url: string;
}
- .. _PostOrderResponse:
- .. code-block:: tsref
+ .. ts:def:: PostOrderResponse
interface PostOrderResponse {
// Order ID of the response that was just created
@@ -105,16 +101,13 @@ Receiving Payments
**Response:**
- Returns a `CheckPaymentResponse`_, whose format can differ based on the
status of the payment.
+ Returns a `CheckPaymentResponse`, whose format can differ based on the
status of the payment.
- .. _CheckPaymentResponse:
- .. code-block:: tsref
+ .. ts:def:: CheckPaymentResponse
type CheckPaymentResponse = CheckPaymentPaidResponse |
CheckPaymentUnpaidResponse
- .. _CheckPaymentPaidResponse:
- .. _tsref-type-CheckPaymentPaidResponse:
- .. code-block:: tsref
+ .. ts:def:: CheckPaymentPaidResponse
interface CheckPaymentPaidResponse {
paid: true;
@@ -129,9 +122,7 @@ Receiving Payments
contract_terms: ContractTerms;
}
- .. _CheckPaymentUnpaidResponse:
- .. _tsref-type-CheckPaymentUnpaidResponse:
- .. code-block:: tsref
+ .. ts:def:: CheckPaymentUnpaidResponse
interface CheckPaymentUnpaidResponse {
paid: false;
@@ -150,21 +141,20 @@ Giving Refunds
.. http:post:: /refund
Increase the refund amount associated with a given order. The user should be
- redirected to the `refund_redirect_url` to trigger refund processing in the
wallet.
+ redirected to the ``refund_redirect_url`` to trigger refund processing in
the wallet.
**Request**
- The request body is a `RefundRequest`_ object.
+ The request body is a `RefundRequest` object.
**Response**
:status 200 OK:
- The refund amount has been increased, the backend responds with a
`MerchantRefundResponse`_
+ The refund amount has been increased, the backend responds with a
`MerchantRefundResponse`
:status 400 Bad request:
The refund amount is not consistent: it is not bigger than the previous
one.
- .. _RefundRequest:
- .. code-block:: tsref
+ .. ts:def:: RefundRequest
interface RefundRequest {
// Order id of the transaction to be refunded
@@ -177,8 +167,7 @@ Giving Refunds
reason: string;
}
- .. _MerchantRefundResponse:
- .. code-block:: tsref
+ .. ts:def:: MerchantRefundResponse
interface MerchantRefundResponse {
// Public key of the merchant
@@ -197,16 +186,14 @@ Giving Refunds
refund_redirect_url: string;
}
- .. _MerchantRefundPermission:
- .. _tsref-type-MerchantRefundPermissoin:
- .. code-block:: tsref
+ .. ts:def:: MerchantRefundPermission
interface MerchantRefundPermission {
// Amount to be refunded.
- refund_amount: AmountJson;
+ refund_amount: Amount;
// Fee for the refund.
- refund_fee: AmountJson;
+ refund_fee: Amount;
// Public key of the coin being refunded.
coin_pub: string;
@@ -227,18 +214,18 @@ Giving Customer Tips
.. http:post:: /tip-authorize
Authorize a tip that can be picked up by the customer's wallet by POSTing to
- `/tip-pickup`. Note that this is simply the authorization step the back
- office has to trigger first. The user should be navigated to the
`tip_redirect_url`
+ ``/tip-pickup``. Note that this is simply the authorization step the back
+ office has to trigger first. The user should be navigated to the
``tip_redirect_url``
to trigger tip processing in the wallet.
**Request**
- The request body is a `TipCreateRequest`_ object.
+ The request body is a `TipCreateRequest` object.
**Response**
:status 200 OK:
- A tip has been created. The backend responds with a
`TipCreateConfirmation`_
+ A tip has been created. The backend responds with a `TipCreateConfirmation`
:status 404 Not Found:
The instance is unknown to the backend, expired or was never enabled or
the reserve is unknown to the exchange or expired (see detailed status
@@ -249,8 +236,7 @@ Giving Customer Tips
:status 412 Precondition Failed:
The tip amount requested exceeds the available reserve balance for tipping.
- .. _TipCreateRequest:
- .. code-block:: tsref
+ .. ts:def:: TipCreateRequest
interface TipCreateRequest {
// Amount that the customer should be tipped
@@ -264,8 +250,7 @@ Giving Customer Tips
next_url: string;
}
- .. _TipCreateConfirmation:
- .. code-block:: tsref
+ .. ts:def:: TipCreateConfirmation
interface TipCreateConfirmation {
// Token that will be handed to the wallet,
@@ -286,12 +271,11 @@ Giving Customer Tips
**Response**
:status 200 OK:
- A tip has been created. The backend responds with a `TipQueryResponse`_
+ A tip has been created. The backend responds with a `TipQueryResponse`
:status 412 Precondition Failed:
The merchant backend instance does not have a tipping reserve configured.
- .. _TipQueryResponse:
- .. code-block:: tsref
+ .. ts:def:: TipQueryResponse
interface TipQueryResponse {
// Amount still available
@@ -329,7 +313,7 @@ Tracking Wire Transfers
:status 200 OK:
The wire transfer is known to the exchange, details about it follow in the
body.
- The body of the response is a `MerchantTrackTransferResponse`_. Note that
+ The body of the response is a `TrackTransferResponse`. Note that
the similarity to the response given by the exchange for a /track/transfer
is completely intended.
@@ -337,13 +321,11 @@ Tracking Wire Transfers
The wire transfer identifier is unknown to the exchange.
:status 424 Failed Dependency: The exchange provided conflicting information
about the transfer. Namely,
- there is at least one deposit among the deposits aggregated by `wtid` that
accounts for a coin whose
+ there is at least one deposit among the deposits aggregated by ``wtid``
that accounts for a coin whose
details don't match the details stored in merchant's database about the
same keyed coin.
- The response body contains the `TrackTransferConflictDetails`_.
+ The response body contains the `TrackTransferConflictDetails`.
- .. _MerchantTrackTransferResponse:
- .. _tsref-type-TrackTransferResponse:
- .. code-block:: tsref
+ .. ts:def:: TrackTransferResponse
interface TrackTransferResponse {
// Total amount transferred
@@ -365,7 +347,7 @@ Tracking Wire Transfers
deposits_sums: TrackTransferDetail[];
// signature from the exchange made with purpose
- // `TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT`
+ // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT``
exchange_sig: EddsaSignature;
// public EdDSA key of the exchange that was used to generate the
signature.
@@ -375,15 +357,14 @@ Tracking Wire Transfers
exchange_pub: EddsaSignature;
}
- .. _tsref-type-TrackTransferDetail:
- .. code-block:: tsref
+ .. ts:def:: TrackTransferDetail
interface TrackTransferDetail {
// Business activity associated with the wire transferred amount
- // `deposit_value`.
+ // ``deposit_value``.
order_id: string;
- // The total amount the exchange paid back for `order_id`.
+ // The total amount the exchange paid back for ``order_id``.
deposit_value: Amount;
// applicable fees for the deposit
@@ -393,23 +374,21 @@ Tracking Wire Transfers
**Details:**
- .. _tsref-type-TrackTransferConflictDetails:
- .. _TrackTransferConflictDetails:
- .. code-block:: tsref
+ .. ts:def:: TrackTransferConflictDetails
interface TrackTransferConflictDetails {
- // Numerical `error code <error-codes>`_
+ // Numerical `error code <error-codes>`
code: number;
// Text describing the issue for humans.
- hint: String;
+ hint: string;
- // A /deposit response matching `coin_pub` showing that the
- // exchange accepted `coin_pub` for `amount_with_fee`.
+ // A /deposit response matching ``coin_pub`` showing that the
+ // exchange accepted ``coin_pub`` for ``amount_with_fee``.
exchange_deposit_proof: DepositSuccess;
- // Offset in the `exchange_transfer_proof` where the
- // exchange's response fails to match the `exchange_deposit_proof`.
+ // Offset in the ``exchange_transfer_proof`` where the
+ // exchange's response fails to match the ``exchange_deposit_proof``.
conflict_offset: number;
// The response from the exchange which tells us when the
@@ -420,7 +399,7 @@ Tracking Wire Transfers
// Public key of the coin for which we have conflicting information.
coin_pub: EddsaPublicKey;
- // Merchant transaction in which `coin_pub` was involved for which
+ // Merchant transaction in which ``coin_pub`` was involved for which
// we have conflicting information.
transaction_id: number;
@@ -445,12 +424,12 @@ Tracking Wire Transfers
:status 200 OK:
The deposit has been executed by the exchange and we have a wire transfer
identifier.
- The response body is a JSON array of `TransactionWireTransfer`_ objects.
+ The response body is a JSON array of `TransactionWireTransfer` objects.
:status 202 Accepted:
The deposit request has been accepted for processing, but was not yet
executed. Hence the exchange does not yet have a wire transfer identifier.
The merchant should come back later and ask again.
- The response body is a :ref:`TrackTransactionAcceptedResponse
<TrackTransactionAcceptedResponse>`. Note that
+ The response body is a `TrackTransactionAcceptedResponse
<TrackTransactionAcceptedResponse>`. Note that
the similarity to the response given by the exchange for a /track/order
is completely intended.
:status 404 Not Found: The transaction is unknown to the backend.
@@ -458,13 +437,11 @@ Tracking Wire Transfers
The exchange previously claimed that a deposit was not included in a wire
transfer, and now claims that it is. This means that the exchange is
dishonest. The response contains the cryptographic proof that the exchange
- is misbehaving in the form of a `TransactionConflictProof`_.
+ is misbehaving in the form of a `TransactionConflictProof`.
**Details:**
- .. _tsref-type-TransactionWireTransfer:
- .. _TransactionWireTransfer:
- .. code-block:: tsref
+ .. ts:def:: TransactionWireTransfer
interface TransactionWireTransfer {
@@ -482,9 +459,7 @@ Tracking Wire Transfers
amount: Amount;
}
- .. _tsref-type-CoinWireTransfer:
- .. _CoinWireTransfer:
- .. code-block:: tsref
+ .. ts:def:: CoinWireTransfer
interface CoinWireTransfer {
// public key of the coin that was deposited
@@ -497,12 +472,10 @@ Tracking Wire Transfers
deposit_fee: Amount;
}
- .. _TransactionConflictProof:
- .. _tsref-type-TransactionConflictProof:
- .. code-block:: tsref
+ .. ts:def:: TransactionConflictProof
interface TransactionConflictProof {
- // Numerical `error code <error-codes>`_
+ // Numerical `error code <error-codes>`
code: number;
// Human-readable error description
@@ -510,14 +483,14 @@ Tracking Wire Transfers
// A claim by the exchange about the transactions associated
// with a given wire transfer; it does not list the
- // transaction that `transaction_tracking_claim` says is part
+ // transaction that ``transaction_tracking_claim`` says is part
// of the aggregate. This is
- // a `/track/transfer` response from the exchange.
+ // a ``/track/transfer`` response from the exchange.
wtid_tracking_claim: TrackTransferResponse;
// The current claim by the exchange that the given
// transaction is included in the above WTID.
- // (A response from `/track/order`).
+ // (A response from ``/track/order``).
transaction_tracking_claim: TrackTransactionResponse;
// Public key of the coin for which we got conflicting information.
@@ -536,18 +509,18 @@ Transaction history
**Request**
- :query date: time threshold, see `delta` for its interpretation.
- :query start: row number threshold, see `delta` for its interpretation.
Defaults to `UINT64_MAX`, namely the biggest row id possible in the database.
- :query delta: takes value of the form `N (-N)`, so that at most `N` values
strictly younger (older) than `start` and `date` are returned. Defaults to
`-20`.
- :query ordering: takes value `descending` or `ascending` according to the
results wanted from younger to older or vice versa. Defaults to `descending`.
+ :query date: time threshold, see ``delta`` for its interpretation.
+ :query start: row number threshold, see ``delta`` for its interpretation.
Defaults to ``UINT64_MAX``, namely the biggest row id possible in the database.
+ :query delta: takes value of the form ``N (-N)``, so that at most ``N``
values strictly younger (older) than ``start`` and ``date`` are returned.
Defaults to ``-20``.
+ :query ordering: takes value ``"descending"`` or ``"ascending"`` according
to the results wanted from younger to older or vice versa. Defaults to
``"descending"``.
**Response**
- :status 200 OK: The response is a JSON `array` of `TransactionHistory`_.
The array is sorted such that entry `i` is younger than entry `i+1`.
+ :status 200 OK:
+ The response is a JSON ``array`` of `TransactionHistory`. The array is
+ sorted such that entry ``i`` is younger than entry ``i+1``.
- .. _tsref-type-TransactionHistory:
- .. _TransactionHistory:
- .. code-block:: tsref
+ .. ts:def:: TransactionHistory
interface TransactionHistory {
// The serial number this entry has in the merchant's DB.
@@ -583,21 +556,18 @@ Dynamic Merchant Instance
:status 200 OK:
The backend has successfully returned the list of instances stored. Returns
- a `InstancesResponse`_.
+ a `InstancesResponse`.
- .. _InstancesResponse:
- .. code-block:: tsref
+ .. ts:def:: InstancesResponse
interface InstancesResponse {
- // List of instances that are present in the backend(see `below
<Instance>`_)
+ // List of instances that are present in the backend (see `Instance`)
instances: Instance[];
}
-The `instance` object describes the instance registered with the backend. It
has the following structure:
+ The `Instance` object describes the instance registered with the backend. It
has the following structure:
- .. Instance:
- .. _tsref-type-Instance:
- .. code-block:: tsref
+ .. ts:def:: Instance
interface Instance {
// Merchant name corresponding to this instance.
@@ -620,16 +590,15 @@ The `instance` object describes the instance registered
with the backend. It has
**Request**
- The request must be a `CreateInstanceRequest`_.
+ The request must be a `CreateInstanceRequest`.
**Response**
:status 200 OK:
The backend has successfully created the instance. The response is a
- `CreateInstanceResponse`_.
+ `CreateInstanceResponse`.
- .. _CreateInstanceRequest:
- .. code-block:: tsref
+ .. ts:def:: CreateInstanceRequest
interface CreateInstanceRequest {
// The URL where the wallet has to send coins.
@@ -646,8 +615,7 @@ The `instance` object describes the instance registered
with the backend. It has
}
- .. _CreateInstanceResponse:
- .. code-block:: tsref
+ .. ts:def:: CreateInstanceResponse
interface CreateInstanceResponse {
// Merchant instance of the response that was created
@@ -670,10 +638,9 @@ The `instance` object describes the instance registered
with the backend. It has
:status 200 OK:
The backend has successfully returned the list of instances stored. Returns
- a `QueryInstancesResponse`_.
+ a `QueryInstancesResponse`.
- .. _QueryInstancesResponse:
- .. code-block:: tsref
+ .. ts:def:: QueryInstancesResponse
interface QueryInstancesResponse {
// The URL where the wallet has to send coins.
@@ -698,16 +665,15 @@ The `instance` object describes the instance registered
with the backend. It has
**Request**
- The request must be a `PostInstanceUpdateRequest`_.
+ The request must be a `PostInstanceUpdateRequest`.
**Response**
:status 200 OK:
The backend has successfully updated the instance. The response is a
- `PostInstanceUpdateResponse`_.
+ `PostInstanceUpdateResponse`.
- .. _PostInstanceUpdateRequest:
- .. code-block:: tsref
+ .. ts:def:: PostInstanceUpdateRequest
interface PostInstanceUpdateRequest {
// Merchant instance that is to be updaated. Required.
@@ -722,8 +688,7 @@ The `instance` object describes the instance registered
with the backend. It has
}
- .. _PostInstanceUpdateResponse:
- .. code-block:: tsref
+ .. ts:def:: PostInstanceUpdateResponse
interface PostInstanceUpdateResponse {
// Merchant instance of the response that was updated
@@ -746,10 +711,9 @@ The `instance` object describes the instance registered
with the backend. It has
:status 200 OK:
The backend has successfully removed the instance. The response is a
- `PostInstanceRemoveResponse`_.
+ `PostInstanceRemoveResponse`.
- .. _PostInstanceRemoveResponse:
- .. code-block:: tsref
+ .. ts:def:: PostInstanceRemoveResponse
interface PostInstanceRemoveResponse {
deleted: true;
@@ -760,11 +724,9 @@ The `instance` object describes the instance registered
with the backend. It has
The Contract Terms
------------------
-The `contract terms` must have the following structure:
+The contract terms must have the following structure:
- .. _ContractTerms:
- .. _tsref-type-ContractTerms:
- .. code-block:: tsref
+ .. ts:def:: ContractTerms
interface ContractTerms {
// Human-readable description of the whole purchase
@@ -807,9 +769,9 @@ The `contract terms` must have the following structure:
// between the 'max_fee' and the sum of the actual deposit fees.
// Optional, default value if missing is 1. 0 and negative values are
// invalid and also interpreted as 1.
- wire_fee_amortization: Integer;
+ wire_fee_amortization: number;
- // List of products that are part of the purchase (see `below
<Product>`_)
+ // List of products that are part of the purchase (see `Product`).
products: Product[];
// Time when this contract was generated
@@ -860,11 +822,9 @@ The `contract terms` must have the following structure:
listing it in the exchanges arry, or for which the merchant accepts an
auditor
that audits that exchange by listing it in the auditors array.
- The `product` object describes the product being purchased from the
merchant. It has the following structure:
+ The `Product` object describes the product being purchased from the
merchant. It has the following structure:
- .. _Product:
- .. _tsref-type-Product:
- .. code-block:: tsref
+ .. ts:def:: Product
interface Product {
// Human-readable product description.
@@ -873,27 +833,26 @@ The `contract terms` must have the following structure:
// The quantity of the product to deliver to the customer (optional, if
applicable)
quantity?: string;
- // The price of the product; this is the total price for the amount
specified by `quantity`
+ // The price of the product; this is the total price for the amount
specified by 'quantity'
price: Amount;
// merchant-internal identifier for the product
product_id?: string;
- // a list of objects indicating a `taxname` and its amount. Again,
italics denotes the object field's name.
+ // a list of objects indicating a 'taxname' and its amount. Again,
italics denotes the object field's name.
taxes?: any[];
// time indicating when this product should be delivered
delivery_date: Timestamp;
// where to deliver this product. This may be an URL for online delivery
- // (i.e. `http://example.com/download` or `mailto:address@hidden`),
- // or a location label defined inside the proposition's `locations`.
- // The presence of a colon (`:`) indicates the use of an URL.
+ // (i.e. 'http://example.com/download' or 'mailto:address@hidden'),
+ // or a location label defined inside the proposition's 'locations'.
+ // The presence of a colon (':') indicates the use of an URL.
delivery_location: string;
}
- .. _tsref-type-Merchant:
- .. code-block:: ts
+ .. ts:def:: Merchant
interface Merchant {
// label for a location with the business address of the merchant
@@ -908,9 +867,7 @@ The `contract terms` must have the following structure:
}
- .. _tsref-type-Location:
- .. _Location:
- .. code-block:: ts
+ .. ts:def:: Location
interface Location {
country?: string;
@@ -923,8 +880,7 @@ The `contract terms` must have the following structure:
street_number?: string;
}
- .. _tsref-type-Auditor:
- .. code-block:: tsref
+ .. ts:def:: Auditor
interface Auditor {
// official name
@@ -937,8 +893,7 @@ The `contract terms` must have the following structure:
url: string;
}
- .. _tsref-type-Exchange:
- .. code-block:: tsref
+ .. ts:def:: Exchange
interface Exchange {
// the exchange's base URL
@@ -953,25 +908,27 @@ The `contract terms` must have the following structure:
Customer-facing API
-------------------
-The `/public/*` endpoints are publicly exposed on the internet and accessed
+The ``/public/*`` endpoints are publicly exposed on the internet and accessed
both by the user's browser and their wallet.
.. http:post:: /public/pay
Pay for a proposal by giving a deposit permission for coins. Typically used
by
- the customer's wallet. Can also be used in `abort-refund` mode to refund
coins
+ the customer's wallet. Can also be used in ``abort-refund`` mode to refund
coins
that were already deposited as part of a failed payment.
**Request:**
- The request must be a :ref:`pay request <PayRequest>`.
+ The request must be a `pay request <PayRequest>`.
**Response:**
:status 200 OK:
- The exchange accepted all of the coins. The body is a `PaymentResponse`_
if the request used the mode "pay", or a `MerchantRefundResponse`_ if the
request used was the mode "abort-refund".
- The `frontend` should now fullfill the contract.
+ The exchange accepted all of the coins. The body is a `PaymentResponse` if
+ the request used the mode "pay", or a `MerchantRefundResponse` if the
+ request used was the mode "abort-refund".
+ The ``frontend`` should now fullfill the contract.
:status 412 Precondition Failed:
The given exchange is not acceptable for this merchant, as it is not in the
list of accepted exchanges and not audited by an approved auditor.
@@ -979,22 +936,21 @@ both by the user's browser and their wallet.
One of the coin signatures was not valid.
:status 403 Forbidden:
The exchange rejected the payment because a coin was already spent before.
- The response will include the `coin_pub` for which the payment failed,
- in addition to the response from the exchange to the `/deposit` request.
+ The response will include the 'coin_pub' for which the payment failed,
+ in addition to the response from the exchange to the ``/deposit`` request.
The backend will return verbatim the error codes received from the exchange's
:ref:`deposit <deposit>` API. If the wallet made a mistake, like by
double-spending for example, the frontend should pass the reply verbatim to
- the browser/wallet. This should be the expected case, as the `frontend`
+ the browser/wallet. This should be the expected case, as the ``frontend``
cannot really make mistakes; the only reasonable exception is if the
- `backend` is unavailable, in which case the customer might appreciate some
+ ``backend`` is unavailable, in which case the customer might appreciate some
reassurance that the merchant is working on getting his systems back online.
- .. _PaymentResponse:
- .. code-block:: tsref
+ .. ts:def:: PaymentResponse
interface PaymentResponse {
- // Signature on `TALER_PaymentResponsePS`_ with the public
+ // Signature on `TALER_PaymentResponsePS` with the public
// key of the merchant instance.
sig: EddsaSignature;
@@ -1002,23 +958,9 @@ both by the user's browser and their wallet.
h_contract_terms: HashCode;
}
- .. _PayRequest:
- .. code-block:: tsref
+ .. ts:def:: PayRequest
interface PayRequest {
- // Signature on `TALER_PaymentResponsePS`_ with the public
- // key of the instance in the proposal.
- sig: EddsaSignature;
-
- // Proposal data hash being signed over
- h_proposal_data: HashCode;
-
- // Proposal, send for convenience so the frontend
- // can do order processing without a second lookup on
- // a successful payment
- proposal: Proposal;
-
- // Coins with signature.
coins: CoinPaySig[];
// The merchant public key, used to uniquely
@@ -1032,6 +974,28 @@ both by the user's browser and their wallet.
mode: "pay" | "abort-refund";
}
+ .. ts:def:: CoinPaySig
+
+ export interface CoinPaySig {
+ // Signature by the coin.
+ coin_sig: string;
+
+ // Public key of the coin being spend.
+ coin_pub: string;
+
+ // Signature made by the denomination public key.
+ ub_sig: string;
+
+ // The denomination public key associated with this coin.
+ denom_pub: string;
+
+ // The amount that is subtracted from this coin with this payment.
+ contribution: Amount;
+
+ // URL of the exchange this coin was withdrawn from.
+ exchange_url: string;
+ }
+
.. http:get:: /public/pay
@@ -1048,11 +1012,9 @@ both by the user's browser and their wallet.
**Response**
:status 200 OK:
- The response is a `PublicPayStatusResponse`_.
+ The response is a `PublicPayStatusResponse`.
-
- .. _PublicPayStatusResponse:
- .. code-block:: tsref
+ .. ts:def:: PublicPayStatusResponse
interface PublicPayStatusResponse {
// Has the payment for this order been completed?
@@ -1063,9 +1025,7 @@ both by the user's browser and their wallet.
}
- .. _RefundInfo:
- .. _tsref-type-RefundInfo:
- .. code-block:: tsref
+ .. ts:def:: RefundInfo
interface RefundInfo {
@@ -1113,12 +1073,12 @@ both by the user's browser and their wallet.
**Request**
- The request body is a `TipPickupRequest`_ object.
+ The request body is a `TipPickupRequest` object.
**Response**
:status 200 OK:
- A tip is being returned. The backend responds with a `TipResponse`_
+ A tip is being returned. The backend responds with a `TipResponse`
:status 401 Unauthorized:
The tip amount requested exceeds the tip.
:status 404 Not Found:
@@ -1126,8 +1086,7 @@ both by the user's browser and their wallet.
:status 409 Conflict:
Some of the denomination key hashes of the request do not match those
currently available from the exchange (hence there is a conflict between what
the wallet requests and what the merchant believes the exchange can provide).
- .. _TipPickupRequest:
- .. code-block:: tsref
+ .. ts:def:: TipPickupRequest
interface TipPickupRequest {
@@ -1138,6 +1097,8 @@ both by the user's browser and their wallet.
planchets: PlanchetDetail[];
}
+ .. ts:def:: PlanchetDetail
+
interface PlanchetDetail {
// Hash of the denomination's public key (hashed to reduce
// bandwidth consumption)
@@ -1148,8 +1109,7 @@ both by the user's browser and their wallet.
}
- .. _TipResponse:
- .. code-block:: tsref
+ .. ts:def:: TipResponse
interface TipResponse {
// Public key of the reserve
diff --git a/core/api-sync.rst b/core/api-sync.rst
index 701c7df..207124a 100644
--- a/core/api-sync.rst
+++ b/core/api-sync.rst
@@ -110,11 +110,9 @@ Receiving Terms of Service
**Response:**
- Returns a `SyncTermsOfServiceResponse`_.
+ Returns a `SyncTermsOfServiceResponse`.
- .. _SyncTermsOfServiceResponse:
- .. _tsref-type-SyncTermsOfServiceResponse:
- .. code-block:: tsref
+ .. ts:def:: SyncTermsOfServiceResponse
interface SyncTermsOfServiceResponse {
// maximum wallet database backup size supported
@@ -125,7 +123,7 @@ Receiving Terms of Service
// how long after an account (or device) becomes dormant does the
// service expire the respective records?
- inactive_expiration: relative-time;
+ inactive_expiration: RelativeTime;
// Fee for an account, per year.
annual_fee: Amount;
@@ -140,11 +138,9 @@ Receiving Terms of Service
**Response:**
- Returns a `SaltResponse`_.
+ Returns a `SaltResponse`.
- .. _SaltResponse:
- .. _tsref-type-SaltResponse:
- .. code-block:: tsref
+ .. ts:def:: SaltResponse
interface SaltResponse {
// salt value, at least 128 bits of entropy
diff --git a/core/taler-uri.rst b/core/taler-uri.rst
index 40c110c..caa32bb 100644
--- a/core/taler-uri.rst
+++ b/core/taler-uri.rst
@@ -4,7 +4,7 @@
The taler:// URI scheme
=======================
-The `taler` URI scheme represents actions that are processed by a Taler
wallet. The basic syntax is as follows:
+The ``taler`` URI scheme represents actions that are processed by a Taler
wallet. The basic syntax is as follows:
.. code:: none
@@ -14,21 +14,21 @@ The `taler` URI scheme represents actions that are
processed by a Taler wallet.
Requesting a Payment
--------------------
-Payments are requested with the `pay` action. The parameters are a
hierarchical identifier for the requested payment:
+Payments are requested with the ``pay`` action. The parameters are a
hierarchical identifier for the requested payment:
.. code:: none
'taler://pay/' merchant-host '/' merchant-query '/' merchant-instance '/'
order-id [ '/' session-id ]
-The components `merchant-host`, `merchant-query` and `order-id` identify the
URL that is used to claim the contract
+The components ``merchant-host``, ``merchant-query`` and ``order-id`` identify
the URL that is used to claim the contract
for this payment request.
-To make the URI shorter (which is important for QR code payments), `-` (minus)
can be substituted to get a default value
+To make the URI shorter (which is important for QR code payments), ``-``
(minus) can be substituted to get a default value
for some components:
-* the default for `merchant-instance` is `default`
-* the default for `merchant-query` is `/public/proposal`
+* the default for ``merchant-instance`` is ``default``
+* the default for ``merchant-query`` is ``/public/proposal``
The following is a minimal example for a payment request from the demo
merchant, using the default instance and no session-bound payment:
@@ -45,7 +45,7 @@ Withdrawing
'taler://withdraw/' bank-host '/' bank-query '/' withdraw-uid
-When `bank-query` is `-`, the default `withdraw-operation` will be used.
+When ``bank-query`` is ``-``, the default ``withdraw-operation`` will be used.
Example:
@@ -73,7 +73,7 @@ in newer wallets.
Special URLs for fulfillment
----------------------------
-The special `fulfillment-success` action can be used in a fulfillment URI to
indicate success
+The special ``fulfillment-success`` action can be used in a fulfillment URI to
indicate success
with a message, without directing the user to a website. This is useful in
applications that are not Web-based:
When wallets encounter this URI in any other circumstance than going to a
fulfillment URL, they must raise an error.
diff --git a/core/wireformats.rst b/core/wireformats.rst
index 12d2363..724b069 100644
--- a/core/wireformats.rst
+++ b/core/wireformats.rst
@@ -59,9 +59,9 @@ follow the payto:// specification for SEPA:
* payto://sepa/IBAN
-The implementation of the @code{ebics} plugin which is envisioned to
+The implementation of the ``ebics`` plugin which is envisioned to
support the @code{sepa} method is currently incomplete. Specifically,
-we need a working implementation of `libebics` which is a sub-project
+we need a working implementation of ``libebics`` which is a sub-project
trying to implement the EBICS [#ebics]_ standard.
.. [#sepa] SEPA - Single Euro Payments Area:
diff --git a/onboarding.rst b/onboarding.rst
index ea0ae83..daeebdd 100644
--- a/onboarding.rst
+++ b/onboarding.rst
@@ -136,8 +136,8 @@ The following commands do that:
Building the documentation
==========================
-All the Taler documentation is built by the user `docbuilder` that
-runs a Buildbot worker. The following commands set the `docbuilder` up,
+All the Taler documentation is built by the user ``docbuilder`` that
+runs a Buildbot worker. The following commands set the ``docbuilder`` up,
starting with a empty home directory.
::
@@ -156,9 +156,9 @@ starting with a empty home directory.
Building the Websites.
======================
-Taler Websites, `www.taler.net` and `stage.taler.net`, are built by the
-user `taler-websites` by the means of a Buildbot worker. The following
-commands set the `taler-websites` up, starting with a empty home directory.
+Taler Websites, ``www.taler.net`` and ``stage.taler.net``, are built by the
+user ``taler-websites`` by the means of a Buildbot worker. The following
+commands set the ``taler-websites`` up, starting with a empty home directory.
::
# Log-in as the 'taler-websites' user.
@@ -175,7 +175,7 @@ commands set the `taler-websites` up, starting with a empty
home directory.
Code coverage.
==============
-Code coverage tests are run by the `lcovworker` user, and are also driven
+Code coverage tests are run by the ``lcovworker`` user, and are also driven
by Buildbot.
::
@@ -191,12 +191,12 @@ by Buildbot.
$ buildbot-worker start worker/
-The results are then published at `https://lcov.taler.net/`.
+The results are then published at ``https://lcov.taler.net/``.
Online services checker.
========================
-The user `demo-checker` runs periodic checks to see if all the
-`*.demo.taler.net` services are up and running. It is driven by
+The user ``demo-checker`` runs periodic checks to see if all the
+``*.demo.taler.net`` services are up and running. It is driven by
Buildbot, and can be bootstrapped as follows.
::
--
To stop receiving notification emails like this one, please contact
address@hidden.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] [taler-docs] branch master updated: The big doc refactoring,
gnunet <=