|
| 1 | +// Copyright 2022 Parity Technologies (UK) Ltd. |
| 2 | +// This file is part of Polkadot. |
| 3 | + |
| 4 | +// Polkadot is free software: you can redistribute it and/or modify |
| 5 | +// it under the terms of the GNU General Public License as published by |
| 6 | +// the Free Software Foundation, either version 3 of the License, or |
| 7 | +// (at your option) any later version. |
| 8 | + |
| 9 | +// Polkadot is distributed in the hope that it will be useful, |
| 10 | +// but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 | +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 12 | +// GNU General Public License for more details. |
| 13 | + |
| 14 | +// You should have received a copy of the GNU General Public License |
| 15 | +// along with Polkadot. If not, see <http://www.gnu.org/licenses/>. |
| 16 | + |
| 17 | +//! Staging primitives used to accumulate changes before going live. |
| 18 | +
|
| 19 | +use crate::{v1, v2}; |
| 20 | + |
| 21 | +use parity_scale_codec::{Decode, Encode}; |
| 22 | +use sp_std::{collections::btree_map::BTreeMap, prelude::*}; |
| 23 | + |
| 24 | +sp_api::decl_runtime_apis! { |
| 25 | + /// The API for querying the state of parachains on-chain. |
| 26 | + #[api_version(4294967295)] // Macro doesn't allow specifying `u32::MAX`. |
| 27 | + pub trait ParachainHost<H: Encode + Decode = v1::Hash, N: Encode + Decode = v1::BlockNumber> { |
| 28 | + /// Get the current validators. |
| 29 | + fn validators() -> Vec<v1::ValidatorId>; |
| 30 | + |
| 31 | + /// Returns the validator groups and rotation info localized based on the hypothetical child |
| 32 | + /// of a block whose state this is invoked on. Note that `now` in the `GroupRotationInfo` |
| 33 | + /// should be the successor of the number of the block. |
| 34 | + fn validator_groups() -> (Vec<Vec<v1::ValidatorIndex>>, v1::GroupRotationInfo<N>); |
| 35 | + |
| 36 | + /// Yields information on all availability cores as relevant to the child block. |
| 37 | + /// Cores are either free or occupied. Free cores can have paras assigned to them. |
| 38 | + fn availability_cores() -> Vec<v1::CoreState<H, N>>; |
| 39 | + |
| 40 | + /// Yields the persisted validation data for the given `ParaId` along with an assumption that |
| 41 | + /// should be used if the para currently occupies a core. |
| 42 | + /// |
| 43 | + /// Returns `None` if either the para is not registered or the assumption is `Freed` |
| 44 | + /// and the para already occupies a core. |
| 45 | + fn persisted_validation_data(para_id: v1::Id, assumption: v1::OccupiedCoreAssumption) |
| 46 | + -> Option<v1::PersistedValidationData<H, N>>; |
| 47 | + |
| 48 | + /// Returns the persisted validation data for the given `ParaId` along with the corresponding |
| 49 | + /// validation code hash. Instead of accepting assumption about the para, matches the validation |
| 50 | + /// data hash against an expected one and yields `None` if they're not equal. |
| 51 | + fn assumed_validation_data( |
| 52 | + para_id: v1::Id, |
| 53 | + expected_persisted_validation_data_hash: v1::Hash, |
| 54 | + ) -> Option<(v1::PersistedValidationData<H, N>, v1::ValidationCodeHash)>; |
| 55 | + |
| 56 | + /// Checks if the given validation outputs pass the acceptance criteria. |
| 57 | + #[changed_in(4294967295)] |
| 58 | + fn check_validation_outputs(para_id: v1::Id, outputs: v1::CandidateCommitments) -> bool; |
| 59 | + |
| 60 | + /// Returns the session index expected at a child of the block. |
| 61 | + /// |
| 62 | + /// This can be used to instantiate a `SigningContext`. |
| 63 | + fn session_index_for_child() -> v1::SessionIndex; |
| 64 | + |
| 65 | + /// Fetch the validation code used by a para, making the given `OccupiedCoreAssumption`. |
| 66 | + /// |
| 67 | + /// Returns `None` if either the para is not registered or the assumption is `Freed` |
| 68 | + /// and the para already occupies a core. |
| 69 | + fn validation_code(para_id: v1::Id, assumption: v1::OccupiedCoreAssumption) |
| 70 | + -> Option<v1::ValidationCode>; |
| 71 | + |
| 72 | + /// Get the receipt of a candidate pending availability. This returns `Some` for any paras |
| 73 | + /// assigned to occupied cores in `availability_cores` and `None` otherwise. |
| 74 | + fn candidate_pending_availability(para_id: v1::Id) -> Option<v1::CommittedCandidateReceipt<H>>; |
| 75 | + |
| 76 | + /// Get a vector of events concerning candidates that occurred within a block. |
| 77 | + fn candidate_events() -> Vec<v1::CandidateEvent<H>>; |
| 78 | + |
| 79 | + /// Get all the pending inbound messages in the downward message queue for a para. |
| 80 | + fn dmq_contents( |
| 81 | + recipient: v1::Id, |
| 82 | + ) -> Vec<v1::InboundDownwardMessage<N>>; |
| 83 | + |
| 84 | + /// Get the contents of all channels addressed to the given recipient. Channels that have no |
| 85 | + /// messages in them are also included. |
| 86 | + fn inbound_hrmp_channels_contents(recipient: v1::Id) -> BTreeMap<v1::Id, Vec<v1::InboundHrmpMessage<N>>>; |
| 87 | + |
| 88 | + /// Get the validation code from its hash. |
| 89 | + fn validation_code_by_hash(hash: v1::ValidationCodeHash) -> Option<v1::ValidationCode>; |
| 90 | + |
| 91 | + /// Scrape dispute relevant from on-chain, backing votes and resolved disputes. |
| 92 | + fn on_chain_votes() -> Option<v1::ScrapedOnChainVotes<H>>; |
| 93 | + |
| 94 | + /***** Added in v2 *****/ |
| 95 | + |
| 96 | + /// Get the session info for the given session, if stored. |
| 97 | + /// |
| 98 | + /// NOTE: This function is only available since parachain host version 2. |
| 99 | + fn session_info(index: v1::SessionIndex) -> Option<v2::SessionInfo>; |
| 100 | + |
| 101 | + /// Submits a PVF pre-checking statement into the transaction pool. |
| 102 | + /// |
| 103 | + /// NOTE: This function is only available since parachain host version 2. |
| 104 | + fn submit_pvf_check_statement(stmt: v2::PvfCheckStatement, signature: v1::ValidatorSignature); |
| 105 | + |
| 106 | + /// Returns code hashes of PVFs that require pre-checking by validators in the active set. |
| 107 | + /// |
| 108 | + /// NOTE: This function is only available since parachain host version 2. |
| 109 | + fn pvfs_require_precheck() -> Vec<v1::ValidationCodeHash>; |
| 110 | + |
| 111 | + /// Fetch the hash of the validation code used by a para, making the given `OccupiedCoreAssumption`. |
| 112 | + /// |
| 113 | + /// NOTE: This function is only available since parachain host version 2. |
| 114 | + fn validation_code_hash(para_id: v1::Id, assumption: v1::OccupiedCoreAssumption) |
| 115 | + -> Option<v1::ValidationCodeHash>; |
| 116 | + |
| 117 | + /***** Staging *****/ |
| 118 | + |
| 119 | + /// Checks if the given validation outputs pass the acceptance criteria. |
| 120 | + fn check_validation_outputs( |
| 121 | + para_id: v1::Id, |
| 122 | + relay_parent_number: v1::BlockNumber, |
| 123 | + outputs: v1::CandidateCommitments, |
| 124 | + ) -> bool; |
| 125 | + } |
| 126 | +} |
0 commit comments