From db6bd65c627e8431f3cf5bf88f6d1c779836a7cc Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 8 Apr 2022 19:22:40 +0200 Subject: -update spec --- core/api-exchange.rst | 117 +++++++++++++++++++++++++++++++++------------- manpages/taler.conf.5.rst | 4 ++ 2 files changed, 88 insertions(+), 33 deletions(-) diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 203b1c92..b55fb6be 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -3071,6 +3071,9 @@ Wallet-to-wallet transfers // EdDSA public key exchange used for 'exchange_sig'. exchange_pub: EddsaPublicKey; + // EdDSA public key used to approve merges of this purse. + merge_pub: EddsaPublicKey; + // AES-GCM Encrypted contract terms using encryption // key derived from DH of 'contract_pub' and the 'purse_pub'. // Optional, may be omitted if not desired by the client. @@ -3150,6 +3153,9 @@ Wallet-to-wallet transfers // (amount, h_contract_terms, expiration). purse_sig: EddsaSignature; + // EdDSA public key used to approve merges of this purse. + merge_pub: EddsaPublicKey; + // Total amount to be paid into the purse. // Clients may make several requests, i.e. if a // first request failed with a double-spending error. @@ -3160,9 +3166,9 @@ Wallet-to-wallet transfers // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; - // Client-side timestamp of when the payment was made. - payment_timestamp: Timestamp; - + // Minimum age of deposits made into the purse + minimum_age: Integer; + // 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 will be auto-refunded. @@ -3382,12 +3388,6 @@ Wallet-to-wallet transfers 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 - reporting on the completion of merge operation. Basically - forstalls returning a 202 response for up to timeout milliseconds - to possibly return a 200 response instead. - **Response:** :http:statuscode:`200 OK`: @@ -3432,29 +3432,11 @@ Wallet-to-wallet transfers // 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 - // the total value of the purse minus the deposit fees. - // If the deposit fees are lower, the contribution to the - // reserve can be higher! - merge_value_after_fees: Amount; - - // SHA-512 hash of the contact of the purse. - h_contract_terms: HashCode; + merge_sig: EddsaSignature; // Client-side timestamp of when the merge request was made. merge_timestamp: Timestamp; - // Indicative time by which the purse should expire - // if it has not been paid. - purse_expiration: Timestamp; - - // Optional encrypted contract, in case the seller is - // proposing the contract and thus establishing the - // purse with the payment. - contract?: EncryptedContract; - } .. ts:def:: MergeSuccess @@ -3464,13 +3446,10 @@ Wallet-to-wallet transfers // Amount merged (excluding deposit fees). merge_amount: Amount; - // SHA-512 hash of the contact of the purse. - h_contract_terms: HashCode; - // Time at which the merge came into effect. // Maximum of the "payment_timestamp" and the // "merge_timestamp". - contract_time: Timestamp; + exchange_timestamp: Timestamp; // EdDSA signature of the exchange affirming the merge of // purpose ``TALER_SIGNATURE_PURSE_MERGE_SUCCESS`` @@ -3486,6 +3465,76 @@ Wallet-to-wallet transfers .. ts:def:: MergeAccepted interface MergeAccepted { + + // Current balance in the purse. + balance: Amount; + + } + + + +.. http:POST:: /reserves/$RESERVE_PUB/purse + + Create purse for an account. + Endpoint to be used by the seller. + + **Request:** + + The request body must be a `ReservePurseRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The operation succeeded, the exchange confirms that the + purse was allocated. + The response will include a `MergePending` object. + :http:statuscode:`401 Unauthorized`: + Account signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`402 Payment Required`: + The account needs to contain more funding to create more purses. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The refund operation failed as we could not find the purse. + This response comes with a standard `ErrorDetail` response. + + **Details:** + + .. ts:def:: ReservePurseRequest + + interface ReservePurseRequest { + + // EdDSA signature of the account/reserve affirming the merge + // over a `TALER_XXX`. + // Must be of purpose ``TALER_SIGNATURE_XXX`` + reserve_sig: EddsaSignature; + + // Minimum amount that must be credited to the reserve, that is + // the total value of the purse minus the deposit fees. + // If the deposit fees are lower, the contribution to the + // reserve can be higher! + merge_value_after_fees: Amount; + + // SHA-512 hash of the contact of the purse. + h_contract_terms: HashCode; + + // Client-side timestamp of when the merge request was made. + merge_timestamp: Timestamp; + + // Indicative time by which the purse should expire + // if it has not been paid. + purse_expiration: Timestamp; + + // Optional encrypted contract, in case the seller is + // proposing the contract and thus establishing the + // purse with the payment. + contract?: EncryptedContract; + + } + + .. ts:def:: MergePending + + interface MergePending { // The number of remaining purses that can still be opened // under the given account. @@ -3493,7 +3542,9 @@ Wallet-to-wallet transfers } - + +-- TODO: API to deposit into existing purse + .. _exchange_wads: diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index a6b65196..bcb62551 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -316,6 +316,10 @@ IDLE_RESERVE_EXPIRATION_TIME LEGAL_RESERVE_EXPIRATION_TIME After what time do we forget about (drained) reserves during garbage collection? +AGGREGATOR_SHIFT + Delay between a deposit being eligible for aggregation and + the aggregator actually triggering. + EXCHANGE POSTGRES BACKEND DATABASE OPTIONS ------------------------------------------ -- cgit v1.2.3