DD 55: Wallet Problem Reports
#############################

.. note::

   **Status**: Early work in progress / DD number reservation.

.. warning::

   We concluded that we don't need the problem reports feature right now,
   as all cases we care about are already covered by something else.

Summary
=======

This design document specifies global error reports generated/managed by wallet-core
and rendered by the wallet UIs.

Motivation
==========

Sometimes the wallet encounters issues that go beyond the scope of single transaction.

Requirements
============

* problem reports must have a clear lifecycle
* problem reports must have some type of identification that allows to
  easily find out if a new problem report needs to be created when an
  error happens or whether an existing one has been created

Proposed Solution
=================

Report identification
---------------------

The report identifier serves multiple purposes:

1. Usage as a reference in wallet-core APIs
2. De-duplication. The report ID should allow easy identification of an already existing report for a particular problem.

New wallet-core requests
------------------------

* ``listProblemReports``
* ``acknowledgeProblemReport``: Mark a problem report as read.
* ``deleteProblemReport``: Delete the problem report.

New wallet-core notification type
---------------------------------

* ``problem-report`` to notify clients about status changes or an error report
  (including creation!)


Types of reports
----------------

(Currently we don't have any good examples where this is actually needed.)

Examples of what should NOT be a report
---------------------------------------

* money lost due to the exchange stopping to offer a denomination

  * => Should be a transactions item

* money locked behind a (long) pending refresh

  * => Should be a pending transaction

* money lost due to a permanently failing refresh

  * => pending or final transaction item

* money lost due to expired denominations (auto-refresh wasn't done fast enough)

  * => transaction item

* a denomination changed its info (expiration, fees)

  * => exchange entry state

* Important information about the exchange changed (master pub, accounts, keys)

  => exchange entry state


Definition of Done
==================

TBD.

Alternatives
============

* Report problems with an API specific to each resource (exchange entry, transaction, ...)
* Have an *alerts* API that returns alerts to the client that the client can show to to the user,
  but that a user can't interact with.

Drawbacks
=========

TBD.

Discussion / Q&A
================

* When is a report amended vs a new report created?

 * example: Exchange stops offering denomination D1. Later, it stops offering D2.
   Are two reports generated or is the first report changed?