anoma#82 Moved specs namada-interface repo (anoma#83)

* moved specs to namada-interface repo
* formatting and renaming specs index page
* updated link in the main README

README.md

@@ -4,6 +4,8 @@
     <img style="width: 300px;" src="banner-image.png" />
 </div>
 
+There is a seperate more details specifications documentation under [/specs](https://github.com/anoma/namada-interface/blob/main/specs)
+
 <h2> Run namada-interface </h2>
 
 ```bash
@@ -25,7 +27,7 @@ yarn start
 for solving possible issue see [Troubleshooting](#troubleshooting)
 
 - [Introduction](#introduction)
-- [anoma-lib](#anoma-lib)
+  - [Usage](#usage)
   - [Project Structure](#project-structure)
     - [Utils / Theme](#utils--theme)
       - [Colors](#colors)

specs/README.md

@@ -0,0 +1,7 @@
+[Browser Extension](/specs/browser-extension/)
+
+[Web Wallet](/specs/web-wallet)
+
+[UI](/specs/web-wallet.md)
+
+[Explorer](/specs/explorer.md) (WIP)

specs/browser-extension/api.md

@@ -0,0 +1,59 @@
+# Browser Extension - API
+
+## Requirements
+
+- User should be able to approve or reject connection from `namada-interface` or any other web client
+- User should be able to load accounts from extension into `namada-interface` or to any web client
+
+## API Methods
+
+The extension should provide an API to any client, that should roughly approximate the following:
+
+- `enable(chainId: string): Promise<void>`
+- `getSigner(chainId: string): Signer`
+- `addChain(chainConfig: ChainConfig): Promise<boolean>` - **NOTE** In Keplr, this is called `Keplr.experimentalSuggestChain()`
+- `<Signer>signer.accounts(): Account[]`
+- `<Signer>signer.sign(account: Account, tx: Transaction): Promise<Transaction>`
+
+API functionality should be implemented within the background scripts of the extension, making it available when the extension is not visible.
+
+Our `background` scripts should provide a class instance with these methods exposed via `window.Anoma`, following an interface such as the following (for a basic use-case):
+
+```ts
+// NOTE: Interfacing with wasm, we use Uint8Array instead of string. This may make
+// for a cleaner interface to our existing transaction code, but we may opt for using
+// string instead in the extension:
+type Transaction {
+  hash: Uint8Array;
+  tx: Uint8Array;
+}
+
+type Account {
+  alias: string;
+  address: string;
+  publicKey: Uint8Array;
+}
+
+interface Signer {
+  private readonly _privateKey: Uint8Array;
+  public get accounts(): Account[];
+  public sign(account: Account; tx: Transaction): Promise<Transaction>;
+}
+
+type ChainConfig {
+  chainId: string;
+  rpc: string;
+  // etc.
+}
+
+interface Anoma {
+  public enable(chainId: string): Promise<void>;
+  public getSigner(chainId: string): Signer;
+  public addChain(chainConfig: ChainConfig): Promise<boolean>;
+  public get chains(): string[];
+}
+```
+
+## References
+
+- See `keplr-wallet` - We want to be able to query accounts/signers in a similar manner to this (hopefully with a slightly more elegant API of our choosing) <https://github.com/chainapsis/keplr-extension>

specs/browser-extension/architecture.md

@@ -0,0 +1,74 @@
+# Browser Extension - Architecture
+
+The architecture of the extension and extension API somewhat resembles that of `@keplr-wallet/extension` in that it provides the following:
+
+- A web client can connect to an API and issue commands
+- The API calls are proxied to background services that handle storage
+- The background services can handle authentication
+- The background services can message the content scripts, which can push messages back to the client
+
+There are a few key differences in functionality however. Our extension will only handle the creation of a seed and derived keypairs, as well as signing transactions.
+It will not be responsible for allowing the user to send transfer transactions, but should be responsible for submitting account initialization transactions. The
+web client will be able to request accounts from the extension, query balances on those extensions, and submit transactions (transparent, MASP, IBC, Ethereum Bridge), and will also
+house any integrations with other wallets.
+
+## Architecture
+
+A high-level overview of this architecture should resemble the following:
+
+```
+--------------
+| Web Client | - namada-interface
+--------------
+      ^
+      |
+----------------
+| Injected API |
+----------------
+      ^
+      |
+  ---------   ----------------
+  | PROXY |-->| API Instance | (content-scripts)
+  ---------   ----------------
+                      |
+              ------------------     -----------------------
+              | Service Worker |---->| Storage (IndexedDB) |
+              ------------------     -----------------------
+              (background-scripts)   (Key-value store)
+                      |
+               ---------------
+               | WebAssembly |
+               ---------------
+               (namada types, other crypto functions)
+```
+
+The proxy is necessary to forward data via messages (using `window.postMessage`) to execute functions within the extension, as well as return message data to the client.
+
+Essentially, any wasm- or storage-related functionality will be handled by the Service Worker (or background script in Firefox). This background process has access to IndexedDB,
+and is configured in the manifest versions 2 and 3 to execute wasm code.
+
+## Authentication
+
+In `@keplr-wallet/extension`, authentication is handled by retrieving an encrypted mnemonic phrase and attempting to decrypt it, which if successful, will set the provided
+password in the state of the background-scripts class instance for some duration. This is how authenication works on `namada-interface`, with the caveat that being a client-side-only
+application, that state is lost as soon as the user refreshed the page, as the password is not persisted outside of the app state. As authentication will now occur within the extension,
+state can be maintained in the background services, and the interface will only need to query the extension to retrieve the authenticated state.
+
+The flow may resemble the following:
+
+1. The interface accepts a password and posts a message to authenticate via the proxy
+2. The proxy fetches the decrypted mnemonic from storage and attempts to decrypt it
+3. If successful, the users credentials are proxied back to the extension for persisting their session
+
+## Manifest considerations
+
+Currently, Firefox does not support `manifest_version: 3`, but Chrome no longer accepts `manifest_version: 2` into their extension store. It is best that we follow what the `metamask-extension`
+is doing by supporting multiple both versions. `@keplr-wallet/extension` is currently using only version 2 in all browsers, but as we will be a new submission, we need to support version 3.
+
+This has some implications for how the `background-scripts` are designed:
+
+- As `manifest_version: 3` installs the `background-scripts` as a Service Worker, we no longer have any access to `window`. As such, we will need to code this with that in mind, which means
+  we can't make any usage of the `window` API within both v2 and v3 manifests
+- We should still be able to make use of the WebExtensions API via `browser` using `webextension-polyfill.js` within the service worker
+- Any use of the `window` API will need to be handled either in the content scripts (where it is limited to the DOM, and does not contain other globals), or in the injected scripts (web client context)
+- Sharing any state between the content scripts and the service worker requires use of the storage api (i.e., `browser.storage.local`)

specs/browser-extension/interface.md

@@ -0,0 +1,16 @@
+# Browser Extension - Interface
+
+The interface for the browser extension should follow a similar stack to what we presently utilize in `namada-interface`. This will make it possible
+to reuse similar components and development processes as we currently employ.
+
+The stack should resemble the following:
+
+- TypeScript
+- React
+- Redux-Toolkit (`@reduxjs/toolkit`)
+- Styled-Components
+
+While this stack is generally consistent, we should perhaps move away from `create-react-app`, as this imits the control we
+have on the build pipeline (making it more difficult to customize). We should consider using Parcel and
+[@parcel/config-web-extension](https://parceljs.org/recipes/web-extension/) as an improvement in development process,
+or a custom build pipline with Webpack, versus using `create-react-app`.

specs/browser-extension/key-management.md

@@ -0,0 +1,15 @@
+# Browser Extension - Key Management
+
+We need to move all key-management into an extension, from which we can query from clients such as `namada.me`.
+
+## Requirements
+
+- User should be able to generate a mnemonic
+- User should be prompted to set a password for this seed
+- User should be able to generate keys for any supported chain
+- User should be able to input a derivation path to derive a new account
+- User should be able to sign transactions in `namada-interface` using keys stored in extension
+
+## References
+
+- See `polkadot{js} extension` - This is the experience we wish to replicate <https://github.com/polkadot-js>

specs/browser-extension/security.md

@@ -0,0 +1,29 @@
+# Browser Extension - Security
+
+The different components of this browser extension need to be able to communicate with each other, and as such make use of the `window.postMessage` and
+the `browser.runtime.onMessage` APIs to exchange messages between the web client, content and background scripts.
+
+The process roughly looks like this:
+
+1. Web client can utilize `postMessage` (via an injected script from the extension) to send a message to an instantiated proxy
+2. The content script can listen for these messages from the proxy and route them to the background script
+3. The background script can handle these messages and routes responses to the content script
+4. Finally, the content script can relay this message via `postMessage` to the injected script on the web client
+
+## Origin validation
+
+When the `postMessage` API is being used, we check that the origin matches. This validation is necessary to avoid cross-domain messages from occuring.
+
+In addition, we also implement [https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#connection-based_messaging](connection-based messaging)
+when communicating between the web client and the content scripts. This requires that we establish a "port" over which we post messages.
+
+## Routing
+
+When the extension is installed, the content and background scripts establish a shared state variable, `anomaExtensionRouterId`, stored in the extension's `localStorage`, which allows
+us to validate messages between the two before performing any actions in the background scripts.
+
+## Resources
+
+- [https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#connection-based_messaging](Connection-Based Messaging)
+- [https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime](WebExtensions API - browser runtime)
+- [https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage](postMessage API)

specs/browser-extension/session.md

@@ -0,0 +1,27 @@
+# Browser Extension - Session Management
+
+As the user's keys will be managed within the browser extension, the way `namada-interface` will handle session management will fundamentally change.
+
+Presently, in `namada-interface`, a user's data (mnemonic, derived keys, persisted state) is encrypted and stored in the browser via `localStorage` API. Authentication is
+performed by attempting to decrypt the user's seed with a given password. As there is no server-side component to the application, or any authentication authority
+to provide a session token for maintaining a login session state, as soon as the user's password becomes undefined, the user is no longer logged in.
+
+With the browser extension in place, the user's session can be persisted outside of `namada-interface` and within the background processing of the extension. We should consider the following:
+
+- Once a user has authenticated and approved a connection to the extension, accounts will be availabe to the interface
+- We can set a session timeout variable (a fixed timeout), or make this timeout relative to inactivity, after which we encrypt the stored keys
+- From `namada-interface`, all authentication will simply depend on it's connection to a key store in the extension, and will maintain no login state of its own.
+  Authentication simply means the user has decrypted their extension data and connected the interface to it.
+
+## References
+
+### keplr-wallet session management
+
+In the following block, we can see how `keplr-wallet` authenticates a user. As the stored keyring is encrypted, the
+extension will attempt to decrypt the values in storage and load the values into the application's context, thus
+establishing a session for the user.
+
+- Unlock the keyring:
+  <https://github.com/chainapsis/keplr-wallet/blob/master/packages/background/src/keyring/keyring.ts#L345-L377>
+
+See `keyring.ts` at <https://github.com/chainapsis/keplr-wallet/blob/master/packages/background/src/keyring/keyring.ts>

specs/browser-extension/storage.md

@@ -0,0 +1,17 @@
+# Browser Extension - Storage
+
+## Requirements
+
+- The user's generated mnemonic should be stored in the browser from the extension (encrypted with the password provided during Account Creation)
+- Any derived keys will also need to be stored and encrypted in a similar fashion
+
+## References
+
+- See `keplr-wallet/packages/store` for Key/Value store Promised-based store (IndexedDB) - This can be reused to actually store the data
+
+### keplr-wallet key storage implementation
+
+- `CreatePrivateKeyStore`
+  <https://github.com/chainapsis/keplr-wallet/blob/a3aedc2b2769227cbc7e5da0e649101ad3edd721/packages/background/src/keyring/keyring.ts#L1088-L1103>
+
+See `keyring.ts` at <https://github.com/chainapsis/keplr-wallet/blob/master/packages/background/src/keyring/keyring.ts>

specs/explorer.md

@@ -0,0 +1,9 @@
+# Web explorer interface
+
+* Block explorer
+  * Display PoS state
+  * Display governance state
+  * Display transparent transfers
+  * Display transfers in and out of the MASP
+  * Display total values for the MASP
+  * Allows tx hashes of shielded transfers to be looked up for confirmation