1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301
// Copyright (C) Parity Technologies (UK) Ltd.
// This file is part of Polkadot.
// Polkadot is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Polkadot is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Polkadot. If not, see <http://www.gnu.org/licenses/>.
//! Runtime API module declares the `trait ParachainHost` which is part
//! of the Runtime API exposed from the Runtime to the Host.
//!
//! The functions in trait ParachainHost` can be part of the stable API
//! (which is versioned) or they can be staging (aka unstable/testing
//! functions).
//!
//! The separation outlined above is achieved with the versioned API feature
//! of `decl_runtime_apis!` and `impl_runtime_apis!`. Before moving on let's
//! see a quick example about how API versioning works.
//!
//! # Runtime API versioning crash course
//!
//! The versioning is achieved with the `api_version` attribute. It can be
//! placed on:
//! * trait declaration - represents the base version of the API.
//! * method declaration (inside a trait declaration) - represents a versioned method, which is not
//! available in the base version.
//! * trait implementation - represents which version of the API is being implemented.
//!
//! Let's see a quick example:
//!
//! ```nocompile
//! sp_api::decl_runtime_apis! {
//! #[api_version(2)]
//! pub trait MyApi {
//! fn fn1();
//! fn fn2();
//! #[api_version(3)]
//! fn fn3();
//! #[api_version(4)]
//! fn fn4();
//! }
//! }
//!
//! struct Runtime {}
//!
//! sp_api::impl_runtime_apis! {
//! #[api_version(3)]
//! impl self::MyApi<Block> for Runtime {
//! fn fn1() {}
//! fn fn2() {}
//! fn fn3() {}
//! }
//! }
//! ```
//! A new API named `MyApi` is declared with `decl_runtime_apis!`. The trait declaration
//! has got an `api_version` attribute which represents its base version - 2 in this case.
//!
//! The API has got three methods - `fn1`, `fn2`, `fn3` and `fn4`. `fn3` and `fn4` has got
//! an `api_version` attribute which makes them versioned methods. These methods do not exist
//! in the base version of the API. Behind the scenes the declaration above creates three
//! runtime APIs:
//! * `MyApiV2` with `fn1` and `fn2`
//! * `MyApiV3` with `fn1`, `fn2` and `fn3`.
//! * `MyApiV4` with `fn1`, `fn2`, `fn3` and `fn4`.
//!
//! Please note that `v4` contains all methods from `v3`, `v3` all methods from `v2` and so on.
//!
//! Back to our example. At the end runtime API is implemented for `struct Runtime` with
//! `impl_runtime_apis` macro. `api_version` attribute is attached to the `impl` block which
//! means that a version different from the base one is being implemented - in our case this
//! is `v3`.
//!
//! This version of the API contains three methods so the `impl` block has got definitions
//! for them. Note that `fn4` is not implemented as it is not part of this version of the API.
//! `impl_runtime_apis` generates a default implementation for it calling `unimplemented!()`.
//!
//! Hopefully this should be all you need to know in order to use versioned methods in the node.
//! For more details about how the API versioning works refer to `spi_api`
//! documentation [here](https://docs.substrate.io/rustdocs/latest/sp_api/macro.decl_runtime_apis.html).
//!
//! # How versioned methods are used for `ParachainHost`
//!
//! Let's introduce two types of `ParachainHost` API implementation:
//! * stable - used on stable production networks like Polkadot and Kusama. There is only one stable
//! API at a single point in time.
//! * staging - methods that are ready for production, but will be released on Rococo first. We can
//! batch together multiple changes and then release all of them to production, by making staging
//! production (bump base version). We can not change or remove any method in staging after a
//! release, as this would break Rococo. It should be ok to keep adding methods to staging across
//! several releases. For experimental methods, you have to keep them on a separate branch until
//! ready.
//!
//! The stable version of `ParachainHost` is indicated by the base version of the API. Any staging
//! method must use `api_version` attribute so that it is assigned to a specific version of a
//! staging API. This way in a single declaration one can see what's the stable version of
//! `ParachainHost` and what staging versions/functions are available.
//!
//! All stable API functions should use primitives from the latest version.
//! In the time of writing of this document - this is `v2`. So for example:
//! ```ignore
//! fn validators() -> Vec<v2::ValidatorId>;
//! ```
//! indicates a function from the stable `v2` API.
//!
//! All staging API functions should use primitives from `vstaging`. They should be clearly
//! separated from the stable primitives.
use crate::{
slashing,
vstaging::{
self, CandidateEvent, CommittedCandidateReceiptV2 as CommittedCandidateReceipt, CoreState,
ScrapedOnChainVotes,
},
ApprovalVotingParams, AsyncBackingParams, BlockNumber, CandidateCommitments, CandidateHash,
CoreIndex, DisputeState, ExecutorParams, GroupRotationInfo, Hash, NodeFeatures,
OccupiedCoreAssumption, PersistedValidationData, PvfCheckStatement, SessionIndex, SessionInfo,
ValidatorId, ValidatorIndex, ValidatorSignature,
};
use alloc::{
collections::{btree_map::BTreeMap, vec_deque::VecDeque},
vec::Vec,
};
use polkadot_core_primitives as pcp;
use polkadot_parachain_primitives::primitives as ppp;
sp_api::decl_runtime_apis! {
/// The API for querying the state of parachains on-chain.
#[api_version(5)]
pub trait ParachainHost {
/// Get the current validators.
fn validators() -> Vec<ValidatorId>;
/// Returns the validator groups and rotation info localized based on the hypothetical child
/// of a 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<Vec<ValidatorIndex>>, GroupRotationInfo<BlockNumber>);
/// Yields information on all availability cores as relevant to the child block.
/// Cores are either free or occupied. Free cores can have paras assigned to them.
fn availability_cores() -> Vec<CoreState<Hash, BlockNumber>>;
/// Yields the persisted validation data for the given `ParaId` along with an assumption that
/// should be used if the para currently occupies a core.
///
/// 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(para_id: ppp::Id, assumption: OccupiedCoreAssumption)
-> Option<PersistedValidationData<Hash, BlockNumber>>;
/// Returns the persisted validation data for the given `ParaId` along with the corresponding
/// validation code hash. Instead of accepting assumption about the para, matches the validation
/// data hash against an expected one and yields `None` if they're not equal.
fn assumed_validation_data(
para_id: ppp::Id,
expected_persisted_validation_data_hash: Hash,
) -> Option<(PersistedValidationData<Hash, BlockNumber>, ppp::ValidationCodeHash)>;
/// Checks if the given validation outputs pass the acceptance criteria.
fn check_validation_outputs(para_id: ppp::Id, outputs: CandidateCommitments) -> bool;
/// Returns the session index expected at a child of the block.
///
/// This can be used to instantiate a `SigningContext`.
fn session_index_for_child() -> SessionIndex;
/// Fetch the validation code used by a para, making the given `OccupiedCoreAssumption`.
///
/// Returns `None` if either the para is not registered or the assumption is `Freed`
/// and the para already occupies a core.
fn validation_code(
para_id: ppp::Id,
assumption: OccupiedCoreAssumption,
) -> Option<ppp::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.
fn candidate_pending_availability(para_id: ppp::Id) -> Option<CommittedCandidateReceipt<Hash>>;
/// Get a vector of events concerning candidates that occurred within a block.
fn candidate_events() -> Vec<CandidateEvent<Hash>>;
/// Get all the pending inbound messages in the downward message queue for a para.
fn dmq_contents(
recipient: ppp::Id,
) -> Vec<pcp::v2::InboundDownwardMessage<BlockNumber>>;
/// Get the contents of all channels addressed to the given recipient. Channels that have no
/// messages in them are also included.
fn inbound_hrmp_channels_contents(
recipient: ppp::Id,
) -> BTreeMap<ppp::Id, Vec<pcp::v2::InboundHrmpMessage<BlockNumber>>>;
/// Get the validation code from its hash.
fn validation_code_by_hash(hash: ppp::ValidationCodeHash) -> Option<ppp::ValidationCode>;
/// Scrape dispute relevant from on-chain, backing votes and resolved disputes.
fn on_chain_votes() -> Option<ScrapedOnChainVotes<Hash>>;
/***** Added in v2 *****/
/// Get the session info for the given session, if stored.
///
/// NOTE: This function is only available since parachain host version 2.
fn session_info(index: SessionIndex) -> Option<SessionInfo>;
/// Submits a PVF pre-checking statement into the transaction pool.
///
/// NOTE: This function is only available since parachain host version 2.
fn submit_pvf_check_statement(stmt: PvfCheckStatement, signature: ValidatorSignature);
/// Returns code hashes of PVFs that require pre-checking by validators in the active set.
///
/// NOTE: This function is only available since parachain host version 2.
fn pvfs_require_precheck() -> Vec<ppp::ValidationCodeHash>;
/// Fetch the hash of the validation code used by a para, making the given `OccupiedCoreAssumption`.
///
/// NOTE: This function is only available since parachain host version 2.
fn validation_code_hash(para_id: ppp::Id, assumption: OccupiedCoreAssumption)
-> Option<ppp::ValidationCodeHash>;
/// Returns all onchain disputes.
fn disputes() -> Vec<(SessionIndex, CandidateHash, DisputeState<BlockNumber>)>;
/// Returns execution parameters for the session.
fn session_executor_params(session_index: SessionIndex) -> Option<ExecutorParams>;
/// Returns a list of validators that lost a past session dispute and need to be slashed.
/// NOTE: This function is only available since parachain host version 5.
fn unapplied_slashes() -> Vec<(SessionIndex, CandidateHash, slashing::PendingSlashes)>;
/// Returns a merkle proof of a validator session key.
/// NOTE: This function is only available since parachain host version 5.
fn key_ownership_proof(
validator_id: ValidatorId,
) -> Option<slashing::OpaqueKeyOwnershipProof>;
/// Submit an unsigned extrinsic to slash validators who lost a dispute about
/// a candidate of a past session.
/// NOTE: This function is only available since parachain host version 5.
fn submit_report_dispute_lost(
dispute_proof: slashing::DisputeProof,
key_ownership_proof: slashing::OpaqueKeyOwnershipProof,
) -> Option<()>;
/***** Added in v6 *****/
/// Get the minimum number of backing votes for a parachain candidate.
/// This is a staging method! Do not use on production runtimes!
#[api_version(6)]
fn minimum_backing_votes() -> u32;
/***** Added in v7: Asynchronous backing *****/
/// Returns the state of parachain backing for a given para.
#[api_version(7)]
fn para_backing_state(_: ppp::Id) -> Option<vstaging::async_backing::BackingState<Hash, BlockNumber>>;
/// Returns candidate's acceptance limitations for asynchronous backing for a relay parent.
#[api_version(7)]
fn async_backing_params() -> AsyncBackingParams;
/***** Added in v8 *****/
/// Returns a list of all disabled validators at the given block.
#[api_version(8)]
fn disabled_validators() -> Vec<ValidatorIndex>;
/***** Added in v9 *****/
/// Get node features.
/// This is a staging method! Do not use on production runtimes!
#[api_version(9)]
fn node_features() -> NodeFeatures;
/***** Added in v10 *****/
/// Approval voting configuration parameters
#[api_version(10)]
fn approval_voting_params() -> ApprovalVotingParams;
/***** Added in v11 *****/
/// Claim queue
#[api_version(11)]
fn claim_queue() -> BTreeMap<CoreIndex, VecDeque<ppp::Id>>;
/***** Added in v11 *****/
/// Elastic scaling support
#[api_version(11)]
fn candidates_pending_availability(para_id: ppp::Id) -> Vec<CommittedCandidateReceipt<Hash>>;
}
}