more work on DD13 spec

1 files changed, 183 insertions, 73 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 44dfd2a5..089890af 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -398,7 +398,8 @@ possibly by using HTTPS.
       // ``payto://`` URI identifying the account and wire method
       payto_uri: string;
 
-      // Signature using the exchange's offline key
+      // Signature using the exchange's offline key over
+      // a `TALER_MasterWireDetailsPS`
       // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``.
       master_sig: EddsaSignature;
     }
@@ -858,6 +859,7 @@ Management operations authorized by master key
       payto_uri: string;
 
       // Signature using the exchange's offline key
+      // over a `TALER_MasterWireDetailsPS`
       // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``.
       master_sig_wire: EddsaSignature;
 
@@ -964,8 +966,9 @@ This part of the API is for the use by auditors interacting with the exchange.
 
     interface AuditorSignatureAddMessage {
 
-      // Signature by the auditor.
-      // Must have purpose ``TALER_SIGNATURE_AUDITOR_XXX``.
+      // Signature by the auditor over a
+      // `TALER_ExchangeKeyValidityPS`.
+      // Must have purpose ``TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS``.
       auditor_sig: EddsaSignature;
 
     }
@@ -1022,8 +1025,9 @@ exchange.
   .. ts:def:: ReserveStatusRequest
 
     interface ReserveStatusRequest {
-      // Signature of type
-      // TALER_SIGNATURE_RESERVE_STATUS_REQUEST
+      // Signature of purpose
+      // ``TALER_SIGNATURE_RESERVE_STATUS_REQUEST`` over
+      // a `TALER_ReserveStatusRequestSignaturePS`.
       reserve_sig: EddsaSignature;
     }
 
@@ -1072,7 +1076,8 @@ exchange.
       request_timestamp: Timestamp;
 
       // Signature created with the reserve's private key.
-      // Must be of purpose TALER_SIGNATURE_RESERVE_HISTORY_REQUEST.
+      // Must be of purpose ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` over
+      // a `TALER_ReserveHistoryRequestSignaturePS`.
       reserve_sig: EddsaSignature;
 
     }
@@ -1096,7 +1101,8 @@ exchange.
       h_wire: HashCode;
 
       // Signature created with the reserve's private key.
-      // Must be of purpose TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST.
+      // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST`` over
+      // a `TALER_AccountSetupRequestSignaturePS`.
       reserve_sig: EddsaSignature;
 
     }
@@ -1125,12 +1131,17 @@ exchange.
       // Hash of the contract.
       h_contract: HashCode;
 
+      // Hash of the wire details of the reserve.
+      h_wire: HashCode;
+
       // Signature created with the reserve's private key.
-      // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE.
+      // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` over
+      // a `TALER_AccountMergeSignaturePS`.
       reserve_sig: EddsaSignature;
 
       // Signature created with the purse's private key.
-      // Must be of purpose TALER_SIGNATURE_PURSE_MERGE.
+      // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``
+      // over a `TALER_PurseMergeSignaturePS`.
       purse_sig: EddsaSignature;
 
       // Deposit fees that were charged to the purse.
@@ -1151,8 +1162,9 @@ exchange.
       // Hash of the blinded coin to be signed.
       h_coin_envelope: HashCode;
 
-      // Signature of ``TALER_WithdrawRequestPS`` created with the reserve's
-      // private key.
+      // Signature over a `TALER_WithdrawRequestPS`
+      // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW``
+      // created with the reserve's private key.
       reserve_sig: EddsaSignature;
 
       // Fee that is charged for withdraw.
@@ -1198,11 +1210,11 @@ exchange.
       receiver_account_details: string;
 
       // This is a signature over a
-      // struct ``TALER_ReserveCloseConfirmationPS`` with purpose
+      // struct `TALER_ReserveCloseConfirmationPS` with purpose
       // ``TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED``.
       exchange_sig: EddsaSignature;
 
-      // Public key used to create ``exchange_sig``.
+      // Public key used to create 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
       // Time when the reserve was closed.
@@ -1219,11 +1231,11 @@ exchange.
       amount: Amount;
 
       // This is a signature over
-      // a struct ``TALER_PaybackConfirmationPS`` with purpose
-      // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK``.
+      // a struct `TALER_RecoupConfirmationPS` with purpose
+      // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``.
       exchange_sig: EddsaSignature;
 
-      // Public key used to create ``exchange_sig``.
+      // Public key used to create 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
       // Time when the funds were paid back into the reserve.
@@ -1262,7 +1274,8 @@ exchange.
 
     interface ReserveHistoryRequest {
       // Signature of type
-      // TALER_SIGNATURE_RESERVE_HISTORY_REQUEST
+      // ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST``
+      // over a `TALER_ReserveHistoryRequestSignaturePS`.
       reserve_sig: EddsaSignature;
 
       // Time when the client made the request.
@@ -1332,7 +1345,8 @@ exchange.
       coin_ev: CoinEnvelope;
 
       // Signature of `TALER_WithdrawRequestPS` created with
-      // the `reserves's private key <reserve-priv>`.
+      // the `reserves's private key <reserve-priv>`
+      // using purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW``.
       reserve_sig: EddsaSignature;
 
     }
@@ -1340,7 +1354,7 @@ exchange.
   .. 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;
 
@@ -1363,6 +1377,8 @@ exchange.
       history: TransactionHistoryItem[]
     }
 
+.. _delete-reserve:
+
 .. http:DELETE:: /reserves/$RESERVE_PUB
 
   Forcefully closes a reserve.
@@ -1432,7 +1448,6 @@ credited an amount specified in the deposit permission, possibly a fraction of
 the total coin's value, minus the deposit fee as specified by the coin's
 denomination.
 
-
 .. _deposit:
 
 .. http:POST:: /coins/$COIN_PUB/deposit
@@ -1445,10 +1460,9 @@ denomination.
   exchange. The exchange MUST return a 307 or 308 redirection to the correct
   base URL if this is the case.
 
-  The request should contain a JSON object with the
-  following fields:
+  **Request:**
 
-  **Request:** The request body must be a `DepositRequest` object.
+  The request body must be a `DepositRequest` object.
 
   **Response:**
 
@@ -1516,7 +1530,7 @@ denomination.
       // exchange, possibly zero if refunds are not allowed.
       refund_deadline: Timestamp;
 
-      // Signature of `TALER_DepositRequestPS`, made by the customer with the
+      // Signature over `TALER_DepositRequestPS`, made by the customer with the
       // `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
     }
@@ -1604,14 +1618,16 @@ denomination.
       // exchange, possibly zero if refunds are not allowed.
       refund_deadline: Timestamp;
 
-      // Signature by the coin.
+      // Signature over `TALER_DepositRequestPS`, made by the customer with the
+      // `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
 
       // Hash of the bank account from where we received the funds.
       h_wire: HashCode;
 
       // Hash of the public denomination key used to sign the coin.
-      // FIXME: why do we care to have this?
+      // Needed because 'coin_sig' signs over this, and
+      // that is important to fix the coin's denomination.
       h_denom_pub: HashCode;
 
       // Hash over the proposal data of the contract that
@@ -1631,7 +1647,9 @@ denomination.
       // subtracting the amounts.
       amount: Amount;
 
-      // Signature by the coin.
+      // Signature by the coin over a
+      // `TALER_RefreshMeltCoinAffirmationPS` of
+      // purpose ``TALER_SIGNATURE_WALLET_COIN_MELT``.
       coin_sig: EddsaSignature;
 
       // Melt fee.
@@ -1641,7 +1659,8 @@ denomination.
       rc: TALER_RefreshCommitmentP;
 
       // Hash of the public denomination key used to sign the coin.
-      // FIXME: why do we care to have this?
+      // Needed because 'coin_sig' signs over this, and
+      // that is important to fix the coin's denomination.
       h_denom_pub: HashCode;
 
     }
@@ -1658,7 +1677,7 @@ denomination.
       // adding the amounts to the coin's denomination value.
       amount: Amount;
 
-      // Refund fee in case of type "REFUND".
+      // Refund fee.
       refund_fee: Amount;
 
       // Hash over the proposal data of the contract that
@@ -1668,7 +1687,9 @@ denomination.
       // Refund transaction ID.
       rtransaction_id: Integer;
 
-      // `EdDSA Signature <eddsa-sig>` authorizing the REFUND. Made with
+      // `EdDSA Signature <eddsa-sig>` authorizing the REFUND over a
+      // `TALER_MerchantRefundConfirmationPS` with
+      // purpose ``TALER_SIGNATURE_MERCHANT_REFUND_OK``. Made with
       // the `public key of the merchant <merchant-pub>`.
       merchant_sig: EddsaSignature;
 
@@ -1689,11 +1710,14 @@ denomination.
       // Date when the operation was made.
       timestamp: Timestamp;
 
-      // Signature by the coin.
+      // Signature by the coin over a
+      // `TALER_RecoupRequestPS` with purpose
+      // ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
       coin_sig: EddsaSignature;
 
       // Hash of the public denomination key used to sign the coin.
-      // FIXME: why do we care to have this?
+      // Needed because 'coin_sig' signs over this, and
+      // that is important to fix the coin's denomination.
       h_denom_pub: HashCode;
 
       // Coin blinding key.
@@ -1702,11 +1726,12 @@ denomination.
       // Reserve receiving the recoup.
       reserve_pub: EddsaPublicKey;
 
-      // Signature by the exchange, must be
-      // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP.
+      // Signature by the exchange over a
+      // `TALER_RecoupConfirmationPS`, must be
+      // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``.
       exchange_sig: EddsaSignature;
 
-      // Public key used to sign ``exchange_sig``
+      // Public key of the private key used to create 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
     }
@@ -1725,11 +1750,12 @@ denomination.
       // Date when the operation was made.
       timestamp: Timestamp;
 
-      // Signature by the exchange
-      // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH.
+      // Signature by the exchange over a
+      // `TALER_RecoupRefreshConfirmationPS`
+      // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
       exchange_sig: EddsaSignature;
 
-      // Public key used to sign ``exchange_sig``,
+      // Public key of the private key used to create 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
     }
@@ -1749,21 +1775,24 @@ denomination.
       // Date when the operation was made.
       timestamp: Timestamp;
 
-      // Signature by the coin.
+      // Signature by the coin over a `TALER_RecoupRequestPS`
+      // with purpose ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
       coin_sig: EddsaSignature;
 
       // Hash of the public denomination key used to sign the coin.
-      // FIXME: why do we care to have this?
+      // Needed because 'coin_sig' signs over this, and
+      // that is important to fix the coin's denomination.
       h_denom_pub: HashCode;
 
       // Coin blinding key.
       coin_blind: DenominationBlindingKeyP;
 
-      // Signature by the exchange
-      // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH.
+      // Signature by the exchange over a
+      // `TALER_RecoupRefreshConfirmationPS`
+      // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
       exchange_sig: EddsaSignature;
 
-      // Public key used to sign ``exchange_sig``,
+      // Public key used to sign 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
       // Blinding factor of the revoked new coin.
@@ -1795,11 +1824,14 @@ denomination.
       // Date when the purse was set to expire.
       purse_expiration: Timestamp;
 
-      // Signature by the coin.
+      // Signature by the coin over a
+      // `TALER_PurseDepositSignaturePS` of
+      // purpose ``TALER_SIGNATURE_PURSE_DEPOSIT``.
       coin_sig: EddsaSignature;
 
       // Hash of the public denomination key used to sign the coin.
-      // FIXME: why do we care to have this?
+      // Needed because 'coin_sig' signs over this, and
+      // that is important to fix the coin's denomination.
       h_denom_pub: HashCode;
 
     }
@@ -2167,6 +2199,7 @@ in using this API.
     interface RecoupWithdrawalConfirmation {
       // Tag to distinguish the `RecoupConfirmation` response type.
       refreshed: false;
+
       // Public key of the reserve that will receive the recoup.
       reserve_pub: EddsaPublicKey;
     }
@@ -2176,6 +2209,7 @@ in using this API.
     interface RecoupRefreshConfirmation {
       // Tag to distinguish the `RecoupConfirmation` response type.
       refreshed: true;
+
       // Public key of the old coin that will receive the recoup.
       old_coin_pub: EddsaPublicKey;
     }
@@ -2250,7 +2284,8 @@ typically also view the balance.)
       deposits: TrackTransferDetail[];
 
       // Signature from the exchange made with purpose
-      // `TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT`.
+      // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT``
+      // over a `TALER_WireDepositDataPS`.
       exchange_sig: EddsaSignature;
 
       // Public EdDSA key of the exchange that was used to generate the signature.
@@ -2286,7 +2321,7 @@ typically also view the balance.)
 
   **Request:**
 
-  :query merchant_sig: EdDSA signature of the merchant made with purpose ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION``, affirming that it is really the merchant who requires obtaining the wire transfer identifier.
+  :query merchant_sig: EdDSA signature of the merchant made with purpose ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION`` over a `TALER_DepositTrackPS`, affirming that it is really the merchant who requires obtaining the wire transfer identifier.
 
   **Response:**
 
@@ -2320,7 +2355,8 @@ typically also view the balance.)
       // Total amount transferred.
       total_amount: Amount;
 
-      // Binary-only Signature_ for purpose `TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE`
+      // Binary-only Signature_ with purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE``
+      // over a `TALER_ConfirmWirePS`
       // whereby the exchange affirms the successful wire transfer.
       exchange_sig: EddsaSignature;
 
@@ -2392,7 +2428,10 @@ Refunds
       // EdDSA public key of the merchant.
       merchant_pub: EddsaPublicKey;
 
-      // EdDSA signature of the merchant affirming the refund.
+      // EdDSA signature of the merchant over a
+      // `TALER_RefundRequestPS` with purpose
+      // ``TALER_SIGNATURE_MERCHANT_REFUND``
+      // affirming the refund.
       merchant_sig: EddsaPublicKey;
 
     }
@@ -2402,7 +2441,9 @@ Refunds
     interface RefundSuccess {
 
       // The EdDSA :ref:`signature` (binary-only) with purpose
-      // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the
+      // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND`` over
+      // a `TALER_RecoupRefreshConfirmationPS`
+      // using a current signing key of the
       // exchange affirming the successful refund.
       exchange_sig: EddsaSignature;
 
@@ -2500,7 +2541,10 @@ Wallet-to-wallet transfers
       // SHA-512 hash of the contact of the purse.
       h_contract_terms: HashCode;
 
-      // EdDSA signature of the exchange affirming the purse status.
+      // EdDSA signature of the exchange over a
+      // `TALER_PurseStatusResponseSignaturePS`
+      // with purpose ``TALER_SIGNATURE_PURSE_STATUS_RESPONSE``
+      // affirming the purse status.
       exchange_sig: EddsaSignature;
 
       // EdDSA public key exchange used for 'exchange_sig'.
@@ -2523,7 +2567,9 @@ Wallet-to-wallet transfers
 
   Deposit money into a purse. Endpoint used by the buyer.
 
-  **Request:** The request body must be a `PurseRequest` object.
+  **Request:**
+
+  The request body must be a `PurseRequest` object.
 
   **Response:**
 
@@ -2557,6 +2603,11 @@ Wallet-to-wallet transfers
     In this case, the response is a `PurseDepositDoubleSpendError`.
     If the value of all successful coins is below the purse fee,
     the exchange may not setup the purse at all.
+  :http:statuscode:`425 Too Early`:
+    This response type is used if the given purse expiration time
+    is too far in the future (at least from the perspective
+    of the exchange). Thus, retrying at a later time may
+    succeed. The client should look at the ``Date:`` header of the response to see if a minor time difference is to blame and possibly adjust the request accordingly.
 
 
   **Details:**
@@ -2565,7 +2616,10 @@ Wallet-to-wallet transfers
 
     interface PurseRequest {
 
-      // EdDSA signature of the purse confirming the key
+      // EdDSA signature of the purse over a
+      // `TALER_PurseRequestSignaturePS`
+      // of purpose ``TALER_SIGNATURE_PURSE_REQUEST``
+      // confirming the key
       // invariants associated with the purse.
       // (amount, h_contract_terms, expiration).
       purse_sig: EddsaSignature;
@@ -2651,7 +2705,8 @@ Wallet-to-wallet transfers
       total_deposit_fees: Amount;
 
       // EdDSA signature of the exchange affirming the payment,
-      // of purpose TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED
+      // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED``
+      // over a `TALER_PurseDepositConfirmedSignaturePS`.
       // Signs over the above and the purse public key and
       // the hash of the contract terms.
       exchange_sig: EddsaSignature;
@@ -2676,22 +2731,68 @@ Wallet-to-wallet transfers
 
   .. ts:def:: PurseConflict
 
-    interface PurseConflict {
+    // Union discriminated by the "type" field.
+    type PurseConflict =
+    | PurseMergeConflict
+    | PurseRequestConflict;
 
-      // Total amount to be paid into the purse as per
-      // the previous request.
-      total_purse_amount: Amount;
+  .. ts:def:: PurseMergeConflict
+
+    interface PurseMergeConflict {
+      type: "MERGE";
 
       // SHA-512 hash of the contact of the purse.
       h_contract_terms: HashCode;
 
+      // Hash of the wire details of the reserve.
+      h_wire: HashCode;
+
+      // Reserve merging the purse.
+      reserve_pub: EddsaPublicKey;
+
       // Indicative time by which the purse should expire
       // if it has not been merged into an account. At this
       // point, all of the deposits made should be
       // auto-refunded.
       purse_expiration: Timestamp;
 
-      // EdDSA signature of the purse confirming that the
+      // When was the merge request generated.
+      merge_timestamp: Timestamp;
+
+      // Total amount to be merged into the reserve.
+      // (excludes fees).
+      purse_value_after_fees: Amount;
+
+      // EdDSA signature of the purse over
+      // `TALER_PurseMergeSignaturePS` of
+      // purpose ``TALER_SIGNATURE_PURSE_MERGE``
+      // confirming that the
+      // above details hold for this purse.
+      purse_sig: EddsaSignature;
+    }
+
+  .. ts:def:: PurseRequestConflict
+
+    interface PurseRequestConflict {
+      type: "REQUEST";
+
+      // SHA-512 hash of the contact of the purse.
+      h_contract_terms: HashCode;
+
+      // Indicative time by which the purse should expire
+      // if it has not been merged into an account. At this
+      // point, all of the deposits made should be
+      // auto-refunded.
+      purse_expiration: Timestamp;
+
+       // Total amount to be paid into the purse as per
+      // the previous request.
+      total_purse_amount: Amount;
+
+      // EdDSA signature of the purse over
+      // `TALER_PurseRequestSignaturePS` of
+      // purpose ``TALER_SIGNATURE_PURSE_REQUEST``
+      // confirming that the
       // above details hold for this purse.
       purse_sig: EddsaSignature;
 
@@ -2723,7 +2824,9 @@ Wallet-to-wallet transfers
   Merge purse with account, adding the value of the purse into
   the account.  Endpoint to be used by the seller.
 
-  **Request:** The request body must be a `MergeRequest` object.
+  **Request:**
+
+  The request body must be a `MergeRequest` object.
 
   :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
     wait up to ``timeout_ms`` milliseconds to receive payment before
@@ -2764,15 +2867,17 @@ Wallet-to-wallet transfers
     interface MergeRequest {
 
       // payto://-URI of the account the purse is to be merged into.
-      // Must be of the form: "payto://taler/EXCHANGE_URL/RESERVE_PUB".
+      // Must be of the form: 'payto://taler/$EXCHANGE_URL/$RESERVE_PUB'.
       payto_uri: string;
 
-      // EdDSA signature of the account/reserve affirming the merge.
-      // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE
+      // EdDSA signature of the account/reserve affirming the merge
+      // over a `TALER_AccountMergeSignaturePS`.
+      // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE``
       reserve_sig: EddsaSignature;
 
-      // EdDSA signature of the purse private key affirming the merge.
-      // Must be of purpose TALER_SIGNATURE_PURSE_MERGE.
+      // EdDSA signature of the purse private key affirming the merge
+      // over a `TALER_PurseMergeSignaturePS`.
+      // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``.
       purse_sig: EddsaSignature;
 
       // Minimum amount that must be credited to the reserve, that is
@@ -2814,7 +2919,8 @@ Wallet-to-wallet transfers
       contract_time: Timestamp;
 
       // EdDSA signature of the exchange affirming the merge of
-      // purpose TALER_SIGNATURE_PURSE_MERGE_SUCCESS.
+      // purpose ``TALER_SIGNATURE_PURSE_MERGE_SUCCESS``
+      // over `TALER_PurseMergeSuccessSignaturePS`.
       // Signs over the above and the account public key.
       exchange_sig: EddsaSignature;
 
@@ -2877,17 +2983,18 @@ Wallet-to-wallet transfers
       kyc_timestamp: Timestamp;
 
       // Bank account to be associated with the account.
-      // Can be ``payto://void/`` to not associate the
+      // Can be 'payto://void/' to not associate the
       // account with any bank account. In this case,
       // closing the account will result in the balance
       // being forfeit.  If the provided wire method is
-      // not supported by the exchange *and* not ``void``,
+      // not supported by the exchange *and* not 'void',
       // this is a ``Bad Request`` (HTTP status 400).
       payto_uri: string;
 
       // EdDSA signature of the reserve affirming the request
       // to create the account, must be of purpose
-      // TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST
+      // ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST``
+      // and over `TALER_AccountSetupRequestSignaturePS`.
       reserve_sig: EddsaPublicKey;
 
     }
@@ -2902,7 +3009,8 @@ Wallet-to-wallet transfers
 
       // EdDSA signature of the exchange affirming the account
       // is KYC'ed, must be of purpose
-      // TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS.
+      // ``TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS``
+      // and over `TALER_AccountSetupRequestSignaturePS`.
       exchange_sig: EddsaSignature;
 
       // public key used to create the signature.
@@ -2983,7 +3091,7 @@ wallet-to-wallet payments.  Only another exchange should access this endpoint.
       amount: Amount;
 
       // payto://-URI of the account the purse is to be merged into.
-      // Must be of the form: "payto://taler/EXCHANGE_URL/RESERVE_PUB".
+      // Must be of the form: 'payto://taler/EXCHANGE_URL/RESERVE_PUB'.
       payto_uri: string;
 
       // Purse public key.
@@ -3000,11 +3108,13 @@ wallet-to-wallet payments.  Only another exchange should access this endpoint.
       merge_timestamp: Timestamp;
 
       // Signature created with the reserve's private key.
-      // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE
+      // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE``
+      // and over `TALER_AccountMergeSignaturePS`.
       reserve_sig: EddsaSignature;
 
       // Signature created with the purse's private key.
-      // Must be of purpose TALER_SIGNATURE_PURSE_MERGE
+      // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``
+      // and over `TALER_PurseMergeSignaturePS`.
       purse_sig: EddsaSignature;
 
       // Deposit fees that were charged to the purse.