From 66511f0daef5c9aea63fca67eadbf2a0daa8bfc2 Mon Sep 17 00:00:00 2001 From: Javed Khan Date: Mon, 23 Oct 2023 18:28:24 -0700 Subject: [PATCH 1/3] specs: add validator set specs --- state/validators.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 state/validators.md diff --git a/state/validators.md b/state/validators.md new file mode 100644 index 0000000000..af09f57596 --- /dev/null +++ b/state/validators.md @@ -0,0 +1,38 @@ +# Validator Selection Scheme + +## Abstract + +This document elucidates the validator selection mechanism as outlined in the [Rollkit repository](https://github.com/rollkit/rollkit). The scheme establishes an initial set of validators at the genesis of the blockchain, then leverages a priority-based system to determine the proposer of new blocks, ensuring a decentralized and fair block proposal mechanism. + +## Protocol/Component Description + +The protocol initializes with a predefined set of validators as stated in the `GenesisDoc`. These validators are part of the `GenesisValidator` struct which includes their address, public key, voting power, and name. Post genesis, the validator set might change, and is managed through Tendermint's `ValidatorSet` and `State` structures. + +The `ValidatorSet` represents a set of `Validator` at a given height, ordered by their voting power in descending order and secondary by their address in ascending order. The `ProposerPriority` of each validator and the designated proposer changes every round, upon calling `.IncrementProposerPriority()`. + +In the `State` struct, three kinds of validator sets are defined: `Validators`, `NextValidators`, and `LastValidators`. The `NextValidators` set is generated by copying the current `Validators` set and incrementing the proposer priority, as seen in the `updateState` function. + +The next proposer is ascertained based on the priority and verified in `manager.go` through the `IsProposer` method. Only the identified proposer is permitted to publish new blocks, ensuring a single block proposer at any given time. + +Furthermore, the block header contains hashes of the current and next validator sets (termed as aggregators) which are assigned during block creation and verified during block verification, ensuring continuity and agreement on the validator sets across the network. + +## Message Structure/Communication Format + +The primary structures encompassing validator information include `GenesisValidator`, `ValidatorSet`, and `State`. These structures are serialized using JSON and the communication occurs through the Tendermint's ABCI (Application BlockChain Interface) as seen in `updateState` method where `ValidatorUpdates` from the response is used to update the state's validator sets. + +## Assumptions and Considerations + +1. The addresses of the validators must be unique; otherwise, the system panics as seen in `NewValidatorSet`. +2. The validator set size has an implied limit equal to that of the `MaxVotesCount`. +3. The protocol assumes a synchronous, reliable communication among the validators via Tendermint's ABCI. +4. The scheme relies on a priority mechanism to ensure a fair rotation of block proposers. +5. It's assumed that the validators are honest and the network is secure, although the protocol has provisions to verify the consistency of validator sets across blocks. + +## Implementation + +The implementation reuses Tendermint types for managing validator sets, their priorities, and the communication between nodes. The key functions involved include `NewValidatorSet`, `updateState`, `IsProposer`, `publishBlock`, `CreateBlock`, and `Verify` among others, which are defined in various files like `state.go`, `manager.go`, `block.go`, etc., within the Rollkit repository. + +## References + +- [Rollkit GitHub Repository](https://github.com/rollkit/rollkit) +- [Tendermint Core Documentation](https://docs.tendermint.com/master/) From 84e3cdb7d489fff1fab28d33dd9d5329e095795e Mon Sep 17 00:00:00 2001 From: Javed Khan Date: Wed, 1 Nov 2023 16:32:04 -0700 Subject: [PATCH 2/3] specs: rewrite for centralized sequencer --- state/validators.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/state/validators.md b/state/validators.md index af09f57596..5cdfcc335d 100644 --- a/state/validators.md +++ b/state/validators.md @@ -1,38 +1,40 @@ -# Validator Selection Scheme +# Sequencer Selection Scheme ## Abstract -This document elucidates the validator selection mechanism as outlined in the [Rollkit repository](https://github.com/rollkit/rollkit). The scheme establishes an initial set of validators at the genesis of the blockchain, then leverages a priority-based system to determine the proposer of new blocks, ensuring a decentralized and fair block proposal mechanism. +The Sequencer Selection scheme describes the process of selecting a block proposer i.e. sequencer from the validator set. ## Protocol/Component Description -The protocol initializes with a predefined set of validators as stated in the `GenesisDoc`. These validators are part of the `GenesisValidator` struct which includes their address, public key, voting power, and name. Post genesis, the validator set might change, and is managed through Tendermint's `ValidatorSet` and `State` structures. +There is exactly one sequencer which is configured at genesis. `GenesisDoc` usually contains an array of validators as it is imported from `CometBFT`. If there is more than one validator defined +in the genesis validator set, an error is thrown. -The `ValidatorSet` represents a set of `Validator` at a given height, ordered by their voting power in descending order and secondary by their address in ascending order. The `ProposerPriority` of each validator and the designated proposer changes every round, upon calling `.IncrementProposerPriority()`. +The `State` struct defines a `Sequencer` field which contains the public key of the first and only validator of the genesis. -In the `State` struct, three kinds of validator sets are defined: `Validators`, `NextValidators`, and `LastValidators`. The `NextValidators` set is generated by copying the current `Validators` set and incrementing the proposer priority, as seen in the `updateState` function. +The `Header` struct defines a field called `ProposerAddress` which is the pubkey of the original proposer of the block. -The next proposer is ascertained based on the priority and verified in `manager.go` through the `IsProposer` method. Only the identified proposer is permitted to publish new blocks, ensuring a single block proposer at any given time. +The `SignedHeader` struct commits over the header and the proposer address and stores the result in `LastCommitHash`. -Furthermore, the block header contains hashes of the current and next validator sets (termed as aggregators) which are assigned during block creation and verified during block verification, ensuring continuity and agreement on the validator sets across the network. +A new untrusted header is verified by checking it's `ProposerAddress` and matching it against the best known header. In case of a mismatch, an error is thrown. + +When a new node is syncing, the block manager matches the `proposerKey` against the `Sequencer` field of the `lastState`. If a block is not signed by the expected proposer, it is ignored. ## Message Structure/Communication Format -The primary structures encompassing validator information include `GenesisValidator`, `ValidatorSet`, and `State`. These structures are serialized using JSON and the communication occurs through the Tendermint's ABCI (Application BlockChain Interface) as seen in `updateState` method where `ValidatorUpdates` from the response is used to update the state's validator sets. +The primary structures encompassing validator information include `SignedHeader`, `Header`, and `State`. Some fields are repurposed from CometBFT as seen in `GenesisDoc` `Validators`. ## Assumptions and Considerations -1. The addresses of the validators must be unique; otherwise, the system panics as seen in `NewValidatorSet`. -2. The validator set size has an implied limit equal to that of the `MaxVotesCount`. -3. The protocol assumes a synchronous, reliable communication among the validators via Tendermint's ABCI. -4. The scheme relies on a priority mechanism to ensure a fair rotation of block proposers. -5. It's assumed that the validators are honest and the network is secure, although the protocol has provisions to verify the consistency of validator sets across blocks. +1. There must be exactly one validator defined in the genesis file, which determines the sequencer for all the blocks. ## Implementation -The implementation reuses Tendermint types for managing validator sets, their priorities, and the communication between nodes. The key functions involved include `NewValidatorSet`, `updateState`, `IsProposer`, `publishBlock`, `CreateBlock`, and `Verify` among others, which are defined in various files like `state.go`, `manager.go`, `block.go`, etc., within the Rollkit repository. +The implementation is split across multiple functions including `IsProposer`, `publishBlock`, `CreateBlock`, and `Verify` among others, which are defined in various files like `state.go`, `manager.go`, `block.go`, `header.go` etc., within the repository. + +See [block manager] ## References -- [Rollkit GitHub Repository](https://github.com/rollkit/rollkit) -- [Tendermint Core Documentation](https://docs.tendermint.com/master/) +[1] [Block Manager][block manager] + +[block manager]: https://github.com/rollkit/rollkit/blob/v0.11.x/block/block-manager.md From 0dad209695ec6904d4a89a927c6aa84d625f9d8f Mon Sep 17 00:00:00 2001 From: Manav Aggarwal Date: Fri, 3 Nov 2023 16:10:06 +0100 Subject: [PATCH 3/3] Update state/validators.md --- state/validators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/state/validators.md b/state/validators.md index 5cdfcc335d..618574c5c5 100644 --- a/state/validators.md +++ b/state/validators.md @@ -15,7 +15,7 @@ The `Header` struct defines a field called `ProposerAddress` which is the pubkey The `SignedHeader` struct commits over the header and the proposer address and stores the result in `LastCommitHash`. -A new untrusted header is verified by checking it's `ProposerAddress` and matching it against the best known header. In case of a mismatch, an error is thrown. +A new untrusted header is verified by checking its `ProposerAddress` and matching it against the best-known header. In case of a mismatch, an error is thrown. When a new node is syncing, the block manager matches the `proposerKey` against the `Sequencer` field of the `lastState`. If a block is not signed by the expected proposer, it is ignored.