commit c781c0350e8684d08399de05700d4f247c33f2d3
parent fbdab6656201010293d63c5b47775094f5f0e600
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Tue, 7 Oct 2025 21:58:27 +0200
dd13 user stories overhaul
Diffstat:
1 file changed, 84 insertions(+), 53 deletions(-)
diff --git a/design-documents/070-alias-directory-mailbox.rst b/design-documents/070-alias-directory-mailbox.rst
@@ -72,34 +72,52 @@ computing base.
User Stories
============
+Both the Mailbox server URI and the Taldir server URI have hard-coded defaults that can be overriden in expert settings.
+In the user stories, we use the placeholders ``$MAILBOX_SERVER`` and
+``$TALDIR_SERVER`` for those URIs.
+
+Alias Registration
+------------------
+
+ Prerequisites: Alice has installed Taler Wallet
+
+Alice opens the Taler Wallet and browses to ``Settings -> Aliases``.
+The interface offers registration of any Alias type supported by the Taldir instance through
+a ``+`` button and suitable follow-up screens.
+
+ **Technical Note**: Alice registers an Alias with the Mailbox URI that corresponds to her Wallet ID (See also :ref:`Mailbox API <api-mailbox>`). The interface does not require Alice to input the URI manually, the Wallet can synthesize the Mailbox URI from an address: ``$MAILBOX_SERVER/SHA512(WalletPublicKey)``.
+
+
+ **Technical Note**: Supported alias types are found in the ``/config`` endpoint of the mailbox server.
+
+
+Alice chooses an alias type and is then prompted to provide her type-specific alias, e.g. *alice@example.com* would be an alias of type *email*.
+This initiates the Alias validation procedure.
+
+ **Technical Note**: This initiates the alias registration flow provided in :ref:`Taldir API <api-taldir>`.
-US-1: Alias registration
-------------------------
-
-Prerequisites: Alice has installed Taler Wallet
-
-In the Taler Wallet, Alice is provided with an option
-to register one or more Aliases with her Wallet Address.
-This requires a Wallet interface element that is probably found somewhere in
-the settings or hidden in a menu.
-More specifically, Alice will be able to register an Alias with
-the Mailbox URI that corresponds to her Wallet ID (See also :ref:`Mailbox API <api-mailbox>`).
-The interface does not require Alice to input the URI manually, the
-Wallet can synthesize the Mailbox URI.
-Both the Mailbox server URI and the Taldir server URI have hard-coded defaults
-that can be overriden in expert settings.
-The interface offers registration of Aliases supported by the Taldir instance.
-Alice chooses an Alias and is then prompted to provide her handle, e.g. *alice@example.com*.
-This initiates the Alias validation procedure (See also :ref:`Taldir API <api-taldir>`).
The registration procedure may succeed or fail.
Alice may retry on failure to register the same Alias.
Alice may also register other Aliases.
-Alice may use this screen to display a QR code of her mailbox URI, see also US-4.
-US-2: Send Payment Request
---------------------------
+.. _dd-13-us-alias-mgmt:
+
+Alias Management
+----------------
+
+ Prerequisites: Alice has registered one or more aliases
-Prerequisites: Bob has installed Taler Wallet
+Alice opens ``Settings -> Aliases`` to manage her aliases.
+The UI shows all registered aliases with expiration times.
+The UI allows Alice to delete registrations (or disable auto-renewal) and renew a registration pre-emptively before it expires.
+Alice may use this screen to display a QR code of her mailbox URI, see also :ref:`Friends Management <dd-13-us-friends-mgmt>`.
+
+ This may require separation into two or three stories.
+
+Send Payment Request
+--------------------
+
+ Prerequisites: Bob has installed Taler Wallet, Bob knows one of Alice's aliases
Bob wants to request money from Alice.
He opens his Taler wallet and opens ``Taler Button->Send`` screen from the menu.
@@ -108,74 +126,89 @@ Once Bob has entered all necessary details, a payment request (:ref:`DD 13 <dd-1
created and the screen with QR code is shown.
This screen now also allows to send the request to a friend by using the friend list.
The *Request from Friend* screen brings up the friends list to select a friend.
-Bob may also import a friend here ad-hoc, see US-4.
-Bob selects the friend and the request is sent to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`.
-This request may fail, for example if Alice's Mailbox is full.
+Bob may also import a friend here ad-hoc, see :ref:`Friends Management <dd-13-us-friends-mgmt>`.
+Bob selects the friend and the request is sent to Alice.
+
+ **Technical Note**: This will trigger the wallet to send the payment request to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`. The message format is still TBD.
+
+The request may fail, for example if Alice's Mailbox is full.
**Note**: Sending messages via Mailbox API may incur fees.
-US-3: Receive Payment Request
------------------------------
+Receive Payment Request
+-----------------------
-Prerequisites: Alice has installed Taler Wallet, Alice has registered an Alias.
+ Prerequisites: Alice has installed Taler Wallet, Alice has registered an Alias, Bob has sent a payment request.
-Alice's Wallet periodically checks her Mailbox using the :ref:`Mailbox API <api-mailbox>`
-for new payment requests and downloads the messages locally.
-Remote messages are deleted after download.
+ **Technical Note**: The Wallet periodically checks Mailboxes using the :ref:`Mailbox API <api-mailbox>` for new payment requests and downloads the messages locally. Remote messages are deleted after download.
- **Note**: When are local messages deleted?
-If a new payment request ID is found the Wallet should notify Alice.
+The new payment request by Bob is received by the Wallet and it notifies Alice.
+
+ **Technical Note**: Notice request is *NEW*. This requires requests to have unique IDs. Also, maybe notifications should happen even if the ID is already seen, but the message is new.
- **Note**: Notice request *ID*. This requires requests to have unique IDs. Also, maybe notifications should happen even if the ID is already seen, but the message is new.
+Alice interacts with the notification or manually browses to ``Mailbox``.
-The wallet provides a screen with payment request overviews (list of messages
+ **TODO**: Does this exist / make sense?
+
+There, the wallet provides a screen with payment request overviews (e.g. list of messages
in the local mailbox).
Alice selects Bob's payment request either through the notification or from the list
of payment requests.
Alice creates a P2P payment based on the metadata in the payment request.
She may also decline to pay.
-US-4: Friend List
+ **Note**: When are local messages deleted?
+
+.. _dd-13-us-friends-mgmt:
+
+Friends Management
-----------------
-Prerequisites: Alice has installed Taler Wallet
+ Prerequisites: Alice has installed Taler Wallet
Alice opens ``Settings->Friends``.
The list of friends is empty in the beggining.
There is a button to *Add a friend* which opens a UI.
The UI consists of a search input and an Alias type selector.
Alice selects the Alias type (e.g. GitHub or Email) and inputs a friends Alias.
-This will initiate a lookup request to the :ref:`Taldir API <api-taldir>`.
+
+ **Technical Note**: This will initiate a lookup request using the :ref:`Taldir API <api-taldir>`.
+
If no results were found, Alice cannot import this friend.
If found, Alice will be able to import this friend into the friend list.
-Alternatively, the friend can also be imported using a QR code, see US-1.
+Alternatively, the friend can also be imported using a QR code, see :ref:`Alias Management <dd-13-us-alias-mgmt>`.
-The wallet periodically performs lookups for friends where their Taldir registrations
-have expired and refresh accordingly.
+ **Technical Note**: The wallet periodically performs lookups for friends where their Taldir registrations have expired and refresh accordingly.
-US-5: Send Money
-----------------
+Send Money
+----------
-Prerequisites: Alice has installed Taler Wallet, Alice has registered an Alias.
+ Prerequisites: Alice has installed Taler Wallet, Alice has registered an Alias.
Bob wants to directly send money to Alice (e.g. PayPal style).
He opens his Taler wallet and opens ``Taler Button->Receive``.
A screen that allows to create a payment offer is shown to Bob.
-Once Bob has entered all necessary details, the payment offer is created according to :ref:`DD 13 <dd-13>` and the screen with the QR code is shown.
-There he selects the *Receive from Alias*.
-The *Receive from Alias* screen consists of a search input and an Alias type selector.
+Once Bob has entered all necessary details, the payment offer is created and the screen with the QR code is shown.
+There, he selects the *Receive from Friend*.
+The *Receive from Friend* screen consists of a search input and an Alias type selector.
This screen now also allows to send the request to a friend by using the friend list.
+Bob selects *Send to Friend*.
The *Send to Friend* screen brings up the friends list to select a friend.
-Bob may also import a friend here ad-hoc, see US-4.
-Bob selects the friend and the request is sent to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`.
+
+ **Note**: At this point, Bob may now also import a friend here ad-hoc, see :ref:`Friends Management <dd-13-us-friends-mgmt>`.
+
+Bob selects the friend and the payment offer is sent to Alice.
+
+ **Technical Note**: The offer is sent to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`.
+
This request may fail, for example if Alice's Mailbox is full.
**Note**: Sending messages via Mailbox API may incur fees. So does creating a purse in the offer. This should probably be done in a single user action.
- **Note**: Should mailbox be used to notify Alice of payment?
+ **Note**: Should mailbox be used to notify Alice of payment? A: Yes
Open Questions
@@ -216,9 +249,7 @@ flag or dev-mode flag.)
- :ref:`Taldir API <api-taldir>` implemented and deployed with at least SMS and Email validators. (DONE)
- :ref:`Mailbox API <api-mailbox>` implemented and deployed.
-- Wallet functionality to support US-1 implemented.
-- Wallet functionality to support US-2 implemented.
-- Wallet functionality to support US-2 implemented.
+- Wallet functionality to support user stories implemented.
Alternatives
============
