diff options
Diffstat (limited to 'core/api-exchange.rst')
| -rw-r--r-- | core/api-exchange.rst | 222 |
1 files changed, 149 insertions, 73 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 0b039d38..cba9a6d3 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -76,6 +76,15 @@ possibly by using HTTPS. If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the privacy policy was not configured correctly. +.. http:get:: /seed + + Return an entropy seed. The exchange will return a high-entropy + value that will differ for every call. The response is NOT in + JSON, but simply high-entropy binary data in the HTTP body. + This API can be used by wallets to guard themselves against + running on low-entropy (bad PRNG) hardware. Naturally, the entropy + returned MUST be mixed with locally generated entropy. + .. http:get:: /keys Get a list of all denomination keys offered by the bank, @@ -96,7 +105,7 @@ possibly by using HTTPS. .. ts:def:: ExchangeKeysResponse interface ExchangeKeysResponse { - // libtool-style representation of the Taler protocol version, see + // libtool-style representation of the Exchange protocol version, see // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning // The format is "current:revision:age". version: string; @@ -399,70 +408,108 @@ exchange. .. ts:def:: TransactionHistoryItem - interface TransactionHistoryItem { - // Either "WITHDRAW", "DEPOSIT", "RECOUP", or "CLOSING" - type: string; + // Union discriminated by the "type" field. + type ReserveTransaction = + | ReserveWithdrawTransaction + | ReserveCreditTransaction + | ReserveClosingTransaction + | ReserveRecoupTransaction; + + .. ts:def:: ReserveWithdrawTransaction + + interface ReserveWithdrawTransaction { + type: "WITHDRAW"; + + // Amount withdrawn. + amount: Amount; + + // Hash of the denomination public key of the coin. + h_denom_pub: HashCode; + + // Hash of the blinded coin to be signed + h_coin_envelope: HashCode; + + // Signature of 'TALER_WithdrawRequestPS' created with the reserves's + // private key. + reserve_sig: EddsaSignature; + + // Fee that is charged for withdraw. + withdraw_fee: Amount; + } + + + .. ts:def:: ReserveCreditTransaction + + interface ReserveCreditTransaction { + type: "CREDIT"; - // The amount that was withdrawn or deposited (incl. fee) - // or paid back, or the closing amount. + // Amount deposited. amount: Amount; - // Hash of the denomination public key of the coin, if - // type is "WITHDRAW". - h_denom_pub?: Base32; + // Sender account payto://-URL + sender_account_url: string; - // Hash of the blinded coin to be signed, if - // type is "WITHDRAW". - h_coin_envelope?: Base32; + // Opaque identifier internal to the exchange that + // uniquely identifies the wire transfer that credited the reserve. + wire_reference: Base32; - // Signature of 'TALER_WithdrawRequestPS' created with the `reserves's - // private key <reserve-priv>`. Only present if type is "WITHDRAW". - reserve_sig?: EddsaSignature; + // Timestamp of the incoming wire transfer. + timestamp: Timestamp; + } - // The fee that was charged for "WITHDRAW". - withdraw_fee?: Amount; - // The fee that was charged for "CLOSING". - closing_fee?: Amount; + .. ts:def:: ReserveClosingTransaction - // Sender account payto://-URL, only present if type is "DEPOSIT". - sender_account_url?: string; + interface ReserveClosingTransaction { + type: "CLOSING"; - // Receiver account details, only present if type is "CLOSING". - receiver_account_details?: any; + // Closing balance. + amount: Amount; - // Transfer details uniquely identifying the transfer, only present if type is "DEPOSIT". - wire_reference?: any; + // Closing fee charged by the exchange. + closing_fee: Amount; - // Wire transfer subject, only present if type is "CLOSING". - wtid?: any; + // Wire transfer subject. + wtid: string; - // Hash of the wire account into which the funds were - // returned to, present if type is "CLOSING". - h_wire?: Base32; + // payto:// URI of the the wire account into which the funds were returned to. + receiver_account_details: string; - // If ``type`` is "RECOUP", this is a signature over - // a struct `TALER_RecoupConfirmationPS` with purpose - // TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP. - // If ``type`` is "CLOSING", this is a signature over a - // struct `TALER_ReserveCloseConfirmationPS` with purpose + // 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; + exchange_sig: EddsaSignature; - // Public key used to create ``exchange_sig``, only present if - // ``exchange_sig`` is present. - exchange_pub?: EddsaPublicKey; + // Public key used to create exchange_sig. + exchange_pub: EddsaPublicKey; - // Public key of the coin that was paid back; only present if type is "RECOUP". - coin_pub?: CoinPublicKey; + // Time when the reserve was closed. + timestamp: Timestamp; + } - // Timestamp when the exchange received the /recoup or executed the - // wire transfer. Only present if ``type`` is "DEPOSIT", "RECOUP" or - // "CLOSING". - timestamp?: Timestamp; - } + .. ts:def:: ReserveRecoupTransaction + + interface ReserveRecoupTransaction { + type: "RECOUP"; + + // Amount paid back. + amount: Amount; + + // This is a signature over + // a struct TALER_PaybackConfirmationPS with purpose + // TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK. + exchange_sig: EddsaSignature; + + // Public key used to create exchange_sig. + exchange_pub: EddsaPublicKey; + + // Time when the funds were paid back into the reserve. + timestamp: Timestamp; + + // Public key of the coin that was paid back. + coin_pub: CoinPublicKey; + } .. http:post:: /reserves/$RESERVE_PUB/withdraw @@ -578,13 +625,18 @@ denomination. 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`. :status 404 Not Found: Either the denomination key is not recognized (expired or invalid) or the wire type is not recognized. + :status 409 Conflict: + The deposit operation has either failed because the coin has insufficient + residual value, or because the same public key of the coin has been + previously used with a different denomination. Which case it is + can be decided by looking at the error code + (``TALER_EC_DEPOSIT_INSUFFICIENT_FUNDS`` or ``TALER_EC_COIN_CONFLICTING_DENOMINATION_KEY``). + The fields of the response are the same in both cases. + The request should not be repeated again with this coin. + In this case, the response is a `DepositDoubleSpendError`. **Details:** @@ -593,7 +645,7 @@ denomination. interface DepositRequest { // Amount to be deposited, can be a fraction of the // coin's total value. - f: Amount; + contribution: Amount; // 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. @@ -614,10 +666,7 @@ denomination. // exchange's unblinded RSA signature of the coin ub_sig: RsaSignature; - // timestamp when the contract was finalized, must match approximately the - // current time of the exchange; if the timestamp is too far off, the - // exchange returns "400 Bad Request" with an error code of - // "TALER_EC_DEPOSIT_INVALID_TIMESTAMP". + // timestamp when the contract was finalized. timestamp: Timestamp; // indicative time by which the exchange undertakes to transfer the funds to @@ -654,6 +703,9 @@ denomination. // URL, or if the base URL has changed since the deposit. transaction_base_url?: string; + // timestamp when the deposit was received by the exchange. + exchange_timestamp: Timestamp; + // 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 @@ -710,7 +762,8 @@ 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", "MELT", "RECOUP", + // or "RECOUP-REFRESH" coin_sig?: EddsaSignature; // Deposit fee in case of type "MELT". @@ -723,6 +776,11 @@ denomination. // only present if ``type`` is "DEPOSIT" h_wire?: HashCode; + // Hash of the public denomination key used to sign the coin. + // only present if ``type`` is "DEPOSIT", "RECOUP", + // "RECOUP-REFRESH", or "MELT". + h_denom_pub?: HashCode; + // Deposit fee in case of type "REFUND". refund_fee?: Amount; @@ -735,6 +793,14 @@ denomination. // "REFUND" rtransaction_id?: Integer; + // Coin blinding key. Only present if ``type`` is + // "RECOUP" or "RECOUP-REFRESH" + coin_blind?: DenominationBlindingKeyP; + + // Reserve receiving the recoup. Only present if ``type`` is + // "RECOUP" + reserve_pub?: EddsaPublicKey; + // `EdDSA Signature <eddsa-sig>` authorizing the REFUND. Made with // the `public key of the merchant <merchant-pub>`. // Only present if ``type`` is "REFUND" @@ -795,12 +861,16 @@ the API during normal operation. One of the signatures is invalid. :status 200 OK: 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. :status 404: the exchange does not recognize the denomination key as belonging to the exchange, or it has expired + :status 409 Conflict: + The operation is not allowed as the coin has insufficient + residual value, or because the same public key of the coin has been + previously used with a different denomination. Which case it is + can be decided by looking at the error code + (``TALER_EC_MELT_INSUFFICIENT_FUNDS`` or ``TALER_EC_COIN_CONFLICTING_DENOMINATION_KEY``). + The response is `MeltForbiddenResponse` in both cases. **Details:** @@ -1028,9 +1098,9 @@ the API during normal operation. } -------------------- -Emergency Cash-Back -------------------- +------ +Recoup +------ This API is only used if the exchange is either about to go out of business or has had its private signing keys compromised (so in @@ -1069,13 +1139,17 @@ 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`. :status 404 Not Found: The denomination key is not in the set of denomination keys where emergency pay back is enabled, or the blinded coin is not known to have been withdrawn. + :status 409 Conflict: + The operation is not allowed as the coin has insufficient + residual value, or because the same public key of the coin has been + previously used with a different denomination. Which case it is + can be decided by looking at the error code + (``TALER_EC_RECOUP_COIN_BALANCE_ZERO`` or ``TALER_EC_COIN_CONFLICTING_DENOMINATION_KEY``). + The response is a `DepositDoubleSpendError`. **Details:** @@ -1177,7 +1251,7 @@ typically also view the balance.) .. ts:def:: TrackTransferResponse interface TrackTransferResponse { - // Total amount transferred + // Actual amount of the wire transfer, excluding the wire fee. total: Amount; // Applicable wire fee that was charged @@ -1232,7 +1306,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`` , affirming that it is really the merchant who requires obtaining the wire transfer identifier. **Response:** @@ -1283,11 +1357,12 @@ typically also view the balance.) } +.. _exchange_refund: + ------- Refunds ------- -.. _refund: .. http:POST:: /coins/$COIN_PUB/refund Undo deposit of the given coin, restoring its value. @@ -1316,10 +1391,6 @@ Refunds // must be larger than the refund fee. refund_amount: Amount; - // Refund fee associated with the given coin. - // must be smaller than the refund amount. - refund_fee: Amount; - // SHA-512 hash of the contact of the merchant with the customer. h_contract_terms: HashCode; @@ -1348,4 +1419,9 @@ Refunds // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. exchange_pub: EddsaPublicKey; + + // Refund fee charged by the exchange for the given coin. + // must be smaller than the refund amount. + refund_fee: Amount; + } |