# Weak Subjectivity: implementation roadmap

###### tags: `weak subjectivity`

**Author(s):** Victor Farazdagi (Prysmatic Labs)

*Last Updated: Apr 17, 2021*

[TOC]

## Overview

This roadmap outlines the tasks we need to complete to support WS as outlined in [specs](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/weak-subjectivity.md). This is a follow-up document to [Weak subjectivity todos before mainnet](/scB0xoCjRjaHM13Cf7wp5w?view) by Terence and parts of the whole of this document will become a GH tracking issue for the topic of Weak Subjectivity.

## Current state of affairs

- We've introduced an RPC endpoint to obtain block and state roots + epoch in [PR #7216](https://github.com/prysmaticlabs/prysm/pull/7216). It exposes `GetWeakSubjectivityCheckpoint()` function.
- In the `PR #7216` WS period calculations have been implemented in [slot_epoch.go:WeakSubjectivityCheckptEpoch()](https://github.com/prysmaticlabs/prysm/blob/0b06c48ed0196f2bea2df7a59013c5a95e55b7fc/beacon-chain/core/helpers/slot_epoch.go#L203), however, calculations there are outdated, and the helper needs to be updated.
- State embedding, when it comes to genesis state, has been implemented in [PR #8614](https://github.com/prysmaticlabs/prysm/pull/8614). We need to make sure that similar methods work for an arbitrary checkpoint state.

:::info
**Progress so far:**

Item | Owner | URL | Status
------|------|------------|-------
1. Calculating weak subjectivity period | Victor | [PR#8695](https://github.com/prysmaticlabs/prysm/pull/8695) | done
2. Weak subjectivity sync using a checkpoint | Victor | TBA | in-progress
3. Weak subjectivity sync using a given state | Victor | TBA | in-progress
4. Checking if weak subjectivity checkpoint is stale | Victor | [PR#8706](https://github.com/prysmaticlabs/prysm/pull/8706) | done
5. Fetching historical blocks | To be assigned | TBA | N/A
6. Exposing weak subjectivity checkpoint via RPC endpoint | Victor | [PR#8707](https://github.com/prysmaticlabs/prysm/pull/8707) | done
7. Validate peers agains WS checkpoint | Victor | TBA | N/A
:::

## Tasks

### 1. Calculating weak subjectivity period

For short-range attacks the canonical chain is protected by slashing mechanism. However, if a node stays offline for long enough, there may occur a situation when 1/3 of validators it knows about from the last sync have already exited (and have "nothing at stake"), but continue attesting, thus giving a probability of forming a chain with conflicting finalized states (exploiting retired validators and/or relying on diverging validator sets). The weak subjectivity period refers to number of recent epochs within which there must be a weak subjectivity checkpoint, to ensure that "nothing at stake" long-range attack is avoided.

We need to update [slot_epoch.go:WeakSubjectivityCheckptEpoch()](https://github.com/prysmaticlabs/prysm/blob/0b06c48ed0196f2bea2df7a59013c5a95e55b7fc/beacon-chain/core/helpers/slot_epoch.go#L203) to comply with the current [specs](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/weak-subjectivity.md#calculating-the-weak-subjectivity-period).

Owner | Link to PR | Status
------|------------|-------
Victor | [PR #8695](https://github.com/prysmaticlabs/prysm/pull/8695) | done

### 2. Weak subjectivity sync using a checkpoint
When CLI node is started with a weak subjectivity checkpoint in a `block_root:epoch_number` form, synchronization must take into account weak subjectivity requirements.

There are two cases possible:
- Checkpoint epoch is in the future (node's stored finalized epoch is lower than checkpoint epoch): during sync when node arrives at checkpoint epoch, and checkpoint root is not part of the chain, node must halt with a descriptive error.
- Checkpoint epoch is in the past (node's stored finalized epoch is higher than checkpoint epoch): before proceeding with sync, node must assert that block root at checkpoint epoch of the canonical chain is equal to the provided root. Halt the node with descriptive error, otherwise.

Owner | Link to PR | Status
------|------------|-------
Victor | TBA | in-progress

See [weak_subjectivity_checks.go:VerifyWeakSubjectivityRoot()](https://github.com/prysmaticlabs/prysm/blob/f822f0436e28d278a9cae7da00ea57d72a6be2bf/beacon-chain/blockchain/weak_subjectivity_checks.go#L15) and the corresponding [PR#7344](https://github.com/prysmaticlabs/prysm/pull/7344)

### 3. Weak subjectivity sync using a given state

Variation of weak subjectivity sync, when SSZ state is provided at startup. Node should be able to start syncing from a given state. This will augment state embedding (should we opt for embedding when distributing weak subjectivity checkpoints) and allow feeding different states w/o binary recompilation.

Owner | Link to PR | Status
------|------------|-------
Victor | TBA | N/A

### 4. Checking if weak subjectivity checkpoint is stale

To check that weak subjectivity checkpoint is not stale at the time of node startup (client either accepts state as input param, or fetches state for a specified checkpoint), the specs define [is_within_weak_subjectivity_period()](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/weak-subjectivity.md#checking-for-stale-weak-subjectivity-checkpoint). We need to support the corresponding helper method.

Owner | Link to PR | Status
------|------------|-------
Victor | [PR #8706](https://github.com/prysmaticlabs/prysm/pull/8706) | done

### 5. Fetching historical blocks

When node is started from a given state -- there should be a mechanism that will allow it to fill the gap. Node may already contain part of canonical chain (up to some epoch) or be a new node (from genesis), and backfilling blocks in between should be possible (mandatory?).

When backfilling blocks, we should allow end-users to select (with a CLI flag), whether they require to redo state transitions or just verifying block roots is enough.

Owner | Link to PR | Status
------|------------|-------
To be assigned | TBA | N/A

### 6. Exposing weak subjectivity checkpoint via RPC endpoint

One way to distribute weak subjectivity checkpoints, is by exposing some RPC endpoint which can be used to obtain one.

Currently, we do provide [GetWeakSubjectivityCheckpoint()](https://github.com/prysmaticlabs/prysm/blob/1c6c058bba13920598c69bf5346aa4e957bd0147/beacon-chain/rpc/beacon/blocks.go#L366) method, but it works incorrectly: it just provides a block root and epoch of the weak subjectivity period (where period is just a span within which there must exist weak subjctivity point).

That's if weak subjectivity period is computed to be 752, our current endpoint will return the root of the starting slot of 752th epoch.

The correct way to implement it, is to subtract weak subjectivity period from the currently known epoch, and assuming this will result in a positive number, use that epoch (or some epoch after that) as a weak subjectivity checkpoint. This is safe as weak subjectivity period, gives us range within which finalizing conflicting blocks will result in 1/3 of validators being slashed.

Owner | Link to PR | Status
------|------------|-------
Victor | [PR #8707](https://github.com/prysmaticlabs/prysm/pull/8707) | done

### 7. Validate peers agains WS checkpoint
Consider decreasing scores of peers (or marking them as bad), when they return block with the root that doesn't match that of provided weak subjectivity checkpoint.

Owner | Link to PR | Status
------|------------|-------
Victor | TBA | N/A
## Implementation plan
We'll start with support of checkpoints in form of `block_root:epoch_number` (items 1, 2 and 4). With syncing from state (item 3) following up shortly, then, allowing to back sync historical blocks (item 5). We will support distribution of weak subjectivity checkpoints using RPC endpoint (item 6).

## References

- [Weak subjectivity todos before mainnet](/scB0xoCjRjaHM13Cf7wp5w?view)
- [Specs](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/weak-subjectivity.md) and for a more in-depth of coverage of WS period calculations, see [Weak Subjectivity Analysis](https://github.com/runtimeverification/beacon-chain-verification/blob/master/weak-subjectivity/weak-subjectivity-analysis.pdf).
- [Proof of Stake: How I Learned to Love Weak Subjectivity](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/)
- [Weak Subjectivity in Eth2.0](https://notes.ethereum.org/@adiasg/weak-subjectvity-eth2)