First pass at wallet design doc

doc/wallet/design.md

@@ -0,0 +1,79 @@
+
+Mode of Interactions
+====================
+
+There's a variety of ways wallet software can be integrated with, from hardware
+to automated bots to the more classic desktop wallets. No single implementation
+can hope to accomodate all possible interactions, especially if it wants to
+remain user friendly (who or whatever the user may be). With that in mind, Grin
+needs to provide a healthy base for a more complete wallet ecosystem to
+develop.
+
+We propose to achieve this by implementing, as part of the "standard" wallet:
+
+* A good set of APIs that are flexible enough for most cases.
+* One or two default main mode of interaction.
+
+While not being exhaustive, the different ways we can imagine wallet software
+working with Grin are the following:
+
+1. A receive-only online wallet server. This should have some well-known network
+address that can be reached by a client. There should be a spending key kept
+offline.
+2. A fully offline interaction. The sender uses her wallet to dump a file that's
+sent to the receiver in any practical way. The receiver builds upon that file,
+sending it back to the sender. The sender finalizes the transaction and sends it
+to a Grin node.
+3. Hardware wallet. Similar to offline but the hardware wallet interacts with
+a computer to produce required public keys and signatures.
+4. Web wallet. A 3rd party runs the required software behind the scenes and
+handles some of the key generation. This could be done in a custodial,
+non-custodial and multisig fashion.
+5. Fully programmatic. Similar to the online server, but both for receiving and
+sending, most likely by an automated bot of some sorts.
+
+As part of the Grin project, we will only consider the first 2 modes of
+interaction. We hope that other projects and businesses will tackle other modes
+and perhaps even create new ones we haven't considered.
+
+Design Considerations
+=====================
+
+Lower-level APIs
+----------------
+
+Rust can easily be [reused by other languages](https://doc.rust-lang.org/1.2.0/book/rust-inside-other-languages.html)
+like Ruby, Python or node.js, using standard FFI libraries. By providing APIs
+to build and manipulate commitments, related bulletproofs and aggregate
+signatures we can kill many birds with one stone:
+
+* Make the job of wallet implementers easier. The underlying cryptographic
+concepts can be quite complex.
+* Make wallet implementations more secure. As we provide a higher level API,
+there is less risk in misusing lower-level constructs.
+* Provide some standardization in the way aggregations are done. There are
+sometimes multiple ways to build a commitment or aggregate signatures or proofs
+in a multiparty output.
+* Provide more eyeballs and more security to the standard library. We need to
+have the wallet APIs thoroughly reviewed regardless.
+
+Receive-only Online Wallet
+--------------------------
+
+To be receive only we need an aggregation between a "hot" receiving key and an
+offline spending key. To receive, only the receiving key should be required, to
+spend both keys are needed.
+
+This can work by forming a multi-party output (multisig) where only the public
+part of the spending key is known to the receiving server. Practically a master
+public key that can be derived similarly to Hierarchical Deterministic wallets
+would provide the best security and privacy.
+
+TODO figure out what's needed for the bulletproof. Maybe pre-compute multiple
+of them for ranges of receiving amounts (i.e. 1-10 grins, 10-100 grins, etc).
+
+Offline Wallet
+--------------
+
+This is likely the simplest to implement, with each interaction dumping its
+intermediate values to a file and building off each other.