Merge pull request #3923 from AlphaWallet/add-organize-docs

Add docs and some re-organization of docs

CONTRIBUTING.md

@@ -37,9 +37,3 @@ Avoid using `switch-default`
 Others
 ---
 Hide changes behind a flag in `Features.swift` if the change isn't ready yet but should be merged first. For example, maybe it needs more testing, but would be benefit to merge earlier to avoid merge conflicts.
-
-How to Add a New Chain
----
-1. Open RPCServers.swift
-2. Add a new case to the enum
-3. Build and fix the errors. Do not use `switch-default:`

README.md

@@ -66,6 +66,8 @@ If you get a "Bundle does not exist. Please install bundle." error, please consu
 
 This makefile has been tested to run on "Monterey"-12.0.1. It will not work on "Catalina" or "Big Sur".
 
+Read [INTRODUCTION-CODE.md](docs/INTRODUCTION-CODE.md).
+
 ### Updating GemFile or Podfile
 
 After the Gemfile is updated, run `make install_gems` to update the gems in the vendor/bundle directory.

UPDATE.md

@@ -1,8 +0,0 @@
-Normally this file should be about update history but since this is an iPhone app, we took the convenience to keep the update procedure to AppStore here.
-
-- Ensure the build is incremented by bundle and build number
-- Backward test against previous builds to ensure that it doesn't break previous versions
-- Ensure travis CI is passing
-- Run through all the major functions - Redeem, transfer, sell, backup and restore key
-- Ensure contract for any placeholder event is correct and working with Payment Server
-- Update the app store description and keywords in each localised langauge.

docs/INTRODUCTION-CODE.md

@@ -0,0 +1,60 @@
+Refer to [High Level Blocks](high-level-blocks.md)
+
+Flow coordinators
+===
+The app uses [Flow coordinators](https://khanlou.com/2015/10/coordinators-redux/) to avoid coupling between view controllers.
+
+One unfortunate thing with the codebase is that a lot of the logic ends up being in the coordinators. Those should and can be moved into separate logic types.
+
+Almost every view controller has an auxiliary protocol defined in the same file, at the top of the file. Never open another view controller from each view controller. Go through the protocol which will be implemented by a coordinator.
+
+User interface & Storyboard
+===
+The app UI is built entirely in code. No storyboard/nib/xib is used.
+
+Notable Types
+===
+* `AppDelegate` and `AppCoordinator` is where the app starts
+* `InCoordinator` is where the bulk of the app branches from
+* `MigrationInitializer` stores Realm migration code
+* `MigrationInitializerForOneChainPerDatabase` should never be modified
+* `Constants`
+* `Config`
+* `Features` holds flags to toggle features. This is usually meant to be for WIP features that would be good to merge (big changes, or we want to test them) yet not ready yet
+* Always use `R` to access strings, image files, colors and other files bundled with the app. eg. `R.string.localizable.addrpcServerNavigationTitle()`. This avoids runtime errors and crashes
+* `Constants.Credentials` is where API keys are stored. Replace them when making production builds
+* Use the logging functions to generate logs to help development. Beware of performance and too much noise
+    * `debugLog()`
+    * `infoLog()`
+    * `warnLog()`
+    * `verboseLog()`
+    * `errorLog()`
+
+TestFlight
+===
+1. Update the build number and if necessary the version number. Commit this
+2. Make sure `Constants.Credentials` is updated. Do not commit these changes unless you are sure your repo is private
+3. Archive the `AlphaWallet` target for `Any iOS Device (arm64)`
+4. Submit
+
+Submission to the app store
+===
+Submit the appropriate TestFlight build or repeat the process and submit the new build
+
+Tips
+===
+Some specific tasks:
+
+Tip: Figure out where to change
+---
+An easy way to figure out which part of the code makes a change is to look for text in the UI like the title of the current screen or a button. Look for it in `R.generated.swift` (this file is automatically generated and updated based on the localization strings files while building the project). Look for the function returning the string you want and then find callers for that function.
+
+Tip: Navigating the code base
+---
+Look for implementors and callers of protocols is a very important part of working with the code base. As of writing, AppCode provides better code navigation functionality than Xcode.
+
+Tip: Add support for a new chain
+---
+1. Open `RPCServer`
+2. Add a new case to the enum
+3. Build and fix the errors. Do not use `switch-default:`

docs/code.md

@@ -1,39 +0,0 @@
-### Localization
-
-Format for localization keys:
-`feature.section.element.type`, or could be simply as `feature.section.type`
-
-Examples:
-```
-key: transactions.myAddress.button.title, 
-value: My Address
-comment: The title of the my address button on the transactions page
-
-key: deposit.buy.button.coinbase.title, 
-value: via Coinbase
-comment: The title of the deposit button in the alert sheet
-
-key: exchange.error.failedToGetRates
-value: Failed to get rates
-comment: Error messesage when failed to update rates on pairs of tokens
-
-
-
-key: welcome.privateAndSecure.label.title
-value: Private & Secure
-comment: 
-
-key: welcome.privateAndSecure.label.description
-value: Private keys never leave your device.
-comment:
-
-```
-
-Generic keys and values:
-```
-Ok - Ok
-Cancel - Cancel
-Done - Done
-Send - Send
-Refresh - Refresh
-```

docs/high-level-blocks.md

@@ -0,0 +1,42 @@
+# High level about AlphaWallet apps
+
+This is intentionally kept not specific to iOS and Android, but for both AlphaWallet apps
+
+# Keys and addresses
+
+- Supports multiple seeds and "raw" private keys
+    - A limitation is only the 0th address of each seed is available in the app
+    - The address generated from each seed is always the 0th Ethereum mainnet address (i.e. we always use the coin type = Ethereum mainnet (60), e.g the user can't access the 0th Ropsten address). See [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki#Coin_type)
+- Supports multiple-chains concurrently. App bundles about 30 chains and users can add more manually
+
+## WalletConnect v1
+
+A "proxy" server-client protocol that in theory allows dapps that support it to be used with any wallet by initiating a connection through scanning a QR code. Eg [https://example.walletconnect.org](https://example.walletconnect.org/)
+
+## WalletConnect v2
+
+Coming soon. There is onging work on iOS to implement their beta SDK.
+
+## Accessing nodes and data
+
+Infura and a few similar providers to make calls and post transactions against nodes
+
+Etherscan and a few similar providers to query data derived from nodes or aggregated from it. eg. transaction history
+
+We also use OpenSea API to access NFT data. This is richer than Etherscan's for NFTs.
+
+## Dapp Browser
+
+This is a native webview with the web3.js provider JavaScript injected so dapps can access the user wallets. The JavaScript provider code delegates calls by the dapp to the app native code to perform actions like returning the wallet address, signing a transaction, etc
+
+## TokenScript
+
+There is some support for TokenScript. Basically a way to read an XML file which describes the actions a token offers and how it can be presented. This is currently available in a limited form in the apps.
+
+## ENS
+
+[Ethereum Name Service](https://ens.domains) has a similar goal as DNS. The most basic functionality provided by ENS is mapping from a readable name to an address and the reverse mapping. eg. vitalik.eth ↔ 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045.
+
+## EIPs
+
+[Ethereum Improvement Proposals](https://eips.ethereum.org) and the [Github repo](https://github.com/ethereum/EIPs/) describes many standards that are implemented by the wallet. Eg. [EIP55](https://eips.ethereum.org/EIPS/eip-55) describes an algorithm to compute the uppercase and lowercase combinations for an Ethereum address such that it acts like a checksum.