Add wallets/SPEC.md

Author: ekzyis

wallets/SPEC.md

@@ -0,0 +1,132 @@
+# Wallet Specification
+
+## UI/UX Requirements
+
+### The First Time
+
+The first time a user clicks on 'wallets' — first time means there was the orange indicator because they never attached any wallet —, a button is shown to start a **wizard**. The wizard can be skipped at any time in which case they will be redirected to "_Not the First Time_."
+
+_* maybe no button and immediately show wizard? *_
+
+The wizard starts with a page where the user is asked to attach a receiving wallet (or skip).
+
+#### 1. Attach receive (or skip)
+
+The page shows a **table of wallets** that can receive. The table has following columns:
+
+- name
+- image
+- button to attach receive (**column is highlighted on this page**)
+- button to attach send (**column is muted on this page**)
+- popularity (how many stackers use this wallet to receive?)
+- self-custodial
+- KYC
+- Platform (iOS, Android, Windows, Linux, MacOS, Umbrel, Start9, Web)
+
+Boolean columns can have a checkbox as a filter.
+
+_* we might want to highlight some wallets based on popularity: "most stackers use this wallet to receive" *_
+
+_* there might not be enough space on mobile for all columns / we need to find ways to save space, like via icons *_
+
+_* 'attach send' button might need to be disabled on this page to not mess with flow? *_
+
+The page also has a **search bar**. Users can enter wallet names and this will filter the name column. The search bar will try to **autocomplete wallets via dropdown** as the user types to prevent typos.
+
+Wallet examples:
+
+- CashApp
+- Strike
+- Wallet of Satoshi
+- Phoenix
+- Zeus
+- Alby Hub
+- Coinos
+- LND
+- Core Lightning
+- LNbits
+- Electrum
+- Cashu.me
+- Minibits
+- ...
+
+On selection, a wallet can have its own wizard that will guide the user through the process of attaching the wallet for receiving.
+
+If a wallet has no wizard, the user will only be shown input fields.
+
+Once a receiving wallet passed all tests (validation + network tests) and was successfully saved on the server or the step is skipped, the user is redirected to the next step:
+
+#### 2. Attach send (or skip)
+
+If the user attached a wallet during the previous step and it supports sending, we can ask them here if they want to continue configuring it for sending.
+
+Else — like in the previous step — this step shows a table of wallets that can send and a search bar. The only difference is that we highlight the column to attach send.
+
+Clicking on a wallet will start a wizard if available else the user will only be shown input fields.
+
+Once a sending wallet passed all tests (validation + network tests) and was successfully saved locally or the step is skipped, the user is redirected to the next step:
+
+#### 2.1 Wallet encryption
+
+This step only shows up if a sending wallet was attached.
+
+The step informs the user that the sending wallet is only stored on the device so they will not be able to use it on another device.
+
+If they want to use it on another device, they need to (a) write down the following 12 words and enter them into the other device or (b) manually configure the sending wallet on the other device again.
+
+If they choose (a), we will migrate the local wallet that was saved in the previous step to the server.
+
+After this step, the user is redirected to the next step:
+
+#### 3. Global wallet settings
+
+- configure dust limit
+- configure max fee for withdrawals (% and absolute amount, whatever is higher)
+- configure proxy for lightning address or not
+
+#### 3. Wallet badges
+
+Let them know that they now have a horse or gun so they know what it means when they see it next to the nym of other users.
+
+Also let them know that they now have a Stacker News lightning address.
+
+_* let users decide if they (additionally) want to show off which wallet they are using?? *_
+
+#### Other considerations
+
+- users can leave wizard at any point in time
+- when they click on 'wallets' again, we will show them an option to continue where they left off or start new wizard
+- show wizard progress bar
+- when a wallet is attached, you can create another wallet of the same type via context menu
+
+_* starting a new wizard: what to do with any existing data on device or server? *_
+
+_* separate forms to save receive and send: (how to) share common fields like URL for LNbits? *_
+
+### Not the First Time
+
+Show table of wallets with buttons to attach send or receive + search bar.
+
+If wallet encryption was enabled, we can show them which send wallets they have on the server but can't decrypt currently (lock symbol).
+
+If wallet encryption was not enabled, give them the option to enable it.
+
+## Technical Requirements
+
+- we can fetch all wallets at once on page load
+- if wallet encryption is enabled, we sync wallet updates and deletes between devices ASAP
+  - don't poll for wallets but poll for wallet updates via timestamp column for last update of wallets
+  - reload wallets on change
+- users can only save individual wallets, and only save or receive, not both at the same time
+
+### implementation details
+
+- replace generic, "obfuscated" code for mutations, typedefs etc. with code generated during build time
+  - easy to read and reason about
+  - DX needs to be considered
+- abstract away that send wallets can be stored locally or on server via custom GraphQL scalar serialization and local fields
+  - we can use `useQuery` to fetch wallets as if everything about wallets is always stored on the server
+  - we can use `useMutation` to store wallets as if everything about wallets is always stored on the server
+    - encryption of send wallets must be handled in GraphQL layer somehow
+    - was thinking about serialization of custom [scalars](https://graphql.org/learn/schema/#scalar-types) ... but they run on the server, not on the client
+    - make sure this ACTUALLY works 100% and would NEVER send unencrypted values to the server