From 5afa96005420ae9b0d99eff62f4cce0afe6c6fa4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 26 Sep 2023 14:40:01 +0200 Subject: donau: reserve -> charity --- core/api-donau.rst | 82 +++++++++++++++++++++++++++--------------------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/core/api-donau.rst b/core/api-donau.rst index 222609cf..23952a7a 100644 --- a/core/api-donau.rst +++ b/core/api-donau.rst @@ -491,8 +491,8 @@ Withdrawal This API is used by the wallet to obtain digital coins. When transferring money to the donau such as via SEPA transfers, the donau creates -a *reserve*, which keeps the money from the customer. The customer must -specify an EdDSA reserve public key as part of the transfer, and can then +a *charity*, which keeps the money from the customer. The customer must +specify an EdDSA charity public key as part of the transfer, and can then withdraw digital coins using the corresponding private key. All incoming and outgoing transactions are recorded under the corresponding public key by the donau. @@ -500,67 +500,67 @@ donau. .. note:: Eventually the donau will need to advertise a policy for how long it will - keep transaction histories for inactive or even fully drained reserves. We + keep transaction histories for inactive or even fully drained charitys. We will therefore need some additional handler similar to ``/keys`` to advertise those terms of service. -.. http:get:: /reserves/$RESERVE_PUB +.. http:get:: /charitys/$CHARITY_PUB - Request information about a reserve. + Request information about a charity. **Request:** :query timeout_ms=MILLISECONDS: *Optional.* If specified, the donau will wait up to MILLISECONDS for incoming funds - before returning a 404 if the reserve does + before returning a 404 if the charity does not yet exist. **Response:** :http:statuscode:`200 OK`: - The donau responds with a `ReserveSummary` object; the reserve was known to the donau. + The donau responds with a `CharitySummary` object; the charity was known to the donau. :http:statuscode:`404 Not found`: - The reserve key does not belong to a reserve known to the donau. + The charity key does not belong to a charity known to the donau. **Details:** - .. ts:def:: ReserveSummary + .. ts:def:: CharitySummary - interface ReserveSummary { - // Balance left in the reserve. + interface CharitySummary { + // Balance left in the charity. balance: Amount; } -.. http:post:: /reserves/$RESERVE_PUB/history +.. http:post:: /charitys/$CHARITY_PUB/history - Request information about the history of a reserve. + Request information about the history of a charity. **Request:** - The request body must be a `ReserveHistoryRequest` object. + The request body must be a `CharityHistoryRequest` object. **Response:** :http:statuscode:`200 OK`: - The Donau responds with a `ReserveStatus` object; the reserve was known to the Donau. + The Donau responds with a `CharityStatus` object; the charity was known to the Donau. :http:statuscode:`403 Forbidden`: - The *TALER_SIGNATURE_RESERVE_HISTORY_REQUEST* is invalid. + The *TALER_SIGNATURE_CHARITY_HISTORY_REQUEST* is invalid. This response comes with a standard `ErrorDetail` response. Alternatively, the provided timestamp is not close to the current time. :http:statuscode:`404 Not found`: - The reserve key does not belong to a reserve known to the donau. + The charity key does not belong to a charity known to the donau. **Details:** - .. ts:def:: ReserveHistoryRequest + .. ts:def:: CharityHistoryRequest - interface ReserveHistoryRequest { + interface CharityHistoryRequest { // Signature of type - // ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` - // over a `TALER_ReserveHistoryRequestSignaturePS`. - reserve_sig: EddsaSignature; + // ``TALER_SIGNATURE_CHARITY_HISTORY_REQUEST`` + // over a `TALER_CharityHistoryRequestSignaturePS`. + charity_sig: EddsaSignature; // Time when the client made the request. // Timestamp must be reasonably close to the time of @@ -569,17 +569,17 @@ donau. request_timestamp: Timestamp; } - .. ts:def:: ReserveStatus + .. ts:def:: CharityStatus - interface ReserveStatus { - // Balance left in the reserve. + interface CharityStatus { + // Balance left in the charity. balance: Amount; // If set, gives the maximum age group that the client is required to set // during withdrawal. maximum_age_group: number; - // Transaction history for this reserve. + // Transaction history for this charity. // May be partial (!). history: TransactionHistoryItem[]; } @@ -590,12 +590,12 @@ donau. // Union discriminated by the "type" field. type TransactionHistoryItem = - | ReserveWithdrawTransaction - | ReserveCreditTransaction; + | CharityWithdrawTransaction + | CharityCreditTransaction; - .. ts:def:: ReserveWithdrawTransaction + .. ts:def:: CharityWithdrawTransaction - interface ReserveWithdrawTransaction { + interface CharityWithdrawTransaction { type: "WITHDRAW"; // Amount withdrawn. @@ -608,17 +608,17 @@ donau. h_coin_envelope: HashCode; // Signature over a `TALER_WithdrawRequestPS` - // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW`` - // created with the reserve's private key. - reserve_sig: EddsaSignature; + // with purpose ``TALER_SIGNATURE_WALLET_CHARITY_WITHDRAW`` + // created with the charity's private key. + charity_sig: EddsaSignature; // Fee that is charged for withdraw. withdraw_fee: Amount; } - .. ts:def:: ReserveCreditTransaction + .. ts:def:: CharityCreditTransaction - interface ReserveCreditTransaction { + interface CharityCreditTransaction { type: "CREDIT"; // Amount deposited. @@ -628,7 +628,7 @@ donau. sender_account_url: string; // Opaque identifier internal to the donau that - // uniquely identifies the wire transfer that credited the reserve. + // uniquely identifies the wire transfer that credited the charity. wire_reference: Integer; // Timestamp of the incoming wire transfer. @@ -715,9 +715,9 @@ Batch Withdraw ~~~~~~~~~~~~~~ -.. http:post:: /reserves/$RESERVE_PUB/batch-withdraw +.. http:post:: /charitys/$CHARITY_PUB/batch-withdraw - Withdraw multiple coins from the same reserve. Note that the client should + Withdraw multiple coins from the same charity. Note that the client should commit all of the request details, including the private key of the coins and the blinding factors, to disk *before* issuing this request, so that it can recover the information if necessary in case of transient failures, like @@ -736,17 +736,17 @@ Batch Withdraw A signature is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: - A denomination key or the reserve are not known to the donau. If the + A denomination key or the charity are not known to the donau. If the denomination key is unknown, this suggests a bug in the wallet as the wallet should have used current denomination keys from ``/keys``. In this case, the response will be a `DonationUnitUnknownMessage`. - If the reserve is unknown, the wallet should not report a hard error yet, but + If the charity is unknown, the wallet should not report a hard error yet, but instead simply wait for up to a day, as the wire transaction might simply not yet have completed and might be known to the donau in the near future. In this case, the wallet should repeat the exact same request later again using exactly the same blinded coin. :http:statuscode:`409 Conflict`: - The balance of the reserve is not sufficient to withdraw the coins of the + The balance of the charity is not sufficient to withdraw the coins of the indicated donation units. :http:statuscode:`410 Gone`: A requested denomination key is not yet or no longer valid. -- cgit v1.2.3