[Design] Atomic Swap user interface

[tuliomir]

Summary

The atomic swap feature is implemented in the headless in a simple design and, keeping the same in the desktop wallet, could create a poor visual usability to the users.

We propose here a new, simplified visual flow to improve this usability, integrating with a backend for an improved real-time collaboration experience, but with graceful degradation for the current robust solution of a direct string exchange and direct input/output manipulation.

Acceptance Criteria

• The user should be able to request to send tokens just as easily as in the Send Tokens screen.
• The interface should help the user identify what tokens are being sent and received on this wallet at all times, to prevent scam attempts
• There should be an option for the user to edit the inputs directly, for advanced usage
• The Hathor Labs Atomic Swap backend should be used by default

Guide-level explanation

To preserve the existing interface on the Send Tokens screen, the proposal editing screen will follow the pattern of showing inputs and ouputs grouped by tokens, with the main difference being that they will be exhibited read-only. Here is the current interface on the Send Tokens screen:

Here is the new proposed layout:

Adding inputs and outputs will be done using Send and Receive buttons that will be added at the Proposal screen. These operations will use the current PartialTxProposal facade on the wallet-lib, that already has the send and receive operations to build the proposal.

Above the inputs and outputs section, that will have the title Proposal Details, a highlighted Summary section will display the wallet's balance for this proposal, with the total amount of tokens being sent and tokens being received displayed in an easy to read format.

Below is the proposed simplified user flow. Further explanation on the states will be described afterwards.

Edit Proposal states

The initial screen, accessible through the "Atomic Swap" button on the navigation bar, shows every proposal that is being currently listened to.

• All proposal contents are loaded at wallet loading time, to update the wallet's locked balance by atomic swap utxos
• Clicking on any of them navigates the user to its full details
• An option is available for removing any proposal from this list

Once on the Proposal Details screen, the editing will be made through the Send and Receive buttons.

• Clicking Send will open a modal allowing the user to inform how many tokens should be sent and, optionally, to which address.
• Clicking Receive will open a modal allowing the user to inform how many tokens should be received and in which address ( belonging to this wallet ) Only registered tokens will be allowed to be selected on the proposal by the user.

If any change is desired, the user may remove all inputs and outputs from this wallet through the button "Remove all interactions". That way, all the other participants' changes are preserved and the current user may adjust its parts from scratch.

Whenever there is one input from the user's wallet and the proposal is complete ( there is at least one input, the sum of inputs and outputs match ), a new button will be shown to "Sign my Inputs". When the proposal is complete and all of its inputs are signed, a button is shown to "Send Proposal".

At any moment, if an external participant changes the proposal contents, the local changes are discarded and overwritten by the external contents.

By default, only the proposal balance and the action buttons will be displayed to keep the screen uncluttered. A link to "Show Details" will be rendered right below the action buttons, and clicking this link will display the inputs and outputs as shown in the current flow drawings.

Editing Functionalities

Some functionalities were ommited from the flow drawing above, but will be implemented, such as:

1) Alert when changing a proposal that already has signatures Whenever a user tries to make any change to a proposal that already has at least one signature, a modal will open to confirm this decision, since it will affect every other participant that has already signed their part of the proposal.

2) Lock utxos on save only By default, the "Send" and "Receive" operations on the TxProposal class mark the wallet's utos as used. This should be avoided until the proposal changes are saved, or the user might get confused have his utxos locked while experimenting with the proposal possibilities.

Alternatives

The concepts below were discarded since the proposal described above is simpler and efficient for the initial implementation.

Simple and Advanced modes

To achieve this, the screen would be segmented into "Simple" and "Advanced" display modes. In the "Simple" display, the user would only see the information of "Send" and "Receive" tokens.

This information would be a representation built from the user's inputs OR the proposal's inputs and outputs. For example, the screen above could mean:

• The user has manually entered the 2.40 HTR value from the form
• The imported transaction has one input from a utxo that belongs to this wallet, with the value of 2.40 HTR
• The imported transaction has multiple inputs from utxos that belongs to this wallet, with the total summed value of 2.40 HTR

By selecting the Advanced View, the user would then see the full inputs and outputs using the same visual identity as what the Send Tokens screen already has.

In addition to the interface with Send/Receive instead of Inputs/Outputs, the Simple Mode would also omit the proposal communication with the other participants, as by default the wallet would use Hathor Labs's Atomic Swap backend in the "Save and Upload" button. The Advanced mode will include the possibility of the graceful fallback to proposal string exchange.

Other interface possibilities will be discussed in the Alternatives section below.

Simple Mode Flow

Below is the full workflow of this Simple Mode interaction

Advanced Mode Flow

Below is the simplified workflow of the Advanced Mode interaction, built upon the Simple Mode above:

Task Breakdown

Total: 9,8 dev days

Component	Effort
Initial screen: proposals followed list	1.1
Import Existing Proposal screen	0.7
New proposal screen	0.8
Send/Receive modals	1
Edit Atomic Swap screen with modal buttons	3
Manage state changes: open, signing, signed...	1.0
"Remove everything from my wallet" button	0.5
Integrate with lib: sign and send proposal	1.5

[tuliomir]

Reviewers: @r4mmer , @pedroferreira1

[pedroferreira1]

It's still confusing to me the difference between the simple mode and advanced mode. If I understood correctly, only the advanced mode has the full string with the proposal, is that correct?

I thought about having a single screen only, no need to separate between simple/advanced.

The screen at first will always be readonly, with the description of the current proposal with the lists of inputs and outputs in it. If the users wants to edit it, then he can click on the Receive or Send buttons, which would open a modal with the summary of sends/receives already there and fields to add more.

And the main screen would always be readonly, with the description of the current proposal there.

What do you think?

Apart from that, I didn't understand why the 'Import' and 'Create New' are in all screens, is there any reason for that?

[tuliomir]

I drew this new diagram with your suggestions, with the only change being that I moved the summary of sends/receives to the main screen instead of the modals.

I feel this is important to make sure the user is always aware of the final balance of the proposal, since it can change almost invisibly via a websocket update.

Also removed the redundant "Import" and "Create New" buttons.

I think we should still think about how to remove / edit manually some output or input ( for example, allow the user to choose one specific UTXO ) or import/export the exchange string, so I didn't add this directly to the design above, so that we discuss this better.

[pedroferreira1]

Hi, I have some questions regarding the flow:

1. Why do we have this + button besides the outputs and inputs? And also why do we have this token select?

2. This is not possible, you can sign the inputs only when the transaction is completed and won't be changed anymore.

[tuliomir]

Hi @pedroferreira1 ,

the flow image was improved and now has a more consistent design. The signing criteria was also fixed.

[r4mmer]

LGTM

[pedroferreira1]

In general the UI/UX is approved for me, there are just some small improvements that I feel are important.

1. In the inputs list, I think adding the value for each input seems important, so the user can understand why there are many (or one) input only.
2. In the inputs and outputs list I feel we should mark the ones belonging to the user's wallet.
3. In the outputs list I think we should mark the change outputs (I think we have this information in the PartialTx object).
4. In the modal where we create a "Send", we should allow the user to choose an input. If the input value is smaller than the amount he wants to send, the user must select more inputs. If it's bigger, we create a change output for him.

Besides that, regarding utxo locks, there are some important things to be considered when implementing the UX (but they don't change the UI). For instance, if the user reloads the wallet, the utxo marked as spent is not marked anymore, so every time the user opens his wallet, we must go through all the open atomic swaps and mark his open utxos as spent, so we don't select them again.

Maybe we should also mark in the balance if the user has balance "locked" in open atomic swap proposals.

[tuliomir]

Hi Pedro,

1. Added the value on the inputs as well. What do you think of this exhibition on the image below?

2. They are already marked as related to this wallet by the color and the "remove" button on the rightmost column. Do you think they need another indication?

3. Also added an icon for indicating change output, see the image below. All new icons have explanatory texts on hover as well.

4. I think this would clutter the interface. This current implementation of the atomic swap is focused on simple interactions, and choosing inputs manually is already a kind of advanced feature on the existing "Send Tokens", as it requires clicking an additional checkbox. What do you think of keeping this feature for a next design, already having feedback from the implementation of this one? That would be my suggestion.

On that note, I also talked with @trondbjoroy and further simplified the "Edit Swap" screen by hiding all inputs and outputs by default. To show them, the user would click a link, like so:

5. About utxo locks, I agree this locked balance check can be made at wallet loading time: updated the design to reflect this. I'm just not finding a reasonable way to display what amount of the locked balance is specifically tied to atomic swaps.

[pedroferreira1]

Added the value on the inputs as well. What do you think of this exhibition on the image below?

I like it.

They are already marked as related to this wallet by the color and the "remove" button on the rightmost column. Do you think they need another indication?

From our meeting to discuss the UI I thought we wouldn't allow the user to remove inputs/outputs manually, he would need to empty his part of the swap and fill everything again. Otherwise would be confusing removing an input and forgetting to remove a change output that was added because the utxo used was big.

If we decide to have only a full empty action, then we need to mark somehow the inputs/outputs as belonging to the wallet.

Also added an icon for indicating change output, see the image below. All new icons have explanatory texts on hover as well.

Personally I don't like the icon. I think I prefer having a column marking the ones that are change outputs of your wallet.

I think this would clutter the interface. This current implementation of the atomic swap is focused on simple interactions, and choosing inputs manually is already a kind of advanced feature on the existing "Send Tokens", as it requires clicking an additional checkbox. What do you think of keeping this feature for a next design, already having feedback from the implementation of this one? That would be my suggestion.

Why would this clutter the interface? If we use the same approach as in the Send Tokens screen it would be hidden. We have this feature in the headless wallet, I feel it's good for the user to be able to select the inputs he wants to use.

[tuliomir]

The following changes were made on the Input/Output visualization:

• Added the "Change output" column on the outputs

• Changed the "Remove" button column on both to a "Is mine" column

• Moved the "Remove input/output" funcionality to a "Remove all interactions" button

• Added a "Choose inputs automatically" checkbox, similar to the existing one on the "Send Tokens" screen

[pedroferreira1]

For me this is approved, there are some small thing I feel could be improved but they are really small.

1. I don't think I like the button name "Remove all interactions". Maybe "Remove all my inputs and outputs"
2. In the send modal, I feel the optional field (change address) should be the last, I prefer having the required fields first and then the optional one.

[tuliomir]

Updated the flow image with these changes :+1: