-
Notifications
You must be signed in to change notification settings - Fork 15
Add state representation #32
Changes from 1 commit
a453c4d
62420a9
cf6e484
a1340ff
a2adee4
6201f4c
2b14d8d
9ce5d6c
06f6436
05b2d47
00d4675
5a60665
2df269d
4cf479a
411925c
7f31112
34d9ddc
8339f86
61cbe55
f7bc92b
0828bf3
3f320e0
d87ef53
08dfbc5
313388e
ecda995
4fd51b7
fa9307b
e1d624c
39bc623
6bba8c6
6e036ad
747b594
62f759c
09f95d2
5449c59
e8cc2d3
e4005c8
8785e68
70ac923
f1cba75
a9d5149
4fbff8a
4a50807
a8c17a7
73de678
b4db7e3
2c4e44c
4d87996
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -7,6 +7,7 @@ Consensus Rules | |
- [Constants](#constants) | ||
- [Types](#types) | ||
- [Reserved Namespace IDs](#reserved-namespace-ids) | ||
- [Reserved State Subtree IDs](#reserved-state-subtree-ids) | ||
- [Rewards and Penalties](#rewards-and-penalties) | ||
- [Leader Selection](#leader-selection) | ||
- [Fork Choice](#fork-choice) | ||
|
@@ -41,12 +42,14 @@ Consensus Rules | |
| `GENESIS_COIN_COUNT` | `uint64` | `10**8` | `4u` | `(= 100000000)` Number of coins at genesis. | | ||
| `UNBONDING_DURATION` | `uint32` | | `block` | Duration, in blocks, for unbonding a validator or delegation. | | ||
| `MAX_VALIDATORS` | `uint16` | `64` | | Maximum number of active validators. | | ||
| `STATE_SUBTREE_RESERVED_BYTES` | `uint64` | `1` | `byte` | Number of bytes reserved to identify state subtrees. | | ||
|
||
## Types | ||
|
||
| name | type | | ||
| ------------- | -------- | | ||
| `NamespaceID` | `uint64` | | ||
| name | type | | ||
| ---------------- | -------- | | ||
| `NamespaceID` | `uint64` | | ||
| `StateSubtreeID` | `byte` | | ||
|
||
## Reserved Namespace IDs | ||
|
||
|
@@ -57,6 +60,14 @@ Consensus Rules | |
| `EVIDENCE_NAMESPACE_ID` | `NamespaceID` | `0x0000000000000000000000000000000000000000000000000000000000000003` | | ||
| `PARITY_SHARE_NAMESPACE_ID` | `NamespaceID` | `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF` | | ||
|
||
## Reserved State Subtree IDs | ||
|
||
| name | type | value | | ||
| ---------------------------- | ---------------- | ------ | | ||
| `ACCOUNTS_SUBTREE_ID` | `StateSubtreeID` | `0x01` | | ||
| `VALIDATORS_SUBTREE_ID` | `StateSubtreeID` | `0x02` | | ||
| `VALIDATOR_COUNT_SUBTREE_ID` | `StateSubtreeID` | `0x03` | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Shouldn't this be part of the validator subtree (e.g the left-most branch in the validator subtree contains the count)? Why do we need this again? Isn't that implicitly given by the number of leaves in the subtree that aren't default values (i.e. no active validators). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It could, but mangling multiple leaf types into a single tree (or subtree) makes things more complicated. E.g. you'd need subtree-specific logic if you want to parallelize updating the validator set and the validator count state. If they're in separate subtrees then you can have a single global whole-SMT-level process that handles updating subtrees in parallel. The validator count is needed not for light nodes knowing they've downloaded the entire validator set, but for proving with a fraud proof that the number of active validators exceeds the maximum. See other comment further down for some more on this. |
||
|
||
## Rewards and Penalties | ||
|
||
| name | type | value | unit | description | | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -44,9 +44,10 @@ Data Structures | |
- [Message](#message) | ||
- [State](#state) | ||
- [Account](#account) | ||
- [PeriodEntry](#periodentry) | ||
- [Validator](#validator) | ||
- [Delegation](#delegation) | ||
- [Validator](#validator) | ||
- [ActiveValidatorCount](#activevalidatorcount) | ||
- [PeriodEntry](#periodentry) | ||
- [Decimal](#decimal) | ||
- [Consensus Parameters](#consensus-parameters) | ||
|
||
|
@@ -480,14 +481,18 @@ enum VoteType : uint8_t { | |
|
||
# State | ||
|
||
| name | type | description | | ||
| --------------- | ------------------------- | ---------------------------- | | ||
| `accountsRoot` | [HashDigest](#hashdigest) | Merkle root of account tree. | | ||
| `numValidators` | `uint32` | Number of active validators. | | ||
| name | type | description | | ||
| ----------- | ------------------------- | -------------------------- | | ||
| `stateRoot` | [HashDigest](#hashdigest) | Merkle root of state tree. | | ||
|
||
The state of the LazyLedger chain contains only account balances and the validator set (which is extra metadata on top of the plain account balances). | ||
The state of the LazyLedger chain is intentionally restricted to containing only account balances and the validator set metadata. One unified [Sparse Merkle Trees](#sparse-merkle-tree) is maintained for the entire chain state, the _state tree_. | ||
|
||
One unified [Sparse Merkle Trees](#sparse-merkle-tree) is maintained for both account account balances and validator metadata, the _accounts tree_. The final state root is computed as the [hash](#hashdigest) of the accounts tree root and number of active validators. The latter is necessary to ensure light nodes can determine the entire validator set from a single state root commitment. | ||
The state tree is separated into `2**(8*STATE_SUBTREE_RESERVED_BYTES)` subtrees, each of which can be used to store a different component of the state. This is done by slicing off the highest `STATE_SUBTREE_RESERVED_BYTES` bytes from the key and replacing them with the appropriate [reserved state subtree ID](consensus.md#reserved-state-subtree-ids). Reducing the key size within subtrees also reduces the collision resistance of keys by `8*STATE_SUBTREE_RESERVED_BYTES` bits, but this is not an issue due the number of bits removed being small. | ||
|
||
Three subtrees are maintained: | ||
1. [Accounts](#account) | ||
1. [Active validator set](#validator) | ||
1. [Active validator count](#activevalidatorcount) | ||
|
||
## Account | ||
|
||
|
@@ -496,19 +501,32 @@ One unified [Sparse Merkle Trees](#sparse-merkle-tree) is maintained for both ac | |
| `balance` | `uint64` | Coin balance. | | ||
| `nonce` | `uint64` | Account nonce. Every outgoing transaction from this account increments the nonce. | | ||
| `isValidator` | `bool` | Whether this account is a validator or not. Mutually exclusive with `isDelegating`. | | ||
| `validatorInfo` | [Validator](#validator) | _Optional_, only if `isValidator` is set. Validator info. | | ||
| `isDelegating` | `bool` | Whether this account is delegating its stake or not. Mutually exclusive with `isValidator`. | | ||
| `delegationInfo` | [Delegation](#delegation) | _Optional_, only if `isDelegating` is set. Delegation info. | | ||
|
||
In the accounts tree, accounts (i.e. leaves) are keyed by the [hash](#hashdigest) of their [address](#address). | ||
In the accounts subtree, accounts (i.e. leaves) are keyed by the [hash](#hashdigest) of their [address](#address). The first byte is then replaced with `ACCOUNTS_SUBTREE_ID`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Effectively, this means that the hash used in the subtree returns 31 bytes. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not the hash function in general, but specifically how the key is calculated, yes. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If we say it's the hash function, this is easier to formalize. e.g. we can say the key for an account in the set There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hmm. I'm not really a fan because that would mean we need 1) a different hashing function for each subtree (not great, not terrible) and 2) to slice off the first byte of every single hashing operation. That cost will add up quickly, especially if doing proofs in smart contracts. I'd much prefer just changing how the keys are calculated, which is a one-time calculation per leaf. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. IMO It's just another way to writing down the same thing though (of course in 2) the slicing off could be done more efficiently by replacing the 1st byte instead; but this is just an implementation detail). |
||
|
||
## PeriodEntry | ||
## Delegation | ||
|
||
| name | type | description | | ||
| ------------ | -------- | ------------------------------------------------------------- | | ||
| `rewardRate` | `uint64` | Rewards per unit of voting power accumulated so far, in `1u`. | | ||
```C++ | ||
enum DelegationStatus : uint8_t { | ||
Bonded = 1, | ||
Unbonding = 2, | ||
}; | ||
``` | ||
|
||
For explanation on entries, see the [reward distribution rationale document](../rationale/distributing_rewards.md). | ||
| name | type | description | | ||
| ----------------- | --------------------------- | --------------------------------------------------- | | ||
| `status` | `DelegationStatus` | Status of this delegation. | | ||
| `validator` | [Address](#address) | The validator being delegating to. | | ||
| `stakedBalance` | `uint64` | Delegated stake, in `4u`. | | ||
| `beginEntry` | [PeriodEntry](#periodentry) | Entry when delegation began. | | ||
| `endEntry` | [PeriodEntry](#periodentry) | Entry when delegation ended (i.e. began unbonding). | | ||
| `unbondingHeight` | `uint64` | Block height delegation began unbonding. | | ||
|
||
Delegation objects represent a delegation. They have two statuses: | ||
1. `Bonded`: This delegation is enabled for a `Queued` _or_ `Bonded` validator. Delegations to a `Queued` validator can be withdrawn immediately, while delegations for a `Bonded` validator must be unbonded first. | ||
1. `Unbonding`: This delegation is unbonding. It will remain in this status for at least `UNBONDING_DURATION` blocks, and while unbonding may still be slashed. Once the unbonding duration has expired, the delegation can be withdrawn. | ||
|
||
## Validator | ||
|
||
|
@@ -540,27 +558,23 @@ Validator objects represent all the information needed to be keep track of a val | |
1. `Unbonding`: This validator is in the process of unbonding, which can be voluntary (the validator decided to stop being an active validator) or forced (the validator committed a slashable offence and was kicked from the active validator set). Validators will remain in this status for at least `UNBONDING_DURATION` blocks, and while unbonding may still be slashed. | ||
1. `Unbonded`: This validator has completed its unbonding and has withdrawn its stake. The validator object will remain in this status until `delegatedCount` reaches zero, at which point it is destroyed. | ||
|
||
## Delegation | ||
In the validators subtree, validators are keyed by the [hash](#hashdigest) of their [address](#address). The first byte is then replaced with `VALIDATORS_SUBTREE_ID`. By construction, the validators subtree will be a subset of a mirror of the [accounts subtree](#account). | ||
|
||
```C++ | ||
enum DelegationStatus : uint8_t { | ||
Bonded = 1, | ||
Unbonding = 2, | ||
}; | ||
``` | ||
## ActiveValidatorCount | ||
|
||
| name | type | description | | ||
| ----------------- | --------------------------- | --------------------------------------------------- | | ||
| `status` | `DelegationStatus` | Status of this delegation. | | ||
| `validator` | [Address](#address) | The validator being delegating to. | | ||
| `stakedBalance` | `uint64` | Delegated stake, in `4u`. | | ||
| `beginEntry` | [PeriodEntry](#periodentry) | Entry when delegation began. | | ||
| `endEntry` | [PeriodEntry](#periodentry) | Entry when delegation ended (i.e. began unbonding). | | ||
| `unbondingHeight` | `uint64` | Block height delegation began unbonding. | | ||
| name | type | description | | ||
| --------------- | -------- | ---------------------------- | | ||
| `numValidators` | `uint32` | Number of active validators. | | ||
|
||
Delegation objects represent a delegation. They have two statuses: | ||
1. `Bonded`: This delegation is enabled for a `Queued` _or_ `Bonded` validator. Delegations to a `Queued` validator can be withdrawn immediately, while delegations for a `Bonded` validator must be unbonded first. | ||
1. `Unbonding`: This delegation is unbonding. It will remain in this status for at least `UNBONDING_DURATION` blocks, and while unbonding may still be slashed. Once the unbonding duration has expired, the delegation can be withdrawn. | ||
Since the [validator set](#validator) is stored in a Sparse Merkle Tree, there is no compact way of proving that the number of active validators exceeds `MAX_VALIDATORS` without keeping track of the number of active validators. There is only a single leaf in the active validator count subtree, which is keyed with zero (i.e. `0x0000000000000000000000000000000000000000000000000000000000000000`), and the first byte replaced with `VALIDATOR_COUNT_SUBTREE_ID`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. imo this should be part of validator subtree: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Unlike moving the inactive validator set into the accounts subtree, I might be okay with moving the validator count into the active validators subtree because it's guaranteed to be in a fixed location. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it semantically belongs to the validator subtree and also a single value tree seems weird. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Alright, will migrate the count into the active validators subtree. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fixed in 4d87996. |
||
|
||
## PeriodEntry | ||
|
||
| name | type | description | | ||
| ------------ | -------- | ------------------------------------------------------------- | | ||
| `rewardRate` | `uint64` | Rewards per unit of voting power accumulated so far, in `1u`. | | ||
|
||
For explanation on entries, see the [reward distribution rationale document](../rationale/distributing_rewards.md). | ||
|
||
## Decimal | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In tendermint, the header references current and next validators:
https://github.com/tendermint/tendermint/blob/206c814a8e64cb4b9eb2abbb2fdadc6933b28584/types/block.go#L352-L353
Should we have two subtrees for that? Or, further split the validator subtree? The number of validators should easily fit into that tree in any case.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This isn't needed with immediate execution. Regardless, the validator set for the current block is the next validator set of the previous block, so we don't need to maintain two trees. Only the next validator set is needed to be stored in the tree at any given time.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That makes sense. I'm wondering if there is a reason in tendermint for having both validator sets referenced. Might have to do with deferred execution (related tendermint/tendermint#2483) or maybe it is just for convenience 🤔
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How would a light client verify this property efficiently if only the next valset is stored & merkelized? Doesn't it need a commit to the next valst (of the previous block) that can be easyily verified on the current block (e.g. via a root included int the header) without recomputing the cur vals?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Transcluding conversation from Slack:
It might be worth it to have a dedicated field in the block header for this, and just making sure it matches up with the last intermediate state root's active validator subtree root.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@buchmann clarified here why both hashes are part of the header (and not just the state root/tree) in tendermint:
celestiaorg/celestia-core#3 (comment)