mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-05-31 06:21:02 +00:00
implement provisioner (#1473)
* sketch out provisioner basics
* handle provisionable data
* stub out select_inherent_data
* split runtime APIs into sub-chapters to improve linkability
* explain SignedAvailabilityBitfield semantics
* add internal link to further documentation
* some more work figuring out how the provisioner can do its thing
* fix broken link
* don't import enum variants where it's one layer deep
* make request_availability_cores a free fn in util
* document more precisely what should happen on block production
* finish first-draft implementation of provisioner
* start working on the full and proper backed candidate selection rule
* Pass number of block under construction via RequestInherentData
* Revert "Pass number of block under construction via RequestInherentData"
This reverts commit 850fe62cc0dfb04252580c21a985962000e693c8.
That initially looked like the better approach--it spent the time
budget for fetching the block number in the proposer, instead of
the provisioner, and that felt more appropriate--but it turns out
not to be obvious how to get the block number of the block under
construction from within the proposer. The Chain API may be less
ideal, but it should be easier to implement.
* wip: get the block under production from the Chain API
* add ChainApiMessage to AllMessages
* don't break the run loop if a provisionable data channel closes
* clone only those backed candidates which are coherent
* propagate chain_api subsystem through various locations
* add delegated_subsystem! macro to ease delegating subsystems
Unfortunately, it doesn't work right:
```
error[E0446]: private type `CandidateBackingJob` in public interface
--> node/core/backing/src/lib.rs:775:1
|
86 | struct CandidateBackingJob {
| - `CandidateBackingJob` declared as private
...
775 | delegated_subsystem!(CandidateBackingJob as CandidateBackingSubsystem);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ can't leak private type
```
I'm not sure precisely what's going wrong, here; I suspect the problem is
the use of `$job as JobTrait>::RunArgs` and `::ToJob`; the failure would be
that it's not reifying the types to verify that the actual types are public,
but instead referring to them via `CandidateBackingJob`, which is in fact private;
that privacy is the point.
Going to see if I can generic my way out of this, but we may be headed for a
quick revert here.
* fix delegated_subsystem
The invocation is a bit more verbose than I'd prefer, but it's also
more explicit about what types need to be public. I'll take it as a win.
* add provisioning subsystem; reduce public interface of provisioner
* deny missing docs in provisioner
* refactor core selection per code review suggestion
This is twice as much code when measured by line, but IMO it is
in fact somewhat clearer to read, so overall a win.
Also adds an improved rule for selecting availability bitfields,
which (unlike the previous implementation) guarantees that the
appropriate postconditions hold there.
* fix bad merge double-declaration
* update guide with (hopefully) complete provisioner candidate selection procedure
* clarify candidate selection algorithm
* Revert "clarify candidate selection algorithm"
This reverts commit c68a02ac9cf42b3a4a28eb197d38633a40d0e3e6.
* clarify candidate selection algorithm
* update provisioner to implement candidate selection per the guide
* add test that no more than one bitfield is selected per validator
* add test that each selected bitfield corresponds to an occupied core
* add test that more set bits win conflicts
* add macro for specializing runtime requests; specailize all runtime requests
* add tests harness for select_candidates tests
* add first real select_candidates test, fix test_harness
* add mock overseer and test that success is possible
* add test that the candidate selection algorithm picks the right ones
* make candidate selection test somewhat more stringent
This commit is contained in:
Peter Goodspeed-Niklaus
committed by
GitHub
GitHub
parent
877a5059aa
commit
21cec309a4
@@ -15,6 +15,15 @@
|
||||
- [Validity Module](runtime/validity.md)
|
||||
- [Router Module](runtime/router.md)
|
||||
- [Runtime APIs](runtime-api/README.md)
|
||||
- [Validators](runtime-api/validators.md)
|
||||
- [Validator Groups](runtime-api/validator-groups.md)
|
||||
- [Availability Cores](runtime-api/availability-cores.md)
|
||||
- [Global Validation Data](runtime-api/global-validation-data.md)
|
||||
- [Local Validation Data](runtime-api/local-validation-data.md)
|
||||
- [Session Index](runtime-api/session-index.md)
|
||||
- [Validation Code](runtime-api/validation-code.md)
|
||||
- [Candidate Pending Availability](runtime-api/candidate-pending-availability.md)
|
||||
- [Candidate Events](runtime-api/candidate-events.md)
|
||||
- [Node Architecture](node/README.md)
|
||||
- [Subsystems and Jobs](node/subsystems-and-jobs.md)
|
||||
- [Overseer](node/overseer.md)
|
||||
|
||||
@@ -40,7 +40,54 @@ Note that block authors must re-send a `ProvisionerMessage::RequestBlockAuthorsh
|
||||
|
||||
## Block Production
|
||||
|
||||
When a validator is selected by BABE to author a block, it becomes a block producer. The provisioner is the subsystem best suited to choosing which specific backed candidates and availability bitfields should be assembled into the block. To engage this functionality, a `ProvisionerMessage::RequestInherentData` is sent; the response is a set of non-conflicting candidates and the appropriate bitfields. Non-conflicting means that there are never two distinct parachain candidates included for the same parachain and that new parachain candidates cannot be included until the previous one either gets declared available or expired.
|
||||
When a validator is selected by BABE to author a block, it becomes a block producer. The provisioner is the subsystem best suited to choosing which specific backed candidates and availability bitfields should be assembled into the block. To engage this functionality, a `ProvisionerMessage::RequestInherentData` is sent; the response is a set of non-conflicting candidates and the appropriate bitfields. Non-conflicting means that there are never two distinct parachain candidates included for the same parachain and that new parachain candidates cannot be backed until the previous one either gets declared available or expired.
|
||||
|
||||
### Bitfield Selection
|
||||
|
||||
Our goal with respect to bitfields is simple: maximize availability. However, it's not quite as simple as always including all bitfields; there are constraints which still need to be met:
|
||||
|
||||
- We cannot choose more than one bitfield per validator.
|
||||
- Each bitfield must correspond to an occupied core.
|
||||
|
||||
Beyond that, a semi-arbitrary selection policy is fine. In order to meet the goal of maximizing availability, a heuristic of picking the bitfield with the greatest number of 1 bits set in the event of conflict is useful.
|
||||
|
||||
### Candidate Selection
|
||||
|
||||
The goal of candidate selection is to determine which cores are free, and then to the degree possible, pick a candidate appropriate to each free core.
|
||||
|
||||
To determine availability:
|
||||
|
||||
- Get the list of core states from the runtime API
|
||||
- For each core state:
|
||||
- On `CoreState::Scheduled`, then we can make an `OccupiedCoreAssumption::Free`.
|
||||
- On `CoreState::Occupied`, then we may be able to make an assumption:
|
||||
- If the bitfields indicate availability and there is a scheduled `next_up_on_available`, then we can make an `OccupiedCoreAssumption::Included`.
|
||||
- If the bitfields do not indicate availability, and there is a scheduled `next_up_on_time_out`, and `occupied_core.time_out_at == block_number_under_production`, then we can make an `OccupiedCoreAssumption::TimedOut`.
|
||||
- If we did not make an `OccupiedCoreAssumption`, then continue on to the next core.
|
||||
- Now compute the core's `validation_data_hash`: get the `LocalValidationData` from the runtime, given the known `ParaId` and `OccupiedCoreAssumption`; this can be combined with a cached `GlobalValidationData` to compute the hash.
|
||||
- Find an appropriate candidate for the core.
|
||||
- There are two constraints: `backed_candidate.candidate.descriptor.para_id == scheduled_core.para_id && candidate.candidate.descriptor.validation_data_hash == computed_validation_data_hash`.
|
||||
- In the event that more than one candidate meets the constraints, selection between the candidates is arbitrary. However, not more than one candidate can be selected per core.
|
||||
|
||||
The end result of this process is a vector of `BackedCandidate`s, sorted in order of their core index.
|
||||
|
||||
### Determining Bitfield Availability
|
||||
|
||||
An occupied core has a `CoreAvailability` bitfield. We also have a list of `SignedAvailabilityBitfield`s. We need to determine from these whether or not a core at a particular index has become available.
|
||||
|
||||
The key insight required is that `CoreAvailability` is transverse to the `SignedAvailabilityBitfield`s: if we conceptualize the list of bitfields as many rows, each bit of which is its own column, then `CoreAvailability` for a given core index is the vertical slice of bits in the set at that index.
|
||||
|
||||
To compute bitfield availability, then:
|
||||
|
||||
- Start with a copy of `OccupiedCore.availability`
|
||||
- For each bitfield in the list of `SignedAvailabilityBitfield`s:
|
||||
- Get the bitfield's `validator_index`
|
||||
- Update the availability. Conceptually, assuming bit vectors: `availability[validator_index] |= bitfield[core_idx]`
|
||||
- Availability has a 2/3 threshold. Therefore: `3 * availability.count_ones() >= 2 * availability.len()`
|
||||
|
||||
### Notes
|
||||
|
||||
See also: [Scheduler Module: Availability Cores](../../runtime/scheduler.md#availability-cores).
|
||||
|
||||
One might ask: given `ProvisionerMessage::RequestInherentData`, what's the point of `ProvisionerMessage::RequestBlockAuthorshipData`? The answer is that the block authorship data includes more information than is present in the inherent data; disputes, for example.
|
||||
|
||||
@@ -51,10 +98,10 @@ The subsystem should maintain a set of handles to Block Authorship Provisioning
|
||||
### On Overseer Signal
|
||||
|
||||
- `ActiveLeavesUpdate`:
|
||||
- For each `activated` head:
|
||||
- spawn a Block Authorship Provisioning Job with the given relay parent, storing a bidirectional channel with that job.
|
||||
- For each `deactivated` head:
|
||||
- terminate the Block Authorship Provisioning Job for the given relay parent, if any.
|
||||
- For each `activated` head:
|
||||
- spawn a Block Authorship Provisioning Job with the given relay parent, storing a bidirectional channel with that job.
|
||||
- For each `deactivated` head:
|
||||
- terminate the Block Authorship Provisioning Job for the given relay parent, if any.
|
||||
- `Conclude`: Forward `Conclude` to all jobs, waiting a small amount of time for them to join, and then hard-exiting.
|
||||
|
||||
### On `ProvisionerMessage`
|
||||
|
||||
@@ -7,17 +7,19 @@ Every block in the relay-chain contains a *state root* which is the root hash of
|
||||
Although Runtime APIs are often used for simple storage access, they are actually empowered to do arbitrary computation. The implementation of the Runtime APIs lives within the Runtime as Wasm code and exposes extern functions that can be invoked with arguments and have a return value. Runtime APIs have access to a variety of host functions, which are contextual functions provided by the Wasm execution context, that allow it to carry out many different types of behaviors.
|
||||
|
||||
Abilities provided by host functions includes:
|
||||
* State Access
|
||||
* Offchain-DB Access
|
||||
* Submitting transactions to the transaction queue
|
||||
* Optimized versions of cryptographic functions
|
||||
* More
|
||||
|
||||
* State Access
|
||||
* Offchain-DB Access
|
||||
* Submitting transactions to the transaction queue
|
||||
* Optimized versions of cryptographic functions
|
||||
* More
|
||||
|
||||
So it is clear that Runtime APIs are a versatile and powerful tool to leverage the state of the chain. In general, we will use Runtime APIs for these purposes:
|
||||
* Access of a storage item
|
||||
* Access of a bundle of related storage items
|
||||
* Deriving a value from storage based on arguments
|
||||
* Submitting misbehavior reports
|
||||
|
||||
* Access of a storage item
|
||||
* Access of a bundle of related storage items
|
||||
* Deriving a value from storage based on arguments
|
||||
* Submitting misbehavior reports
|
||||
|
||||
More broadly, we have the goal of using Runtime APIs to write Node-side code that fulfills the requirements set by the Runtime. In particular, the constraints set forth by the [Scheduler](../runtime/scheduler.md) and [Inclusion](../runtime/inclusion.md) modules. These modules are responsible for advancing paras with a two-phase protocol where validators are first chosen to validate and back a candidate and then required to ensure availability of referenced data. In the second phase, validators are meant to attest to those para-candidates that they have their availability chunk for. As the Node-side code needs to generate the inputs into these two phases, the runtime API needs to transmit information from the runtime that is aware of the Availability Cores model instantiated by the Scheduler and Inclusion modules.
|
||||
|
||||
@@ -35,180 +37,3 @@ The next sections will contain information on specific runtime APIs. The format
|
||||
/// best for the implementation to return an error indicating the failure mode.
|
||||
fn some_runtime_api(at: Block, arg1: Type1, arg2: Type2, ...) -> ReturnValue;
|
||||
```
|
||||
|
||||
## Validators
|
||||
|
||||
Yields the validator-set at the state of a given block. This validator set is always the one responsible for backing parachains in the child of the provided block.
|
||||
|
||||
```rust
|
||||
fn validators(at: Block) -> Vec<ValidatorId>;
|
||||
```
|
||||
|
||||
## Validator Groups
|
||||
|
||||
Yields the validator groups used during the current session. The validators in the groups are referred to by their index into the validator-set.
|
||||
|
||||
```rust
|
||||
/// A helper data-type for tracking validator-group rotations.
|
||||
struct GroupRotationInfo {
|
||||
session_start_block: BlockNumber,
|
||||
group_rotation_frequency: BlockNumber,
|
||||
now: BlockNumber,
|
||||
}
|
||||
|
||||
impl GroupRotationInfo {
|
||||
/// Returns the index of the group needed to validate the core at the given index,
|
||||
/// assuming the given amount of cores/groups.
|
||||
fn group_for_core(&self, core_index, cores) -> GroupIndex;
|
||||
|
||||
/// Returns the block number of the next rotation after the current block. If the current block
|
||||
/// is 10 and the rotation frequency is 5, this should return 15.
|
||||
///
|
||||
/// If the group rotation frequency is 0, returns 0.
|
||||
fn next_rotation_at(&self) -> BlockNumber;
|
||||
|
||||
/// Returns the block number of the last rotation before or including the current block. If the
|
||||
/// current block is 10 and the rotation frequency is 5, this should return 10.
|
||||
///
|
||||
/// If the group rotation frequency is 0, returns 0.
|
||||
fn last_rotation_at(&self) -> BlockNumber;
|
||||
}
|
||||
|
||||
/// Returns the validator groups and rotation info localized based on the block whose state
|
||||
/// this is invoked on. Note that `now` in the `GroupRotationInfo` should be the successor of
|
||||
/// the number of the block.
|
||||
fn validator_groups(at: Block) -> (Vec<Vec<ValidatorIndex>>, GroupRotationInfo);
|
||||
```
|
||||
|
||||
## Availability Cores
|
||||
|
||||
Yields information on all availability cores. Cores are either free or occupied. Free cores can have paras assigned to them. Occupied cores don't, but they can become available part-way through a block due to bitfields and then have something scheduled on them. To allow optimistic validation of candidates, the occupied cores are accompanied by information on what is upcoming. This information can be leveraged when validators perceive that there is a high likelihood of a core becoming available based on bitfields seen, and then optimistically validate something that would become scheduled based on that, although there is no guarantee on what the block producer will actually include in the block.
|
||||
|
||||
```rust
|
||||
fn availability_cores(at: Block) -> Vec<CoreState>;
|
||||
```
|
||||
|
||||
This is all the information that a validator needs about scheduling for the current block. It includes all information on [Scheduler](../runtime/scheduler.md) core-assignments and [Inclusion](../runtime/inclusion.md) state of blocks occupying availability cores. It includes data necessary to determine not only which paras are assigned now, but which cores are likely to become freed after processing bitfields, and exactly which bitfields would be necessary to make them so.
|
||||
|
||||
```rust
|
||||
struct OccupiedCore {
|
||||
/// The ID of the para occupying the core.
|
||||
para_id: ParaId,
|
||||
/// If this core is freed by availability, this is the assignment that is next up on this
|
||||
/// core, if any. None if there is nothing queued for this core.
|
||||
next_up_on_available: Option<ScheduledCore>,
|
||||
/// The relay-chain block number this began occupying the core at.
|
||||
occupied_since: BlockNumber,
|
||||
/// The relay-chain block this will time-out at, if any.
|
||||
time_out_at: BlockNumber,
|
||||
/// If this core is freed by being timed-out, this is the assignment that is next up on this
|
||||
/// core. None if there is nothing queued for this core or there is no possibility of timing
|
||||
/// out.
|
||||
next_up_on_time_out: Option<ScheduledCore>,
|
||||
/// A bitfield with 1 bit for each validator in the set. `1` bits mean that the corresponding
|
||||
/// validators has attested to availability on-chain. A 2/3+ majority of `1` bits means that
|
||||
/// this will be available.
|
||||
availability: Bitfield,
|
||||
/// The group assigned to distribute availability pieces of this candidate.
|
||||
group_responsible: GroupIndex,
|
||||
}
|
||||
|
||||
struct ScheduledCore {
|
||||
/// The ID of a para scheduled.
|
||||
para_id: ParaId,
|
||||
/// The collator required to author the block, if any.
|
||||
collator: Option<CollatorId>,
|
||||
}
|
||||
|
||||
enum CoreState {
|
||||
/// The core is currently occupied.
|
||||
Occupied(OccupiedCore),
|
||||
/// The core is currently free, with a para scheduled and given the opportunity
|
||||
/// to occupy.
|
||||
///
|
||||
/// If a particular Collator is required to author this block, that is also present in this
|
||||
/// variant.
|
||||
Scheduled(ScheduledCore),
|
||||
/// The core is currently free and there is nothing scheduled. This can be the case for parathread
|
||||
/// cores when there are no parathread blocks queued. Parachain cores will never be left idle.
|
||||
Free,
|
||||
}
|
||||
```
|
||||
|
||||
## Global Validation Schedule
|
||||
|
||||
Yields the [`GlobalValidationData`](../types/candidate.md#globalvalidationschedule) at the state of a given block. This applies to all para candidates with the relay-parent equal to that block.
|
||||
|
||||
```rust
|
||||
fn global_validation_data(at: Block) -> GlobalValidationData;
|
||||
```
|
||||
|
||||
## Local Validation Data
|
||||
|
||||
Yields the [`LocalValidationData`](../types/candidate.md#localvalidationdata) for the given [`ParaId`](../types/candidate.md#paraid) along with an assumption that should be used if the para currently occupies a core: whether the candidate occupying that core should be assumed to have been made available and included or timed out and discarded, along with a third option to assert that the core was not occupied. This choice affects everything from the parent head-data, the validation code, and the state of message-queues. Typically, users will take the assumption that either the core was free or that the occupying candidate was included, as timeouts are expected only in adversarial circumstances and even so, only in a small minority of blocks directly following validator set rotations.
|
||||
|
||||
The documentation of [`LocalValidationData`](../types/candidate.md#localvalidationdata) has more information on this dichotomy.
|
||||
|
||||
```rust
|
||||
/// An assumption being made about the state of an occupied core.
|
||||
enum OccupiedCoreAssumption {
|
||||
/// The candidate occupying the core was made available and included to free the core.
|
||||
Included,
|
||||
/// The candidate occupying the core timed out and freed the core without advancing the para.
|
||||
TimedOut,
|
||||
/// The core was not occupied to begin with.
|
||||
Free,
|
||||
}
|
||||
|
||||
/// Returns the local validation data for the given para and occupied core assumption.
|
||||
///
|
||||
/// Returns `None` if either the para is not registered or the assumption is `Freed`
|
||||
/// and the para already occupies a core.
|
||||
fn local_validation_data(at: Block, ParaId, OccupiedCoreAssumption) -> Option<LocalValidationData>;
|
||||
```
|
||||
|
||||
## Session Index
|
||||
|
||||
Get the session index that is expected at the child of a block.
|
||||
|
||||
In the [`Initializer`](../runtime/initializer.md) module, session changes are buffered by one block. The session index of the child of any relay block is always predictable by that block's state.
|
||||
|
||||
This session index can be used to derive a [`SigningContext`](../types/candidate.md#signing-context).
|
||||
|
||||
```rust
|
||||
/// Returns the session index expected at a child of the block.
|
||||
fn session_index_for_child(at: Block) -> SessionIndex;
|
||||
```
|
||||
|
||||
## Validation Code
|
||||
|
||||
Fetch the validation code used by a para, making the given `OccupiedCoreAssumption`.
|
||||
|
||||
```rust
|
||||
fn validation_code(at: Block, ParaId, OccupiedCoreAssumption) -> Option<ValidationCode>;
|
||||
```
|
||||
|
||||
## Candidate Pending Availability
|
||||
|
||||
Get the receipt of a candidate pending availability. This returns `Some` for any paras assigned to occupied cores in `availability_cores` and `None` otherwise.
|
||||
|
||||
```rust
|
||||
fn candidate_pending_availability(at: Block, ParaId) -> Option<CommittedCandidateReceipt>;
|
||||
```
|
||||
|
||||
## Candidate Events
|
||||
|
||||
Yields a vector of events concerning candidates that occurred within the given block.
|
||||
|
||||
```rust
|
||||
enum CandidateEvent {
|
||||
/// This candidate receipt was backed in the most recent block.
|
||||
CandidateBacked(CandidateReceipt, HeadData),
|
||||
/// This candidate receipt was included and became a parablock at the most recent block.
|
||||
CandidateIncluded(CandidateReceipt, HeadData),
|
||||
/// This candidate receipt was not made available in time and timed out.
|
||||
CandidateTimedOut(CandidateReceipt, HeadData),
|
||||
}
|
||||
|
||||
fn candidate_events(at: Block) -> Vec<CandidateEvent>;
|
||||
```
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# Availability Cores
|
||||
|
||||
Yields information on all availability cores. Cores are either free or occupied. Free cores can have paras assigned to them. Occupied cores don't, but they can become available part-way through a block due to bitfields and then have something scheduled on them. To allow optimistic validation of candidates, the occupied cores are accompanied by information on what is upcoming. This information can be leveraged when validators perceive that there is a high likelihood of a core becoming available based on bitfields seen, and then optimistically validate something that would become scheduled based on that, although there is no guarantee on what the block producer will actually include in the block.
|
||||
|
||||
See also the [Scheduler Module](../runtime/scheduler.md) for a high-level description of what an availability core is and why it exists.
|
||||
|
||||
```rust
|
||||
fn availability_cores(at: Block) -> Vec<CoreState>;
|
||||
```
|
||||
|
||||
This is all the information that a validator needs about scheduling for the current block. It includes all information on [Scheduler](../runtime/scheduler.md) core-assignments and [Inclusion](../runtime/inclusion.md) state of blocks occupying availability cores. It includes data necessary to determine not only which paras are assigned now, but which cores are likely to become freed after processing bitfields, and exactly which bitfields would be necessary to make them so.
|
||||
|
||||
```rust
|
||||
struct OccupiedCore {
|
||||
/// The ID of the para occupying the core.
|
||||
para_id: ParaId,
|
||||
/// If this core is freed by availability, this is the assignment that is next up on this
|
||||
/// core, if any. None if there is nothing queued for this core.
|
||||
next_up_on_available: Option<ScheduledCore>,
|
||||
/// The relay-chain block number this began occupying the core at.
|
||||
occupied_since: BlockNumber,
|
||||
/// The relay-chain block this will time-out at, if any.
|
||||
time_out_at: BlockNumber,
|
||||
/// If this core is freed by being timed-out, this is the assignment that is next up on this
|
||||
/// core. None if there is nothing queued for this core or there is no possibility of timing
|
||||
/// out.
|
||||
next_up_on_time_out: Option<ScheduledCore>,
|
||||
/// A bitfield with 1 bit for each validator in the set. `1` bits mean that the corresponding
|
||||
/// validators has attested to availability on-chain. A 2/3+ majority of `1` bits means that
|
||||
/// this will be available.
|
||||
availability: Bitfield,
|
||||
/// The group assigned to distribute availability pieces of this candidate.
|
||||
group_responsible: GroupIndex,
|
||||
}
|
||||
|
||||
struct ScheduledCore {
|
||||
/// The ID of a para scheduled.
|
||||
para_id: ParaId,
|
||||
/// The collator required to author the block, if any.
|
||||
collator: Option<CollatorId>,
|
||||
}
|
||||
|
||||
enum CoreState {
|
||||
/// The core is currently occupied.
|
||||
Occupied(OccupiedCore),
|
||||
/// The core is currently free, with a para scheduled and given the opportunity
|
||||
/// to occupy.
|
||||
///
|
||||
/// If a particular Collator is required to author this block, that is also present in this
|
||||
/// variant.
|
||||
Scheduled(ScheduledCore),
|
||||
/// The core is currently free and there is nothing scheduled. This can be the case for parathread
|
||||
/// cores when there are no parathread blocks queued. Parachain cores will never be left idle.
|
||||
Free,
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,16 @@
|
||||
# Candidate Events
|
||||
|
||||
Yields a vector of events concerning candidates that occurred within the given block.
|
||||
|
||||
```rust
|
||||
enum CandidateEvent {
|
||||
/// This candidate receipt was backed in the most recent block.
|
||||
CandidateBacked(CandidateReceipt, HeadData),
|
||||
/// This candidate receipt was included and became a parablock at the most recent block.
|
||||
CandidateIncluded(CandidateReceipt, HeadData),
|
||||
/// This candidate receipt was not made available in time and timed out.
|
||||
CandidateTimedOut(CandidateReceipt, HeadData),
|
||||
}
|
||||
|
||||
fn candidate_events(at: Block) -> Vec<CandidateEvent>;
|
||||
```
|
||||
@@ -0,0 +1,7 @@
|
||||
# Candidate Pending Availability
|
||||
|
||||
Get the receipt of a candidate pending availability. This returns `Some` for any paras assigned to occupied cores in `availability_cores` and `None` otherwise.
|
||||
|
||||
```rust
|
||||
fn candidate_pending_availability(at: Block, ParaId) -> Option<CommittedCandidateReceipt>;
|
||||
```
|
||||
@@ -0,0 +1,7 @@
|
||||
# Global Validation Data
|
||||
|
||||
Yields the [`GlobalValidationData`](../types/candidate.md#globalvalidationschedule) at the state of a given block. This applies to all para candidates with the relay-parent equal to that block.
|
||||
|
||||
```rust
|
||||
fn global_validation_data(at: Block) -> GlobalValidationData;
|
||||
```
|
||||
@@ -0,0 +1,23 @@
|
||||
# Local Validation Data
|
||||
|
||||
Yields the [`LocalValidationData`](../types/candidate.md#localvalidationdata) for the given [`ParaId`](../types/candidate.md#paraid) along with an assumption that should be used if the para currently occupies a core: whether the candidate occupying that core should be assumed to have been made available and included or timed out and discarded, along with a third option to assert that the core was not occupied. This choice affects everything from the parent head-data, the validation code, and the state of message-queues. Typically, users will take the assumption that either the core was free or that the occupying candidate was included, as timeouts are expected only in adversarial circumstances and even so, only in a small minority of blocks directly following validator set rotations.
|
||||
|
||||
The documentation of [`LocalValidationData`](../types/candidate.md#localvalidationdata) has more information on this dichotomy.
|
||||
|
||||
```rust
|
||||
/// An assumption being made about the state of an occupied core.
|
||||
enum OccupiedCoreAssumption {
|
||||
/// The candidate occupying the core was made available and included to free the core.
|
||||
Included,
|
||||
/// The candidate occupying the core timed out and freed the core without advancing the para.
|
||||
TimedOut,
|
||||
/// The core was not occupied to begin with.
|
||||
Free,
|
||||
}
|
||||
|
||||
/// Returns the local validation data for the given para and occupied core assumption.
|
||||
///
|
||||
/// Returns `None` if either the para is not registered or the assumption is `Freed`
|
||||
/// and the para already occupies a core.
|
||||
fn local_validation_data(at: Block, ParaId, OccupiedCoreAssumption) -> Option<LocalValidationData>;
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
# Session Index
|
||||
|
||||
Get the session index that is expected at the child of a block.
|
||||
|
||||
In the [`Initializer`](../runtime/initializer.md) module, session changes are buffered by one block. The session index of the child of any relay block is always predictable by that block's state.
|
||||
|
||||
This session index can be used to derive a [`SigningContext`](../types/candidate.md#signing-context).
|
||||
|
||||
```rust
|
||||
/// Returns the session index expected at a child of the block.
|
||||
fn session_index_for_child(at: Block) -> SessionIndex;
|
||||
```
|
||||
@@ -0,0 +1,7 @@
|
||||
# Validation Code
|
||||
|
||||
Fetch the validation code used by a para, making the given `OccupiedCoreAssumption`.
|
||||
|
||||
```rust
|
||||
fn validation_code(at: Block, ParaId, OccupiedCoreAssumption) -> Option<ValidationCode>;
|
||||
```
|
||||
@@ -0,0 +1,35 @@
|
||||
# Validator Groups
|
||||
|
||||
Yields the validator groups used during the current session. The validators in the groups are referred to by their index into the validator-set.
|
||||
|
||||
```rust
|
||||
/// A helper data-type for tracking validator-group rotations.
|
||||
struct GroupRotationInfo {
|
||||
session_start_block: BlockNumber,
|
||||
group_rotation_frequency: BlockNumber,
|
||||
now: BlockNumber,
|
||||
}
|
||||
|
||||
impl GroupRotationInfo {
|
||||
/// Returns the index of the group needed to validate the core at the given index,
|
||||
/// assuming the given amount of cores/groups.
|
||||
fn group_for_core(&self, core_index, cores) -> GroupIndex;
|
||||
|
||||
/// Returns the block number of the next rotation after the current block. If the current block
|
||||
/// is 10 and the rotation frequency is 5, this should return 15.
|
||||
///
|
||||
/// If the group rotation frequency is 0, returns 0.
|
||||
fn next_rotation_at(&self) -> BlockNumber;
|
||||
|
||||
/// Returns the block number of the last rotation before or including the current block. If the
|
||||
/// current block is 10 and the rotation frequency is 5, this should return 10.
|
||||
///
|
||||
/// If the group rotation frequency is 0, returns 0.
|
||||
fn last_rotation_at(&self) -> BlockNumber;
|
||||
}
|
||||
|
||||
/// Returns the validator groups and rotation info localized based on the block whose state
|
||||
/// this is invoked on. Note that `now` in the `GroupRotationInfo` should be the successor of
|
||||
/// the number of the block.
|
||||
fn validator_groups(at: Block) -> (Vec<Vec<ValidatorIndex>>, GroupRotationInfo);
|
||||
```
|
||||
@@ -0,0 +1,7 @@
|
||||
# Validators
|
||||
|
||||
Yields the validator-set at the state of a given block. This validator set is always the one responsible for backing parachains in the child of the provided block.
|
||||
|
||||
```rust
|
||||
fn validators(at: Block) -> Vec<ValidatorId>;
|
||||
```
|
||||
@@ -14,82 +14,88 @@ It aims to achieve these tasks with these goals in mind:
|
||||
- Validator assignments should not be gameable. Malicious cartels should not be able to manipulate the scheduler to assign themselves as desired.
|
||||
- High or close to optimal throughput of parachains and parathreads. Work among validator groups should be balanced.
|
||||
|
||||
## Availability Cores
|
||||
|
||||
The Scheduler manages resource allocation using the concept of "Availability Cores". There will be one availability core for each parachain, and a fixed number of cores used for multiplexing parathreads. Validators will be partitioned into groups, with the same number of groups as availability cores. Validator groups will be assigned to different availability cores over time.
|
||||
|
||||
An availability core can exist in either one of two states at the beginning or end of a block: free or occupied. A free availability core can have a parachain or parathread assigned to it for the potential to have a backed candidate included. After backing, the core enters the occupied state as the backed candidate is pending availability. There is an important distinction: a core is not considered occupied until it is in charge of a block pending availability, although the implementation may treat scheduled cores the same as occupied ones for brevity. A core exits the occupied state when the candidate is no longer pending availability - either on timeout or on availability. A core starting in the occupied state can move to the free state and back to occupied all within a single block, as availability bitfields are processed before backed candidates. At the end of the block, there is a possible timeout on availability which can move the core back to the free state if occupied.
|
||||
|
||||
Cores are treated as an ordered list and are typically referred to by their index in that list.
|
||||
|
||||
```dot process
|
||||
digraph {
|
||||
label = "Availability Core State Machine\n\n\n";
|
||||
labelloc = "t";
|
||||
label = "Availability Core State Machine\n\n\n";
|
||||
labelloc = "t";
|
||||
|
||||
{ rank=same vg1 vg2 }
|
||||
{ rank=same vg1 vg2 }
|
||||
|
||||
vg1 [label = "Free" shape=rectangle]
|
||||
vg2 [label = "Occupied" shape=rectangle]
|
||||
vg1 [label = "Free" shape=rectangle]
|
||||
vg2 [label = "Occupied" shape=rectangle]
|
||||
|
||||
vg1 -> vg2 [label = "Assignment & Backing" ]
|
||||
vg2 -> vg1 [label = "Availability or Timeout" ]
|
||||
vg1 -> vg2 [label = "Assignment & Backing" ]
|
||||
vg2 -> vg1 [label = "Availability or Timeout" ]
|
||||
}
|
||||
```
|
||||
|
||||
```dot process
|
||||
digraph {
|
||||
label = "Availability Core Transitions within Block\n\n\n";
|
||||
labelloc = "t";
|
||||
splines="line";
|
||||
label = "Availability Core Transitions within Block\n\n\n";
|
||||
labelloc = "t";
|
||||
splines="line";
|
||||
|
||||
subgraph cluster_left {
|
||||
label = "";
|
||||
labelloc = "t";
|
||||
subgraph cluster_left {
|
||||
label = "";
|
||||
labelloc = "t";
|
||||
|
||||
fr1 [label = "Free" shape=rectangle]
|
||||
fr2 [label = "Free" shape=rectangle]
|
||||
occ [label = "Occupied" shape=rectangle]
|
||||
fr1 [label = "Free" shape=rectangle]
|
||||
fr2 [label = "Free" shape=rectangle]
|
||||
occ [label = "Occupied" shape=rectangle]
|
||||
|
||||
fr1 -> fr2 [label = "No Backing"]
|
||||
fr1 -> occ [label = "Backing"]
|
||||
fr1 -> fr2 [label = "No Backing"]
|
||||
fr1 -> occ [label = "Backing"]
|
||||
|
||||
{ rank=same fr2 occ }
|
||||
}
|
||||
{ rank=same fr2 occ }
|
||||
}
|
||||
|
||||
subgraph cluster_right {
|
||||
label = "";
|
||||
labelloc = "t";
|
||||
subgraph cluster_right {
|
||||
label = "";
|
||||
labelloc = "t";
|
||||
|
||||
occ2 [label = "Occupied" shape=rectangle]
|
||||
fr3 [label = "Free" shape=rectangle]
|
||||
fr4 [label = "Free" shape=rectangle]
|
||||
occ3 [label = "Occupied" shape=rectangle]
|
||||
occ4 [label = "Occupied" shape=rectangle]
|
||||
occ2 [label = "Occupied" shape=rectangle]
|
||||
fr3 [label = "Free" shape=rectangle]
|
||||
fr4 [label = "Free" shape=rectangle]
|
||||
occ3 [label = "Occupied" shape=rectangle]
|
||||
occ4 [label = "Occupied" shape=rectangle]
|
||||
|
||||
occ2 -> fr3 [label = "Availability"]
|
||||
occ2 -> occ3 [label = "No availability"]
|
||||
fr3 -> fr4 [label = "No backing"]
|
||||
fr3 -> occ4 [label = "Backing"]
|
||||
occ3 -> occ4 [label = "(no change)"]
|
||||
occ3 -> fr3 [label = "Availability Timeout"]
|
||||
occ2 -> fr3 [label = "Availability"]
|
||||
occ2 -> occ3 [label = "No availability"]
|
||||
fr3 -> fr4 [label = "No backing"]
|
||||
fr3 -> occ4 [label = "Backing"]
|
||||
occ3 -> occ4 [label = "(no change)"]
|
||||
occ3 -> fr3 [label = "Availability Timeout"]
|
||||
|
||||
{ rank=same; fr3[group=g1]; occ3[group=g2] }
|
||||
{ rank=same; fr4[group=g1]; occ4[group=g2] }
|
||||
}
|
||||
{ rank=same; fr3[group=g1]; occ3[group=g2] }
|
||||
{ rank=same; fr4[group=g1]; occ4[group=g2] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Validator Groups
|
||||
|
||||
Validator group assignments do not need to change very quickly. The security benefits of fast rotation is redundant with the challenge mechanism in the [Validity module](validity.md). Because of this, we only divide validators into groups at the beginning of the session and do not shuffle membership during the session. However, we do take steps to ensure that no particular validator group has dominance over a single parachain or parathread-multiplexer for an entire session to provide better guarantees of liveness.
|
||||
|
||||
Validator groups rotate across availability cores in a round-robin fashion, with rotation occurring at fixed intervals. The i'th group will be assigned to the `(i+k)%n`'th core at any point in time, where `k` is the number of rotations that have occurred in the session, and `n` is the number of cores. This makes upcoming rotations within the same session predictable.
|
||||
|
||||
When a rotation occurs, validator groups are still responsible for distributing availability chunks for any previous cores that are still occupied and pending availability. In practice, rotation and availability-timeout frequencies should be set so this will only be the core they have just been rotated from. It is possible that a validator group is rotated onto a core which is currently occupied. In this case, the validator group will have nothing to do until the previously-assigned group finishes their availability work and frees the core or the availability process times out. Depending on if the core is for a parachain or parathread, a different timeout `t` from the [`HostConfiguration`](../types/runtime.md#host-configuration) will apply. Availability timeouts should only be triggered in the first `t-1` blocks after the beginning of a rotation.
|
||||
|
||||
## Claims
|
||||
|
||||
Parathreads operate on a system of claims. Collators participate in auctions to stake a claim on authoring the next block of a parathread, although the auction mechanism is beyond the scope of the scheduler. The scheduler guarantees that they'll be given at least a certain number of attempts to author a candidate that is backed. Attempts that fail during the availability phase are not counted, since ensuring availability at that stage is the responsibility of the backing validators, not of the collator. When a claim is accepted, it is placed into a queue of claims, and each claim is assigned to a particular parathread-multiplexing core in advance. Given that the current assignments of validator groups to cores are known, and the upcoming assignments are predictable, it is possible for parathread collators to know who they should be talking to now and how they should begin establishing connections with as a fallback.
|
||||
|
||||
With this information, the Node-side can be aware of which parathreads have a good chance of being includable within the relay-chain block and can focus any additional resources on backing candidates from those parathreads. Furthermore, Node-side code is aware of which validator group will be responsible for that thread. If the necessary conditions are reached for core reassignment, those candidates can be backed within the same block as the core being freed.
|
||||
|
||||
Parathread claims, when scheduled onto a free core, may not result in a block pending availability. This may be due to collator error, networking timeout, or censorship by the validator group. In this case, the claims should be retried a certain number of times to give the collator a fair shot.
|
||||
|
||||
Cores are treated as an ordered list of cores and are typically referred to by their index in that list.
|
||||
|
||||
## Storage
|
||||
|
||||
Utility structs:
|
||||
|
||||
@@ -14,6 +14,16 @@ type SignedAvailabilityBitfield = Signed<Bitvec>;
|
||||
struct Bitfields(Vec<(SignedAvailabilityBitfield)>), // bitfields sorted by validator index, ascending
|
||||
```
|
||||
|
||||
### Semantics
|
||||
|
||||
A `SignedAvailabilityBitfield` represents the view from a particular validator's perspective. Each bit in the bitfield corresponds to a single [availability core](../runtime-api/availability-cores.md). A `1` bit indicates that the validator believes the following statements to be true for a core:
|
||||
|
||||
- the availability core is occupied
|
||||
- there exists a [`CommittedCandidateReceipt`](candidate.html#committed-candidate-receipt) corresponding to that core. In other words, that para has a block in progress.
|
||||
- the validator's [Availability Store](../node/utility/availability-store.md) contains a chunk of that parablock's PoV.
|
||||
|
||||
In other words, it is the transpose of [`OccupiedCore::availability`](../runtime-api/availability-cores.md).
|
||||
|
||||
## Proof-of-Validity
|
||||
|
||||
Often referred to as PoV, this is a type-safe wrapper around bytes (`Vec<u8>`) when referring to data that acts as a stateless-client proof of validity of a candidate, when used as input to the validation function of the para.
|
||||
|
||||
Reference in New Issue
Block a user