Move Externalities into its own crate (#3775)

* Move `Externalities` into `substrate-externalities` - `Externalities` now support generic extensions - Split of `primtives-storage` for storage primitive types * Move the externalities scoping into `substrate-externalities` * Fix compilation * Review feedback * Adds macro for declaring extensions * Fix benchmarks * Introduce `ExtensionStore` trait * Last review comments * Implement it for `ExtensionStore`
2026-06-12 08:51:09 +00:00 · 2019-10-09 15:50:30 +02:00
parent 984c6ac839
commit 8a39be474e
95 changed files with 1600 additions and 1420 deletions
@@ -0,0 +1,127 @@
+// Copyright 2017-2019 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate 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.
+
+// Substrate 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 Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Externalities extensions storage.
+//!
+//! Externalities support to register a wide variety custom extensions. The [`Extensions`] provides
+//! some convenience functionality to store and retrieve these extensions.
+//!
+//! It is required that each extension implements the [`Extension`] trait.
+
+use std::{collections::HashMap, any::{Any, TypeId}, ops::DerefMut};
+
+/// Marker trait for types that should be registered as [`Externalities`](crate::Externalities) extension.
+///
+/// As extensions are stored as `Box<Any>`, this trait should give more confidence that the correct
+/// type is registered and requested.
+pub trait Extension: Sized {}
+
+/// Macro for declaring an extension that usable with [`Extensions`].
+///
+/// The extension will be an unit wrapper struct that implements [`Extension`], `Deref` and
+/// `DerefMut`. The wrapped type is given by the user.
+///
+/// # Example
+/// ```
+/// # use substrate_externalities::decl_extension;
+/// decl_extension! {
+///     /// Some test extension
+///     struct TestExt(String);
+/// }
+/// ```
+#[macro_export]
+macro_rules! decl_extension {
+	(
+		$( #[ $attr:meta ] )*
+		$vis:vis struct $ext_name:ident ($inner:ty);
+	) => {
+		$( #[ $attr ] )*
+		$vis struct $ext_name (pub $inner);
+
+		impl $crate::Extension for $ext_name {}
+
+		impl std::ops::Deref for $ext_name {
+			type Target = $inner;
+
+			fn deref(&self) -> &Self::Target {
+				&self.0
+			}
+		}
+
+		impl std::ops::DerefMut for $ext_name {
+			fn deref_mut(&mut self) -> &mut Self::Target {
+				&mut self.0
+			}
+		}
+	}
+}
+
+/// Something that provides access to the [`Extensions`] store.
+///
+/// This is a super trait of the [`Externalities`](crate::Externalities).
+pub trait ExtensionStore {
+	/// Tries to find a registered extension by the given `type_id` and returns it as a `&mut dyn Any`.
+	///
+	/// It is advised to use [`ExternalitiesExt::extension`](crate::ExternalitiesExt::extension)
+	/// instead of this function to get type system support and automatic type downcasting.
+	fn extension_by_type_id(&mut self, type_id: TypeId) -> Option<&mut dyn Any>;
+}
+
+/// Stores extensions that should be made available through the externalities.
+#[derive(Default)]
+pub struct Extensions {
+	extensions: HashMap<TypeId, Box<dyn Any>>,
+}
+
+impl Extensions {
+	/// Create new instance of `Self`.
+	pub fn new() -> Self {
+		Self::default()
+	}
+
+	/// Register the given extension.
+	pub fn register<E: Any + Extension>(&mut self, ext: E) {
+		self.extensions.insert(ext.type_id(), Box::new(ext));
+	}
+
+	/// Return a mutable reference to the requested extension.
+	pub fn get_mut(&mut self, ext_type_id: TypeId) -> Option<&mut dyn Any> {
+		self.extensions.get_mut(&ext_type_id).map(DerefMut::deref_mut)
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+
+	struct DummyExt(u32);
+	impl Extension for DummyExt {}
+
+	struct DummyExt2(u32);
+	impl Extension for DummyExt2 {}
+
+	#[test]
+	fn register_and_retrieve_extension() {
+		let mut exts = Extensions::new();
+		exts.register(DummyExt(1));
+		exts.register(DummyExt2(2));
+
+		let ext = exts.get_mut(TypeId::of::<DummyExt>()).expect("Extension is registered");
+		let ext_ty = ext.downcast_mut::<DummyExt>().expect("Downcasting works");
+
+		assert_eq!(ext_ty.0, 1);
+	}
+}
@@ -0,0 +1,139 @@
+// Copyright 2017-2019 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate 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.
+
+// Substrate 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 Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate externalities abstraction
+//!
+//! The externalities mainly provide access to storage and to registered extensions. Extensions
+//! are for example the keystore or the offchain externalities. These externalities are used to
+//! access the node from the runtime via the runtime interfaces.
+//!
+//! This crate exposes the main [`Externalities`] trait.
+
+use primitive_types::H256;
+
+use std::any::{Any, TypeId};
+
+use primitives_storage::ChildStorageKey;
+
+pub use scope_limited::{set_and_run_with_externalities, with_externalities};
+pub use extensions::{Extension, Extensions, ExtensionStore};
+
+mod extensions;
+mod scope_limited;
+
+/// The Substrate externalities.
+///
+/// Provides access to the storage and to other registered extensions.
+pub trait Externalities: ExtensionStore {
+	/// Read runtime storage.
+	fn storage(&self, key: &[u8]) -> Option<Vec<u8>>;
+
+	/// Get storage value hash. This may be optimized for large values.
+	fn storage_hash(&self, key: &[u8]) -> Option<H256>;
+
+	/// Get child storage value hash. This may be optimized for large values.
+	fn child_storage_hash(&self, storage_key: ChildStorageKey, key: &[u8]) -> Option<H256>;
+
+	/// Read original runtime storage, ignoring any overlayed changes.
+	fn original_storage(&self, key: &[u8]) -> Option<Vec<u8>>;
+
+	/// Read original runtime child storage, ignoring any overlayed changes.
+	fn original_child_storage(&self, storage_key: ChildStorageKey, key: &[u8]) -> Option<Vec<u8>>;
+
+	/// Get original storage value hash, ignoring any overlayed changes.
+	/// This may be optimized for large values.
+	fn original_storage_hash(&self, key: &[u8]) -> Option<H256>;
+
+	/// Get original child storage value hash, ignoring any overlayed changes.
+	/// This may be optimized for large values.
+	fn original_child_storage_hash(&self, storage_key: ChildStorageKey, key: &[u8]) -> Option<H256>;
+
+	/// Read child runtime storage.
+	fn child_storage(&self, storage_key: ChildStorageKey, key: &[u8]) -> Option<Vec<u8>>;
+
+	/// Set storage entry `key` of current contract being called (effective immediately).
+	fn set_storage(&mut self, key: Vec<u8>, value: Vec<u8>) {
+		self.place_storage(key, Some(value));
+	}
+
+	/// Set child storage entry `key` of current contract being called (effective immediately).
+	fn set_child_storage(&mut self, storage_key: ChildStorageKey, key: Vec<u8>, value: Vec<u8>) {
+		self.place_child_storage(storage_key, key, Some(value))
+	}
+
+	/// Clear a storage entry (`key`) of current contract being called (effective immediately).
+	fn clear_storage(&mut self, key: &[u8]) {
+		self.place_storage(key.to_vec(), None);
+	}
+
+	/// Clear a child storage entry (`key`) of current contract being called (effective immediately).
+	fn clear_child_storage(&mut self, storage_key: ChildStorageKey, key: &[u8]) {
+		self.place_child_storage(storage_key, key.to_vec(), None)
+	}
+
+	/// Whether a storage entry exists.
+	fn exists_storage(&self, key: &[u8]) -> bool {
+		self.storage(key).is_some()
+	}
+
+	/// Whether a child storage entry exists.
+	fn exists_child_storage(&self, storage_key: ChildStorageKey, key: &[u8]) -> bool {
+		self.child_storage(storage_key, key).is_some()
+	}
+
+	/// Clear an entire child storage.
+	fn kill_child_storage(&mut self, storage_key: ChildStorageKey);
+
+	/// Clear storage entries which keys are start with the given prefix.
+	fn clear_prefix(&mut self, prefix: &[u8]);
+
+	/// Clear child storage entries which keys are start with the given prefix.
+	fn clear_child_prefix(&mut self, storage_key: ChildStorageKey, prefix: &[u8]);
+
+	/// Set or clear a storage entry (`key`) of current contract being called (effective immediately).
+	fn place_storage(&mut self, key: Vec<u8>, value: Option<Vec<u8>>);
+
+	/// Set or clear a child storage entry. Return whether the operation succeeds.
+	fn place_child_storage(&mut self, storage_key: ChildStorageKey, key: Vec<u8>, value: Option<Vec<u8>>);
+
+	/// Get the identity of the chain.
+	fn chain_id(&self) -> u64;
+
+	/// Get the trie root of the current storage map. This will also update all child storage keys
+	/// in the top-level storage map.
+	fn storage_root(&mut self) -> H256;
+
+	/// Get the trie root of a child storage map. This will also update the value of the child
+	/// storage keys in the top-level storage map.
+	/// If the storage root equals the default hash as defined by the trie, the key in the top-level
+	/// storage map will be removed.
+	fn child_storage_root(&mut self, storage_key: ChildStorageKey) -> Vec<u8>;
+
+	/// Get the change trie root of the current storage overlay at a block with given parent.
+	fn storage_changes_root(&mut self, parent: H256) -> Result<Option<H256>, ()>;
+}
+
+/// Extension for the [`Externalities`] trait.
+pub trait ExternalitiesExt {
+	/// Tries to find a registered extension and returns a mutable reference.
+	fn extension<T: Any + Extension>(&mut self) -> Option<&mut T>;
+}
+
+impl<T: ExtensionStore + ?Sized> ExternalitiesExt for T {
+	fn extension<A: Any + Extension>(&mut self) -> Option<&mut A> {
+		self.extension_by_type_id(TypeId::of::<A>()).and_then(Any::downcast_mut)
+	}
+}
@@ -0,0 +1,37 @@
+// Copyright 2019 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate 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.
+
+// Substrate 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 Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Stores the externalities in an `environmental` value to make it scope limited available.
+
+use crate::Externalities;
+
+environmental::environmental!(ext: trait Externalities);
+
+/// Set the given externalities while executing the given closure. To get access to the externalities
+/// while executing the given closure [`with_externalities`] grants access to them. The externalities
+/// are only set for the same thread this function was called from.
+pub fn set_and_run_with_externalities<F, R>(ext: &mut dyn Externalities, f: F) -> R
+	where F: FnOnce() -> R
+{
+	ext::using(ext, f)
+}
+
+/// Execute the given closure with the currently set externalities.
+///
+/// Returns `None` if no externalities are set or `Some(_)` with the result of the closure.
+pub fn with_externalities<F: FnOnce(&mut dyn Externalities) -> R, R>(f: F) -> Option<R> {
+	ext::with(f)
+}