grassrootseconomics
/
cic-docs
5
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
cic-docs/spec/007_eMoney_integration.md

6.2 KiB
Raw Blame History

Incoming Sarafu

When users exchange CIC <> National Currency we have to manually send them Mpesa or CIC. We would like to automate this.

Solution

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
  • 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 and sent to the user

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 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
  • 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: 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).