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 ###