Apply reviewer suggestions

Co-authored-by: Rodney Lorrimar <rodney.lorrimar@iohk.io>

specifications/wallet/spec-light-mode.md

@@ -7,7 +7,7 @@ Status: DRAFT
 # Synopsis
 
 This document specifies a light-mode for `cardano-wallet`.
-This mode aims to make synchronisation to the blockchain faster by using a less trusted source for blockchain data.
+This mode aims to make synchronisation to the blockchain faster by trusting an off-chain source of aggregated blockchain data.
 
 Light wallets often employ this strategy of using a less trusted data source; for example the [Nami][] wallet uses [Blockfrost][] as data source. The purpose of the light-mode of `cardano-wallet` is to make this "trust vs speed" trade-off readily available to downstream software such as [Daedalus][] with *minimal* changes to its downstream API.
 
@@ -24,7 +24,13 @@ In addition, the "trust versus speed" trade-off will be partially obsoleted by [
 
 As the Cardano blockchain grows in size, retrieving and verifying blocks from the consensus network becomes increasingly time consuming. By making a "trust versus speed" trade-off, we can significantly decrease synchronization times.
 
-## Benefits
+## User-visible benefits
+
+* Allow users to operate their wallet without needing to wait for the node to download and validate the entire blockchain.
+* Allow users to run cardano-wallet and Daedalus on systems with significantly less than 8GB of memory and less than 10GB of disk space.
+* Allow users to control where they sit on the trust vs convenience spectrum, depending upon their current circumstances.
+
+## Technical benefits
 
 * *Speed*. With light-mode, we expect synchronisation times of < 1 minute for a wallet with 1'000 transactions. In contrast, synchronisation of an empty wallet currently takes ~ 50 minutes by connecting to a node.
 * *Compatiblity*. Light-mode is intended to preserve the API presented to downstream software such as [Daedalus][], only *minimal* changes are expected.
@@ -40,6 +46,12 @@ However, these limitations are shared by all existing light wallets. In fact, so
 
 # Specification
 
+## Overview
+
+The implementation of light-mode is based on an efficient query `Address -> Transactions` which the blockchain data source provides. This query is useful to wallets that use *sequential address discovery* (Shelley wallets). These wallets work with a sequence of potential addresses `addr_0`, `addr_1`, `addr_2`, …. For each integer `n`, there is a deterministic procedure for generating the corresponding address `addr_n`. The wallet generates the first few addresses in this sequence and uses the above query to retrieve the corresponding transactions. When no transactions are found for `g` ("address gap") many consecutive addresses, the procedure stops — as the wallet never puts addresses with higher indices on the chain. In other words, this iterative loop yields all transactions that belong to the wallet.
+
+This procedure is implemented and demonstrated in the `light-mode-test` prototype.
+
 ## Functionality
 
 ### Command line
@@ -57,8 +69,8 @@ $ cardano-wallet serve --light CRED
 
 When the executable was started in light-mode:
 
-* The endpoints in the hierarchy `/v2/byron-wallets/*` MUST return an error.
-* The endpoints in the hierarchy `/v2/shared-wallets/*` MAY return an error.
+* The endpoints in the hierarchy `/v2/byron-wallets/*` MUST return an error. Because byron wallets use random derivation indices to generate addresses, they are significantly more challenging to make a light wallet for.
+* (MVP: The endpoints in the hierarchy `/v2/shared-wallets/*` MAY return an error.)
 * The `GET /v2/network/information` endpoint MAY not return `sync_progress` as a percentage quantity from [0..100].
 
 ## Internal
@@ -104,8 +116,8 @@ See also the `light-mode-test` prototype!
 
 ### Benchmarks
 
-* Compare restoration times for an empty wallet in node-mode and in light-mode.
-* Number of requests that we make to the data source needs to be monitored / kept in check.
+* Compare restoration times for an empty wallet in node-mode and in light-mode. The existing nightly wallet restoration benchmark can be updated for this purpose.
+* Number of requests that we make to the data source needs to be monitored / kept in check. The number of requests should scale linearly with the number of transactions and the number of addresses belonging to the wallet. If the data source supports aggregated queries, we can make a single request with a larger body.
 
 ### Testing
 
@@ -120,4 +132,12 @@ See also the `light-mode-test` prototype!
 * [Cardano-launcher][] will have to be modified to not launch the `cardano-node` process when the cardano-wallet is launched in light-mode.
 * Provision of the data source is outside the scope of light-mode. We use [Blockfrost][] for demonstration purposes in the MVP.
 
-  [cardano-launcher]: https://github.com/input-output-hk/cardano-launcher
+  [cardano-launcher]: https://github.com/input-output-hk/cardano-launcher
+
+# Design alternatives
+
+## Byron wallets
+
+Byron wallets cannot be supported by the light-mode as described above, as it is based on an efficient query `Address -> Transactions` which Byron wallets cannot take advantage of. For these wallets, alternative designs would have to be explored Possibilities include:
+* A third-party byron *address discovery service* which takes a byron root XPub and sends back a list of addresses belonging to that wallet. However, that involve an additional reduction in trust.
+* Existing Byron wallets can be *partially supported* in light-mode as long as the database of addresses generated/discovered so far is intact, as we can still retrieve the balance and all transactions. However, in light-mode, these wallets cannot be restored and cannot receive funds from newly generated addresses. Conversion to Shelly wallets is recommended.