From f0cb91b02388972129fa701bb73624f213aa3589 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Thu, 13 Oct 2016 22:29:03 +0200 Subject: Integer->number --- api-exchange.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-exchange.rst b/api-exchange.rst index e1439936..9a8eb5ff 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -823,7 +823,7 @@ the API during normal operation. gamma_tp: EddsaPublicKey; // Specific `gamma` value chosen by the exchange. - gamma: Integer; + gamma: number; } -- cgit v1.2.3 From dd8eb50491d0fe1c5de88fa32975619f45b9938e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 15 Oct 2016 03:21:22 +0200 Subject: updating API documentation for error responses in transaction tracking --- api-merchant.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/api-merchant.rst b/api-merchant.rst index 749681d3..f5a83985 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -229,7 +229,33 @@ The following API are made available by the merchant's `backend` to the merchant is completely intended. :status 404 Not Found: - The wire transfer identifier is unknown to the exchange. + The wire transfer identifier is unknown to the exchange. + + :status 409 Conflict: + 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`_. + + **Details:** + .. _tsref-type-TransactionConflictProof: + .. _TransactionConflictProof: + .. code-block:: tsref + + interface TransactionConflictProof { + // A claim by the exchange about the transfers associated + // with a given wire transfer; it does not list the + // transaction that `transaction_tracking_claim` says is part + // of the aggregate. This is + // 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/transaction`). + transaction_tracking_claim: TrackTransactionResponse; + + // Public key of the coin for which we got conflicting information. + coin_pub: CoinPublicKey; + + } .. http:get:: /track/transaction @@ -257,6 +283,9 @@ The following API are made available by the merchant's `backend` to the merchant :status 404 Not Found: The transaction is unknown to the backend. + :status 409 Conflict: The exchange provided conflicting information about the transfer. + The response body contains the :ref:`TrackTransferConflictDetails`. + **Details:** @@ -290,6 +319,42 @@ The following API are made available by the merchant's `backend` to the merchant deposit_fee: Amount; } + .. _tsref-type-TrackTransferConflictDetails: + .. _TrackTransferConflictDetails: + .. code-block:: tsref + + interface TrackTransferConflictDetails { + // Text describing the issue for humans. + hint: String; + + // 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`. + conflict_offset: number; + + // The response from the exchange which tells us when the + // coin was returned to us, except that it does not match + // the expected value of the coin. + exchange_transfer_proof: TrackTransferResponse; + + // Public key of the coin for which we have conflicting information. + coin_pub: EddsaPublicKey; + + // Merchant transaction in which `coin_pub` was involved for which + // we have conflicting information. + transaction_id: number; + + // Expected value of the coin. + amount_with_fee: Amount; + + // Expected deposit fee of the coin. + deposit_fee: Amount; + + } + .. http:get:: /history Returns transactions up to some point in the past @@ -311,7 +376,7 @@ The following API are made available by the merchant's `backend` to the merchant // Hashcode of the relevant contract h_contract: HashCode; - + // Exchange's base URL exchange: string; -- cgit v1.2.3 From a43b8e5f56b3f2cfa614265f26f4d345ffc087d8 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Sat, 15 Oct 2016 04:40:10 +0200 Subject: receiver token in /track/transfer --- api-merchant.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/api-merchant.rst b/api-merchant.rst index 8705069d..42fb830e 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -222,6 +222,7 @@ The following API are made available by the merchant's `backend` to the merchant :query wtid: raw wire transfer identifier identifying the wire transfer (a base32-encoded value) :query exchange: base URI of the exchange that made the wire transfer + :query receiver: identificative token of the merchant :ref:`instance ` which is being tracked. **Response:** -- cgit v1.2.3 From f761f3632785807fb6154e94dd6c5dee47b6a6a3 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Sat, 15 Oct 2016 22:00:36 +0200 Subject: fix link --- api-merchant.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-merchant.rst b/api-merchant.rst index 42fb830e..dea931e4 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -239,8 +239,8 @@ The following API are made available by the merchant's `backend` to the merchant 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`_. **Details:** - .. _tsref-type-TransactionConflictProof: .. _TransactionConflictProof: + .. _tsref-type-TransactionConflictProof: .. code-block:: tsref interface TransactionConflictProof { @@ -288,7 +288,7 @@ The following API are made available by the merchant's `backend` to the merchant :status 404 Not Found: The transaction is unknown to the backend. :status 409 Conflict: The exchange provided conflicting information about the transfer. - The response body contains the :ref:`TrackTransferConflictDetails`. + The response body contains the `TrackTransferConflictDetails`_. **Details:** -- cgit v1.2.3 From f0f8e4b873acf06cd7ac3dc5ef221bb3ab361fa1 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Tue, 18 Oct 2016 11:44:15 +0200 Subject: FIXME --- api-exchange.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-exchange.rst b/api-exchange.rst index 9a8eb5ff..15acf5ed 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -360,7 +360,7 @@ exchange. // `base32`_ encoding of `TALER_WithdrawRequestPS`_ with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW. This field appears only if `type` is "WITHDRAW". details?: string; - // Signature over the transaction `details`. + // Signature over the transaction `details` (FIXME: Which transaction, which details?). signature?: EddsaSignature; } -- cgit v1.2.3 From 5315da03acdef93934533497d781b47cc17134d9 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 18 Oct 2016 23:04:43 +0200 Subject: update specification to match current implementation --- api-common.rst | 4 ++-- api-exchange.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api-common.rst b/api-common.rst index 3bbc8722..d44e55ec 100644 --- a/api-common.rst +++ b/api-common.rst @@ -70,8 +70,8 @@ handle the error as if an internal error (500) had been returned. interface ErrorDetail { - // Numeric error code. See "taler_error_codes.h". - error_code: number; + // Numeric error code unique to the condition. See "taler_error_codes.h". + code: number; // Human-readable description of the error, i.e. "missing parameter", "commitment violation", ... // The other arguments are specific to the error value reported here. diff --git a/api-exchange.rst b/api-exchange.rst index 15acf5ed..d53056fb 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -392,7 +392,7 @@ exchange. not yet have completed and might be known to the exchange in the near future. In this case, the wallet should repeat the exact same request later again using exactly the same blinded coin. - :status 402 Payment Required: + :status 403 Forbidden: The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination. The response is `WithdrawError`_ object. @@ -475,7 +475,7 @@ denomination. 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: + :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`_. -- cgit v1.2.3 From 9cc3e04399ca7f223a61ebd515f4d8104be886e8 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 19 Oct 2016 12:37:22 +0200 Subject: still on #4251 --- api-merchant.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/api-merchant.rst b/api-merchant.rst index dea931e4..d89e0485 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -85,9 +85,14 @@ The Frontent HTTP API // a timestamp of this deposit permission. It equals just the contract's timestamp timestamp: Timestamp; - // same value held in the contract's `refund` field + // Deadline for the customer to be refunded for this purchase refund_deadline: Timestamp; + // Deadline for the customer to pay for this purchase. Note that is up to the frontend + // to make sure that this value matches the one the backend signed over when the contract + // was generated. + pay_deadline: Timestamp; + // the chosen exchange's base URL exchange: string; @@ -176,10 +181,10 @@ The following API are made available by the merchant's `backend` to the merchant **Request:** The `frontend` passes the :ref:`deposit permission ` - received from the wallet, and optionally adding a field named `pay_deadline`, + received from the wallet, and optionally adding a field named `wire_transfer_deadline`, indicating a deadline by which he would expect to receive the bank transfer - for this deal. Note that the `pay_deadline` must be after the `refund_deadline`. - The backend calculates the `pay_deadline` by adding the `wire_transfer_delay` + for this deal. Note that the `wire_transfer_deadline` must be after the `refund_deadline`. + The backend calculates the `wire_transfer_deadline` by adding the `wire_transfer_delay` value found in the configuration to the current time. **Response:** @@ -233,12 +238,13 @@ The following API are made available by the merchant's `backend` to the merchant is completely intended. :status 404 Not Found: - The wire transfer identifier is unknown to the exchange. + The wire transfer identifier is unknown to the exchange. :status 409 Conflict: - 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`_. + 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`_. + + **Details:** - **Details:** .. _TransactionConflictProof: .. _tsref-type-TransactionConflictProof: .. code-block:: tsref -- cgit v1.2.3 From 835509f59bd11234b0181693396ad40b5ff8e5fc Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 19 Oct 2016 12:49:21 +0200 Subject: still on #4251 --- api-merchant.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api-merchant.rst b/api-merchant.rst index d89e0485..49d2d74a 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -90,7 +90,9 @@ The Frontent HTTP API // Deadline for the customer to pay for this purchase. Note that is up to the frontend // to make sure that this value matches the one the backend signed over when the contract - // was generated. + // was generated. The frontend should never verify if the payment is still on time, + // because when payments are replayed it is expxectable that this deadline is expired, + // and only the backend can detect if a payment is a reply or not. pay_deadline: Timestamp; // the chosen exchange's base URL -- cgit v1.2.3