# Polka Analytics
Documentation for existing problems in the [Polkadot Community](https://polkadot.network/community/) relevant to Polka Analytics (A data visualization platform for Polkadot) and possible solutions.

Table of contents
---
[TOC]

---
User Stories
---
- As a (wannabe) _nominator_, I want to stake tokens (DOT or KSM) on validators to make a profit.

- As a (wannabe) nominator, I want to find the validators with the highest return and the lowest risk to optimize my earning potential.

- As a (wannabe) nominator, I want a list of _"best"_ validators to stake tokens on, to optimally earn rewards.
- As a (wannabe) nominator, I want previous history of slashes of a given validator to evaluate the risk of a potential investment.
- As a (wannabe) nominator, I want previous history of returns for a given validator to speculate future returns.
- As a (wannabe) nominator, I want reliable precalculated expected returns with error bounds for a given validator to save me the trouble of figuring out the earning potential.

### Existing Problems

1. The knowledge barrier for entry to become a nominator is high. There's not enough abstraction for the nominator to simply look at what's the incentive for them and stake.
2. The simplest existing guide for becoming a nominator is [this article on Medium](https://medium.com/@meleacrypto/how-to-nominate-and-choose-a-validator-substrate-polkadot-kusama-easy-guide-4d40197ec094). Which is still too much information for a potential nominator who just wants to stake their tokens to make profit.
3. [Telemetry](https://telemetry.polkadot.io/) provides a lot of information about the validators and what's happening in the chain but provides no information in plain english on how to use that information (even better would be if it makes use of that information and just provides the analysis).

### Potential Solutions (Relevant to Polka Analytics)

1. A step-by-step, straight forward guide to speculate the earning potential and stake, with tools to aid the same.
2. Visualization charts for slash history and reward history.
3. A voting/recommendation system allowing existing nominators to "recommend" or "denounce/blame" a particular validator, allowing others to see the reliability of the same.
4. Expected reward calculator allowing (wannabe) nominators to enter the stake amount and get the result.

Low Fidelity Mockups
---

The above image is the first version of the mockup. The landing page concept will stay the same, but the layout for Viz and Calculator will change as shown below.
The screens shown above are a revised UI mockup for Polka Analytics platform. This follows a dashboard-like layout. The left column has all the tools and menu items, and the main section has all the content for the selected tool/section.

The platform is divided into 3 main parts:

- Network Monitor (Viz)
- Stake & Earn (Calculator)
- Explorer (Validator List)
- Explorer will contain validator cards which lead to validator pages
- The validator page will contain detailed information about the validator along with charts to visualize data.

Product Analytics
---
The written copy would be similar in the lines of MetaMask, clearly stating what we will track and what not. It should be made clear that all data will be anonymous and will never be used for marketing purposes. The fact that user can opt-out anytime should be clearly stated along with the procedure.


A pull-out drawer at the bottom of the screen can be used to include all information and allow the user to see it easily if they want to, without having to read the entire ToS or privacy policy. Once the user's response to their preference has been recorder for (at least) that session, they shouldn't be prompted for the same again, but should know where they can access the same to change their input. This could be a small info icon on the bottom right corner of the screen.

## Execution Plan

### Phase 1

https://xd.adobe.com/view/d1aa22bc-55db-400f-5629-c1777a647b20-a79b/

Phase 1 will attempt to provide a solution to the following problems/questions:

- [How much reward does a particular validator offer?](#How-much-reward-does-a-particular-validator-offer)
- [Which validator will give me the maximum ROI?](#Which-validator-will-give-me-the-maximum-ROI)
- [What are the available validators to stake on?](#What-are-the-available-validators-to-stake-on)
- [How do I stake my tokens?](#How-do-I-stake-my-tokens)
- [Ethical Product Tracking](#Ethical-Product-Tracking)
- [SEO](#SEO)
- [Twitter presence](#Twitter-presence)
- [Kusama Viz fixing issues](#Kusama-Viz-fixing-issues)
- [Development fixes](#Development-fixes)

#### How much reward does a particular validator offer?

→ Each list item will contain the following information:

- Validator Name
- Controller Id
- Stash Id
- Total bonded amount, delegated balances amount
- Expected Daily Reward for unit stake

#### Which validator will give me the maximum ROI?

→ The validator providing the maximum reward will be listed on top of the page as well as in the list. The list will be sorted in decreasing order of the expected reward.

#### What are the available validators to stake on?

→ An exhaustive list of all validators will be available on the platform

#### How do I stake my tokens?

→ To answer this question, we'll build a straight forward, step by step guide explaining how to create an account, get tokens and finally stake them. In doing this, we shall abstract all unnecessary information which is irrelevant or not important for achieving the simple goal of staking tokens.

#### Ethical Product Tracking

→ We'll only track the number of visitors and what part of the product they are using. All data will be anonymous and will not be recorded without clear consent of the user. We'll use [Amplitude](https://amplitude.com/behavioral-analytics-platform) as the tool for product analytics.

#### SEO

→ Currently, the pages haven't been set up to be indexed by search engines at all. The following needs to be done:
- Use SSR [freeCodeCamp Reference](https://www.freecodecamp.org/news/demystifying-reacts-server-side-render-de335d408fe4/), [robots.txt Reference from Google](https://support.google.com/webmasters/answer/6062608?hl=en&ref_topic=6061961)
- Use [React Helmet](https://github.com/nfl/react-helmet#react-helmet) to add `meta` tags for *Polkaviz Project* components.

#### Twitter presence

→ A twitter bot that will tweet the following events on the Kusama Network:

- Most backed validator for the era,
- Milestone events
- New additions to the network

#### Kusama Viz fixing issues

- Rethinking and executing the elements around KusamaViz due to network activity. There are so many validators now which our design didn’t account for earlier.
- Creating specific views (similar to Alexandor Network):
- How many nominators are backing a given validator?
- What validators is a particular nominator is backing?

#### Development fixes

- Bugs that we have encountered that we haven’t been able to fix.
- Technical debt that has occurred in the project due to shipping out MVP code.
- Setting up CI tools, we want to automate the following:
- PolkadotJS package automatic updates:
- The package is a core dependency to get data for the above visualizations, and is in fast iteration at the moment. The Viz breaks most of the time due to these updates.
- Auto-Deploy to Surge:
- When merging to dev - to dev-polkaviz
- When merging to master - to polkviz

---
### Phase 2

Phase 2 will attempt to provide a solution to the following problems/questions:

- [What has been the history of rewards (expected and actual) for a given validator?](#What-has-been-the-history-of-rewards-expected-and-actual-for-a-given-validator)
- [What has been the history of slashes for a given validator?](#What-has-been-the-history-of-slashes-for-a-given-validator)
- [How many nominators have previously backed a given validator and with how much stake?](#How-many-nominators-have-previously-backed-a-given-validator-and-with-how-much-stake)
- [Which validator is the safest bet?](#Which-validator-is-the-safest-bet)
- [Which validator is the most optimal bet (best balance between risk and reward)?](#Which-validator-is-the-most-optimal-bet-best-balance-between-risk-and-reward)

#### What has been the history of rewards (expected and actual) for a given validator?

→ A chart displaying the history of expected and actual rewards (to facilitate easy comparison and analysis) for each validator.

#### What has been the history of slashes for a given validator?

→ A chart displaying the history of how often a validator has been slashed (and how many tokens it cost in total and how much it would have cost if 1 DOT was staked)

#### How many nominators have previously backed a given validator and with how much stake?

→ A chart displaying history of the number of validators backing a given validator in each era. Another chart displaying how much delegated balance a given validator had in each era.

#### Which validator is the safest bet?

→ This will be calculated by as:
`reliability = slash density + f(t)`,
where `slash density = (number of slashes/number of era)` and `f(t) = some function of time`. The validator with the highest reliability will be the safest bet.

#### Which validator is the most optimal bet (best balance between risk and reward)?

→ This will be the validator with the highest reward for the lowest risk.

---
### Phase 3

Phase 3 will attempt to provide a solution to the following problems/questions:

- [How to visualize what's going on in the network?](#How-to-visualize-what%E2%80%99s-going-on-in-the-network)
- [What does the community say about a particular validator?](#What-does-the-community-say-about-a-particular-validator0)
- [How do I track and manage my staked tokens, available tokens, etc.?](#How-do-I-track-and-manage-my-staked-tokens-available-tokens-etc)

#### How to visualize what's going on in the network?

→ Integration of PolkaViz into the Polka Analytics dashboard.

#### What does the community say about a particular validator?

→ Allowing upvote, downvote and comments by authenticated users.

#### How do I track and manage my staked tokens, available tokens, etc.?

→ A dashboard for authenticated users with the following information:

- Available tokens
- List of validators on whom tokens are staked along with information on how many tokens are staked, since when, and what were the earnings for them over time
- Chart of history of change in tokens over time

Execution Timeline
---

gantt
    title Phase 1
    dateFormat  DD-MM-YYYY
    section Calculator
    Predict earnings           :a1, 25-11-2019, 3d
    Validator Table     :a2, after a1  , 1d
    Staking guide        : after a2, 1d
    section Twitter Bot
    Task in sec      :29-11-2019  , 2d
    another task      : 2d

#### Tasks

## Part 1
- ### Kusama Calculator
- [ ] (3d) Using past era points predict future daily earnings
- [ ] (1d) Create a table using [Ant Design Table](https://ant.design/components/table/) for validators containing:
- [ ] Validator Nickname
- [ ] Controller Id
- [ ] Stash Id
- [ ] Commission
- [ ] Expected Reward (for given stake)
- [ ] Validator Rank (based on maximum ROI)
- [ ] (1d) Step by step staking guide for nominators

- ### Analytics
- [ ] (2d) Use [Amplitude](https://amplitude.com/) for product analytics.

- ### SEO (1d)
- [ ] Use SSR [freeCodeCamp Reference](https://www.freecodecamp.org/news/demystifying-reacts-server-side-render-de335d408fe4/)
- [ ] Use [React Helmet](https://github.com/nfl/react-helmet#react-helmet)

- ### Twitter Bot
- [ ] (2d) Awareness on how the bot will function
- [ ] (1d) Find tools to render GIFs based on events
- [ ] (2d) Execution, including the following events
- [ ] Milestones (Significant finalized blocks)
- [ ] Additions to the network
- [ ] Daily highest era points validators
- [ ] Daily highest ROI validators (optional)

## Part 2
- ### Kusama viz fixes
- [ ] (1d) Number of validators UI fix
- [ ] (1d) UI Animations and designs (optional)
- [ ] (3d) Use [Travis CI](https://travis-ci.org/) for:
- [ ] PolkadotJS package automatic updates
- [ ] Auto-Deploy to Surge:
- [ ] When merging to dev - to dev-polkaviz
- [ ] When merging to master - to polkviz
- [ ] (2d) Specific views fixes