Add states and rewards smooth pages

docs/smooth.md

@@ -8,7 +8,7 @@ description: Smooth introduction
 Welcome to the Smooth Documentation! This section provides valuable insights into the Smooth project, an MEV Smoothing Pool designed to enhance rewards for participants in the Ethereum network. 
 
 :::info
-This documentation is a work in progress. 
+Start by reading [Deep Dive into Smooth](/docs/smooth/deep-dive-into-smooth/overview.md) to get a general idea of what Smooth is and how it works.
 :::
 ## What is Smooth and why it matters
 
@@ -18,7 +18,7 @@ Smooth is an MEV Smoothing Pool. It helps earn higher rewards on average by pool
 
 ### Higher rewards?
 
-A Solo staker proposes 5 or 6 blocks on average per year. The chances of getting a "Lottery Block" are very slim, and most likely we are going to get rewards on the order of 0.00-something ETH. 
+A Solo staker proposes 3 blocks on average per year. The chances of getting a "Lottery Block" are very slim, and most likely we are going to get rewards on the order of 0.00-something ETH. 
 
 If we pool together all our rewards, we have collectively a much higher chance of getting lottery blocks, and then we divide the big payout among all participants! It's the same concept as Bitcoin Mining Pools.
 

docs/smooth/deep-dive-into-smooth/oracle-sm.md

@@ -0,0 +1,20 @@
+# Smooth's architecture
+
+Smooth is composed of two main components: the **Oracle** and the **Smart Contract**. These two components work together to track validators and distribute rewards fairly. Both are open source and indispensable to the functioning of Smooth. While the Smart Contract serves to track all the events related to the pool onchain (subscriptions, unsubscriptions, block proposals, etc.), the Oracle is responsible of computing the rewards of each validator.
+
+## The Smart Contract
+
+Smooth's Smart Contract is deployed on the Ethereum mainnet and is responsible for "receiving" all the events related to the pool onchain. This includes subscriptions, unsubscriptions, block proposals, and more. Since it is the Smart Contract the one who holds all the ETH collected by the pool, it is from the Smart Contract where all Smooth users will claim their rewards.
+
+Computing and storing all rewards calculations onchain would be almost impossible and very expensive, so merkle trees are used to summarize the state of all validators. This allows the Smart Contract to store a single hash onchain that represents the state of all validators subscribed to the pool. This hash is called the **Merkle Root** and **is computed by the Oracle**.
+
+
+## The Oracle
+
+As mentioned before, **the Oracle is responsible for computing the rewards of each validator**. It does so by computing a merkle tree that summarizes the state of all validators subscribed to the pool. This merkle tree, computed offchain, is summarized into a **Merkle Root**.
+
+Once every 28800 slots (4 days), the Oracle sends a transaction to the Smart Contract with the updated Merkle Root. 
+
+:::info
+It is not untill the Oracle sends the transaction to the Smart Contract with the updated Merkle Root that the rewards are available to be claimed by the validators. This means that if a validator correctly proposes a block, it will not be able to claim its rewards until the Oracle sends the transaction to the Smart Contract with the updated Merkle Root.
+:::

docs/smooth/deep-dive-into-smooth/overview.md

@@ -0,0 +1,12 @@
+# Deep Dive into Smooth!
+
+In this section, you will find an in-depth explanation on how Smooth works. This includes the different components of Smooth, all states possible of a subscribed Smooth validator, and much more!
+
+:::info
+We recommend reading and understanding the contents of this section before subscribing to Smooth.
+:::
+
+1. [**Smooth's Rewards**](/docs/smooth/deep-dive-into-smooth/rewards.md): Learn how Smooth handles incoming rewards and how they are distributed to validators.
+2. [**Validator States**](/docs/smooth/deep-dive-into-smooth/states.md): A detailed explanation of all possible states of a subscribed Smooth validator.
+
+3. [**Smooth's Oracle and Smart Contract**](/docs/smooth/deep-dive-into-smooth/oracle-sm.md): Learn how the two main components of Smooth, the Oracle and smart contract work together to track validators and distribute rewards.

docs/smooth/deep-dive-into-smooth/rewards.md

@@ -0,0 +1,42 @@
+# Rewards
+
+Recieving and distributing rewards is one of the core functionalities of Smooth. In this section we will explain how rewards are handled by Smooth and how they are distributed to validators, as well as how users can claim their rewards.
+
+## Smooth's source of rewards
+
+A `Reward` is considered to be any balance denominated in ETH that is sent to Smooth's address. When recieved, it is shared fairly among all the participants in the pool. 
+
+There are 2 main sources of rewards in Smooth:
+
+* **Block Proposal rewards**: These rewards are generated by validators within the pool. Whenever a validator successfully proposes a block, it sends the block reward to Smooth's address.
+* **Donations**: This are the rewards that are sent to Smooth's address by anyone who wants to support the project. Smooths only accepts donations in ETH.
+
+## How rewards are distributed
+
+When a validator has an active subscription to the pool (`Active` or `YellowCard` state) it is eligible for rewards, meaning that it will receive a given share of each reward that is sent to the pool. Validators in `RedCard` are considered subscribed, but don't earn rewards until they become active again.
+
+Smooth's distributes rewards to the validators as `Pending Rewards`. These are rewards that are not _consolidated_ yet, meaning that they belong to the validator but they can not be claimed yet, until a valid block proposal is sent to Smooth by that validator. 
+
+Later on, when a validator sends a valid block proposal to Smooth, all its `Pending Rewards` are transformed into `Accumulated Rewards`. These rewards are consolidated and can be claimed by the validator. 
+
+Therefore, we consider that a validator has 2 types of rewards:
+
+* **Pending Rewards**: Rewards that are not consolidated yet. They can not be claimed yet.
+* **Accumulated Rewards**: Rewards that are consolidated and can be claimed by the validator.
+
+:::info
+Dappnode receives a **7%** fee of all rewards distributed by Smooth. This fee is automatically deducted from the rewards before they are distributed to validators. This fee serves to support the development and sustainability of Smooth and Dappnode!
+:::
+
+
+## How rewards are claimed
+
+As a Smooth user, you have a third type of reward: `Claimable Rewards`. These are the sum of all your validator's `Accumulated Rewards` with the same withdrawal address that you have not already claimed.
+
+* **Claimable Rewards**: Rewards that you can claim as a Smooth user. Sum of all your validator's unclaimed `Accumulated Rewards`.
+
+Smoot's users can claim their rewards by visting [Smooth's website](https://smooth.dappnode.io/) and clicking on the `Claim All` button once logged in. This trigger a transaction that will send all claimable rewards to the user's address.
+
+:::tip
+Smooth identifies users through an ETH1 address, which serves as the withdrawal address for all your validators. If you have multiple validators associated with distinct withdrawal addresses, you will need to claim your rewards for each of them separately.
+:::

docs/smooth/deep-dive-into-smooth/states.md

@@ -0,0 +1,33 @@
+# Smooth Validator States
+
+A Smooth validator can be in multiple states depending on its behavior. In this section we will explain all possible states a validator can have, the consequences of being each state, and how a validator can transition from one state to another.
+
+## State Machine Overview
+
+The oracle employs a **state machine** to monitor the status of subscribed validators within Smooth. Various actions trigger state changes, detailed in the following image encompassing all possible transitions. Let's take a look at it:
+
+![statemachine](https://github.com/dappnode/mev-sp-oracle/blob/main/spec/states.png?raw=true)
+
+
+There are 5 different states a validator can have:
+* **Active**: A validator is active and subscribed to the pool, earning rewards over the time.
+* **YellowCard**: The validator missed only its last block proposal, but still earns rewards.
+* **RedCard**: The validator missed two block proposals in a row. In this state the validator does not earn rewards until a valid block has been proposed by it. In other words, this validator is not recieving `Pending Rewards` when somebody contributes to the pool.
+* **NotSubscribed**: The validator is no longer subscribed to the pool, but still tracked by the validator. For example, a validator that unsubscribed. Note that this is still tracked because a validator can unsubscribe but it may still have pending balance to claim. In this state the validator does not earn rewards.
+* **Banned**: The validator is banned forever from the pool. **A validator is banned when its subscribed to the pool but proposes a block with the wrong fee recipient**.
+* **Untracked**: The validator is not tracked by the pool. It never subscribed before nor has any active subscription.
+
+And 6 different actions can trigger a state transition:
+* `ProposalOk`: The validator proposed a valid block with its rewards correctly sent to the smoothing pool address.
+* `ProposalMissed`: The validator should have proposed a block but missed its proposal.
+* `ProposalWrongFee`: The validator proposes a block but with a wrong fee recipient.
+* `ManualSubscription`: The validator manually subscribes to the pool, depositing collateral for its validator index by calling the smart contract function (see event).
+* `AutoSubscription`: The validator is automatically subscribed to the pool, by setting as fee recipient the smoothing pool address.
+* `Unsubscribe`: The validator manually unsubscribes to the pool, calling the unsubscribe function from the smart contract (see event).
+
+
+## The purpose of the State Machine
+
+Beyond tracking validator statuses, the state machine ensures fair reward distribution and encourages correct behavior among validators.
+
+Validators consistently proposing blocks receive greater rewards compared to those frequently missing proposals, promoting active participation and contribution to the pool.

docs/smooth/faq-glossary.md

@@ -12,7 +12,7 @@
 </details>
 
 <details closed>
-  <summary>If I want to unsibscribe my validator from Smooth, when is the best time to do it?</summary>
+  <summary>If I want to unsubscribe my validator from Smooth, when is the best time to do it?</summary>
     Unsubscribing a validator from Smooth causes it to lose all its pending rewards. Hence, the ideal moment to exit Smooth is after successfully proposing a block. A successful block proposal transfers all pending rewards claimable, allowing you to claim them before unsubscribing. This approach minimizes the pending rewards lost when unsubscribing.
 </details>
 

sidebars.js

@@ -373,9 +373,30 @@ const sidebars = {
   smoothSidebar: [
     "smooth",
     {
-      type: "doc",
-      label: "Overview",
-      id: "smooth/in-depth-overview",
+      type: "category",
+      label: "Deep dive into Smooth",
+      items: [
+        {
+          type: "doc",
+          label: "Overview",
+          id: "smooth/deep-dive-into-smooth/overview",
+        },
+        {
+          type: "doc",
+          label: "Rewards",
+          id: "smooth/deep-dive-into-smooth/rewards",
+        },
+        {
+          type: "doc",
+          label: "Validator States",
+          id: "smooth/deep-dive-into-smooth/states",
+        },
+        {
+          type: "doc",
+          label: "Oracle & Smart Contract",
+          id: "smooth/deep-dive-into-smooth/oracle-sm",
+        },
+      ],
     },
     {
       type: "category",