remove reward-related APIs and design considerations

1 files changed, 1 insertions, 540 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 652c7303..46392118 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -199,8 +199,7 @@ This section describes (public) endpoints that wallets must be able
 to interact with directly (without HTTP-based authentication). These
 endpoints are used to process payments (claiming an order, paying
 for the order, checking payment/refund status and aborting payments),
-process refunds (checking refund status, obtaining the refund),
-and to pick up rewards.
+and to process refunds (checking refund status, obtaining the refund).
 
 
 Claiming an order
@@ -837,111 +836,6 @@ the contract. Refunds must be approved by the merchant's business logic.
     }
 
 
-Picking up rewards
-------------------
-
-Rewards are a way for wallets to obtain e-cash from
-a website.
-
-.. http:get:: [/instances/$INSTANCE]/rewards/$REWARD_ID
-
-  Handle request from wallet to provide details about a reward.
-
-  This endpoint typically also supports requests with the "Accept" header
-  requesting "text/html".  In this case, an HTML response suitable for
-  triggering the interaction with the wallet is returned. If the backend
-  installation does not include the required HTML templates, a 406 status
-  code is returned.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    A reward is being returned. The backend responds with a `RewardInformation`.
-  :http:statuscode:`404 Not found`:
-    The reward identifier is unknown.
-  :http:statuscode:`406 Not acceptable`:
-    The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.)
-  :http:statuscode:`410 Gone`:
-    A reward has been fully claimed. The JSON reply still contains the `RewardInformation`.
-
-  .. ts:def:: RewardInformation
-
-    interface RewardInformation {
-
-      // Exchange from which the reward will be withdrawn. Needed by the
-      // wallet to determine denominations, fees, etc.
-      exchange_url: string;
-
-      // URL where to go after obtaining the reward.
-      next_url: string;
-
-      // (Remaining) amount of the reward (including fees).
-      reward_amount: Amount;
-
-      // Timestamp indicating when the reward is set to expire (may be in the past).
-      // Note that rewards that have expired MAY also result in a 404 response.
-      expiration: Timestamp;
-    }
-
-
-.. http:post:: [/instances/$INSTANCE]/rewards/$REWARD_ID/pickup
-
-  Handle request from wallet to pick up a reward.
-
-  **Request:**
-
-  The request body is a `RewardPickupRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    A reward is being returned. The backend responds with a `RewardResponse`.
-  :http:statuscode:`401 Unauthorized`:
-    The reward amount requested exceeds the reward.
-  :http:statuscode:`404 Not found`:
-    The reward identifier is unknown.
-  :http:statuscode:`409 Conflict`:
-    Some of the denomination key hashes of the request do not match those currently available from the exchange (hence there is a conflict between what the wallet requests and what the merchant believes the exchange can provide).
-  :http:statuscode:`410 Gone`:
-    The reward has expired.
-
-  .. ts:def:: RewardPickupRequest
-
-    interface RewardPickupRequest {
-
-      // List of planchets the wallet wants to use for the reward.
-      planchets: PlanchetDetail[];
-    }
-
-  .. ts:def:: PlanchetDetail
-
-    interface PlanchetDetail {
-      // Hash of the denomination's public key (hashed to reduce
-      // bandwidth consumption).
-      denom_pub_hash: HashCode;
-
-      // Coin's blinded public key.
-      coin_ev: CoinEnvelope;
-    }
-
-  .. ts:def:: RewardResponse
-
-    interface RewardResponse {
-
-      // Blind RSA signatures over the planchets.
-      // The order of the signatures matches the planchets list.
-      blind_sigs: BlindSignature[];
-    }
-
-  .. ts:def:: BlindSignature
-
-    interface BlindSignature {
-
-      // The (blind) RSA signature. Still needs to be unblinded.
-      blind_sig: BlindedRsaSignature;
-    }
-
-
 -------------------
 Instance management
 -------------------
@@ -2698,439 +2592,6 @@ once we got a reply from the exchange.
     The transfer cannot be deleted anymore.
 
 
-.. _api-rewards:
-
------------------------
-Backend: Giving rewards
------------------------
-
-.. note::
-
-  This API is deprecated as of protocol v8.
-
-Rewards are a way for websites to give small amounts of e-cash to visitors (for
-example as a financial reward for providing information or viewing
-advertisements).  Rewards are non-contractual: neither merchant nor consumer
-have any contractual information about the other party as a result of the
-reward.
-
-
-Create reserve
---------------
-
-.. note::
-
-  This API is deprecated as of protocol v8.
-
-Reserves are basically funds a merchant has provided to an exchange for a
-rewards campaign. Each reserve has a limited lifetime (say 2--4 weeks). Any
-funds not used to reward customers will automatically be wired back from the
-exchange to the originating account.
-
-Before handing out rewards, a merchant must tell the backend to set up a
-reserve. The backend will return a reserve public key which must be used as
-the wire transfer subject when wiring the reward campaign funds to the
-exchange.
-
-.. http:post:: [/instances/$INSTANCE]/private/reserves
-
-  Create a reserve for rewards.
-
-  This request is **not** idempotent.  However, while repeating
-  it will create another reserve, that is generally pretty harmless
-  (assuming only one of the reserves is filled with a wire transfer).
-  Clients may want to eventually delete the unused reserves to
-  avoid clutter.
-
-  **Request:**
-
-  The request body is a `ReserveCreateRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The backend is waiting for the reserve to be established. The merchant
-    must now perform the wire transfer indicated in the `ReserveCreateConfirmation`.
-  :http:statuscode:`408 Request timeout`:
-    The exchange did not respond on time.
-  :http:statuscode:`409 Conflict`:
-    The exchange does not support the requested wire method or does not allow rewards.
-  :http:statuscode:`502 Bad gateway`:
-    We could not obtain ``/wire`` details from the specified exchange base URL.
-  :http:statuscode:`504 Gateway timeout`:
-    The merchant's interaction with the exchange took too long.
-    The client might want to try again later.
-
-  .. ts:def:: ReserveCreateRequest
-
-    interface ReserveCreateRequest {
-      // Amount that the merchant promises to put into the reserve.
-      initial_balance: Amount;
-
-      // Exchange the merchant intends to use for rewards.
-      exchange_url: string;
-
-      // Desired wire method, for example "iban" or "x-taler-bank".
-      wire_method: string;
-    }
-
-  .. ts:def:: ReserveCreateConfirmation
-
-    interface ReserveCreateConfirmation {
-      // Public key identifying the reserve.
-      reserve_pub: EddsaPublicKey;
-
-      // Wire accounts of the exchange where to transfer the funds.
-      accounts: WireAccount[];
-    }
-
-.. http:get:: [/instances/$INSTANCE]/private/reserves
-
-  Obtain list of reserves that have been created for rewards.
-
-  **Request:**
-
-  :query after: *Optional*.  Only return reserves created after the given timestamp in milliseconds.
-  :query active: *Optional*.  Only return active/inactive reserves depending on the boolean given.
-  :query failures: *Optional*.  Only return reserves where we disagree with the exchange about the initial balance.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    Returns a list of known reward reserves.
-    The body is a `RewardReserveStatus`.
-
-  .. ts:def:: RewardReserveStatus
-
-    interface RewardReserveStatus {
-      // Array of all known reserves (possibly empty!).
-      reserves: ReserveStatusEntry[];
-    }
-
-  .. ts:def:: ReserveStatusEntry
-
-     interface ReserveStatusEntry {
-      // Public key of the reserve.
-      reserve_pub: EddsaPublicKey;
-
-      // Timestamp when it was established.
-      creation_time: Timestamp;
-
-      // Timestamp when it expires.
-      expiration_time: Timestamp;
-
-      // Initial amount as per reserve creation call.
-      merchant_initial_amount: Amount;
-
-      // Initial amount as per exchange, 0 if exchange did
-      // not confirm reserve creation yet.
-      exchange_initial_amount: Amount;
-
-      // Amount picked up so far.
-      pickup_amount: Amount;
-
-      // Amount approved for rewards that exceeds the pickup_amount.
-      committed_amount: Amount;
-
-      // Is this reserve active (false if it was deleted but not purged)?
-      active: boolean;
-    }
-
-
-Query funds remaining
----------------------
-
-.. http:get:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB
-
-  Obtain information about a specific reserve that have been created for rewards.
-
-  **Request:**
-
-  :query rewards: *Optional*. If set to "yes", returns also information about all of the rewards created.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    Returns the `ReserveDetail`.
-  :http:statuscode:`404 Not found`:
-    The reward reserve is not known.
-  :http:statuscode:`502 Bad gateway`:
-    We are having trouble with the request because of a problem with the exchange.
-    Likely returned with an "exchange_code" in addition to a "code" and
-    an "exchange_http_status" in addition to our own HTTP status. Also usually
-    includes the full exchange reply to our request under "exchange_reply".
-    This is only returned if there was actual trouble with the exchange, not
-    if the exchange merely did not respond yet or if it responded that the
-    reserve was not yet filled.
-  :http:statuscode:`504 Gateway timeout`:
-    The merchant's interaction with the exchange took too long.
-    The client might want to try again later.
-
-  .. ts:def:: ReserveDetail
-
-    interface ReserveDetail {
-      // Timestamp when it was established.
-      creation_time: Timestamp;
-
-      // Timestamp when it expires.
-      expiration_time: Timestamp;
-
-      // Initial amount as per reserve creation call.
-      merchant_initial_amount: Amount;
-
-      // Initial amount as per exchange, 0 if exchange did
-      // not confirm reserve creation yet.
-      exchange_initial_amount: Amount;
-
-      // Amount picked up so far.
-      pickup_amount: Amount;
-
-      // Amount approved for rewards that exceeds the pickup_amount.
-      committed_amount: Amount;
-
-      // Array of all rewards created by this reserves (possibly empty!).
-      // Only present if asked for explicitly.
-      rewards?: RewardStatusEntry[];
-
-      // Is this reserve active (false if it was deleted but not purged)?
-      active: boolean;
-
-      // Array of wire accounts of the exchange that could
-      // be used to fill the reserve, can be NULL
-      // if the reserve is inactive or was already filled
-      accounts?: WireAccount[];
-
-      // URL of the exchange hosting the reserve,
-      // NULL if the reserve is inactive
-      exchange_url: string;
-    }
-
-  .. ts:def:: RewardStatusEntry
-
-    interface RewardStatusEntry {
-
-      // Unique identifier for the reward.
-      reward_id: HashCode;
-
-      // Total amount of the reward that can be withdrawn.
-      total_amount: Amount;
-
-      // Human-readable reason for why the reward was granted.
-      reason: string;
-    }
-
-
-Authorizing rewards
--------------------
-
-.. note::
-
-  This API is deprecated as of protocol v8.
-
-.. http:post:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB/authorize-reward
-
-  Authorize creation of a reward from the given reserve.
-
-  **Request:**
-
-  The request body is a `RewardCreateRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    A reward has been created. The backend responds with a `RewardCreateConfirmation`.
-  :http:statuscode:`404 Not found`:
-    The instance or the reserve is unknown to the backend.
-  :http:statuscode:`412 Precondition failed`:
-    The reward amount requested exceeds the available reserve balance for rewards.
-
-  .. ts:def:: RewardCreateRequest
-
-    interface RewardCreateRequest {
-      // Amount that the customer should be rewarded.
-      amount: Amount;
-
-      // Justification for giving the reward.
-      justification: string;
-
-      // URL that the user should be directed to after receiving the reward,
-      // will be included in the reward_token.
-      next_url: string;
-    }
-
-  .. ts:def:: RewardCreateConfirmation
-
-    interface RewardCreateConfirmation {
-      // Unique reward identifier for the reward that was created.
-      reward_id: HashCode;
-
-      // taler://reward URI for the reward.
-      taler_reward_uri: string;
-
-      // URL that will directly trigger processing
-      // the reward when the browser is redirected to it.
-      reward_status_url: string;
-
-      // When does the reward expire?
-      reward_expiration: Timestamp;
-    }
-
-
-.. http:post:: [/instances/$INSTANCE]/private/rewards
-
-  Authorize creation of a reward, with
-  automatic selection of a working reserve of the instance by the
-  backend. Intentionally otherwise identical to the ``/authorize-reward``
-  endpoint given above.
-
-  **Request:**
-
-  The request body is a `RewardCreateRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    A reward has been created. The backend responds with a `RewardCreateConfirmation`.
-  :http:statuscode:`404 Not found`:
-    The instance is unknown to the backend.
-  :http:statuscode:`412 Precondition failed`:
-    The reward amount requested exceeds the available reserve balance for rewards
-    in all of the reserves of the instance.
-
-
-Deleting reserves
------------------
-
-.. note::
-
-  This API is deprecated as of protocol v8.
-
-.. http:delete:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB
-
-  Delete information about a reserve.  Fails if the reserve still has
-  committed to rewards that were not yet picked up and that have not yet
-  expired.
-
-  **Request:**
-
-  :query purge: *Optional*. If set to YES, the reserve and all information
-      about rewards it issued will be fully deleted.
-      Otherwise only the private key would be deleted.
-
-  **Response:**
-
-  :http:statuscode:`204 No content`:
-    The backend has successfully deleted the reserve.
-  :http:statuscode:`404 Not found`:
-    The backend does not know the instance or the reserve.
-  :http:statuscode:`409 Conflict`:
-    The backend refuses to delete the reserve (committed rewards awaiting pickup).
-
-
-Checking reward status
-----------------------
-
-.. note::
-
-  This API is deprecated as of protocol v8.
-
-.. http:get:: [/instances/$INSTANCE]/private/rewards/$REWARD_ID
-
-  Obtain information about a particular reward.
-
-  **Request:**
-
-  :query pickups: *Optional*. If set to "yes", returns also information about all of the pickups.
-  :query min_amount: *Optional*. Minimum pick-up amount the client is interested in.
-  :query timeout_ms=NUMBER: *Optional.*  If specified, the merchant backend will
-    wait up to ``timeout_ms`` milliseconds for rewards of at least min_pick_up to be
-    picked up.  A client must never rely on this behavior, as the
-    merchant backend may return a response immediately.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The reward is known. The backend responds with a `RewardDetails` message.
-  :http:statuscode:`404 Not found`:
-    The reward is unknown to the backend.
-
-  .. ts:def:: RewardDetails
-
-    interface RewardDetails {
-      // Amount that we authorized for this reward.
-      total_authorized: Amount;
-
-      // Amount that was picked up by the user already.
-      total_picked_up: Amount;
-
-      // Human-readable reason given when authorizing the reward.
-      reason: string;
-
-      // Timestamp indicating when the reward is set to expire (may be in the past).
-      expiration: Timestamp;
-
-      // Reserve public key from which the reward is funded.
-      reserve_pub: EddsaPublicKey;
-
-      // Array showing the pickup operations of the wallet (possibly empty!).
-      // Only present if asked for explicitly.
-      pickups?: PickupDetail[];
-    }
-
-  .. ts:def:: PickupDetail
-
-    interface PickupDetail {
-      // Unique identifier for the pickup operation.
-      pickup_id: HashCode;
-
-      // Number of planchets involved.
-      num_planchets: Integer;
-
-      // Total amount requested for this pickup_id.
-      requested_amount: Amount;
-    }
-
-
-.. http:get:: [/instances/$INSTANCE]/private/rewards
-
-  Return the list of all rewards.
-
-  **Request:**
-
-  :query include_expired: *Optional*. If set to "yes", the result includes expired rewards also. Otherwise, only active rewards are returned.
-
-  :query limit: *Optional*. At most return the given number of results. Negative for descending in database row id, positive for ascending in database row id.
-
-  :query offset: *Optional*. Starting ``row_id`` for an iteration.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The backend has successfully found the list of rewards. The backend responds
-    with a `RewardsResponse`.
-
-  .. ts:def:: RewardsResponse
-
-    interface RewardsResponse {
-
-      // List of rewards that are present in the backend.
-      rewards: Reward[];
-    }
-
-  .. ts:def:: Reward
-
-     interface Reward {
-
-      // ID of the reward in the backend database.
-      row_id: number;
-
-      // Unique identifier for the reward.
-      reward_id: HashCode;
-
-      // (Remaining) amount of the reward (including fees).
-      reward_amount: Amount;
-    }
-
 -----------
 OTP Devices
 -----------