=
<>::Api as ApiExt>::StateBackend;
/// Extract the state backend transaction type for a type that implements `ProvideRuntimeApi`.
#[cfg(feature = "std")]
pub type TransactionFor =
as StateBackend>>::Transaction;
/// Something that can be constructed to a runtime api.
#[cfg(feature = "std")]
pub trait ConstructRuntimeApi> {
/// The actual runtime api that will be constructed.
type RuntimeApi: ApiExt;
/// Construct an instance of the runtime api.
fn construct_runtime_api<'a>(call: &'a C) -> ApiRef<'a, Self::RuntimeApi>;
}
/// Extends the runtime api traits with an associated error type. This trait is given as super
/// trait to every runtime api trait.
#[cfg(feature = "std")]
pub trait ApiErrorExt {
/// Error type used by the runtime apis.
type Error: std::fmt::Debug + From;
}
/// Extends the runtime api implementation with some common functionality.
#[cfg(feature = "std")]
pub trait ApiExt: ApiErrorExt {
/// The state backend that is used to store the block states.
type StateBackend: StateBackend>;
/// The given closure will be called with api instance. Inside the closure any api call is
/// allowed. After doing the api call, the closure is allowed to map the `Result` to a
/// different `Result` type. This can be important, as the internal data structure that keeps
/// track of modifications to the storage, discards changes when the `Result` is an `Err`.
/// On `Ok`, the structure commits the changes to an internal buffer.
fn map_api_result result::Result, R, E>(
&self,
map_call: F,
) -> result::Result where Self: Sized;
/// Checks if the given api is implemented and versions match.
fn has_api(
&self,
at: &BlockId,
) -> Result where Self: Sized;
/// Check if the given api is implemented and the version passes a predicate.
fn has_api_with bool>(
&self,
at: &BlockId,
pred: P,
) -> Result where Self: Sized;
/// Start recording all accessed trie nodes for generating proofs.
fn record_proof(&mut self);
/// Extract the recorded proof.
///
/// This stops the proof recording.
///
/// If `record_proof` was not called before, this will return `None`.
fn extract_proof(&mut self) -> Option;
/// Convert the api object into the storage changes that were done while executing runtime
/// api functions.
///
/// After executing this function, all collected changes are reset.
fn into_storage_changes(
&self,
backend: &Self::StateBackend,
changes_trie_state: Option<&ChangesTrieState, NumberFor>>,
parent_hash: Block::Hash,
) -> Result, String> where Self: Sized;
}
/// Before calling any runtime api function, the runtime need to be initialized
/// at the requested block. However, some functions like `execute_block` or
/// `initialize_block` itself don't require to have the runtime initialized
/// at the requested block.
///
/// `call_api_at` is instructed by this enum to do the initialization or to skip
/// it.
#[cfg(feature = "std")]
#[derive(Clone, Copy)]
pub enum InitializeBlock<'a, Block: BlockT> {
/// Skip initializing the runtime for a given block.
///
/// This is used by functions who do the initialization by themselves or don't require it.
Skip,
/// Initialize the runtime for a given block.
///
/// If the stored `BlockId` is `Some(_)`, the runtime is currently initialized at this block.
Do(&'a RefCell>>),
}
/// Parameters for [`CallApiAt::call_api_at`].
#[cfg(feature = "std")]
pub struct CallApiAtParams<'a, Block: BlockT, C, NC, Backend: StateBackend>> {
/// A reference to something that implements the [`Core`] api.
pub core_api: &'a C,
/// The block id that determines the state that should be setup when calling the function.
pub at: &'a BlockId,
/// The name of the function that should be called.
pub function: &'static str,
/// An optional native call that calls the `function`. This is an optimization to call into a
/// native runtime without requiring to encode/decode the parameters. The native runtime can
/// still be called when this value is `None`, we then just fallback to encoding/decoding the
/// parameters.
pub native_call: Option,
/// The encoded arguments of the function.
pub arguments: Vec,
/// The overlayed changes that are on top of the state.
pub overlayed_changes: &'a RefCell,
/// The cache for storage transactions.
pub storage_transaction_cache: &'a RefCell>,
/// Determines if the function requires that `initialize_block` should be called before calling
/// the actual function.
pub initialize_block: InitializeBlock<'a, Block>,
/// The context this function is executed in.
pub context: ExecutionContext,
/// The optional proof recorder for recording storage accesses.
pub recorder: &'a Option>,
}
/// Something that can call into the an api at a given block.
#[cfg(feature = "std")]
pub trait CallApiAt {
/// Error type used by the implementation.
type Error: std::fmt::Debug + From;
/// The state backend that is used to store the block states.
type StateBackend: StateBackend>;
/// Calls the given api function with the given encoded arguments at the given block and returns
/// the encoded result.
fn call_api_at<
'a,
R: Encode + Decode + PartialEq,
NC: FnOnce() -> result::Result + UnwindSafe,
C: Core,
>(
&self,
params: CallApiAtParams<'a, Block, C, NC, Self::StateBackend>,
) -> Result, Self::Error>;
/// Returns the runtime version at the given block.
fn runtime_version_at(&self, at: &BlockId) -> Result;
}
/// Auxiliary wrapper that holds an api instance and binds it to the given lifetime.
#[cfg(feature = "std")]
pub struct ApiRef<'a, T>(T, std::marker::PhantomData<&'a ()>);
#[cfg(feature = "std")]
impl<'a, T> From for ApiRef<'a, T> {
fn from(api: T) -> Self {
ApiRef(api, Default::default())
}
}
#[cfg(feature = "std")]
impl<'a, T> std::ops::Deref for ApiRef<'a, T> {
type Target = T;
fn deref(&self) -> &Self::Target {
&self.0
}
}
#[cfg(feature = "std")]
impl<'a, T> std::ops::DerefMut for ApiRef<'a, T> {
fn deref_mut(&mut self) -> &mut T {
&mut self.0
}
}
/// Something that provides a runtime api.
#[cfg(feature = "std")]
pub trait ProvideRuntimeApi {
/// The concrete type that provides the api.
type Api: ApiExt;
/// Returns the runtime api.
/// The returned instance will keep track of modifications to the storage. Any successful
/// call to an api function, will `commit` its changes to an internal buffer. Otherwise,
/// the modifications will be `discarded`. The modifications will not be applied to the
/// storage, even on a `commit`.
fn runtime_api<'a>(&'a self) -> ApiRef<'a, Self::Api>;
}
/// Something that provides information about a runtime api.
#[cfg(feature = "std")]
pub trait RuntimeApiInfo {
/// The identifier of the runtime api.
const ID: [u8; 8];
/// The version of the runtime api.
const VERSION: u32;
}
/// Extracts the `Api::Error` for a type that provides a runtime api.
#[cfg(feature = "std")]
pub type ApiErrorFor = <>::Api as ApiErrorExt>::Error;
decl_runtime_apis! {
/// The `Core` runtime api that every Substrate runtime needs to implement.
#[core_trait]
#[api_version(2)]
pub trait Core {
/// Returns the version of the runtime.
fn version() -> RuntimeVersion;
/// Execute the given block.
#[skip_initialize_block]
fn execute_block(block: Block);
/// Initialize a block with the given header.
#[renamed("initialise_block", 2)]
#[skip_initialize_block]
#[initialize_block]
fn initialize_block(header: &::Header);
}
/// The `Metadata` api trait that returns metadata for the runtime.
pub trait Metadata {
/// Returns the metadata of a runtime.
fn metadata() -> OpaqueMetadata;
}
}