cic-docs/spec/006_Self_Service_Token.md

# Current Platform Incentives spec

<!--
valid status values are: Pre-draft|Draft|Proposal|Accepted
-->
* Authors: Will Ruddick <willruddick@gmail.com> (grassecon.org)
* Date: 2020.05.18
* Version: 1
* Status: Pre-draft

## Rationale
Enabeling users to create their own tokens is one of the main goals of CICs 

## Intro 
Today users only receive tokens created by Grassroots Economics - the reserves of these tokens are donors giving to Grassroots Economics. 
This means Users have very little ‘feeling’ of reserve depletion because it is not their token and not their money behind it.
We want users to be able to create their tokens to create more ownership and diffusion.
A CIC primarliy represents the goods and services committed by the Issuer - which should be a Group Account.
The CIC has an enforced 25% reserve amount.

## Token creation process - UI 
(I will describe this for USSD be a web interface should also be made)
1. Existing User calls Sarafu
   - New user dials ***483****46# where she selects 
   - My Account -> Create Token
   - Note that this ability is whitelisted- to be whitelisted the user must have:
     1. Been a chama account in the system as an active user for some time (at least 3 months)
     1. Have a substantial token balance (his CIC converted to reserve) to reach at least 25% reserve. Minimum 100 USD in value DAI. 
     2. Which will staked into the converter and leveraged into 4x of CIC tokens (the value changes as reserve is removed). 
2. Default Token Options
   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)
3. Chosen Options
   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.
   3. What goods or services will be accepted for these tokens?
   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.
   5. Note that members must ‘join’ the token (via USSD) using the TOKEN_NAME to receive this.
4. Pin 
   * “Enter PIN
   * _______________” 
   * Repeat Pin 
   * “Enter PIN again  
   * _______________”
   * 
   * Pop Up: 
   * “Your TOKEN_NAME token is being created. 
   * You’ll receive an SMS when your token is ready.”  
   * 
   * Error:
   * If the user doesn’t repeat the same password pop up with the text 
   * “Wrong PIN, please try again” 
   * 
   * Clicking back will lead to Repeat Pin screen
5. “You will receive an SMS when your TOKEN_NAME token is ready”
6. Approval
   * At this stage, the wallet creation starts confirmation SMS will be sent only when the Backend process (see below) is over.
   * If token creation succeeds: 
   * Send an SMS to the user with the following text 
   * “You have just created the TOKEN_NAME token!
   * Dial *483*46# to use TOKEN_NAME token
   * Tell your members to JOIN TOKEN_NAME via My Account”
   * If account creation fails: 
   * Send an SMS to the user with the following text: 
   * “Whoops! There was a problem creating your token. To try again Dial *483*46#. If issues persist contact support: 0757628885”

## Token creation process - Backend 

Start this process between step 5 to 6,
Save all the information created in the process on the SEMPO DB.
Generate a token and converter (adding it to the registry) on xDAI and store private and public keys
Mint the standard amount of tokens. (4x the reserve = 40,000)
Convert the existing user's tokens into xDAI and put them into the converter as reserve. (min 10,000)
The new token should have a value of 1:1 with xDAI and be at 25% reserve (Target Reserve Ratio)
Put the TOKEN_NAME tokens into the Users wallet (Group wallet) - note that when other users later join (via my account -> join Chama)  the TOKEN_NAME they will receive tokens from this wallet. - there is a contract here. 
The token owner should not be able to transfer more tokens than he has committed to new users.
The token owner should have his community token for auto-convert set to TOKEN_NAME
This account is a GROUP account. Meaning that only it can cash out 50% a month from it’s own reserve - along with other Chama rules.
If the token has been created send the SMS for the token creation approval. Else send error.


## Action items:
Token Value Alerts
Whenever the token is converted to another token or xDAI and the price changes more than 10% an alter is sent to the token issuer
Message Alert your excahnge value of TOKEN_NAME tokens have changed in +X% / -X% value 
Note that the receipt messages for token transfers that include a conversion should also show the tokens exchange value (this was on the old USSD system)

## Implementation


### Workflow

### Variables
1. TRR for Self Service Tokens (SSTs) 0.25
2. Conversion fee fos SSTs 0.005 (0.5%)
3. Minimum starting reserve 10,000 xDAI
4. Minimum number of chama members (conversion will be locked until the new tokens are sent to this many users)
4. Token Name
5. All users should have a 'community token'
5. Auto-Conversion should by default change all tokens in a user's wallet into their community token. 
   * Note that a user with Sarafu in their wallet will shift their community token to whomever they trade with that is not in Sarafu. (Sarafu is just a temorary token)

### Interface


## Testing
1. Ensure conversions are working between tokens
2. Test out auto-conversion - one user gets sent a foreign token ... try to convert
3. The UX process and various limits - like minimum reserve
4. Ensure that any Sarafu or other token are converted to xDAI 
5. Chama cash out limits remain the same - but instead of sending a GE Agent Sarafu they are sending their own token


## Changelog
<!--
Please remember to describe every change to this document in the changelog using 
serial number:

* version 1:
-->