[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] 12/36: more work on DD13 spec
|
From: |
gnunet |
|
Subject: |
[taler-docs] 12/36: more work on DD13 spec |
|
Date: |
Tue, 22 Jun 2021 19:35:08 +0200 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository docs.
commit d267f23fc695a99d95cbcffc4d35602ccef5c563
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat May 15 16:05:52 2021 +0200
more work on DD13 spec
---
core/api-common.rst | 64 +++++++++----
core/api-exchange.rst | 256 ++++++++++++++++++++++++++++++++++++--------------
core/api-merchant.rst | 4 +-
3 files changed, 234 insertions(+), 90 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
index 81b85ab..cc69870 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -64,6 +64,8 @@ handle the error as if an internal error (500) had been
returned.
changed, the client MUST follow the link to the new location. If possible,
the client SHOULD remember the new URL for the reserve for future
requests.
+ :http:statuscode:`400 Bad request`:
+ One of the arguments to the request is missing or malformed.
:http:statuscode:`500 Internal server error`:
This always indicates some serious internal operational error of the
exchange,
such as a program bug, database problems, etc., and must not be used for
@@ -75,10 +77,7 @@ handle the error as if an internal error (500) had been
returned.
although the auditor API for this is not yet specified. However, as
internal
server errors are always reported to the exchange operator, a good operator
should naturally be able to address them in a timely fashion, especially
- within 24h. When generating an internal server error, the exchange
responds with
- a JSON object containing the following fields: FIXME: What are the fields?
- :http:statuscode:`400 Bad request`:
- One of the arguments to the request is missing or malformed.
+ within 24h.
Unless specified otherwise, all error status codes (4xx and 5xx) have a
message
body with an `ErrorDetail` JSON object.
@@ -720,11 +719,6 @@ within the
struct TALER_MerchantPublicKeyP merchant;
};
-.. _TALER_RefreshCommitmentP:
-.. sourcecode:: c
-
- // FIXME: put definition here
-
.. _TALER_RefreshMeltCoinAffirmationPS:
.. sourcecode:: c
@@ -810,7 +804,6 @@ within the
struct GNUNET_HashCode h_wire_details;
};
-
.. _TALER_MasterWireFeePS:
.. sourcecode:: c
@@ -831,7 +824,7 @@ within the
struct TALER_DepositTrackPS {
/**
- * purpose.purpose = TALER_SIGNATURE_MASTER_SEPA_DETAILS ||
TALER_SIGNATURE_MASTER_TEST_DETAILS
+ * purpose.purpose = TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
struct GNUNET_HashCode h_contract_terms;
@@ -851,7 +844,6 @@ within the
struct TALER_AmountNBO deposit_fee;
};
-
.. _TALER_WireDepositDataPS:
.. _TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT:
.. sourcecode:: c
@@ -934,12 +926,31 @@ within the
.. _TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND:
.. sourcecode:: c
- // FIXME: put definition here
+ struct TALER_RefundConfirmationPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND.
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_HashCode h_contract_terms;
+ struct TALER_CoinSpendPublicKeyP coin_pub;
+ struct TALER_MerchantPublicKeyP merchant;
+ uint64_t rtransaction_id;
+ struct TALER_AmountNBO refund_amount;
+ };
.. _TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION:
.. sourcecode:: c
- // FIXME: put definition here
+ struct TALER_DepositTrackPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION.
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_HashCode h_contract_terms;
+ struct GNUNET_HashCode h_wire;
+ struct TALER_MerchantPublicKeyP merchant;
+ struct TALER_CoinSpendPublicKeyP coin_pub;
+ };
.. _TALER_RefundRequestPS:
.. sourcecode:: c
@@ -957,6 +968,9 @@ within the
struct TALER_AmountNBO refund_fee;
};
+.. _TALER_MerchantRefundConfirmationPS:
+.. sourcecode:: c
+
struct TALER_MerchantRefundConfirmationPS {
/**
* purpose.purpose = TALER_SIGNATURE_MERCHANT_REFUND_OK
@@ -986,7 +1000,6 @@ within the
.. sourcecode:: c
struct TALER_RecoupRefreshConfirmationPS {
-
/**
* purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH
*/
@@ -1105,6 +1118,26 @@ within the
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
};
+.. _TALER_RefreshCommitmentP:
+.. sourcecode:: c
+
+ struct TALER_RefreshCommitmentP {
+ struct GNUNET_HashCode session_hash;
+ };
+
+
+.. _TALER_PurseRequestSignaturePS:
+.. sourcecode:: c
+
+ struct TALER_PurseRequestSignaturePS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_PURSE_REQUEST
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_TIME_AbsoluteNBO purse_expiration;
+ struct TALER_AmountNBO total_purse_amount;
+ struct GNUNET_HashCode h_contract_terms;
+ };
.. _TALER_PurseDepositSignaturePS:
@@ -1137,7 +1170,6 @@ within the
struct GNUNET_HashCode h_contract_terms;
};
-
.. _TALER_PurseMergeSignaturePS:
.. sourcecode:: c
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 44dfd2a..089890a 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.
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 21956e5..c9d9ca5 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1542,11 +1542,13 @@ Creating orders
:ts:type:`PostOrderResponse`.
:http:statuscode:`404 Not found`:
Possible reasons are:
+
(1) The order given used products from the inventory, but those were
not found in the inventory.
(2) The merchant instance is unknown (including possibly the instance
being not configured for new orders).
(3) The wire method specified is not supported by the backend.
+
Details in the error code.
NOTE: currently the client has no good way to find out which product
is not in the inventory, we MAY want to specify that in the reply.
@@ -1624,7 +1626,7 @@ Creating orders
fulfillment_url?: string;
}
- The following `ProductSpecification` can be provided if the parts of the
+ The following `MinimalInventoryProduct` can be provided if the parts of the
order are inventory-based, that is if the `PostOrderRequest` uses
``inventory_products``. For such products, which must be in the backend's
inventory,
the backend can automatically fill in the amount and other details about
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] 17/36: add table to cache /wire reply from partner exchange, (continued)
- [taler-docs] 17/36: add table to cache /wire reply from partner exchange, gnunet, 2021/06/22
- [taler-docs] 26/36: document 409 case, see #6863, gnunet, 2021/06/22
- [taler-docs] 32/36: fix docs, gnunet, 2021/06/22
- [taler-docs] 31/36: add man page for fakebank, gnunet, 2021/06/22
- [taler-docs] 29/36: spec message for denomination expired/revoked/too-early signature (#6889), gnunet, 2021/06/22
- [taler-docs] 34/36: simplify/cleaner docs, gnunet, 2021/06/22
- [taler-docs] 25/36: document new auth policy, gnunet, 2021/06/22
- [taler-docs] 36/36: Merge branch 'dd13', gnunet, 2021/06/22
- [taler-docs] 14/36: finish DD13, gnunet, 2021/06/22
- [taler-docs] 13/36: work on SQL comments, gnunet, 2021/06/22
- [taler-docs] 12/36: more work on DD13 spec,
gnunet <=
- [taler-docs] 08/36: extend wire gateway spec for wads, gnunet, 2021/06/22
- [taler-docs] 23/36: hw, gnunet, 2021/06/22
- [taler-docs] 20/36: deal with purse auto-refund on expiration, ensure exchange has max_deposit_fees always, gnunet, 2021/06/22
- [taler-docs] 21/36: more amounts needed, gnunet, 2021/06/22