cic-docs/spec/007_eMoney_integration.md

99 lines
5.9 KiB
Markdown
Raw Normal View History

2020-05-18 15:41:40 +02:00
## Incoming Sarafu ##
2020-06-30 07:59:31 +02:00
When users exchange CIC <> National Currency we have to manually send them Mpesa or CIC.
2020-05-18 15:41:40 +02:00
We would like to automate this.
## Solution ##
Configure - using our own system AfricasTalking API to automatically send Sarafu / Mpesa based on rules:
2020-06-30 09:11:05 +02:00
- 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
- blockchain_CIC_reserve = the total reserve (xDAI) of the CIC on the blockchain
- trr = the connector weight on blockchain converter between supply and reserve
2020-06-30 08:41:09 +02:00
- 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
2020-06-30 08:41:09 +02:00
- 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
2020-06-30 08:41:09 +02:00
- 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
- 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%
2020-05-18 15:41:40 +02:00
2020-06-30 09:11:05 +02:00
### Incoming CIC Rules - MPESA out ###
2020-06-30 07:59:31 +02:00
- *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
2020-05-18 15:41:40 +02:00
- *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:
2020-06-30 09:11:05 +02:00
- CIC_excahnge_amount = the amount of CIC the user wants to excahnge
2020-06-30 07:55:23 +02:00
The Reserve (xDAI) pulled out
2020-06-30 09:11:05 +02:00
> 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**
2020-06-30 09:11:05 +02:00
2020-05-18 15:41:40 +02:00
2020-06-30 07:59:53 +02:00
### Outgoing Sarafu Rules - MPESA In ###
2020-06-30 07:55:23 +02:00
- *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
2020-05-18 15:41:40 +02:00
- *time* No limit
2020-06-30 08:41:09 +02:00
- *Mpesa_excahnge_amount* The amount of CIC given should be calculated as follows:
2020-06-30 09:11:05 +02:00
- reserveIn_xDAI = Mpesa_excahnge_amount **KSH => USD** rate (this will come out of the xDAI float account)
2020-06-30 07:55:23 +02:00
The amount cashed in = cash_in_amount
2020-06-30 09:11:05 +02:00
> CIC_Created = the amount of CIC created on chain by adding the reserveIn_xDAI
2020-06-30 07:55:23 +02:00
- **CIC_given = CIC_Created - CIC_created*FeeM2CC ()**
2020-06-30 08:41:09 +02:00
### Exchange Rate ###
When dislaying the SPOT price or excahnge rate to a user we should use the following formula:
2020-06-30 09:11:05 +02:00
> Exchange Price = CIC_reserve / (CIC_supply * trr)
2020-06-30 08:41:09 +02:00
### User Interface ###
- When a user chooses to ``Redeem```:
- They should enter the amount (limited to the max in their balance)
2020-06-30 09:11:05 +02:00
- 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
2020-06-30 08:41:09 +02:00
- 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
2020-06-30 09:11:05 +02:00
### Credit Clearing ###
2020-06-30 08:41:09 +02:00
2020-05-18 15:41:40 +02:00
### Security ###
2020-06-30 07:55:23 +02:00
- 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
2020-05-18 15:41:40 +02:00
- 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).