From be69b01fcc7b5cfc3e2575b50211b2d74e47f83d Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 17 Sep 2022 23:27:42 +0200 Subject: -propose reserve open/close API --- core/api-exchange.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) (limited to 'core/api-exchange.rst') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 3e71ba4f..357aa565 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -4372,3 +4372,175 @@ KYC status updates The webhook succeeded. :http:statuscode:`404 Not found`: The specified logic is unknown. + + +--------------- +Reserve control +--------------- + +This section is about a proposed API. It is not implemented. + +.. http:post:: /reserves/$RESERVE_PUB/open + + Request keeping a reserve open for tipping or invoicing. + + **Request:** + + The request body must be a `ReserveOpenRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `ReserveOpenResponse` object. + :http:statuscode:`402 Payment Required`: + The reserve balance is insufficient to pay for the open operation. + The exchange responds with a `RequiredBalanceResponse` object. + :http:statuscode:`403 Forbidden`: + The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The reserve key does not belong to a reserve known to the exchange. + :http:statuscode:`451 Unavailable For Legal Reasons`: + This account has not yet passed the KYC checks. + The client must pass KYC checks before the reserve can be opened. + The response will be an `KycNeededRedirect` object. + + **Details:** + + .. ts:def:: ReserveOpenRequest + + interface ReserveOpenRequest { + // Signature of purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over + // a `TALER_ReserveOpenRequestSignaturePS`. + reserve_sig: EddsaSignature; + + // Time when the client made the request. + // Timestamp must be reasonably close to the time of + // the exchange, otherwise the exchange may reject + // the request (with a status code of 400). + request_timestamp: Timestamp; + + // Desired new expiration time for the reserve. + // If the reserve would expire before this time, + // the exchange will charge account fees (and + // possibly KYC fees) until the expiration time + // exceeds this timestamp. Note that the exchange + // will refuse requests (with a status code of 400) + // if the time is so far in the future that the + // fees are not yet known (see /keys). + reserve_expiration: Timestamp; + + // Desired open purse limit. Can be used to pay the + // annual account fee more than once to get a larger + // purse limit. + purse_limit: Integer; + + } + + .. ts:def:: ReserveOpenResponse + + interface ReserveOpenResponse { + // Balance left in the reserve after the account_fee + // was charged. + balance: Amount; + + // Transaction cost for extending the expiration time. + // Excludes KYC fees. + open_cost: Amount; + + // New expiration time for the reserve. + reserve_expiration: Timestamp; + } + + .. ts:def:: RequiredBalanceResponse + + interface RequiredBalanceResponse { + // Balance left in the reserve after the account_fee + // was charged. + balance: Amount; + + // Transaction cost for extending to the + // requested expiration time. + // Includes applicable KYC fees. + required: Amount; + + } + + + +.. http:post:: /reserves/$RESERVE_PUB/close + + Force immediate closure of a reserve. Does not actually + delete the reserve or the KYC data, but merely forces + the reserve's current balance to be wired back to the + account where it originated from, or another account of + the user's choosing if they performed the required KYC + check and designated another target account. + + **Request:** + + The request body must be a `ReserveCloseRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `ReserveCloseResponse` object. + :http:statuscode:`403 Forbidden`: + The *TALER_SIGNATURE_WALLET_RESERVE_CLOSE* signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The reserve key does not belong to a reserve known to the exchange. + :http:statuscode:`409 Conflict`: + No target account was given, and the exchange does not know an + origin account for this reserve. + :http:statuscode:`451 Unavailable For Legal Reasons`: + This account has not yet passed the KYC checks, hence wiring + funds to a non-origin account is not allowed. + The client must pass KYC checks before the reserve can be opened. + The response will be an `KycNeededRedirect` object. + + **Details:** + + .. ts:def:: ReserveCloseRequest + + interface ReserveCloseRequest { + // Signature of purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE`` over + // a `TALER_ReserveCloseRequestSignaturePS`. + reserve_sig: EddsaSignature; + + // Time when the client made the request. + // Timestamp must be reasonably close to the time of + // the exchange, otherwise the exchange may reject + // the request (with a status code of 400). + request_timestamp: Timestamp; + + // Maximum amount to transfer to the indicated + // account (after fees). If not given, the + // reserve will be completely drained. The amount + // given may exceed the reserve balance, in which case + // the reserve will also be completely drained. + maximum_transfer?: Amount; + + // payto://-URI of the account the reserve balance is to be + // wired to. Must be of the form: 'payto://$METHOD' for a + // wire method supported by this exchange (if the + // method is not supported, this is a bad request (400)). + // If not given, the reserve's origin account + // will be used. If no origin account is known for the + // reserve and not given, this is a conflict (409). + payto_uri?: string; + + } + + .. ts:def:: ReserveCloseResponse + + interface ReserveCloseResponse { + // Balance left in the reserve after the close. + balance: Amount; + + // Actual amount that will be wired (excludes closing fee). + wire_amount: Amount; + + } -- cgit v1.2.3