From ac945b2bda61629c2de8565b0eeb125646d5f3f7 Mon Sep 17 00:00:00 2001 From: nolash Date: Wed, 17 Jun 2020 16:22:06 +0200 Subject: [PATCH 01/23] Separate xdai migration comments --- spec/003_depth_bump.md | 12 ----------- spec/006_Self_Service_Token.md | 38 +--------------------------------- 2 files changed, 1 insertion(+), 49 deletions(-) diff --git a/spec/003_depth_bump.md b/spec/003_depth_bump.md index 09a84a4..e854506 100644 --- a/spec/003_depth_bump.md +++ b/spec/003_depth_bump.md @@ -28,19 +28,12 @@ the price of the token may shoot up and CIC sell offs will cause the reserve to We would need to be able to mint tokens and the reserve outside of the bonding curve in a controled way. The idea would be to keep the CIC price 1:1 with reserve and increase both reserve and supply equally (with the same multiple) (off the curve) To avoid gaming: Excess tokens created in this process (beyond those minted along the bonding curve) should be given to a specific address designated in the Converter constructor. - -> lash: "specific address in the converter constructor." Is this feasible without changing code? Where else could we put this without changing code? Could contract registry help? - A donor in this case can choose to always get back as many CICs as they add to reserve - with no speculative advantage. ## Implementation ### Workflow -> lash: this must be performed as an atomic operation. - -> lash: Is it possible to set up the equation so that we avoid the case of having to handle overshoot in a special wallet; does it help to define the token issuance as the target instead of the amount of reserve? - * A public depthBump Funcation is added to the converter contract which takes in reserve R1 * Calculate the multiple to teh reserve (R1/R0) and mint an amount of tokens T1 = T0(R1/R0) - Where R0 and T0 are the inital amount of reserve and supply * Calculate the amount of tokens (Tc) that would have been created on the bonding curve due to R1. @@ -51,11 +44,6 @@ A donor in this case can choose to always get back as many CICs as they add to r * Amount of Reserve to add R1 8,000,000 * A community Pool account (for excess) in the constructor of the converter contract - -> lash: Who would have spend access to this community pool, and how? - -> lash: Is the community pool the only source of "basic income / usage bonus"? - * Note taht this pool may be used for other system functions like rewards and holding fees ### Interface (CLI) diff --git a/spec/006_Self_Service_Token.md b/spec/006_Self_Service_Token.md index 42fa8ba..5ad09f7 100644 --- a/spec/006_Self_Service_Token.md +++ b/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. From 40c04175bf83a8d5af7f04ef81f55fb55a5829fb Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Fri, 19 Jun 2020 04:20:28 +0000 Subject: [PATCH 02/23] Update 002_xdai_migration.md --- spec/002_xdai_migration.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/spec/002_xdai_migration.md b/spec/002_xdai_migration.md index abcd553..817ca65 100644 --- a/spec/002_xdai_migration.md +++ b/spec/002_xdai_migration.md @@ -29,10 +29,17 @@ Each existing user should have a completley new wallet and private key for secur > lash: what's meant by public and private functions here? +> will: I'm just considering what should be private=internal=only the owner can use vs public functions .... +> Also can we make some of the internal/private functions permissionless post creation (i.e. remove them/ block the doors) ... Upgradability? + > lash: private keys: should we take the opportunity of setting up deterministic wallets? perhaps even on the platform we may want to shuffle private keys once in awhile. +> will: Yes and no. For now on the platform we really want easy trackability to track donor impacts .... I would leave this for the web wallet etc. I just want to make sure the private keys are all secure - who has access etc. + > lash: what is a "facilitator address"? +> Will: Lets remove this - see depth_bump comments + 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. Create Public vs Private Functions - Contracts as permissionless as possible From 6a537899a88c5496757f71b4f48feb33d062edbb Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 05:55:23 +0000 Subject: [PATCH 03/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 40 +++++++++++++++++++++++++++------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 469eec1..86f4d8a 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -1,5 +1,5 @@ ## Incoming Sarafu ## -When chama (group accounts) exchange Sarafu each month for National Currency we have to manually send them Mpesa. +When users exchange CICfor National Currency we have to manually send them Mpesa. We would like to automate this. ## Outgoing Sarafu ## @@ -12,18 +12,42 @@ Configure - using our own system AfricasTalking API to automatically send Sarafu - *white list* The chama (group accounts only) must only be able to cash out - using the exchange option to an Agent 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) - *time* They can only cash out once per month - - *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 + - *rate* The Sarafu (and their community) to Mpesa rate should be calculated as follows: + - CIC_supply_b: Get the total CIC supply off **blockchain** - the amount of **CIC_burn** + - total_reserve_b: Get the total reserve off **blockchain** - the amount of **cash_out** we've gotten (in USD) + - CIC_burn_amount = whatever they have sent to exhange + + +The Reserve (xDAI) pulled out +> const reserveOut_xDAI = total_reserve_b * (Math.pow(1 + (-1 * CIC_burn) / CIC_supply_b, 1 / trr) - 1); + + - Mpesa_out = reserveOut_xDAI **USD => KSH** rate + - reserve_given = reserve_out - CIC_created*fee (0.02) + - Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b - CIC_burn + - Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b - reserveOut_xDAI ### Outgoing Sarafu Rules ### - - *white list* Only users sending via paybill receive Sarafu. Non users receive a invitation to join Sarafu sms - - *amount* The max sarafu out is 20,000 Sarafu per user + - *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 + - *rate* The Mpesa to Sarafu (and their community) rate should be calculated as follows: + - CIC_supply_b: Get the total CIC supply off **blockchain** + the amount of **CIC_given** + - total_reserve_b: Get the total reserve off **blockchain** + the amount of **cash_in** we've gotten (in USD) + - cash_in_amount = Mpesa_in **KSH -> USD** rate (what is the current USD <> KSH rate) + +The amount cashed in = cash_in_amount +> const CIC_Created = cic_supply_b * (Math.pow(1 + cash_in_amount / total_reserve_b, trr) - 1); + + - **CIC_given = CIC_Created - CIC_created*fee (0.02)** + - Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b + CIC_given + - Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b + cash_in_amount + + ### 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). @@ -32,5 +56,5 @@ Configure - using our own system AfricasTalking API to automatically send Sarafu - 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 \ No newline at end of file + - Fees: Mpesa to Sarafu + - Fees: Sarafu to Mpesa \ No newline at end of file From a8df7ca4f7d3bfdcb98a062771021dbbd4961ece Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 05:59:31 +0000 Subject: [PATCH 04/23] updated maths for float accounts --- spec/007_eMoney_integration.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 86f4d8a..f5eff52 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -1,15 +1,12 @@ ## Incoming Sarafu ## -When users exchange CICfor 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: -### Incoming Sarafu Rules ### - - *white list* The chama (group accounts only) must only be able to cash out - using the exchange option to an Agent account +### Incoming Sarafu Rules - MPESA out### + - *white list* The chama (group accounts only but eventually anyone) must only be able to cash out - using the exchange option to an Agent 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) - *time* They can only cash out once per month - *rate* The Sarafu (and their community) to Mpesa rate should be calculated as follows: @@ -22,12 +19,12 @@ The Reserve (xDAI) pulled out > const reserveOut_xDAI = total_reserve_b * (Math.pow(1 + (-1 * CIC_burn) / CIC_supply_b, 1 / trr) - 1); - Mpesa_out = reserveOut_xDAI **USD => KSH** rate - - reserve_given = reserve_out - CIC_created*fee (0.02) + - reserve_given = reserve_out - CIC_created*fee (0.02) (this is given to the user) - Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b - CIC_burn - Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b - reserveOut_xDAI -### Outgoing Sarafu Rules ### +### 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 From dc4128ef78a17b0b0e482ccbdbe089dceeae1d54 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 05:59:53 +0000 Subject: [PATCH 05/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index f5eff52..5f58f38 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -5,7 +5,7 @@ We would like to automate this. ## Solution ## Configure - using our own system AfricasTalking API to automatically send Sarafu / Mpesa based on rules: -### Incoming Sarafu Rules - MPESA out### +### Incoming Sarafu Rules - MPESA out ### - *white list* The chama (group accounts only but eventually anyone) must only be able to cash out - using the exchange option to an Agent 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) - *time* They can only cash out once per month @@ -24,7 +24,7 @@ The Reserve (xDAI) pulled out - Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b - reserveOut_xDAI -### Outgoing Sarafu Rules - MPESA In### +### 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 From 2476d9fc9fdca4591ffbe783feda12ac77a7bb87 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 06:30:38 +0000 Subject: [PATCH 06/23] cleaned formatting on math and variables --- spec/007_eMoney_integration.md | 66 ++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 27 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 5f58f38..67c4717 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -4,44 +4,62 @@ We would like to automate this. ## Solution ## Configure - using our own system AfricasTalking API to automatically send Sarafu / Mpesa based on rules: + +### Variables ### + - blockchain_CIC_Supply = the total supply of the CIC on the blockchain + - blockchain_CIC_reserve = the total reserve (xDAI) of the CIC on the blockchain + - trr = the connector weight on blockchain converter between supply and reserve + - total_CIC_sent = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing + - total_CIC_Reserve_Sent = the total amount of Reserve that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing + - total_CIC_recieved = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing + - total_CIC_Reserve_recieved = the total amount of Reserve that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing + - CIC_supply_b: **blockchain_CIC_Supply** - **total_CIC_sent** + **total_CIC_recieved** = this simulates/tracks the changes to the blockchain + - CIC_reserve_b: **blockchain_CIC_reserve** - **total_CIC_Reserve_Sent** + **total_CIC_Reserve_recieved** = this simulates/tracks the changes to the blockchain + - 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 + - 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 + - Fees: Sarafu to Mpesa FeeCC2M = 2% + - Fees: Sarafu to Mpesa FeeM2CC = 2% ### Incoming Sarafu Rules - MPESA out ### - *white list* The chama (group accounts only but eventually anyone) must only be able to cash out - using the exchange option to an Agent 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) - *time* They can only cash out once per month - - *rate* The Sarafu (and their community) to Mpesa rate should be calculated as follows: - - CIC_supply_b: Get the total CIC supply off **blockchain** - the amount of **CIC_burn** - - total_reserve_b: Get the total reserve off **blockchain** - the amount of **cash_out** we've gotten (in USD) - - CIC_burn_amount = whatever they have sent to exhange - + - *mpesa given* The amount of Mpesa given should be calculated as follows: + The Reserve (xDAI) pulled out -> const reserveOut_xDAI = total_reserve_b * (Math.pow(1 + (-1 * CIC_burn) / CIC_supply_b, 1 / trr) - 1); - - - Mpesa_out = reserveOut_xDAI **USD => KSH** rate - - reserve_given = reserve_out - CIC_created*fee (0.02) (this is given to the user) - - Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b - CIC_burn - - Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b - reserveOut_xDAI +> reserveOut_xDAI = CIC_reserve_b * (Math.pow(1 + (-1 * CIC_excahnge_amount) / CIC_supply_b, 1 / trr) - 1) --> this shoudl be calculated as it is done on contract + - Mpesa_out = reserveOut_xDAI **USD => KSH** rate + - **Mpesa_given = Mpesa_out - Mpesa_out*S22M (fee) this is the amount of Mpesa sent to the user** + - Update CIC variables on database: + - total_CIC_recieved+= CIC_excahnge_amount + - total_CIC_Reserve_Sent+= reserveOut_xDAI + ### 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 (and their community) rate should be calculated as follows: - - CIC_supply_b: Get the total CIC supply off **blockchain** + the amount of **CIC_given** - - total_reserve_b: Get the total reserve off **blockchain** + the amount of **cash_in** we've gotten (in USD) - - cash_in_amount = Mpesa_in **KSH -> USD** rate (what is the current USD <> KSH rate) - + - *CIC given* The amount of CIC given should be calculated as follows: + - reserveIn_xDAI = Mpesa_excahnge_amount **KSH => USD** rate + The amount cashed in = cash_in_amount -> const CIC_Created = cic_supply_b * (Math.pow(1 + cash_in_amount / total_reserve_b, trr) - 1); + +> const CIC_Created = CIC_supply_b * (Math.pow(1 + reserveIn_xDAI / CIC_reserve_b, trr) - 1); - - **CIC_given = CIC_Created - CIC_created*fee (0.02)** + - **CIC_given = CIC_Created - CIC_created*FeeM2CC ()** - Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b + CIC_given - Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b + cash_in_amount - - - + - Update CIC variables on database: + - total_CIC_sent+= CIC_excahnge_amount + - total_CIC_Reserve_recieved+= reserveIn_xDAI + ### Security ### - 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 @@ -49,9 +67,3 @@ The amount cashed in = cash_in_amount - 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 - - Fees: Mpesa to Sarafu - - Fees: Sarafu to Mpesa \ No newline at end of file From 00b270ba08385bb13040342b33cba194568ba080 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 06:31:32 +0000 Subject: [PATCH 07/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 67c4717..b3801ee 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -33,7 +33,7 @@ Configure - using our own system AfricasTalking API to automatically send Sarafu The Reserve (xDAI) pulled out -> reserveOut_xDAI = CIC_reserve_b * (Math.pow(1 + (-1 * CIC_excahnge_amount) / CIC_supply_b, 1 / trr) - 1) --> this shoudl be calculated as it is done on contract +> reserveOut_xDAI = CIC_reserve_b * (Math.pow(1 + (-1 * CIC_excahnge_amount) / CIC_supply_b, 1 / trr) - 1) --> this should be calculated as it is done on contract - Mpesa_out = reserveOut_xDAI **USD => KSH** rate - **Mpesa_given = Mpesa_out - Mpesa_out*S22M (fee) this is the amount of Mpesa sent to the user** @@ -51,7 +51,7 @@ The Reserve (xDAI) pulled out The amount cashed in = cash_in_amount -> const CIC_Created = CIC_supply_b * (Math.pow(1 + reserveIn_xDAI / CIC_reserve_b, trr) - 1); +> CIC_Created = CIC_supply_b * (Math.pow(1 + reserveIn_xDAI / CIC_reserve_b, trr) - 1) --> this should be calculated as it is done on contract - **CIC_given = CIC_Created - CIC_created*FeeM2CC ()** - Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b + CIC_given From 533b09b4b51deb5ae9a9b0e16a423cdf473b6b03 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 06:41:09 +0000 Subject: [PATCH 08/23] User interface --- spec/007_eMoney_integration.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index b3801ee..407e715 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -9,10 +9,12 @@ Configure - using our own system AfricasTalking API to automatically send Sarafu - blockchain_CIC_Supply = the total supply of the CIC on the blockchain - 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 CIC: THe amount of CIC supply we have in our master wallet + - FLoat Mpesa: THe amount of Mpesa supply we have in our PayBill account - total_CIC_sent = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - - total_CIC_Reserve_Sent = the total amount of Reserve that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing + - total_CIC_Reserve_Sent = the total amount of Reserve (xDAI) that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - total_CIC_recieved = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - - total_CIC_Reserve_recieved = the total amount of Reserve that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing + - total_CIC_Reserve_recieved = the total amount of Reserve (xDAI) that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - CIC_supply_b: **blockchain_CIC_Supply** - **total_CIC_sent** + **total_CIC_recieved** = this simulates/tracks the changes to the blockchain - CIC_reserve_b: **blockchain_CIC_reserve** - **total_CIC_Reserve_Sent** + **total_CIC_Reserve_recieved** = this simulates/tracks the changes to the blockchain - CIC_excahnge_amount = the amount of CIC they user has sent to exhange @@ -46,7 +48,7 @@ The Reserve (xDAI) pulled out - *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 - - *CIC given* The amount of CIC given should be calculated as follows: + - *Mpesa_excahnge_amount* The amount of CIC given should be calculated as follows: - reserveIn_xDAI = Mpesa_excahnge_amount **KSH => USD** rate The amount cashed in = cash_in_amount @@ -61,6 +63,29 @@ The amount cashed in = cash_in_amount - total_CIC_Reserve_recieved+= reserveIn_xDAI +### Exchange Rate ### + +When dislaying the SPOT price or excahnge rate to a user we should use the following formula: +> Exchange Price = CIC_reserve_b / (CIC_supply_b * trr) + + +### User Interface ### + +- When a user chooses to ``Redeem```: + - They should enter the amount (limited to the max in their balance) + - They should get a confirmation Based on the above equations: + - The user should be asked you will revice **Mpesa_given** for **CIC_excahnge_amount**: Please type your PIN to confirm + - The user should get a Mpesa responce for recieving the Mpesa + +- When a user chooses to ``Contribute```: + - They should enter the amount of Mpesa they wish to contribute + - They should get a confirmation: + - Based on the above equations: + - The user should be asked you will revice **CIC_given** for **Mpesa_excahnge_amount**: Please type your PIN to confirm + - They will then get instructions on USSD as well as a SMS on how to send Mpesa or Bonga boints to our Lipa na Mpesa + + + ### Security ### - 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 From 7af458a616b9009760059bfc00f484865f18cd48 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 07:11:05 +0000 Subject: [PATCH 09/23] xDAI vs MPESA floats --- spec/007_eMoney_integration.md | 44 ++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 407e715..d43e2af 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -4,6 +4,17 @@ We would like to automate this. ## Solution ## Configure - using our own system AfricasTalking API to automatically send Sarafu / Mpesa based on rules: +- CIC - > Mpesa + - CICs are converted to reserve on-chain and the xDAI is held in a GE account (xDAI Float) + - We send back an equivalent amount of Mpesa to the user from out MPESA float account +- Mpesa -> CIC + - Mpesa are added to our float Mpesa account. + - xDAI from our xDAI float account is added to the reserve of the CIC (Home CIC of the user) and new CICs are minted + - We send back the user an equivalent amount of CIC + +## Un -speced - todo ## +- Define the credit clearing process + ### Variables ### - blockchain_CIC_Supply = the total supply of the CIC on the blockchain @@ -27,54 +38,45 @@ Configure - using our own system AfricasTalking API to automatically send Sarafu - Fees: Sarafu to Mpesa FeeCC2M = 2% - Fees: Sarafu to Mpesa FeeM2CC = 2% -### Incoming Sarafu Rules - MPESA out ### +### Incoming CIC Rules - MPESA out ### - *white list* The chama (group accounts only but eventually anyone) must only be able to cash out - using the exchange option to an Agent 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) - *time* They can only cash out once per month - *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) pulled out -> reserveOut_xDAI = CIC_reserve_b * (Math.pow(1 + (-1 * CIC_excahnge_amount) / CIC_supply_b, 1 / trr) - 1) --> this should be calculated as it is done on contract - - - Mpesa_out = reserveOut_xDAI **USD => KSH** rate +> reserveOut_xDAI = the amount of xDAI pulled from the reserve on-chain + - Mpesa_out = reserveOut_xDAI **USD => KSH** rate (this is from our MPESA float account) - **Mpesa_given = Mpesa_out - Mpesa_out*S22M (fee) this is the amount of Mpesa sent to the user** - - Update CIC variables on database: - - total_CIC_recieved+= CIC_excahnge_amount - - total_CIC_Reserve_Sent+= reserveOut_xDAI - + ### 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 - *Mpesa_excahnge_amount* The amount of CIC given should be calculated as follows: - - reserveIn_xDAI = Mpesa_excahnge_amount **KSH => USD** rate + - reserveIn_xDAI = Mpesa_excahnge_amount **KSH => USD** rate (this will come out of the xDAI float account) The amount cashed in = cash_in_amount -> CIC_Created = CIC_supply_b * (Math.pow(1 + reserveIn_xDAI / CIC_reserve_b, trr) - 1) --> this should be calculated as it is done on contract +> CIC_Created = the amount of CIC created on chain by adding the reserveIn_xDAI - **CIC_given = CIC_Created - CIC_created*FeeM2CC ()** - - Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b + CIC_given - - Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b + cash_in_amount - - Update CIC variables on database: - - total_CIC_sent+= CIC_excahnge_amount - - total_CIC_Reserve_recieved+= reserveIn_xDAI - ### Exchange Rate ### When dislaying the SPOT price or excahnge rate to a user we should use the following formula: -> Exchange Price = CIC_reserve_b / (CIC_supply_b * trr) +> Exchange Price = CIC_reserve / (CIC_supply * trr) ### User Interface ### - When a user chooses to ``Redeem```: - They should enter the amount (limited to the max in their balance) - - They should get a confirmation Based on the above equations: - - The user should be asked you will revice **Mpesa_given** for **CIC_excahnge_amount**: Please type your PIN to confirm + - They should get a confirmation Based on a quote from the blockchain in a SMS: + - The user should be asked you will recieve **Mpesa_given** for **CIC_excahnge_amount** (note this is from blockchain and will change second by second) + - Please type your PIN to confirm - The user should get a Mpesa responce for recieving the Mpesa - When a user chooses to ``Contribute```: @@ -85,6 +87,8 @@ When dislaying the SPOT price or excahnge rate to a user we should use the follo - They will then get instructions on USSD as well as a SMS on how to send Mpesa or Bonga boints to our Lipa na Mpesa +### Credit Clearing ### + ### Security ### - 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 From 3290e7d8a0f4f87019b9a239864d17a05e67c148 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 07:28:32 +0000 Subject: [PATCH 10/23] xDAI <> MPESA --- spec/007_eMoney_integration.md | 63 ++++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 25 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index d43e2af..e27a410 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -3,7 +3,7 @@ When users exchange CIC <> National Currency we have to manually send them Mpesa We would like to automate this. ## 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 - CICs are converted to reserve on-chain and the xDAI is held in a GE account (xDAI Float) - We send back an equivalent amount of Mpesa to the user from out MPESA float account @@ -12,31 +12,22 @@ Configure - using our own system AfricasTalking API to automatically send Sarafu - xDAI from our xDAI float account is added to the reserve of the CIC (Home CIC of the user) and new CICs are minted - We send back the user an equivalent amount of CIC -## Un -speced - todo ## -- Define the credit clearing process - ### Variables ### - blockchain_CIC_Supply = the total supply of the CIC on the blockchain - 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 CIC: THe amount of CIC supply we have in our master wallet + - 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 - - total_CIC_sent = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - - total_CIC_Reserve_Sent = the total amount of Reserve (xDAI) that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - - total_CIC_recieved = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - - total_CIC_Reserve_recieved = the total amount of Reserve (xDAI) that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing - - CIC_supply_b: **blockchain_CIC_Supply** - **total_CIC_sent** + **total_CIC_recieved** = this simulates/tracks the changes to the blockchain - - CIC_reserve_b: **blockchain_CIC_reserve** - **total_CIC_Reserve_Sent** + **total_CIC_Reserve_recieved** = this simulates/tracks the changes to the blockchain - 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 - - Fees: Sarafu to Mpesa FeeCC2M = 2% - - Fees: Sarafu to Mpesa FeeM2CC = 2% ### Incoming CIC Rules - MPESA out ### - *white list* The chama (group accounts only but eventually anyone) must only be able to cash out - using the exchange option to an Agent account @@ -45,10 +36,19 @@ Configure - using our own system AfricasTalking API to automatically send Sarafu - *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) pulled out -> reserveOut_xDAI = the amount of xDAI pulled from the reserve on-chain - - Mpesa_out = reserveOut_xDAI **USD => KSH** rate (this is from our MPESA float account) - - **Mpesa_given = Mpesa_out - Mpesa_out*S22M (fee) this is the amount of Mpesa sent to the user** +The Reserve (xDAI) to be pulled out + +- 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 ### @@ -72,22 +72,35 @@ When dislaying the SPOT price or excahnge rate to a user we should use the follo ### User Interface ### -- When a user chooses to ``Redeem```: +- When a user chooses to ``Redeem get Quote```: - They should enter the amount (limited to the max in their balance) - They should get a confirmation Based on a quote from the blockchain in a SMS: - - The user should be asked you will recieve **Mpesa_given** for **CIC_excahnge_amount** (note this is from blockchain and will change second by second) + - You will recieve **Mpesa_given** for **CIC_excahnge_amount** please confirm this quote in the USSD menue to proceed: (note this is from blockchain and will change second by second) + - The user will return to the USSD menu + - They navigate back to exchange in less than 1 minute and 'confirm exchange quote' (new USSD excahnge menu needed) (the 'confirm Redeem excahnge quote') + - 'confirm Redeem quote' will only show up for a minute - otherwise they have to ask for another quote - Please type your PIN to confirm - - The user should get a Mpesa responce for recieving the Mpesa + - The user should get a Mpesa responce for recieving the **Mpesa_given** -- When a user chooses to ``Contribute```: +- When a user chooses to ``Contribute get Quote```: - They should enter the amount of Mpesa they wish to contribute - - They should get a confirmation: - - Based on the above equations: - - The user should be asked you will revice **CIC_given** for **Mpesa_excahnge_amount**: Please type your PIN to confirm - - They will then get instructions on USSD as well as a SMS on how to send Mpesa or Bonga boints to our Lipa na Mpesa + - They should get a confirmation Based on a quote from the blockchain in a SMS: + - You will recieve **CIC_given** for **Mpesa_excahnge_amount** please confirm this quote in the USSD menu to proceed: (note this is from blockchain and will change second by second) + - The user will return to the USSD menu + - They navigate back to exchange in less than 1 minute and 'confirm exchange quote' (new USSD excahnge menu needed) (the 'confirm Contribute excahnge quote') + - 'confirm Contribute exchange quote' will only show up for a minute - otherwise they have to ask for another quote + - Please type your PIN to confirm + - The user should get a SMS responce from GE for recieving the **CIC_given** ### 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 ### From 607d42c3e44683bcb28755449e77e6567fb45511 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 07:42:57 +0000 Subject: [PATCH 11/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index e27a410..14443ad 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -9,8 +9,7 @@ Configure - using our own system AfricasTalking API to automatically send CIC / - We send back an equivalent amount of Mpesa to the user from out MPESA float account - Mpesa -> CIC - Mpesa are added to our float Mpesa account. - - xDAI from our xDAI float account is added to the reserve of the CIC (Home CIC of the user) and new CICs are minted - - We send back the user an equivalent amount of CIC + - 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 ### Variables ### @@ -30,13 +29,12 @@ Configure - using our own system AfricasTalking API to automatically send CIC / - Alert balance levels ### Incoming CIC Rules - MPESA out ### - - *white list* The chama (group accounts only but eventually anyone) must only be able to cash out - using the exchange option to an Agent 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) - - *time* They can only cash out once per month + - *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 +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 @@ -46,7 +44,7 @@ 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** +- **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 @@ -56,13 +54,18 @@ The Reserve (xDAI) actually pulled out - *amount* The max sarafu out is 20,000 Sarafu per user, KYC_limit max, supply_max - *time* No limit - *Mpesa_excahnge_amount* The amount of CIC given should be calculated as follows: - - reserveIn_xDAI = Mpesa_excahnge_amount **KSH => USD** rate (this will come out of the xDAI float account) + - reserveIn_xDAI = (Mpesa_excahnge_amount - Mpesa_excahnge_amount* fee) **KSH => USD** rate (this will come out of the xDAI float account) -The amount cashed in = cash_in_amount +The CIC to be created (reported for quote): -> CIC_Created = the amount of CIC created on chain by adding the reserveIn_xDAI + - CIC_Created_reported = the amount of CIC created on chain by adding the reserveIn_xDAI + +After the user confirms: + + - CIC_Created = the amount of CIC created on chain by adding the reserveIn_xDAI - - **CIC_given = CIC_Created - CIC_created*FeeM2CC ()** + - **CIC_given** = CIC_Created_reported + - CIC_risk = CIC_given - CIC_Created - this should be monitored and recorded for each transaction ### Exchange Rate ### From 78815a5a3c0bc2b4f8de895256ec2054b9733bd0 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 07:44:33 +0000 Subject: [PATCH 12/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 14443ad..36c2a91 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -58,12 +58,11 @@ The Reserve (xDAI) actually pulled out The CIC to be created (reported for quote): - - CIC_Created_reported = the amount of CIC created on chain by adding the reserveIn_xDAI + - 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 amount of CIC created on chain by adding the reserveIn_xDAI - + - 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 From c109192d3ea1ef746a35155d410a150d5171227a Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Tue, 30 Jun 2020 07:45:42 +0000 Subject: [PATCH 13/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 36c2a91..924cb5e 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -69,7 +69,7 @@ After the user confirms: ### 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) +> Exchange Price = CIC_reserve / (CIC_supply * trr) -> this is pulled from blockchain and should be sent back as a SMS ### User Interface ### From 50323b77e98d6f46eec290b7815c181006802f3c Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Fri, 3 Jul 2020 06:25:55 +0000 Subject: [PATCH 14/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 42 ++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 924cb5e..9dff476 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -74,6 +74,8 @@ When dislaying the SPOT price or excahnge rate to a user we should use the follo ### User Interface ### + + - When a user chooses to ``Redeem get Quote```: - They should enter the amount (limited to the max in their balance) - They should get a confirmation Based on a quote from the blockchain in a SMS: @@ -84,6 +86,26 @@ When dislaying the SPOT price or excahnge rate to a user we should use the follo - Please type your PIN to confirm - The user should get a Mpesa responce for recieving the **Mpesa_given** +User chooses Excahnge Menu option #2 +- Redeem 1000 CIC +- Calculate a quote .... : +- Quotation: Date. +- SMS: You will receive at least 800 KSH for 1000 CIC. (MVP) + - getQuoteRedeemCIC(amount, CIC): + - mvp: return amount = amount - amount * rate; /// Rate is 10% + - best: web3 calls to purchaseReturn +- On the Exchange menu - option #3 is Confirm Quotation: + - Please confirm: "You will receive at least 800 KSH for 1000 CIC." + - Yes. + - mvp: GE receives the 1000 CIC + - best: Then we try a conversion ... with a Min return. + - best: 1000 CIC is sent to the contract (on blockchain) - (xDAI is sent to the GE float account - to be cleared later) + - Mpesa as in the quote - is sent to the user + + + + + - When a user chooses to ``Contribute get Quote```: - They should enter the amount of Mpesa they wish to contribute - They should get a confirmation Based on a quote from the blockchain in a SMS: @@ -94,6 +116,26 @@ When dislaying the SPOT price or excahnge rate to a user we should use the follo - Please type your PIN to confirm - The user should get a SMS responce from GE for recieving the **CIC_given** +User chooses Excahnge Menu option #2 +- Contribute KSH - returning CIC +- Calculate a quote .... : +- Quotation: Date. +- SMS: You will receive at least 1200 CIC for 1000 KSH. (MVP) + - getQuoteContriuteKSH(amount, CIC): + - mvp: return amount = amount + amount * rate; /// Rate is 10% + - best: web3 calls to purchaseReturn +- On the Exchange menu - option #3 is Confirm Quotation: + - Please confirm: "You will receive at least 1200 CIC for 1000 KSH." + - Yes. + - mvp: SMS: Please send 1000 KSH to PayBill account number [phone number] + - best: Then we try a conversion ... with a Min return. + - best: xDAI is sent to the contract (on blockchain) - (xDAI is sent to the GE float account - to be cleared later) + - CIC as in the quote - is sent to the user + + + + + ### Credit Clearing ### Weekly or after alterts we will rebalance our xDAI and Mpesa float accounts. From 7345e00ecb70f3c0b8512355b09c3674e719b836 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Fri, 3 Jul 2020 06:28:05 +0000 Subject: [PATCH 15/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 9dff476..5c90df5 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -103,9 +103,6 @@ User chooses Excahnge Menu option #2 - Mpesa as in the quote - is sent to the user - - - - When a user chooses to ``Contribute get Quote```: - They should enter the amount of Mpesa they wish to contribute - They should get a confirmation Based on a quote from the blockchain in a SMS: From dfa2b156106089d5cdb7508bfecdcbe0bb789f93 Mon Sep 17 00:00:00 2001 From: Phil H Date: Sun, 5 Jul 2020 11:27:41 +0000 Subject: [PATCH 16/23] Update README.md with new grassecon url --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 926c484..cfd9ce4 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ 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) - + [MOOC](https://grassecon.org/mooc) - Very old (paper based systems) + + [Blog](https://www.grassrootseconomics.org/blog) + + [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) From 685de5a0b8650eed6e7cf5e456e9a851eec3942a Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Mon, 13 Jul 2020 12:08:56 +0000 Subject: [PATCH 17/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 5c90df5..7a47e39 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -86,7 +86,9 @@ When dislaying the SPOT price or excahnge rate to a user we should use the follo - Please type your PIN to confirm - The user should get a Mpesa responce for recieving the **Mpesa_given** -User chooses Excahnge Menu option #2 +### USSD Interface ### + +- User chooses Excahnge Menu option #1 Check Excahnge Rate - Redeem 1000 CIC - Calculate a quote .... : - Quotation: Date. From a4ed1c08a9c5aadc8b360eb97cea37bca50f5daa Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Mon, 13 Jul 2020 12:53:35 +0000 Subject: [PATCH 18/23] Update 007_eMoney_integration.md --- spec/007_eMoney_integration.md | 78 ++++++++++------------------------ 1 file changed, 23 insertions(+), 55 deletions(-) diff --git a/spec/007_eMoney_integration.md b/spec/007_eMoney_integration.md index 7a47e39..9e0aa1d 100644 --- a/spec/007_eMoney_integration.md +++ b/spec/007_eMoney_integration.md @@ -72,65 +72,33 @@ When dislaying the SPOT price or excahnge rate to a user we should use the follo > Exchange Price = CIC_reserve / (CIC_supply * trr) -> this is pulled from blockchain and should be sent back as a SMS -### User Interface ### - - - -- When a user chooses to ``Redeem get Quote```: - - They should enter the amount (limited to the max in their balance) - - They should get a confirmation Based on a quote from the blockchain in a SMS: - - You will recieve **Mpesa_given** for **CIC_excahnge_amount** please confirm this quote in the USSD menue to proceed: (note this is from blockchain and will change second by second) - - The user will return to the USSD menu - - They navigate back to exchange in less than 1 minute and 'confirm exchange quote' (new USSD excahnge menu needed) (the 'confirm Redeem excahnge quote') - - 'confirm Redeem quote' will only show up for a minute - otherwise they have to ask for another quote - - Please type your PIN to confirm - - The user should get a Mpesa responce for recieving the **Mpesa_given** - ### USSD Interface ### -- User chooses Excahnge Menu option #1 Check Excahnge Rate -- Redeem 1000 CIC -- Calculate a quote .... : -- Quotation: Date. -- SMS: You will receive at least 800 KSH for 1000 CIC. (MVP) - - getQuoteRedeemCIC(amount, CIC): - - mvp: return amount = amount - amount * rate; /// Rate is 10% - - best: web3 calls to purchaseReturn -- On the Exchange menu - option #3 is Confirm Quotation: - - Please confirm: "You will receive at least 800 KSH for 1000 CIC." - - Yes. - - mvp: GE receives the 1000 CIC - - best: Then we try a conversion ... with a Min return. - - best: 1000 CIC is sent to the contract (on blockchain) - (xDAI is sent to the GE float account - to be cleared later) - - Mpesa as in the quote - is sent to the user - +- Option #4 Exchange + - #1 Get Exchange Rate + - #2 Confirm Exchange -- When a user chooses to ``Contribute get Quote```: - - They should enter the amount of Mpesa they wish to contribute - - They should get a confirmation Based on a quote from the blockchain in a SMS: - - You will recieve **CIC_given** for **Mpesa_excahnge_amount** please confirm this quote in the USSD menu to proceed: (note this is from blockchain and will change second by second) - - The user will return to the USSD menu - - They navigate back to exchange in less than 1 minute and 'confirm exchange quote' (new USSD excahnge menu needed) (the 'confirm Contribute excahnge quote') - - 'confirm Contribute exchange quote' will only show up for a minute - otherwise they have to ask for another quote - - Please type your PIN to confirm - - The user should get a SMS responce from GE for recieving the **CIC_given** - -User chooses Excahnge Menu option #2 -- Contribute KSH - returning CIC -- Calculate a quote .... : -- Quotation: Date. -- SMS: You will receive at least 1200 CIC for 1000 KSH. (MVP) - - getQuoteContriuteKSH(amount, CIC): - - mvp: return amount = amount + amount * rate; /// Rate is 10% - - best: web3 calls to purchaseReturn -- On the Exchange menu - option #3 is Confirm Quotation: - - Please confirm: "You will receive at least 1200 CIC for 1000 KSH." - - Yes. - - mvp: SMS: Please send 1000 KSH to PayBill account number [phone number] - - best: Then we try a conversion ... with a Min return. - - best: xDAI is sent to the contract (on blockchain) - (xDAI is sent to the GE float account - to be cleared later) - - CIC as in the quote - is sent to the user +- 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 + + From ce824818a332d44182339a33dbab5aa4ce838d40 Mon Sep 17 00:00:00 2001 From: Will Ruddick Date: Sat, 18 Jul 2020 05:14:16 +0000 Subject: [PATCH 19/23] bDai --- ...ration.md => 002_dai_reserve_migration.md} | 23 ++++--------------- 1 file changed, 5 insertions(+), 18 deletions(-) rename spec/{002_xdai_migration.md => 002_dai_reserve_migration.md} (69%) diff --git a/spec/002_xdai_migration.md b/spec/002_dai_reserve_migration.md similarity index 69% rename from spec/002_xdai_migration.md rename to spec/002_dai_reserve_migration.md index 817ca65..aa4d5a2 100644 --- a/spec/002_xdai_migration.md +++ b/spec/002_dai_reserve_migration.md @@ -1,4 +1,4 @@ -# xDAI Migration spec +# x/bDAI Migration spec -* Authors: Firstname Lastname (url) -* Date: YYYY.MM.DD -* Version: 1 +* Authors: Gustav Friis +* Date: 2020.07.28 +* Version: 0.1 * Status: Pre-draft -## Rationale - -## Before - -## After - +## Purpose -## Implementation - -## Testing - -## Changelog -