From b06d5d993c1240be54e8f4d25a2858a5e83754e5 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Fri, 10 Jul 2020 19:00:13 -0400 Subject: [PATCH 01/12] create a README on Runtime APIs --- roadmap/implementers-guide/src/SUMMARY.md | 1 + .../src/runtime-api/README.md | 22 +++++++++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 roadmap/implementers-guide/src/runtime-api/README.md diff --git a/roadmap/implementers-guide/src/SUMMARY.md b/roadmap/implementers-guide/src/SUMMARY.md index b5dc3840c605..0a7fa21d2a31 100644 --- a/roadmap/implementers-guide/src/SUMMARY.md +++ b/roadmap/implementers-guide/src/SUMMARY.md @@ -14,6 +14,7 @@ - [InclusionInherent Module](runtime/inclusioninherent.md) - [Validity Module](runtime/validity.md) - [Router Module](runtime/router.md) +- [Runtime APIs](runtime-api/README.md) - [Node Architecture](node/README.md) - [Subsystems and Jobs](node/subsystems-and-jobs.md) - [Overseer](node/overseer.md) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md new file mode 100644 index 000000000000..34d35931dd39 --- /dev/null +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -0,0 +1,22 @@ +# Runtime APIs + +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. + +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 + +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 + +The next sections will contain information on specific runtime APIs. From 5e3dc857a9b52eab8b2b0da3cf13d3adb284e3eb Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Mon, 13 Jul 2020 19:31:30 -0400 Subject: [PATCH 02/12] add ParaId type --- roadmap/implementers-guide/src/types/candidate.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/roadmap/implementers-guide/src/types/candidate.md b/roadmap/implementers-guide/src/types/candidate.md index 0ed38590a733..0002851cee18 100644 --- a/roadmap/implementers-guide/src/types/candidate.md +++ b/roadmap/implementers-guide/src/types/candidate.md @@ -7,6 +7,14 @@ In a way, this entire guide is about these candidates: how they are scheduled, c This section will describe the base candidate type, its components, and variants that contain extra data. +## Para Id + +A unique 32-bit identifier referring to a specific para (chain or thread). The relay-chain runtime guarantees that `ParaId`s are unique for the duration of any session, but recycling and reuse over a longer period of time is permitted. + +```rust +struct ParaId(u32); +``` + ## Candidate Receipt Much info in a [`FullCandidateReceipt`](#full-candidate-receipt) is duplicated from the relay-chain state. When the corresponding relay-chain state is considered widely available, the Candidate Receipt should be favored over the `FullCandidateReceipt`. @@ -64,7 +72,7 @@ This struct is pure description of the candidate, in a lightweight format. /// A unique descriptor of the candidate receipt. struct CandidateDescriptor { /// The ID of the para this is a candidate for. - para_id: Id, + para_id: ParaId, /// The hash of the relay-chain block this is executed in the context of. relay_parent: Hash, /// The collator's sr25519 public key. @@ -82,8 +90,6 @@ struct CandidateDescriptor { The global validation schedule comprises of information describing the global environment for para execution, as derived from a particular relay-parent. These are parameters that will apply to all parablocks executed in the context of this relay-parent. -> TODO: message queue watermarks (first downward messages, then XCMP channels) - ```rust /// Extra data that is needed along with the other fields in a `CandidateReceipt` /// to fully validate the candidate. @@ -112,6 +118,7 @@ This choice can also be expressed as a choice of which parent head of the para w Para validation happens optimistically before the block is authored, so it is not possible to predict with 100% accuracy what will happen in the earlier phase of the [`InclusionInherent`](../runtime/inclusioninherent.md) module where new availability bitfields and availability timeouts are processed. This is what will eventually define whether a candidate can be backed within a specific relay-chain block. > TODO: determine if balance/fees are even needed here. +> TODO: message queue watermarks (first downward messages, then XCMP channels) ```rust /// Extra data that is needed along with the other fields in a `CandidateReceipt` From 8651e37f7104343516ee0f1bf7e74ae1e31e3693 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Mon, 13 Jul 2020 19:55:19 -0400 Subject: [PATCH 03/12] write up runtime APIs --- .../src/runtime-api/README.md | 119 ++++++++++++++++++ .../src/runtime/scheduler.md | 3 +- 2 files changed, 120 insertions(+), 2 deletions(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index 34d35931dd39..e46ec8fe42dc 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -20,3 +20,122 @@ So it is clear that Runtime APIs are a versatile and powerful tool to leverage t * Submitting misbehavior reports The next sections will contain information on specific runtime APIs. + +## 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() -> Vec; +``` + +## 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. + fn group_for_core(usize) -> usize; +} + +/// 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() -> (Vec>, GroupRotationInfo); +``` + +## ScheduledParas + +Yields information on the scheduling of paras. + +```rust +fn scheduled_paras() -> ScheduledParas; +``` + +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: 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, + /// 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, + /// 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, +} + +struct ScheduledCore { + /// The ID of a para scheduled. + para: ParaId, + /// The collator required to author the block, if any. + collator: Option, +} + +enum CoreState { + /// The core is currently occupied by the given `ParaId`. + Occupied(OccupiedCore), + /// The core is currently free, with the given `ParaId` 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) +} +``` + +```rust +struct ScheduledParas { + /// All cores, along with their state. There should be as many items in this vector as there + /// are cores in the system. + cores: Vec, +} +``` + +## Global Validation Schedule + +Yields the [`GlobalValidationSchedule`](../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_schedule() -> GlobalValidationSchedule; +``` + +## 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. + Freed, +} + +/// 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(ParaId, OccupiedCoreAssumption) -> Option; +``` diff --git a/roadmap/implementers-guide/src/runtime/scheduler.md b/roadmap/implementers-guide/src/runtime/scheduler.md index 0b6a60a383ee..efa85a15c48b 100644 --- a/roadmap/implementers-guide/src/runtime/scheduler.md +++ b/roadmap/implementers-guide/src/runtime/scheduler.md @@ -131,8 +131,7 @@ Storage layout: ValidatorGroups: Vec>; /// A queue of upcoming claims and which core they should be mapped onto. ParathreadQueue: ParathreadQueue; -/// One entry for each availability core. Entries are `None` if the core is not currently occupied. Can be -/// temporarily `Some` if scheduled but not occupied. +/// One entry for each availability core. Entries are `None` if the core is not currently occupied. /// The i'th parachain belongs to the i'th core, with the remaining cores all being /// parathread-multiplexers. AvailabilityCores: Vec>; From 539b7ba50adac51ec344f7968ebca3644ee98d88 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Mon, 13 Jul 2020 20:27:52 -0400 Subject: [PATCH 04/12] more preamble --- roadmap/implementers-guide/src/runtime-api/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index e46ec8fe42dc..b4280992da83 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -19,6 +19,10 @@ So it is clear that Runtime APIs are a versatile and powerful tool to leverage t * 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. + +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. ## Validators From ac39016394d7b16f8413e4a697af739116565af8 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Mon, 13 Jul 2020 20:41:01 -0400 Subject: [PATCH 05/12] rename --- .../implementers-guide/src/runtime-api/README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index b4280992da83..d710eab17743 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -56,12 +56,12 @@ impl GroupRotationInfo { fn validator_groups() -> (Vec>, GroupRotationInfo); ``` -## ScheduledParas +## Availability Cores -Yields information on the scheduling of paras. +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 ```rust -fn scheduled_paras() -> ScheduledParas; +fn availability_cores() -> AvailabilityCores; ``` 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. @@ -100,12 +100,15 @@ enum CoreState { /// /// If a particular Collator is required to author this block, that is also present in this /// variant. - Scheduled(ScheduledCore) + 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, } ``` ```rust -struct ScheduledParas { +struct AvailabilityCores { /// All cores, along with their state. There should be as many items in this vector as there /// are cores in the system. cores: Vec, From 8eebbe81458a435ef887809d45e55c80153ef461 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Mon, 13 Jul 2020 21:00:43 -0400 Subject: [PATCH 06/12] rejig runtime APIs --- .../src/runtime-api/README.md | 29 ++++++++++++ .../src/types/overseer-protocol.md | 44 +++++++++---------- 2 files changed, 51 insertions(+), 22 deletions(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index d710eab17743..8f47c29217fb 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -146,3 +146,32 @@ enum OccupiedCoreAssumption { /// and the para already occupies a core. fn local_validation_data(ParaId, OccupiedCoreAssumption) -> Option; ``` + +## 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 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() -> SessionIndex; +``` + +## Validation Code + +Fetch the validation code used by a para, making the given `OccupiedCoreAssumption`. + +```rust +fn validation_code(ParaId, OccupiedCoreAssumption) -> 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(ParaId) -> Option; +``` diff --git a/roadmap/implementers-guide/src/types/overseer-protocol.md b/roadmap/implementers-guide/src/types/overseer-protocol.md index b822508f4a3e..3298d8f65f99 100644 --- a/roadmap/implementers-guide/src/types/overseer-protocol.md +++ b/roadmap/implementers-guide/src/types/overseer-protocol.md @@ -228,33 +228,33 @@ enum ProvisionerMessage { The Runtime API subsystem is responsible for providing an interface to the state of the chain's runtime. -Other subsystems query this data by sending these messages. +This is fueled by an auxiliary type encapsulating all request types defined in the Runtime API section of the guide. -```rust -/// The information on validator groups, core assignments, -/// upcoming paras and availability cores. -struct SchedulerRoster { - /// Validator-to-groups assignments. - validator_groups: Vec>, - /// All scheduled paras. - scheduled: Vec, - /// Upcoming paras (chains and threads). - upcoming: Vec, - /// Occupied cores. - availability_cores: Vec>, -} +> TODO: link to the Runtime API section. Not possible currently because of https://github.com/Michael-F-Bryan/mdbook-linkcheck/issues/25. Once v0.7.1 is released it will work. +```rust enum RuntimeApiRequest { /// Get the current validator set. Validators(ResponseChannel>), - /// Get the assignments of validators to cores, upcoming parachains. - SchedulerRoster(ResponseChannel), - /// Get a signing context for bitfields and statements. - SigningContext(ResponseChannel), - /// Get the validation code for a specific para, assuming execution under given block number, and - /// an optional block number representing an intermediate parablock executed in the context of - /// that block. - ValidationCode(ParaId, BlockNumber, Option, ResponseChannel), + /// Get the validator groups and rotation info. + ValidatorGroups(ResponseChannel<(Vec>, GroupRotationInfo)>), + /// Get the session index for children of the block. This can be used to construct a signing + /// context. + SessionIndex(ResponseChannel), + /// Get the validation code for a specific para, using the given occupied core assumption. + ValidationCode(ParaId, OccupiedCoreAssumption, ResponseChannel>), + /// Get the global validation schedule at the state of a given block. + GlobalValidationSchedule(ResponseChannel), + /// Get the local validation data for a specific para, with the given occupied core assumption. + LocalValidationData( + ParaId, + OccupiedCoreAssumption, + ResponseChannel>, + ), + /// Get information about all availability cores. + AvailabilityCores(ResponseChannel), + /// Get a committed candidate receipt for all candidates pending availability. + CandidatePendingAvailability(ParaId, ResponseChannel>), } enum RuntimeApiMessage { From 8c8193db0d96c7b51229503da91724c47ee5d7f0 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Tue, 14 Jul 2020 18:56:48 -0400 Subject: [PATCH 07/12] add occupied_since to `BlockNumber` --- roadmap/implementers-guide/src/runtime-api/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index 8f47c29217fb..b3e75c22bad0 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -73,6 +73,8 @@ struct OccupiedCore { /// 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, + /// 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 From 2456ae616a5ecd03d35a429e34e658071492fe59 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Tue, 14 Jul 2020 19:31:32 -0400 Subject: [PATCH 08/12] improve group_for_core --- roadmap/implementers-guide/src/runtime-api/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index b3e75c22bad0..75b2af848095 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -46,8 +46,9 @@ struct GroupRotationInfo { } impl GroupRotationInfo { - /// Returns the index of the group needed to validate the core at the given index. - fn group_for_core(usize) -> usize; + /// 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(core_index: usize, cores: usize) -> usize; } /// Returns the validator groups and rotation info localized based on the block whose state From 00f74466efa142200243436d2742925665da9dd7 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Tue, 14 Jul 2020 19:41:05 -0400 Subject: [PATCH 09/12] improve docs on availability cores runtime API --- .../implementers-guide/src/runtime-api/README.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index 75b2af848095..065ecd7e4115 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -59,10 +59,10 @@ fn validator_groups() -> (Vec>, 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 +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() -> AvailabilityCores; +fn availability_cores() -> Vec; ``` 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. @@ -96,9 +96,9 @@ struct ScheduledCore { } enum CoreState { - /// The core is currently occupied by the given `ParaId`. + /// The core is currently occupied. Occupied(OccupiedCore), - /// The core is currently free, with the given `ParaId` scheduled and given the opportunity + /// 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 @@ -110,14 +110,6 @@ enum CoreState { } ``` -```rust -struct AvailabilityCores { - /// All cores, along with their state. There should be as many items in this vector as there - /// are cores in the system. - cores: Vec, -} -``` - ## Global Validation Schedule Yields the [`GlobalValidationSchedule`](../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. From fde221b43c1f9798bbea727fc7cdd6b2f29db6c8 Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Tue, 14 Jul 2020 19:42:41 -0400 Subject: [PATCH 10/12] guide: freed -> free --- roadmap/implementers-guide/src/runtime-api/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index 065ecd7e4115..65ead0ab5869 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -132,7 +132,7 @@ enum OccupiedCoreAssumption { /// The candidate occupying the core timed out and freed the core without advancing the para. TimedOut, /// The core was not occupied to begin with. - Freed, + Free, } /// Returns the local validation data for the given para and occupied core assumption. From 69c0d5549b44eb29ac8b702251c0ea37dcae4f7c Mon Sep 17 00:00:00 2001 From: Robert Habermeier Date: Wed, 15 Jul 2020 13:47:01 -0400 Subject: [PATCH 11/12] Update roadmap/implementers-guide/src/runtime-api/README.md Co-authored-by: Peter Goodspeed-Niklaus --- roadmap/implementers-guide/src/runtime-api/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index 65ead0ab5869..1614386a5bc3 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -146,7 +146,7 @@ fn local_validation_data(ParaId, OccupiedCoreAssumption) -> Option Date: Wed, 15 Jul 2020 22:50:33 -0400 Subject: [PATCH 12/12] add explicit block parameter to runtime API fns --- .../src/runtime-api/README.md | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/roadmap/implementers-guide/src/runtime-api/README.md b/roadmap/implementers-guide/src/runtime-api/README.md index 1614386a5bc3..4631fab30b50 100644 --- a/roadmap/implementers-guide/src/runtime-api/README.md +++ b/roadmap/implementers-guide/src/runtime-api/README.md @@ -23,14 +23,25 @@ More broadly, we have the goal of using Runtime APIs to write Node-side code tha 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 next sections will contain information on specific runtime APIs. The format is this: + +```rust +/// Fetch the value of the runtime API at the block. +/// +/// Definitionally, the `at` parameter cannot be any block that is not in the chain. +/// Thus the return value is unconditional. However, for in-practice implementations +/// it may be possible to provide an `at` parameter as a hash, which may not refer to a +/// valid block or one which implements the runtime API. In those cases it would be +/// 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() -> Vec; +fn validators(at: Block) -> Vec; ``` ## Validator Groups @@ -54,7 +65,7 @@ impl GroupRotationInfo { /// 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() -> (Vec>, GroupRotationInfo); +fn validator_groups(at: Block) -> (Vec>, GroupRotationInfo); ``` ## Availability Cores @@ -62,7 +73,7 @@ fn validator_groups() -> (Vec>, GroupRotationInfo); 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() -> Vec; +fn availability_cores(at: Block) -> Vec; ``` 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. @@ -115,7 +126,7 @@ enum CoreState { Yields the [`GlobalValidationSchedule`](../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_schedule() -> GlobalValidationSchedule; +fn global_validation_schedule(at: Block) -> GlobalValidationSchedule; ``` ## Local Validation Data @@ -139,7 +150,7 @@ enum OccupiedCoreAssumption { /// /// 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(ParaId, OccupiedCoreAssumption) -> Option; +fn local_validation_data(at: Block, ParaId, OccupiedCoreAssumption) -> Option; ``` ## Session Index @@ -152,7 +163,7 @@ This session index can be used to derive a [`SigningContext`](../types/candidate ```rust /// Returns the session index expected at a child of the block. -fn session_index_for_child() -> SessionIndex; +fn session_index_for_child(at: Block) -> SessionIndex; ``` ## Validation Code @@ -160,7 +171,7 @@ fn session_index_for_child() -> SessionIndex; Fetch the validation code used by a para, making the given `OccupiedCoreAssumption`. ```rust -fn validation_code(ParaId, OccupiedCoreAssumption) -> ValidationCode; +fn validation_code(at: Block, ParaId, OccupiedCoreAssumption) -> ValidationCode; ``` ## Candidate Pending Availability @@ -168,5 +179,5 @@ fn validation_code(ParaId, OccupiedCoreAssumption) -> ValidationCode; 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(ParaId) -> Option; +fn candidate_pending_availability(at: Block, ParaId) -> Option; ```