From 6cab40a908e53da6216811011aa580ef42d785cb Mon Sep 17 00:00:00 2001 From: Daniel Cason Date: Fri, 8 Mar 2024 08:49:49 +0100 Subject: [PATCH] spec/english: references to the Gdocs spec --- specs/english/starknet/validator_set.md | 61 +++++++++++++++++++------ 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/specs/english/starknet/validator_set.md b/specs/english/starknet/validator_set.md index a9a8cc5cb..34be29c9d 100644 --- a/specs/english/starknet/validator_set.md +++ b/specs/english/starknet/validator_set.md @@ -8,6 +8,9 @@ Principles: - Validators must acknowledge to Ethereum the inclusion of validator set updates in committed blocks +The Starkware team has produced a document describing their specification and +requirements on [Google docs][starkware-spec]. + ## Epochs The heights of the blockchain are divided into sub-sequences with a predefined @@ -22,6 +25,13 @@ in blocks or heights, of any epoch: > Example: if `E = 3`, heights `0, 1, 2` belong to epoch `0`, > heights `3, 4, 5` belong to epoch `1`, etc. +In the [Starkware spec][starkware-spec] a different nomenclature is adopted: + +- Epoch `e` is represented by "Starknet Validator Epochs" or _SVE_; +- The length of an epoch `E` is represented by _N_, the number of blocks in a _SVE_. + +### Use of Epochs + In the context of validator sets and validator set updates, epochs are relevant for two reasons: @@ -48,7 +58,7 @@ transactions included in the block, committed at height `H`. > be adopted in future heights, belonging to future epochs. We define `S(H)` as follows, where `H_0` denotes the first height of the -current branch of the blockchain: +blockchain: - `S(H_0)` is known a priori by all participants (e.g., from genesis); - For every height `H > H_0`, `S(H) = S(H-1) + updates(H)`. @@ -60,6 +70,12 @@ where `apply` is a deterministic function. The validator set updates in `updates(H)` are applied to `S(H)` in the order in which they appear in block `H`. +The first height of the blockchain `H_0` is typically `H_0 = 0` for new +blockchains. +Due to the possibility of [forks][forks-spec], we consider a fork as a new +instance of the blockchain, which can start from an arbitrary height `H_0`. + + ## Validator Sets We denote by `V(e)` the validator set adopted in heights of an epoch `e`. @@ -70,27 +86,33 @@ The validator set `V(e)` used in epoch `e` is the validator set computed two epochs before `e`, namely the value of the state variable `S` in the last height of epoch `e - 2`. In the case where epoch `e - 2` does not exist or it is not part of the -current branch of the blockchain, the initial state `S(H0)` is considered. +current branch of the blockchain, the initial state `S(H_0)` is considered. More precisely: -- `V(e) = S(max{H', H0})`, where height `H' = last(e - 2) = (e - 1) * E - 1` +- `V(e) = S(max{H', H_0})`, where height `H' = last(e - 2) = (e - 1) * E - 1` -The validator set of the first epoch in the current execution is always the -"genesis" validator set `S(H0)`. +The validator set of the first epoch present in a branch of the blockchain is +the validator set `S(H_0)`, where `H_0` is the first height of that branch. +This distinction is important, in terms of validator sets, because when there +is a [fork][forks-spec] in the blockchain, the new branch starting from height +`H_0` has is validator set _reset_ to `S(H_0)`. +This means that `S(H_0)` is not computed in the usual way, i.e., derived from +`S(H_0 - 1)`, but externally _enforced_. -> Example: if `E = 3` and the current branch of the blockchain starts at height -> `H0 = 3`, then the validator sets: +> Example: if the current branch starts in height `H_0 = 3` and `E = 3`, +> then the validator sets: > - `V(3) = S(5)`, as `5` is the last height of epoch `e - 2 = 1`, formed by > heights `3, 4, 5`. -> - `V(2) = S(3)`, the "genesis" state `S(H0)`, as `2 < H0` is the last height -> of epoch `0`. -> - `V(1) = S(3)`, the "genesis" state `S(H0)`, as epoch `e - 2 = -1` does not exist. +> - `V(2) = S(3)`, the initial validator set `S(H_0)` of the branch, +> as `last(e - 2) = 2 < H_0 = 3`. +> - `V(1) = S(3)`, the initial validator set `S(H_0)` of the branch, +> as epoch `e - 2 = -1` does not exist. -It is possible to simplify the algorithm to compute the validator set for an -epoch if we introduce an intermediate variable `nextV(e)`, which stores -validator set for epoch `e + 1`. -At the beginning of a new epoch `e`, that is, in height `H = first(e) = e * E`, -we update the current and next validator sets as follows: +It is possible to simplify the algorithm to compute the validator set for a +regular epoch, i.e., that is not the first one of a branch, if we introduce an +intermediate variable `nextV(e)`, which stores validator set for epoch `e + 1`. +At the beginning of a new epoch `e`, in height `H = first(e) = e * E`, +we update the state variables as follows: - `V(e) = nextV(e - 1)`, i.e., the current validator set is the previous next validator set. @@ -100,6 +122,12 @@ we update the current and next validator sets as follows: At the end, this algorithm is very similar to the one adopted in CometBFT, if we replace heights by epochs. +In the [Starkware spec][starkware-spec] a different nomenclature is adopted: + +- `V(e)`, the current validator set, is referred to as _V_; +- `nextV(e)` is referred to in the text as _Staged Updates_; +- `S(H)`, where `e(H) = e` is reflected to in the text as _Pending Updates_. + ## Interaction with L1 Up to here, the specification considers the protocol for configuring and @@ -151,3 +179,6 @@ added to a list of pending updates in the associated Ethereum contract. Once a proof of a Starknet block `H` containing `u` is received and validated, the Ethereum contract that has produced `u` marks the validator set update `u` as completed. + +[starkware-spec]: https://docs.google.com/document/d/1OaYLh9o10DIsGpW0GTRhWl-IJiVyjRsy7UttHs9_1Fw +[forks-spec]: ./forks-TODO.md