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.
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.
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:
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 toEVANOR
. 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.
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.
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.
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.
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:
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
.
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.
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 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 :
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 as a basis for our smart contacts:
EVANOR
& vice versa (Case of a driver who wants to withdraw his money from his wallet).EVANOR
token versus FIAT tableA 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.
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 ..@eva.coop 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.
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.
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.
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?
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
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!
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
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).
The following diagrame presents the high level architecture of the API