Merge branch 'master' of https://gitlab.com/grassrootseconomics/cic-docs into lash/review-selfservice-token

README.md

@@ -3,11 +3,13 @@ Community Inclusion Currency (CIC) technology seeks to give organizations and co
  + [White Paper](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/CIC-White-Paper.pdf)
  + [Training Materials](https://docs.google.com/document/d/1CI-Xz9R3FgZ70uWgq81U5uwfaYrm9f6Ji4f7dL2-V90/edit?usp=sharing) 
  + [Frequently Asked Questions](https://docs.google.com/document/d/1qtlOEL4pqW1vOL893BaXH9OqRSAO3k0q2eWbVIkxEvU/edit?usp=sharing) 
- + [Blog](https://grassecon.org/blog)
+ + [Blog](https://www.grassrootseconomics.org/blog)
- + [MOOC](https://grassecon.org/mooc) - Very old (paper based systems)
+ + [MOOC](https://www.grassrootseconomics.org/mooc) - Very old (paper based systems)
  + [Village Market Simulator series](https://www.youtube.com/playlist?list=PLPUExzwZAUpbEInJy_8Wj_c_mDsw7-qXe)
  + [Transaction Data CSVs](https://www.grassrootseconomics.org/research): Transaction Datasets and Research
  + [Live Data Dashboard](https://dashboard.sarafu.network)
+ + [Animated Explainer Video](https://www.youtube.com/watch?v=vJL9-FFleow)
+ 
  
  ## Open source code
  + [Managment Platform](https://gitlab.com/grassrootseconomics/cic-platform)

TransactionDatasets.md

@@ -1,5 +1,6 @@
 # TransactionDatasets
-Data Sets from Blockchain Transactions and User Demographics
+Data Sets from Blockchain Transactions and User Demographics found at 
+[grassecon.org/research](http://grassecon.org/research) in csv format and also shown on [dashboard.sarafu.network](https://dashboard.sarafu.network)
 
 Datasets prior to 2020 are pulled from the POA blockchain for each user ex. https://blockscout.com/poa/core/address/0xcb55fc893000a984a5ad73011f93d1540a5f0895/tokens
 As well as user generated data and field surveys collected in Kenya. Fields described below.
@@ -7,29 +8,23 @@ As well as user generated data and field surveys collected in Kenya. Fields desc
 Datasets Starting 2020 are pulled from the POA (xDAI) blockchain for each user ex. https://blockscout.com/poa/core/address/0xcb55fc893000a984a5ad73011f93d1540a5f0895/tokens
 As well as user generated data and field surveys collected in Kenya. Fields described below.
 
-Brief description: Using a simple feature phone interface with USSD each user (people living below the poverty line in Kenya) starts with 400 Tokens and adverstises what they sell on a digital market place avalaible on the same interface. There are no transaction fees. The tokens are used often as a top-up to missing Kenyan shillings. Certian users / vendors were allowed to send 50% of their tokens to Grassroots Economics (GE) in return for Kenyan Shillings on a monthly basis. Each user only has one token assigned to them by GE based on where they live (Currently we have moved all users to the Sarafu token while we prepare for the next phase). When a user sends a token to another user that holds a different token a conversion is made automatically after receipt. This conversion uses a bonding curve (based on the Bancor Protocol) to adjust the token prices relative to eachother. Conversions can be seen as transactions to a contract address then that contract address sending the new token to the user. While the exchange rate information is avaliable to users, practially all the tokens are curently considered ~1:1 with the national currency as well as with eachother. For more information please contact us https://www.grassrootseconomics.org/contact
+Brief description: Using a simple feature phone interface with USSD each user (people living below the poverty line in Kenya) starts with 400 Tokens and adverstises what they sell on a digital market place avalaible on the same interface. There are no transaction fees. The tokens are used often as a top-up to missing Kenyan shillings. Certian users / vendors were allowed to send 50% of their tokens to Grassroots Economics (GE) in return for Kenyan Shillings on a monthly basis (see Agent transactions). Each user only has one token assigned to them by GE based on where they live (Currently we have moved all users to the Sarafu token while we prepare for the next phase). When a user sends a token to another user that holds a different token a conversion is made automatically after receipt. This conversion uses a bonding curve (based on the Bancor Protocol) to adjust the token prices relative to eachother. Conversions can be seen as transactions to a contract address then that contract address sending the new token to the user. While the exchange rate information is avaliable to users, practially all the tokens are curently considered ~1:1 with the national currency as well as with eachother. For more information please contact us https://www.grassrootseconomics.org/contact
 
 
 --------
 
-Post 2020 xDAI
+Post 2020 xDAI data (current)
 The Transaction csv fields:
 
 1. id - internal transaction ID number
 1. timeset - date and time of transaction
-1. transfer_subtype - internal typing: DISBURSMENT = from Grassroots Economics, RECLEMATION = Back to GE, STANDARD =  a trade between users, AGENT = when a group account is cashing out (see held_roles) below
+1. transfer_subtype - internal typing: DISBURSMENT = from Grassroots Economics, RECLAMATION = Back to GE, STANDARD =  a trade between users, AGENT = when a group account is cashing out (see held_roles) below
 1. transfer_use - The category the sender marked the transaction as - used for 'confidence' later for the user category - note this will be changed to boolean
-1. tx_hash - hashed transaction address on blockchain 
+1. tx_hash - hashed transaction address on blockchain (not currently shown)
 1. source - wallet ID of sender 
 1. s_comm_tkn - Short name of Token that the source uses (each user should only have 1 token) - note that currently all users have Sarafu only
-1. s_gender - From user input
-1. s_location - Village name, From user input
-1. s_business_type - Entered by GE staff based on user inputed products or services
 1. target - wallet ID of recipent 
 1. t_comm_tkn
-1. t_gender
-1. t_location
-1. t_business_type
 1. token_name - the token that was traded
 1. token_address - the blockchain address of token that was traded
 1. weight - How many tokens were traded
@@ -41,9 +36,11 @@ The user summary csv fields:
 1. old_POA__blockchain_address - Wallet ID on POA Blockchain if they had one
 1. comm_tkn - Their token name (each user only has 1 token) currenlty only Sarafu
 1. bal - current balance of [comm_tkn] as of file date
-1. location - User input (village name) 
+1. location_path - The smallest to largest region names on Open Street Maps for that users physical location
+1. location_lat - The smallest region latitude
+1. location_lon - The smallest region longitude
 1. held_roles - Standard transactions are between Beneficiaries, anything to an Admin is a Reclemation or from and Admin is a Disbursment and anything to a Agent is a Agent_out
-1. gender
+1. gender - user input gender
 1. business_type - Input by GE staff based on what the users sell
 1. ovol_in - total number of tokens that came into this account from non-STANDARD transactions
 1. ovol_out
@@ -58,7 +55,6 @@ The user summary csv fields:
 1. sunique_in - number of uniquie transactions incomming from STANDARD transactions
 1. sunique_in
 1. start - day and time of first transaction (when the user account was setup)
-1. confidence - based on how many other purchasing users agree with the business_type
 
 ----
 

spec/002_dai_reserve_migration.md

@@ -1,4 +1,4 @@
-# xDAI Migration spec
+# x/bDAI Migration spec
 
 <!--
 valid status values are: Pre-draft
@@ -10,40 +10,46 @@ valid status values are: Pre-draft
 
 ## Rationale
 We want to give donors and community members a way to contribute to and cash-out from Community Inclusion Currencies with National Currency. 
-By connecting to a reserve that is stable to the US dollar called xDAI we bring some stability and the ability for many to support local communities. 
+By connecting to a reserve that is stable to the US dollar called x/bDAI we bring some stability and the ability for many to support local communities. 
-We also enable any CICs that have xDAI as a reserve to convert to any other CIC with xDAI as reserve. 
+We also enable any CICs that have bDAI as a reserve to convert to any other CIC with bDAI as reserve. 
 
 ## Before 
 Currently we are using a virtual reserve a generic ERC20 token. We have 2 Million of those reserve tokens against 8 Million Sarafu issued (the current Kenyan CIC). (Call those Sarafu_1 or S1)
 
 ## After
-We have 40,000 xDAI to put as the reserve and are looking at minting (16Million) tokens (called Sarafu_2 S2)
+We have 40,000 DAI to bridge to a bDAI token and put as the reserve and are looking at minting (16Million) tokens (called Sarafu_2 S2)
 with a connector weight (target Reserve Ratio) of 0.25 (25%) and an inital price of roughly 100 Sarafu to 1 xDAI (USD stable) 
 (Note that the 100 Sarafu to 1 xDAI will approximate the Kenyan Shillings to USD rate)
 
 ## Implementation
-Each existing user should have a completley new wallet and private key for security reasons and be given the same balances they currently have with the new (xDAI reserve) Sarafu. Roughly 8Million Sarafu_1 in wallet will be replaced with Sarafu_2
+
+Each existing user should have a completley new wallet and private key for security reasons and be given the same balances they currently have with the new (bDAI reserve) Sarafu. Roughly 8Million Sarafu_1 in wallet will be replaced with Sarafu_2
 
 ### Workflow
+
+1. Bridge bDAI to DAI on BloxBerg
+1. Setup an onserver node on BloxBerg
 1. Synch db <->Blockchain - ensure synronization between our db (USSD interface) and blockchain
-1. Finalize any contract changes to Bancor Suite (such as [Depth Bump](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/003_depth_bump.md)) 
+1. (delayed) Finalize any contract changes to Bancor Suite (such as [Depth Bump](https://gitlab.com/grassrootseconomics/cic-docs/-/blob/master/spec/003_depth_bump.md)) 
-1. Create Public vs Private Functions - Contracts as permissionless as possible
+1. Understand all Public vs Private (owner owned) Functions - Make all contracts as permissionless as possible
 1. Create group of govenors on a multi-sig wallet with the power to assign the facilitator address of all blockchain contracts (Bancor Suite). 
+1. Security checkes
 1. Deploy contracts to create Sarafu_2, set inital variables - deposit reserve and mint tokens
 1. Migration - New wallets for users - Replicate user accounts with new token Sarafu_2 - ensure private keys are safely stored 
-1. Can our own xDAI node process transactions?
 
 ### Variables
 
 1. Synch variables, - synch frequency - and limitations
-2. Contract variables (reserve ratio (0.25), reserve amount (40k xDAI), number of Sarafu_2 (16Million), convert fee 0.005 (0.5%))
+2. Contract variables (reserve ratio (0.25), reserve amount (40k bDAI), number of Sarafu_2 (16Million), convert fee 0.005 (0.5%))
 3. Migration speed - how often is synching done between USSD db and blockchain
-4. 3rd party Fiat <-> xDAI conversion costs and speed
+4. 3rd party Fiat <-> bDAI conversion costs and speed
 
 ### Interface
 This migration will all be done at code and command line level, while some testing can be done on the platform gui
 
 ## Testing
+1. Check bDAI to DAI on bridge on BloxBerg
+1. Test observer node on BloxBerg for dashboard
 1. Check db<->blockchain synch - verify they are synched and we can do external transactions and handle RPC failure
 1. Token Governance
 1. Contract deplyment - conversions, transfers all work as expected 

spec/006_Self_Service_Token.md

@@ -24,24 +24,14 @@ Enabeling users to create their own tokens is one of the main goals of CICs
 2. Token Long Name - 128 character limit
 3. Token short name no more than 6 Character - must be unique
 2. Reserve amount - amount of tokens they want to put in reserve (minimum upon conversion 100k xDAI)
-
-> lash: Does the current conversion price between xdai and sarafu play a role here? The chama may have sarafu initially, and that will be translated into the xdai (which for their part is just some abstraction of ksh anyway). How sensitive is this to timing / quality of arbitrage agents?
-
-> lash: Do donors play a role in the initial reserves here? Like a frational top-up? If it does, should it be allocated before or after conversion?
-
 3. Number of chama members (NCM) (before we enable conversion of the new tokens there must be at least this many token members with a positive token balance)
 4. Token Backing Statement: 256 Character limit - What is the off-chain guarentee behind these tokens
-
-> lash: this should rather be a crypto proof of off-chain information sources.
-
 5. Defaults: 
    1. 25% Target Reserve Ratio (1:1 with reserve)
    1. Minimum initial reserve is $100 USD = 100 xDAI in value (of some inital token such as Sarafu)
-
-> lash: do we need to clarify better what the effect of asymmetric changes in real-world assets against the initial issued tokens is? 100 goats may be committed initially, but if they get eaten by mutant locusts, what happens to the value of the token then, and what transparency should be provided in that event? (for example, should the actual backing statement be revised etc?)
-
 5. These should all be added to the Token table information
 
+
 ## Token creation process - Backend 
 
 1. Ensure TOKEN_Name is unique
@@ -58,24 +48,14 @@ Enabeling users to create their own tokens is one of the main goals of CICs
 ## Join Token 
 2. Each user needs to be assigned a default / community token - they start with Sarafu by default.
 2. Users need to be able to change tokens - but after a grace period of 1 month. 
-
-> lash: how should the grace period be enforced? if on smart contract level this would mean changing the bancor contracts most likely. 
-
 3. Users on USSD should not be allowed to join Sarafu or the reserve xDAI as their community token. Admin accounts like the GE Agent will still be in Sarafu as their community token
 
-> lash: not allowed to join sarafu once they _left_ sarafu in the first place, right?
-
 ## Auto Join Token
 1. Users with Sarafu as their token will automatically join a Community Token of a user they trade with (given the recipient is not in Sarafu) - This is a one time event
 
-> lash: who pays the fee for this, or is it negligble?
-
 ## Auto convert
 1. We want to avoid having multiple tokens in user wallets
 1. When a user recieves a token we automatically try to convert that token into her Community token
-
-> lash: where is this enforced? this may be complicated to do on a smart contract level as the network isn't designed to do any per-address discrimination. What consequences can multiple tokens on one account due to external converts have?
-
 2. We should be able to turn this feature off for selected users (like admins)
 3. If users have multiple tokens in their wallet - it is a sign conversion failed - we need some process to retry failed conversions and to altert admins
 
@@ -117,24 +97,11 @@ Enabeling users to create their own tokens is one of the main goals of CICs
    - My Account -> Create Token
    1. Token Name (limited to 9 characters (auto converted to lowercase no special letters) (TOKEN_NAME)
    2. Reserve amount (the minimum is 10,000 Kenyan Shillings in value- higher amount means a higher price of the final tokens) - Max is the user’s current balance. Note that this10,000 Kenyan Shillings can be in the form of other tokens and converted to Sarafu.
-
-> lash: it seems here like there is an option only to put _part_ of the currently held amount of sarafu (or whatever token) in reserve. but elsewhere we're enforcing one token per wallet/group only. shouldn't this choice be all-or-nothing?
-
    3. Token Backing Statement: What goods or services will be accepted for these tokens?
-
-> lash: isn't this rather difficult to handle on a phone interface? what about timeouts? how do we sanitize the input? what about the real-world documents that get signed? how about if there are many types of goods and/or they will change over time?
-
    4. Please confirm that you will accept (4x Reserve) of TOKEN_NAME's for (goods or services)? 
       *. Yes / No (if no -please contact Office 0757628885)
    4. How many people are in this chama that will recieve (Token_Name) - Minimum 10 - Note your account will be locked until you've sent out all all your tokens to this many users.
-
-> lash: where should this lock be enforced? that seems like a specialized token contract. does that mean that our bancor suite would have to support "non-standard erc20 tokens" only?
-
-
    5. Note that members must ‘join’ the token (via USSD) using the TOKEN_NAME to receive this.
-
-> lash: what happens then if a user never joins? do the tokens just linger? are they returned? is the above account forever locked? is there any use case where they wouldn't join?
-
 4. Pin 
    * “Enter PIN
    * _______________” 
@@ -169,9 +136,6 @@ Enabeling users to create their own tokens is one of the main goals of CICs
 2. Also when people buy in they are adding to theri own token's reserve and minting new tokens.
 3. Since GE is the intermediary for Kenyan Shillings Mpesa - sending TOken X to the GE Agent Account should first convert that token to 
    it's own reserve and give back that much Mpesa (limited by chama rules)
-
-> lash: is the ge agent getting xdai or sarafu here?
-
 4. When a user sends mpesa to us - they can mint whatever their current currency is.
 
 

spec/007_eMoney_integration.md

@@ -1,36 +1,122 @@
 ## Incoming Sarafu ##
-When chama (group accounts) exchange Sarafu each month for National Currency we have to manually send them Mpesa.
+When users exchange CIC <> National Currency we have to manually send them Mpesa or CIC.
 We would like to automate this.
 
-## Outgoing Sarafu ##
-When anyone sends us Mpesa on our paybill we have to manuall send them Sarafu
-
 ## Solution ##
-Configure - using our own system AfricasTalking API to automatically send Sarafu / Mpesa based on rules:
+Configure - using our own system AfricasTalking API to automatically send CIC / Mpesa based on rules:
- 
+- CIC - > Mpesa 
-### Incoming Sarafu Rules ###
+   - CICs are converted to reserve on-chain and the xDAI is held in a GE account (xDAI Float)
- - *white list* The chama (group accounts only) must only be able to cash out - using the exchange option to an Agent account
+   - We send back an equivalent amount of Mpesa to the user from out MPESA float account
- - *amount* The max cash out is the minimum of (30,000 Sarafu, half their balance, their total amount of outward trade volume to other users (standard transactions)
+- Mpesa -> CIC
- - *time* They can only cash out once per month
+   - Mpesa are added to our float Mpesa account.
- - *rate* The Sarafu to Mpesa rate should be a config variable set to 1.0 -> a 0% cash out fee. i.e. For 100 Sarafu you get 100 Mpesa. This rate will vary manual based on promotion periods and available Mpesa
+   - xDAI from our xDAI float account is added to the reserve of the CIC (Home CIC of the user) and new CICs are minted and sent to the user
 
 
-### Outgoing Sarafu Rules ###
+### Variables ###
- - *white list* Only users sending via paybill receive Sarafu. Non users receive a invitation to join Sarafu sms
+ - blockchain_CIC_Supply = the total supply of the CIC on the blockchain
- - *amount* The max sarafu out is 20,000 Sarafu per user
+ - blockchain_CIC_reserve = the total reserve (xDAI) of the CIC on the blockchain
+ - trr = the connector weight on blockchain converter between supply and reserve
+ - FLoat xDAI: THe amount of xDAI we have in our master wallet
+ - FLoat Mpesa: THe amount of Mpesa supply we have in our PayBill account
+ - CIC_excahnge_amount = the amount of CIC they user has sent to exhange
+ - Mpesa_excahnge_amount = the amount of MPesa the user has sent to exhange
+ - Rate: USD -> KSH
+ - Rate: KSH -> USD
+ - Fees: Sarafu to Mpesa FeeCC2M = 2%
+ - Fees: Sarafu to Mpesa FeeM2CC = 2%
+ - The account to which CIC are sent should be a Agent account
+ - The cash-out rules for a chama (minimum and time limit)
+ - Alert balance levels
+ 
+### Incoming CIC Rules - MPESA out ###
+ - *white list* The chama (group accounts only but eventually anyone) can cash out - note the chama limits
+ - *amount* See KYC_limit max, supply_max
+ - *mpesa given* The amount of Mpesa given should be calculated as follows:
+ - CIC_excahnge_amount = the amount of CIC the user wants to excahnge
+
+The Reserve (xDAI) to be pulled out (reported):
+
+- reserveOut_xDAI_reported = the amount of xDAI that would be pulled from the reserve on-chain (by getting a quote on-chain)
+- reserveOut_Mpesa = reserveOut_xDAI_reported **USD => KSH** rate
+- reserveOut_Mpesa_reported = reserveOut_xDAI_reported **USD => KSH** rate
+
+After the user confirms:
+
+The Reserve (xDAI) actually pulled out 
+- reserveOut_xDAI = the amount of xDAI actually pulled from the reserve on-chain
+-  **Mpesa_out** = reserveOut_Mpesa_reported (this is actually given to the user) - **and GE takes on the Mpesa risk**
+  -  reserveOut_Mpesa = reserveOut_xDAI **USD => KSH** rate (this is from our MPESA float account)
+  -  Mpesa_risk = Mpesa_out - reserveOut_Mpesa - this should me monitored and recorded for each transactions
+
+
+### Outgoing Sarafu Rules - MPESA In ###
+ - *white list* Only users sending via paybill receive Sarafu. Non users receive a invitation to join Sarafu sms (alert to admins there was a donation).
+ - *amount* The max sarafu out is 20,000 Sarafu per user, KYC_limit max, supply_max
  - *time* No limit
- - *rate* The Mpesa to Sarafu rate should be a config variable set to 1.2 -> a 20% cash in bonus. i.e. For 100 Mpesa you get 120 Sarafu. This rate will vary manual based on promotion periods and available Sarafu
+ - *Mpesa_excahnge_amount* The amount of CIC given should be calculated as follows:
+ - reserveIn_xDAI = (Mpesa_excahnge_amount - Mpesa_excahnge_amount* fee) **KSH => USD** rate (this will come out of the xDAI float account)
+    
+The CIC to be created (reported for quote): 
+
+  - CIC_Created_reported = the amount of CIC to be created on chain by adding the reserveIn_xDAI (quote from blockchain)
+    
+After the user confirms:
+
+  - CIC_Created = the actualy amount of CIC created on chain by adding the reserveIn_xDAI 
+  - **CIC_given** = CIC_Created_reported
+     -  CIC_risk =  CIC_given - CIC_Created - this should be monitored and recorded for each transaction
+  
+### Exchange Rate ###
+
+When dislaying the SPOT price or excahnge rate to a user we should use the following formula:
+> Exchange Price = CIC_reserve / (CIC_supply * trr) -> this is pulled from blockchain and should be sent back as a SMS
+
+
+### USSD Interface ###
+
+- Option #4 Exchange
+   - #1 Get Exchange Rate
+   - #2 Confirm Exchange
+
+- User chooses Exchange Menu option #1 Get Exchange Rate - then chooses the direction of the exchange
+   - #1 [CIC] -> Mpesa
+      - Enter the amount of [CIC] you wish to redeem (limited to their balance)
+   - #2 Mpesa -> [CIC]
+      - Enter the amount of Mpesa you wish to contribute
+   - Enter pin to confirm 
+   - You will recieve a SMS shortly
+       - perhpas for MVP we can just spit this back out on USSD. 
+       - SMS: You will receive at least 800 KSH for 1000 CIC. This quotation is stored for the user but only valid for a period of time (1 hour?)
+      
+- User chooses Exchange Menu option #2 Confirm Exchange - if they don't have an active quotation they must goto option #1 first.
+   
+If the quotation is for CIC->Mpesa then: 
+   - Show the last quotation message
+   - Enter your pin to confirm
+   - You will recieve a SMS shortly
+
+If the quotation is for Mpesa-> then: 
+   - Show the last quotation. message - which includes instruction for sending on paybill
+   
+
+
+
+
+
+
+### Credit Clearing ###
+Weekly or after alterts we will rebalance our xDAI and Mpesa float accounts.
+
+As our float account gets more and more full of xDAI (and mpesa float shrinks) - we will convert the xDAI to Mpesa
+via xdai.io to get ETH - then using localcryptos or BitCoinSuisse to get Kenyan Shilllings / Mpesa (note there are MANY fees along this path)
+
+If we get a large amount of Mpesa and want to convert to xDAI -> CIC ... then we send the Mpesa eitheir to localCryptos or bitcoinSwuiss to get ETH
+then we use xdai.io to convert that ETH to xDAI ... then we add that to our xDAI float
 
 
 ### Security ###
- - Balance alerts: The paybill from which Sarafu is sent needs to send a sms and email alert when low 
+ - Balance alerts: On both Mpesa and CIC balances: The paybill from which Sarafu is sent needs to send a sms and email alert when low 
  - Failure alerts: If the API session fails an sms and email alert should be sent
  - Reject on not enough Mpesa balance: If there is not enough Mpesa (on incoming Sarafu) the transaction should be rejected and an email sent to admin along with a SMS to admin and user (Sarafu should not be taken from user). (message should be visible also on mgmt platform txn view and user view and admin view).
  - Reject on not enough Sarafu balance: If there is not enough Sarafu (on incoming Mpesa) the transaction should be rejected and an email sent to admin along with a SMS to admin and user (Mpesa should not be taken from user). (message should be visible also on mgmt platform txn view and user view and admin view).
 
-### Variables ###
- - The account from which Sarafu is sent should be a Agent account
- - The cash-out rules for a chama (minimum and time limit)
- - Alert balance levels
- - Rate: Mpesa to Sarafu 
- - Rate: Sarafu to Mpesa

spec/010_Web_Wallet.md

@@ -1,50 +1,121 @@
-# Title
+# CIC Wallet Infrastructure 
 
 <!--
 valid status values are: Pre-draft|Draft|Proposal|Accepted
 -->
-* Authors: Firstname Lastname <email> (url)
+* Authors: Gustav Friis
-* Date: YYYY.MM.DD
+* Date: 2020.07.28
-* Version: 1
+* Version: 0.1
 * Status: Pre-draft
 
-## Rationale
-<!--
-Why are you proposing this?
--->
 
-## Before 
-<!--
-What is the current state of the described topic?
--->
 
-## After
+## Purpose
-<!--
-How will things be different after this has been done?
--->
 
-## Implementation
+Build a non-custodial wallet infrastructure designed to enable Kenyan end-users to use xDAI and / or Bloxberg blockchain based Community Inclusion Currencies (CICs) from a smartphone and / or desktop.
-<!--
-Here is the description of how these changes should be implemented.
-Please use subheadings to improve readability.
-Some suggestions:
 
-### Workflow
+## Target group
 
-### Variables
+Existing or new Kenyan CIC end-users, who are individuals or small businesses using CICs to pay for goods and services. From the user-interviews with B4H we’ve found that these users are certainly not web3 savvy and to a varying degree are web2 savvy either. He/she just wants to interact with his/her wallet funds (displaying balance, paying & receiving) in the community currency (which value let's remember is equivalent to Kenyan Shilling).
+
+## User-stories
+
+
+
+- Get directed to web wallet via URL
+
+- Signing up
+
+- Choosing a reference currency
+
+- Displaying balance
+
+- Send payment to known contact
+
+- Send payment to unknown receiver (referral link)
+
+- Initiate payment by scanning QR code
+
+- Receive payment via QR code
+
+- Receive payment via link
+
+- Claim payment link
+
+- Payment notification
+
+- Transaction details
+
+- Transaction history overview
+
+- Cash in and out from CICs to M-Pesa 
+
+**Settings including**
+
+- Backup wallet
+- Change base currency
+- Support
+- Social media 
+- Sign out
+- Share with friends 
+
+## Technical implementation
+
+
+### Wallet creation
+
+Using BIP39 HD and secp256k1
+
+### Wallet authentication and recovery
+
+Based on an open-source fork of Portis https://assets.portis.io/white-paper/latest.pdf, but instead of relying only on email as a string it can be any identifier which Grassroots Economica already has in place for its users.
+
+The current PoC implementation of this can be found here:
+
+https://github.com/multiplycharity/multiply-monorepo/tree/master/packages/sdk
+https://github.com/multiplycharity/multiply-monorepo/blob/master/packages/server/src/controllers/accounts.js
+
+From the Portis Whitepaper allowing SMS / Email / Password authenticated and recovery:
+
+“Portis lets users create an encryption key on their Client, so once they generate blockchain wallets on their devices, they will be able to encrypt them using said encryption key, and store the encrypted wallets on the Portis servers. All cryptographic keys are generated and managed by the user on their devices, and all encryption is done locally in the Client. Portis servers are never in the position of learning your cryptographic keys. When the already encrypted data travels between the user’s device and our servers, it is encrypted and authenticated by TLS. All of the user’s sensitive data is encrypted when they create their account using 64 random bytes generated on the Client, protected using a password that they select. Nobody on earth knows this password besides them as it never leaves the Client. Using a KDF algorithm, a Backup Recovery Phrase is derived from the password, to offer users a means of resetting their password in case they forget it.”
+
+
+### Interface with the existing Grassroots Economics Platform
+
+
+Existing USSD users
+Gas fees on xDAI
+AfricasTalking API 
+
+
+### Claimable transactions 
+
+
+Using the open-source Linkdrop SDK
+
+	
+## Tech stack
+
+
+Expo
+React Native
+MongoDB
+Node.js
+
+
+## Portability
+
+Portability into native mobile apps and desktop apps following this pattern https://www.youtube.com/watch?v=ykBxY01j_rA
+
+
+
+## Future developments
+
+Migrate to Gnosis Safe smart-contract wallet
+User facing decentralized exchange
+User facing on-the ground marketplace
+Native implementation of P2P platforms like Mylocalcrypto
 
-### Interface
--->
 
-## Testing
-<!--
-Please describe what test vectors that are required for this implementation
--->
 
-## Changelog
-<!--
-Please remember to describe every change to this document in the changelog using 
-serial number:
 
-* version 1:
--->