Add staging runtime api

bridges/bin/rialto/runtime/src/lib.rs

@@ -731,7 +731,7 @@ impl_runtime_apis! {
 		}
 	}
 
-	impl polkadot_primitives::v2::ParachainHost<Block, Hash, BlockNumber> for Runtime {
+	impl polkadot_primitives::runtime_api::ParachainHost<Block, Hash, BlockNumber> for Runtime {
 		fn validators() -> Vec<polkadot_primitives::v2::ValidatorId> {
 			polkadot_runtime_parachains::runtime_api_impl::v2::validators::<Runtime>()
 		}

node/client/src/lib.rs

@@ -19,8 +19,9 @@
 //! Provides the [`AbstractClient`] trait that is a super trait that combines all the traits the client implements.
 //! There is also the [`Client`] enum that combines all the different clients into one common structure.
 
-use polkadot_primitives::v2::{
-	AccountId, Balance, Block, BlockNumber, Hash, Header, Nonce, ParachainHost,
+use polkadot_primitives::{
+	runtime_api::ParachainHost,
+	v2::{AccountId, Balance, Block, BlockNumber, Hash, Header, Nonce},
 };
 use sc_client_api::{AuxStore, Backend as BackendT, BlockchainEvents, KeyIterator, UsageProvider};
 use sc_executor::NativeElseWasmExecutor;

node/core/runtime-api/src/lib.rs

@@ -23,7 +23,10 @@
 #![warn(missing_docs)]
 
 use polkadot_node_subsystem_util::metrics::{self, prometheus};
-use polkadot_primitives::v2::{Block, BlockId, Hash, ParachainHost};
+use polkadot_primitives::{
+	runtime_api::ParachainHost,
+	v2::{Block, BlockId, Hash},
+};
 use polkadot_subsystem::{
 	errors::RuntimeApiError,
 	messages::{RuntimeApiMessage, RuntimeApiRequest as Request},

node/core/runtime-api/src/tests.rs

@@ -21,10 +21,11 @@ use futures::channel::oneshot;
 use polkadot_node_primitives::{BabeAllowedSlots, BabeEpoch, BabeEpochConfiguration};
 use polkadot_node_subsystem_test_helpers::make_subsystem_context;
 use polkadot_primitives::v2::{
-	AuthorityDiscoveryId, CandidateEvent, CommittedCandidateReceipt, CoreState, GroupRotationInfo,
-	Id as ParaId, InboundDownwardMessage, InboundHrmpMessage, OccupiedCoreAssumption,
-	PersistedValidationData, PvfCheckStatement, ScrapedOnChainVotes, SessionIndex, SessionInfo,
-	ValidationCode, ValidationCodeHash, ValidatorId, ValidatorIndex, ValidatorSignature,
+	AuthorityDiscoveryId, BlockNumber, CandidateEvent, CandidateHash, CommittedCandidateReceipt,
+	CoreState, DisputeState, GroupRotationInfo, Id as ParaId, InboundDownwardMessage,
+	InboundHrmpMessage, OccupiedCoreAssumption, PersistedValidationData, PvfCheckStatement,
+	ScrapedOnChainVotes, SessionIndex, SessionInfo, ValidationCode, ValidationCodeHash,
+	ValidatorId, ValidatorIndex, ValidatorSignature,
 };
 use sp_core::testing::TaskExecutor;
 use std::{
@@ -189,6 +190,10 @@ sp_api::mock_impl_runtime_apis! {
 		) -> Option<ValidationCodeHash> {
 			self.validation_code_hash.get(&para).map(|c| c.clone())
 		}
+
+		fn staging_get_disputes() -> Vec<(SessionIndex, CandidateHash, DisputeState<BlockNumber>)> {
+			unimplemented!()
+		}
 	}
 
 	impl BabeApi<Block> for MockRuntimeApi {

node/overseer/src/lib.rs

@@ -71,7 +71,10 @@ use futures::{channel::oneshot, future::BoxFuture, select, Future, FutureExt, St
 use lru::LruCache;
 
 use client::{BlockImportNotification, BlockchainEvents, FinalityNotification};
-use polkadot_primitives::v2::{Block, BlockId, BlockNumber, Hash, ParachainHost};
+use polkadot_primitives::{
+	runtime_api::ParachainHost,
+	v2::{Block, BlockId, BlockNumber, Hash},
+};
 use sp_api::{ApiExt, ProvideRuntimeApi};
 
 use polkadot_node_network_protocol::v1 as protocol_v1;

node/service/src/lib.rs

@@ -54,7 +54,7 @@ pub use sp_core::traits::SpawnNamed;
 #[cfg(feature = "full-node")]
 pub use {
 	polkadot_overseer::{Handle, Overseer, OverseerConnector, OverseerHandle},
-	polkadot_primitives::v2::ParachainHost,
+	polkadot_primitives::runtime_api::ParachainHost,
 	relay_chain_selection::SelectRelayChain,
 	sc_client_api::AuxStore,
 	sp_authority_discovery::AuthorityDiscoveryApi,

node/service/src/overseer.rs

@@ -34,7 +34,7 @@ use polkadot_overseer::{
 	Overseer, OverseerConnector, OverseerHandle,
 };
 
-use polkadot_primitives::v2::ParachainHost;
+use polkadot_primitives::runtime_api::ParachainHost;
 use sc_authority_discovery::Service as AuthorityDiscoveryService;
 use sc_client_api::AuxStore;
 use sc_keystore::LocalKeystore;

primitives/src/lib.rs

@@ -19,4 +19,14 @@
 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
+// `v2` is currently the latest stable version of the runtime API.
 pub mod v2;
+
+// The 'staging' version is special - while other versions are set in stone,
+// the staging version is malleable. Once it's released, it gets the next
+// version number.
+pub mod vstaging;
+
+// `runtime_api` contains the actual API implementation. It contains stable and
+// unstable functions.
+pub mod runtime_api;

primitives/src/runtime_api.rs

@@ -0,0 +1,159 @@
+// Copyright 2017-2022 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 functions).
+//!
+//! 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.
+//!
+//! On the other hand a staging function's name should be prefixed with
+//! `staging_` like this:
+//! ```ignore
+//! fn staging_get_disputes() -> Vec<(vstaging::SessionIndex, vstaging::CandidateHash, vstaging::DisputeState<vstaging::BlockNumber>)>;
+//! ```
+//!
+//! How a staging function becomes stable?
+//!
+//! Once a staging function is ready to be versioned the `renamed` macro
+//! should be used to rename it and version it. For the example above:
+//! ```ignore
+//! #[renamed("staging_get_session_disputes", 3)]
+//! fn get_session_disputes() -> Vec<(v3::SessionIndex, v3::CandidateHash, v3::DisputeState<v3::BlockNumber>)>;
+//! ```
+//! 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).
+
+use crate::v2;
+use parity_scale_codec::{Decode, Encode};
+use polkadot_core_primitives as pcp;
+use polkadot_parachain::primitives as ppp;
+use sp_staking;
+use sp_std::{collections::btree_map::BTreeMap, prelude::*};
+
+sp_api::decl_runtime_apis! {
+	/// The API for querying the state of parachains on-chain.
+	#[api_version(2)]
+	pub trait ParachainHost<H: Encode + Decode = pcp::v2::Hash, N: Encode + Decode = pcp::v2::BlockNumber> {
+		/// Get the current validators.
+		fn validators() -> Vec<v2::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<v2::ValidatorIndex>>, v2::GroupRotationInfo<N>);
+
+		/// 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<v2::CoreState<H, N>>;
+
+		/// 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: v2::OccupiedCoreAssumption)
+			-> Option<v2::PersistedValidationData<H, N>>;
+
+		/// 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: pcp::v2::Hash,
+		) -> Option<(v2::PersistedValidationData<H, N>, ppp::ValidationCodeHash)>;
+
+		/// Checks if the given validation outputs pass the acceptance criteria.
+		fn check_validation_outputs(para_id: ppp::Id, outputs: v2::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() -> sp_staking::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: v2::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<v2::CommittedCandidateReceipt<H>>;
+
+		/// Get a vector of events concerning candidates that occurred within a block.
+		fn candidate_events() -> Vec<v2::CandidateEvent<H>>;
+
+		/// Get all the pending inbound messages in the downward message queue for a para.
+		fn dmq_contents(
+			recipient: ppp::Id,
+		) -> Vec<pcp::v2::InboundDownwardMessage<N>>;
+
+		/// 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<N>>>;
+
+		/// 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<v2::ScrapedOnChainVotes<H>>;
+
+		/***** 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: sp_staking::SessionIndex) -> Option<v2::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: v2::PvfCheckStatement, signature: v2::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: v2::OccupiedCoreAssumption)
+			-> Option<ppp::ValidationCodeHash>;
+
+
+		/***** Replaced in v2 *****/
+
+		/// Old method to fetch v1 session info.
+		#[changed_in(2)]
+		fn session_info(index: sp_staking::SessionIndex) -> Option<v2::OldV1SessionInfo>;
+
+		/***** STAGING *****/
+
+		/// Returns all onchain disputes.
+		/// This is a staging method! Do not use on production runtimes!
+		fn staging_get_disputes() -> Vec<(v2::SessionIndex, v2::CandidateHash, v2::DisputeState<v2::BlockNumber>)>;
+	}
+}

primitives/src/v2/mod.rs

@@ -19,7 +19,7 @@
 use bitvec::vec::BitVec;
 use parity_scale_codec::{Decode, Encode};
 use scale_info::TypeInfo;
-use sp_std::{collections::btree_map::BTreeMap, prelude::*};
+use sp_std::prelude::*;
 
 use application_crypto::KeyTypeId;
 use inherents::InherentIdentifier;
@@ -1651,107 +1651,6 @@ impl PvfCheckStatement {
 	}
 }
 
-sp_api::decl_runtime_apis! {
-	/// The API for querying the state of parachains on-chain.
-	#[api_version(2)]
-	pub trait ParachainHost<H: Encode + Decode = Hash, N: Encode + Decode = BlockNumber> {
-		/// 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<N>);
-
-		/// 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<H, N>>;
-
-		/// 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: Id, assumption: OccupiedCoreAssumption)
-			-> Option<PersistedValidationData<H, N>>;
-
-		/// 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: Id,
-			expected_persisted_validation_data_hash: Hash,
-		) -> Option<(PersistedValidationData<H, N>, ValidationCodeHash)>;
-
-		/// Checks if the given validation outputs pass the acceptance criteria.
-		fn check_validation_outputs(para_id: 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: Id, assumption: OccupiedCoreAssumption)
-			-> Option<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: Id) -> Option<CommittedCandidateReceipt<H>>;
-
-		/// Get a vector of events concerning candidates that occurred within a block.
-		fn candidate_events() -> Vec<CandidateEvent<H>>;
-
-		/// Get all the pending inbound messages in the downward message queue for a para.
-		fn dmq_contents(
-			recipient: Id,
-		) -> Vec<InboundDownwardMessage<N>>;
-
-		/// 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: Id) -> BTreeMap<Id, Vec<InboundHrmpMessage<N>>>;
-
-		/// Get the validation code from its hash.
-		fn validation_code_by_hash(hash: ValidationCodeHash) -> Option<ValidationCode>;
-
-		/// Scrape dispute relevant from on-chain, backing votes and resolved disputes.
-		fn on_chain_votes() -> Option<ScrapedOnChainVotes<H>>;
-
-		/***** 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<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: Id, assumption: OccupiedCoreAssumption)
-			-> Option<ValidationCodeHash>;
-
-
-		/***** Replaced in v2 *****/
-
-		/// Old method to fetch v1 session info.
-		#[changed_in(2)]
-		fn session_info(index: SessionIndex) -> Option<OldV1SessionInfo>;
-	}
-}
-
 /// Old, v1-style info about session info. Only needed for limited
 /// backwards-compatibility.
 #[derive(Clone, Encode, Decode, RuntimeDebug, TypeInfo)]