mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-16 16:41:10 +00:00
Markdown linter (#1309)
* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
This commit is contained in:
Chevdor
@@ -2,9 +2,16 @@
|
||||
|
||||
Runtime APIs are the means by which the node-side code extracts information from the state of the runtime.
|
||||
|
||||
Every block in the relay-chain contains a *state root* which is the root hash of a state trie encapsulating all storage of runtime modules after execution of the block. This is a cryptographic commitment to a unique state. We use the terminology of accessing the *state at* a block to refer accessing the state referred to by the state root of that block.
|
||||
Every block in the relay-chain contains a *state root* which is the root hash of a state trie encapsulating all storage
|
||||
of runtime modules after execution of the block. This is a cryptographic commitment to a unique state. We use the
|
||||
terminology of accessing the *state at* a block to refer accessing the state referred to by the state root of that
|
||||
block.
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
@@ -14,16 +21,25 @@ Abilities provided by host functions includes:
|
||||
* 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:
|
||||
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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Node-side code is also responsible for detecting and reporting misbehavior performed by other validators, and the set of Runtime APIs needs to provide methods for observing live disputes and submitting reports as transactions.
|
||||
Node-side code is also responsible for detecting and reporting misbehavior performed by other validators, and the set of
|
||||
Runtime APIs needs to provide methods for observing live disputes and submitting reports as transactions.
|
||||
|
||||
The next sections will contain information on specific runtime APIs. The format is this:
|
||||
|
||||
@@ -38,9 +54,16 @@ The next sections will contain information on specific runtime APIs. The format
|
||||
fn some_runtime_api(at: Block, arg1: Type1, arg2: Type2, ...) -> ReturnValue;
|
||||
```
|
||||
|
||||
Certain runtime APIs concerning the state of a para require the caller to provide an `OccupiedCoreAssumption`. This indicates how the result of the runtime API should be computed if there is a candidate from the para occupying an availability core in the [Inclusion Module](../runtime/inclusion.md).
|
||||
Certain runtime APIs concerning the state of a para require the caller to provide an `OccupiedCoreAssumption`. This
|
||||
indicates how the result of the runtime API should be computed if there is a candidate from the para occupying an
|
||||
availability core in the [Inclusion Module](../runtime/inclusion.md).
|
||||
|
||||
The choices of assumption are 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 choices of assumption are 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.
|
||||
|
||||
```rust
|
||||
/// An assumption being made about the state of an occupied core.
|
||||
@@ -52,4 +75,4 @@ enum OccupiedCoreAssumption {
|
||||
/// The core was not occupied to begin with.
|
||||
Free,
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
@@ -1,14 +1,26 @@
|
||||
# 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.
|
||||
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.
|
||||
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. The implementation of this runtime API should invoke `Scheduler::clear` and `Scheduler::schedule(Vec::new(), current_block_number + 1)` to ensure that scheduling is accurate.
|
||||
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. The implementation of this runtime API should invoke `Scheduler::clear` and `Scheduler::schedule(Vec::new(),
|
||||
current_block_number + 1)` to ensure that scheduling is accurate.
|
||||
|
||||
```rust
|
||||
struct OccupiedCore {
|
||||
|
||||
+2
-1
@@ -1,6 +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.
|
||||
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>;
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
# Disputes Info
|
||||
|
||||
Get information about all disputes known by the chain as well as information about which validators the disputes subsystem will accept disputes from. These disputes may be either live or concluded. The [`DisputeState`](../types/disputes.md#disputestate) can be used to determine whether the dispute still accepts votes, as well as which validators' votes may be included.
|
||||
Get information about all disputes known by the chain as well as information about which validators the disputes
|
||||
subsystem will accept disputes from. These disputes may be either live or concluded. The
|
||||
[`DisputeState`](../types/disputes.md#disputestate) can be used to determine whether the dispute still accepts votes, as
|
||||
well as which validators' votes may be included.
|
||||
|
||||
```rust
|
||||
struct Dispute {
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Persisted Validation Data
|
||||
|
||||
Yields the [`PersistedValidationData`](../types/candidate.md#persistedvalidationdata) for the given [`ParaId`](../types/candidate.md#paraid) along with an assumption that should be used if the para currently occupies a core:
|
||||
Yields the [`PersistedValidationData`](../types/candidate.md#persistedvalidationdata) for the given
|
||||
[`ParaId`](../types/candidate.md#paraid) along with an assumption that should be used if the para currently occupies a
|
||||
core:
|
||||
|
||||
```rust
|
||||
/// Returns the persisted validation data for the given para and occupied core assumption.
|
||||
@@ -8,4 +10,4 @@ Yields the [`PersistedValidationData`](../types/candidate.md#persistedvalidation
|
||||
/// Returns `None` if either the para is not registered or the assumption is `Freed`
|
||||
/// and the para already occupies a core.
|
||||
fn persisted_validation_data(at: Block, ParaId, OccupiedCoreAssumption) -> Option<PersistedValidationData>;
|
||||
```
|
||||
```
|
||||
|
||||
@@ -4,18 +4,18 @@
|
||||
|
||||
There are two main runtime APIs to work with PVF pre-checking.
|
||||
|
||||
The first runtime API is designed to fetch all PVFs that require pre-checking voting. The PVFs are
|
||||
identified by their code hashes. As soon as the PVF gains required support, the runtime API will
|
||||
not return the PVF anymore.
|
||||
The first runtime API is designed to fetch all PVFs that require pre-checking voting. The PVFs are identified by their
|
||||
code hashes. As soon as the PVF gains required support, the runtime API will not return the PVF anymore.
|
||||
|
||||
```rust
|
||||
fn pvfs_require_precheck() -> Vec<ValidationCodeHash>;
|
||||
```
|
||||
|
||||
The second runtime API is needed to submit the judgement for a PVF, whether it is approved or not.
|
||||
The voting process uses unsigned transactions. The [`PvfCheckStatement`](../types/pvf-prechecking.md) is circulated through the network via gossip similar to a normal transaction. At some point the validator
|
||||
will include the statement in the block, where it will be processed by the runtime. If that was the
|
||||
last vote before gaining the super-majority, this PVF will not be returned by `pvfs_require_precheck` anymore.
|
||||
The second runtime API is needed to submit the judgement for a PVF, whether it is approved or not. The voting process
|
||||
uses unsigned transactions. The [`PvfCheckStatement`](../types/pvf-prechecking.md) is circulated through the network via
|
||||
gossip similar to a normal transaction. At some point the validator will include the statement in the block, where it
|
||||
will be processed by the runtime. If that was the last vote before gaining the super-majority, this PVF will not be
|
||||
returned by `pvfs_require_precheck` anymore.
|
||||
|
||||
```rust
|
||||
fn submit_pvf_check_statement(stmt: PvfCheckStatement, signature: ValidatorSignature);
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
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.
|
||||
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).
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# 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 and this is assumed to be as-of the child of the block whose state is being queried.
|
||||
Yields the validator groups used during the current session. The validators in the groups are referred to by their index
|
||||
into the validator-set and this is assumed to be as-of the child of the block whose state is being queried.
|
||||
|
||||
```rust
|
||||
/// A helper data-type for tracking validator-group rotations.
|
||||
|
||||
@@ -1,6 +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.
|
||||
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>;
|
||||
|
||||
Reference in New Issue
Block a user