# Eva Platform

This document is provided to issue the required within Eva's platform and to explain the development stack. It is open for modification, it is simply how we see the platform at an high level point of view as of May 29th 2018.

## Our Vision

### The guidelines of our Minimum Viable Product
The goal is to offer an application that provides the same customer experience as Uber and Lyft. The user doesn't need any knowledge about cryptocurrency, per example manipulating his public and private owner/active keys on the blockchain and his wallet addresses.

## Our Technology
- Mobile App : React Native
- Services API : Python API using Flask, SQLAlchemy and PgSQL.
- FIAT Payment Provider: Still unknown. We look at solution like Paypal's BrainTree.
### Networking


### Services API
Behind the client app, EVA put an API to interact with the EOS Blochain, the APP and the market place. the main functionalities are the following:

- Create EOS account for a new user
- Translate user's phone number to his EOS account.
- Store users Wallet keys (for account recovery) encrypted with the user's password
- Interact with processor's API for paiement (FIAT & Crypto)

### Exchange
At EVA we've put the user experience a prime goal, and the reason of the exchange is to facilitate and enhance the user experience in the first place by allowing him to pay by any other currency.
The main currency which is going to run our smart contract is our ICO `EVANOR`, so to meet our goal we will be facing a big challenge to convert the FIAT to`EVANOR`. We will accept other cryptocurrencies in further improvements.

We observe two possible cases when a rider wants to initiate a riding smart contract with a driver.

#### The ride hailing smart contracts returns `INSUFICIENT_FUNDS`
The exchange will be connected in real time third party payment processors for FIAT currencies.

The following examples demonstrate how the communication could work between different agents for a 10$ USD ride.


#### The ride hailing smart contracts returns `ENOUGH_FUNDS`
Because the rider's wallet has enough tokens to proceed on the contract with the driver, he will simply proceed to the next step which is initating the contract.

#### How will the token rise?
The main idea is to raise the value of the `EVANOR` token. In order to do that, it is simple. We need more FIAT coming in than getting out. We can do that by always selling the token (when the drivers want to cash out in FIAT) at a lower price than the token buying price in FIAT.

The market place is proposing only one single price for the token. There is no possibility for the user to propose his price. In fact, it is not really an exchange but more of an evanor token provider. The exchange is always between EVA's Services API token reserve and the wallet of the user.

The EVA token reserve is getting new `EVANOR` tokens when it pays a driver in FIAT currencies. The reserve looses `EVANOR` when it is transferring tokens to a rider in exchange of FIAT money.

An example of the amount of EVA token within the reserve could be `5-10%` of the total tokens in the ecosystem. Of course, this reserve will have to be hold across many secure wallets at different locations in order to prevent any attacker to steal all the tokens.

The percentage of the total tokens held by this reserve will have to be carefully studied. Running out of tokens would be catastrophic.


The total market cap valuation within the ecosystem needs to be known in order for the system to know the proper price at which it will offer the conversion in FIAT currencies.

`PRICE_OF_EVANOR_USD = (MARKET CAPITALIZATION IN USD) / (NUMBER OF TOKENS)`.

By always selling at a 5% lower price, we ensure that the token valuation is growing at each transactions. At each ride contract, as a transaction fee an arbitrary number of token will be transferred to the wallet of the local Eva community and also to Eva World. These fees will ensure the sustainability of the network within the local community for marketing, distributing free rides etc.

**Example**
The user pays 10$ USD with his credit card. He receives 20 `EVANOR` because the current market valuation is 2 USD per token. He transfers 17 `EVANOR` which is 85% of his 20 `EVANOR` in the smart contract to the driver. The driver cash out his tokens with a valuation in FIAT of 8.50 USD in total.

The transaction fees would be distributed with a model depending on the local community in which the transaction was processed. 1 `EVANOR` (5%) would go to the local eva community wallets, 1 `EVANOR` (5%) to Eva World and the rest would pay for EOS network computing fees and be forgotten? Some FIAT money coming in needs to be kept to grow token valuation in the overall network in order to create an incentive for people to keep their tokens as a return on their investment and reward early adopters to grow the network. Game theory within the ecosystem as to be perfectly though out. Still working on it.

### Customer Experience facilitator

#### New User
A new user arrives on the app. Let's call this user Melinda.
The local storage on her .APK app has not any information yet. Consequently, she sees the login view. She has no account yet, so she decides to create a new account. She provides her `phone_number`, `first_name`, `last_name`, `birth_date` and password.

- Melinda's cellphone does a `signup call` to the Services API. The API registers her information in the postgresql databse and her password is hashed and salted in a secure manner to counter rainbow tables attacks in case someone can actually read the user table. Her `sms_confirmed` is set to `false`.

- The system pokes the `Twilio API` and send an SMS to her phone number

- Melinda does a second `register` API call where she sends the `sms_confirmation_code`, `owner_private_key`, `active_private_key`, `owner_public_key` and `active_public_key`. The system generates her EOS account_name, a symmetric encryption algorithm is used to generate it. `phone_number` <-> `eos_account_name`. Using cleos and EVA SYS wallet we create her eos blockchain account. Only EVA corporation has the translating key in case we need to trace the individual for criminal activities.

> We need here to prevent DDOS attacks with fakes SIM's card in order to prevent emptying our SYS tokens to generate new accounts. Maybe an in-house POW could solve the problem.

- The Services API saves all Melinda's keys and encrypts it with her password. The API returns all the EOS information she needs and her client app saves it in the `local storage`

- Melinda is now connected in the app

The following diagram resumes the process detailed above:


#### Returning user

Melinda is returning on the app. If she has her EOS information stored on her `local storage`, she is connected.
Otherwise, she logins by providing her phone number and password.

- The client sends the payload to the Services API, the backend verifies the hash of the password, in case of success it decrypts the EOS account payload within the database with her plain text password and returns it.

- The mobile app stores the EOS account information on the `local storage`.

#### Account recovery

The sad thing with this design is we don't have any solution yet to provide any account recovery mechanism because the system has no plain text version of the password in order to decrypt the payload describing the EOS account information of a user.

#### Transfer of tokens between users

An interface will provide the possibility to send `EVANOR` to friends or family. The user will simply provide the phone number of the accounts he wants to transfer some evanor to.

- A payload will be sent to the services API containing the proper keys to issue the token transfer and the destination phone
- The services API will translate this phone number into an EOS account name and send the transaction to the blockchain

## Mobile App

A mobile app is developed using React Native. It is using the library eosjs to talk with the EOS blockchain and the HTTP(S) protocol to communicate with the SERVICES API. Certificate Pinning counters will have to be implemented in order to make it hard for an attacker to eavesdrop the Services API endpoint architecture. This will prevent spamming of our services API.

The challenges on the client side are :

- GPS Navigator using Google Maps
- Local geocoding
- Minimizing the GMaps api calls in order to minimize api fees.
- Communicate securely with the services API server
- Generate Keys.

## EOS Smart contracts
We still don't know if only one smart will be created or many. We simply have high levels needs in the system right now to provide, we will use **Max Gravitt** `EOSRide` [project](https://github.com/gravitt8460/eosride) as a basis for our smart contacts:
- Conversion FIAT to `EVANOR` & vice versa (Case of a driver who wants to withdraw his money from his wallet).
- Price of the lift, base on the distance and the time of the ride. we will use goole map API to get this information.
- Ride reservation, it verifies if the user has sufficient funds on his wallet before contacting the nearest driver.
- Payments between User, Driver and Eva wallets

### Current prices of `EVANOR` token versus FIAT table

A cronjob on one of Eva's server could have the authority to write this table from the current market between currencies. This table would be the reference within the system to propose a FIAT/EVANOR conversion.

It could be even better if it could update itself automatically when FIAT money is going inside or outside the EVANOR economy. There is still a need to consider the valuation between FIAT currencies that changes through time.

| LOCAL_CURRENCY | EVANOR_CONVERSION |
| -------- | -------- |
| CAD | 2.1 |
| USD | 1.7 |
| EUR | 1.5 |
| GBP | 1.3 |

This approach still seems centralized even if its deployed on the blockchain, we can think of a way we could do the thing truly decentralized. We still need to get how the FIAT currencies valuation are behaving with a third party API though.

### Eva communities table

This table represents a listing of Eva's communities throughout the world. A user that sends his latitude/longitude onto the blockchain that doesn't fit in any geographical polygon will be warned: `The city you are in does not offer Eva's ride-hailing service, contact us at [e-mail] blablabla`

| COMMUNITY_PK| LAT_LON_BOUNDS | NUMBER_MEMBERS | TIMESTAMP_CREATED |
| -------- | -------- | -------- | -------- |
| MTL_QC_CA | [(1.2,1.4), ... ] | 3500 | 1527654386 |
| NYC_NY_US | [(1.2,1.4), ... ] | 47301 | 1527354386 |

Only Eva World authoritative accounts can create a new community for now.

### Eva communities ride algorithm pricing table
In order to have a different fee model algorithm depending on the community in which Eva is operating, the fees model must be different depending on the geographical polygon of the community. This model has to be different because the reality of each market is different.

| COMMUNITY_PK| FIAT_PER_KM | FIAT_PER_MIN | LOCAL_FIAT |
| -------- | -------- | -------- | -------- | -------- |
| MTL_QC_CA | 0.3 | 0.5 | CAD |
| NYC_NY_US | 0.4 | 0.7 | USD |

An authoritative community account has the write access to his own `FIAT_PER_KM` and `FIAT_PER_MIN` field. Eva World authoritative accounts could also write on it.

### Eva communities fees structure

| COMMUNITY_PK| RATIO_LOCAL | RATIO_WORLD | LOCAL_ADDRESS | WORLD_ADDRESS |
| -------- | -------- | -------- | -------- | -------- |
| MTL_QC_CA | 0.04 | 0.06 | EOS ... | EOS ... |
| NYC_NY_US | 0.05 | 0.05 | EOS ... | EOS ...|

Only an Eva World authoritative account can modify this table.
It represents the tokens fees distributed at each ride to EVA local and EVA World for a community.

### Riding Smart Contract between driver and rider users.

We will base the rider/driver contractual arrangement based on Max's `eosride` GitHub project.
> There's still an open debate about how the rider --> driver token transfer will be processed, will it be only when the rider arrives at his location? Or will the token be send linearly during the ride?

### Accounts table
The account table should be based on eosio.token contract. It has to handle the `is_driver` field. If the account is a driver it has to be link with a community because the driver is registered legally only in this community. There's no need for

- Only a community authoritative account can promote a user to be a driver in their community.
- Only Eva World authorative accounts can issue a community authoritative account
- Only the contract owner account can generate Eva World authoritative account.

### Example of the stack

Melinda is a rider and bob is a driver.

Melinda has no `EVANOR` tokens in her wallets, she is querying the ride-matching smart contract to get a price from point **A** towards point **B**.

She sends the `estimated_minutes` , `estimated_distance`, `lat`, `lon` to a smart contract in order to receive an estimated price in EVANOR tokens.

If she has enough tokens she calls the smart contract to initiate a ride and find a matching rider, which is bob.

Otherwise, she calls the blockchain to convert this price in her local FIAT currencies. The community fees she has are the one within her latitude and longitude. She sends the payment in FIAT to the payment provider by filling her credit card information or press OK if the local storage already has it.

She is now fetching the current balance in her wallet until she has enough `EVANOR` tokens to proceed with the contract.

Bob as a driver, is periodically fetching the blockchain to know if a ride opportunity is near in a certain radius of him.

A `first comes first` algorithm links Melinda with Bob. Bob is the first driver that has sent he's willing to give the ride to the blockchain.

Bob has to verify on his client if the distance/time proposed his realistic with the GMaps API on his client. If the payload was corrupted by an evil Melinda, he drops the contract. If the information sent by Melinda, he confirms and the contractual arrangement is set.

The ride can start!

### Disclaimer

We're really open to discussion. Our newcomers experience within the blockchain dApp community may have a negative impact on how we think this system should work. Let's find the best solution as a team :D

## Deployment
The whole architecture on the backend will be based upon docker containers to facilitate the mangement and the scalabily of the platform.
The palteform will be hosted in the cloud (DigitalOcean), inside kubernetes or Swarm cluster (not decided yet).

## High level architecture
### EVA-API
The following diagrame presents the high level architecture of the API