referrerpolicy=no-referrer-when-downgrade

sc_client_api/
backend.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19//! Substrate Client data backend
20
21use std::collections::HashSet;
22
23use parking_lot::RwLock;
24
25use sp_api::CallContext;
26use sp_consensus::BlockOrigin;
27use sp_core::offchain::OffchainStorage;
28use sp_runtime::{
29	traits::{Block as BlockT, HashingFor, NumberFor},
30	Justification, Justifications, StateVersion, Storage,
31};
32use sp_state_machine::{
33	backend::AsTrieBackend, ChildStorageCollection, IndexOperation, IterArgs,
34	OffchainChangesCollection, StorageCollection, StorageIterator,
35};
36use sp_storage::{ChildInfo, StorageData, StorageKey};
37pub use sp_trie::MerkleValue;
38
39use crate::{blockchain::Backend as BlockchainBackend, UsageInfo};
40
41pub use sp_state_machine::{Backend as StateBackend, BackendTransaction, KeyValueStates};
42
43/// Extracts the state backend type for the given backend.
44pub type StateBackendFor<B, Block> = <B as Backend<Block>>::State;
45
46/// Describes which block import notification stream should be notified.
47#[derive(Debug, Clone, Copy)]
48pub enum ImportNotificationAction {
49	/// Notify only when the node has synced to the tip or there is a re-org.
50	RecentBlock,
51	/// Notify for every single block no matter what the sync state is.
52	EveryBlock,
53	/// Both block import notifications above should be fired.
54	Both,
55	/// No block import notification should be fired.
56	None,
57}
58
59/// Import operation summary.
60///
61/// Contains information about the block that just got imported,
62/// including storage changes, reorged blocks, etc.
63pub struct ImportSummary<Block: BlockT> {
64	/// Block hash of the imported block.
65	pub hash: Block::Hash,
66	/// Import origin.
67	pub origin: BlockOrigin,
68	/// Header of the imported block.
69	pub header: Block::Header,
70	/// Is this block a new best block.
71	pub is_new_best: bool,
72	/// Optional storage changes.
73	pub storage_changes: Option<(StorageCollection, ChildStorageCollection)>,
74	/// Tree route from old best to new best.
75	///
76	/// If `None`, there was no re-org while importing.
77	pub tree_route: Option<sp_blockchain::TreeRoute<Block>>,
78	/// What notify action to take for this import.
79	pub import_notification_action: ImportNotificationAction,
80}
81
82/// Finalization operation summary.
83///
84/// Contains information about the block that just got finalized,
85/// including tree heads that became stale at the moment of finalization.
86pub struct FinalizeSummary<Block: BlockT> {
87	/// Last finalized block header.
88	pub header: Block::Header,
89	/// Blocks that were finalized.
90	/// The last entry is the one that has been explicitly finalized.
91	pub finalized: Vec<Block::Hash>,
92	/// Heads that became stale during this finalization operation.
93	pub stale_heads: Vec<Block::Hash>,
94}
95
96/// Import operation wrapper.
97pub struct ClientImportOperation<Block: BlockT, B: Backend<Block>> {
98	/// DB Operation.
99	pub op: B::BlockImportOperation,
100	/// Summary of imported block.
101	pub notify_imported: Option<ImportSummary<Block>>,
102	/// Summary of finalized block.
103	pub notify_finalized: Option<FinalizeSummary<Block>>,
104}
105
106/// Helper function to apply auxiliary data insertion into an operation.
107pub fn apply_aux<'a, 'b: 'a, 'c: 'a, B, Block, D, I>(
108	operation: &mut ClientImportOperation<Block, B>,
109	insert: I,
110	delete: D,
111) -> sp_blockchain::Result<()>
112where
113	Block: BlockT,
114	B: Backend<Block>,
115	I: IntoIterator<Item = &'a (&'c [u8], &'c [u8])>,
116	D: IntoIterator<Item = &'a &'b [u8]>,
117{
118	operation.op.insert_aux(
119		insert
120			.into_iter()
121			.map(|(k, v)| (k.to_vec(), Some(v.to_vec())))
122			.chain(delete.into_iter().map(|k| (k.to_vec(), None))),
123	)
124}
125
126/// State of a new block.
127#[derive(Debug, Clone, Copy, PartialEq, Eq)]
128pub enum NewBlockState {
129	/// Normal block.
130	Normal,
131	/// New best block.
132	Best,
133	/// Newly finalized block (implicitly best).
134	Final,
135}
136
137impl NewBlockState {
138	/// Whether this block is the new best block.
139	pub fn is_best(self) -> bool {
140		match self {
141			NewBlockState::Best | NewBlockState::Final => true,
142			NewBlockState::Normal => false,
143		}
144	}
145
146	/// Whether this block is considered final.
147	pub fn is_final(self) -> bool {
148		match self {
149			NewBlockState::Final => true,
150			NewBlockState::Best | NewBlockState::Normal => false,
151		}
152	}
153}
154
155/// Block insertion operation.
156///
157/// Keeps hold if the inserted block state and data.
158pub trait BlockImportOperation<Block: BlockT> {
159	/// Associated state backend type.
160	type State: StateBackend<HashingFor<Block>>;
161
162	/// Returns pending state.
163	///
164	/// Returns None for backends with locally-unavailable state data.
165	fn state(&self) -> sp_blockchain::Result<Option<&Self::State>>;
166
167	/// Append block data to the transaction.
168	fn set_block_data(
169		&mut self,
170		header: Block::Header,
171		body: Option<Vec<Block::Extrinsic>>,
172		indexed_body: Option<Vec<Vec<u8>>>,
173		justifications: Option<Justifications>,
174		state: NewBlockState,
175	) -> sp_blockchain::Result<()>;
176
177	/// Inject storage data into the database.
178	fn update_db_storage(
179		&mut self,
180		update: BackendTransaction<HashingFor<Block>>,
181	) -> sp_blockchain::Result<()>;
182
183	/// Set genesis state. If `commit` is `false` the state is saved in memory, but is not written
184	/// to the database.
185	fn set_genesis_state(
186		&mut self,
187		storage: Storage,
188		commit: bool,
189		state_version: StateVersion,
190	) -> sp_blockchain::Result<Block::Hash>;
191
192	/// Inject storage data into the database replacing any existing data.
193	fn reset_storage(
194		&mut self,
195		storage: Storage,
196		state_version: StateVersion,
197	) -> sp_blockchain::Result<Block::Hash>;
198
199	/// Set storage changes.
200	fn update_storage(
201		&mut self,
202		update: StorageCollection,
203		child_update: ChildStorageCollection,
204	) -> sp_blockchain::Result<()>;
205
206	/// Write offchain storage changes to the database.
207	fn update_offchain_storage(
208		&mut self,
209		_offchain_update: OffchainChangesCollection,
210	) -> sp_blockchain::Result<()> {
211		Ok(())
212	}
213
214	/// Insert auxiliary keys.
215	///
216	/// Values are `None` if should be deleted.
217	fn insert_aux<I>(&mut self, ops: I) -> sp_blockchain::Result<()>
218	where
219		I: IntoIterator<Item = (Vec<u8>, Option<Vec<u8>>)>;
220
221	/// Mark a block as finalized, if multiple blocks are finalized in the same operation then they
222	/// must be marked in ascending order.
223	fn mark_finalized(
224		&mut self,
225		hash: Block::Hash,
226		justification: Option<Justification>,
227	) -> sp_blockchain::Result<()>;
228
229	/// Mark a block as new head. If both block import and set head are specified, set head
230	/// overrides block import's best block rule.
231	fn mark_head(&mut self, hash: Block::Hash) -> sp_blockchain::Result<()>;
232
233	/// Add a transaction index operation.
234	fn update_transaction_index(&mut self, index: Vec<IndexOperation>)
235		-> sp_blockchain::Result<()>;
236
237	/// Configure whether to create a block gap if newly imported block is missing parent
238	fn set_create_gap(&mut self, create_gap: bool);
239}
240
241/// Interface for performing operations on the backend.
242pub trait LockImportRun<Block: BlockT, B: Backend<Block>> {
243	/// Lock the import lock, and run operations inside.
244	fn lock_import_and_run<R, Err, F>(&self, f: F) -> Result<R, Err>
245	where
246		F: FnOnce(&mut ClientImportOperation<Block, B>) -> Result<R, Err>,
247		Err: From<sp_blockchain::Error>;
248}
249
250/// Finalize Facilities
251pub trait Finalizer<Block: BlockT, B: Backend<Block>> {
252	/// Mark all blocks up to given as finalized in operation.
253	///
254	/// If `justification` is provided it is stored with the given finalized
255	/// block (any other finalized blocks are left unjustified).
256	///
257	/// If the block being finalized is on a different fork from the current
258	/// best block the finalized block is set as best, this might be slightly
259	/// inaccurate (i.e. outdated). Usages that require determining an accurate
260	/// best block should use `SelectChain` instead of the client.
261	fn apply_finality(
262		&self,
263		operation: &mut ClientImportOperation<Block, B>,
264		block: Block::Hash,
265		justification: Option<Justification>,
266		notify: bool,
267	) -> sp_blockchain::Result<()>;
268
269	/// Finalize a block.
270	///
271	/// This will implicitly finalize all blocks up to it and
272	/// fire finality notifications.
273	///
274	/// If the block being finalized is on a different fork from the current
275	/// best block, the finalized block is set as best. This might be slightly
276	/// inaccurate (i.e. outdated). Usages that require determining an accurate
277	/// best block should use `SelectChain` instead of the client.
278	///
279	/// Pass a flag to indicate whether finality notifications should be propagated.
280	/// This is usually tied to some synchronization state, where we don't send notifications
281	/// while performing major synchronization work.
282	fn finalize_block(
283		&self,
284		block: Block::Hash,
285		justification: Option<Justification>,
286		notify: bool,
287	) -> sp_blockchain::Result<()>;
288}
289
290/// Provides access to an auxiliary database.
291///
292/// This is a simple global database not aware of forks. Can be used for storing auxiliary
293/// information like total block weight/difficulty for fork resolution purposes as a common use
294/// case.
295pub trait AuxStore {
296	/// Insert auxiliary data into key-value store.
297	///
298	/// Deletions occur after insertions.
299	fn insert_aux<
300		'a,
301		'b: 'a,
302		'c: 'a,
303		I: IntoIterator<Item = &'a (&'c [u8], &'c [u8])>,
304		D: IntoIterator<Item = &'a &'b [u8]>,
305	>(
306		&self,
307		insert: I,
308		delete: D,
309	) -> sp_blockchain::Result<()>;
310
311	/// Query auxiliary data from key-value store.
312	fn get_aux(&self, key: &[u8]) -> sp_blockchain::Result<Option<Vec<u8>>>;
313}
314
315/// An `Iterator` that iterates keys in a given block under a prefix.
316pub struct KeysIter<State, Block>
317where
318	State: StateBackend<HashingFor<Block>>,
319	Block: BlockT,
320{
321	inner: <State as StateBackend<HashingFor<Block>>>::RawIter,
322	state: State,
323}
324
325impl<State, Block> KeysIter<State, Block>
326where
327	State: StateBackend<HashingFor<Block>>,
328	Block: BlockT,
329{
330	/// Create a new iterator over storage keys.
331	pub fn new(
332		state: State,
333		prefix: Option<&StorageKey>,
334		start_at: Option<&StorageKey>,
335	) -> Result<Self, State::Error> {
336		let mut args = IterArgs::default();
337		args.prefix = prefix.as_ref().map(|prefix| prefix.0.as_slice());
338		args.start_at = start_at.as_ref().map(|start_at| start_at.0.as_slice());
339		args.start_at_exclusive = true;
340
341		Ok(Self { inner: state.raw_iter(args)?, state })
342	}
343
344	/// Create a new iterator over a child storage's keys.
345	pub fn new_child(
346		state: State,
347		child_info: ChildInfo,
348		prefix: Option<&StorageKey>,
349		start_at: Option<&StorageKey>,
350	) -> Result<Self, State::Error> {
351		let mut args = IterArgs::default();
352		args.prefix = prefix.as_ref().map(|prefix| prefix.0.as_slice());
353		args.start_at = start_at.as_ref().map(|start_at| start_at.0.as_slice());
354		args.child_info = Some(child_info);
355		args.start_at_exclusive = true;
356
357		Ok(Self { inner: state.raw_iter(args)?, state })
358	}
359}
360
361impl<State, Block> Iterator for KeysIter<State, Block>
362where
363	Block: BlockT,
364	State: StateBackend<HashingFor<Block>>,
365{
366	type Item = StorageKey;
367
368	fn next(&mut self) -> Option<Self::Item> {
369		self.inner.next_key(&self.state)?.ok().map(StorageKey)
370	}
371}
372
373/// An `Iterator` that iterates keys and values in a given block under a prefix.
374pub struct PairsIter<State, Block>
375where
376	State: StateBackend<HashingFor<Block>>,
377	Block: BlockT,
378{
379	inner: <State as StateBackend<HashingFor<Block>>>::RawIter,
380	state: State,
381}
382
383impl<State, Block> Iterator for PairsIter<State, Block>
384where
385	Block: BlockT,
386	State: StateBackend<HashingFor<Block>>,
387{
388	type Item = (StorageKey, StorageData);
389
390	fn next(&mut self) -> Option<Self::Item> {
391		self.inner
392			.next_pair(&self.state)?
393			.ok()
394			.map(|(key, value)| (StorageKey(key), StorageData(value)))
395	}
396}
397
398impl<State, Block> PairsIter<State, Block>
399where
400	State: StateBackend<HashingFor<Block>>,
401	Block: BlockT,
402{
403	/// Create a new iterator over storage key and value pairs.
404	pub fn new(
405		state: State,
406		prefix: Option<&StorageKey>,
407		start_at: Option<&StorageKey>,
408	) -> Result<Self, State::Error> {
409		let mut args = IterArgs::default();
410		args.prefix = prefix.as_ref().map(|prefix| prefix.0.as_slice());
411		args.start_at = start_at.as_ref().map(|start_at| start_at.0.as_slice());
412		args.start_at_exclusive = true;
413
414		Ok(Self { inner: state.raw_iter(args)?, state })
415	}
416}
417
418/// Provides access to storage primitives
419pub trait StorageProvider<Block: BlockT, B: Backend<Block>> {
420	/// Given a block's `Hash` and a key, return the value under the key in that block.
421	fn storage(
422		&self,
423		hash: Block::Hash,
424		key: &StorageKey,
425	) -> sp_blockchain::Result<Option<StorageData>>;
426
427	/// Given a block's `Hash` and a key, return the value under the hash in that block.
428	fn storage_hash(
429		&self,
430		hash: Block::Hash,
431		key: &StorageKey,
432	) -> sp_blockchain::Result<Option<Block::Hash>>;
433
434	/// Given a block's `Hash` and a key prefix, returns a `KeysIter` iterates matching storage
435	/// keys in that block.
436	fn storage_keys(
437		&self,
438		hash: Block::Hash,
439		prefix: Option<&StorageKey>,
440		start_key: Option<&StorageKey>,
441	) -> sp_blockchain::Result<KeysIter<B::State, Block>>;
442
443	/// Given a block's `Hash` and a key prefix, returns an iterator over the storage keys and
444	/// values in that block.
445	fn storage_pairs(
446		&self,
447		hash: <Block as BlockT>::Hash,
448		prefix: Option<&StorageKey>,
449		start_key: Option<&StorageKey>,
450	) -> sp_blockchain::Result<PairsIter<B::State, Block>>;
451
452	/// Given a block's `Hash`, a key and a child storage key, return the value under the key in
453	/// that block.
454	fn child_storage(
455		&self,
456		hash: Block::Hash,
457		child_info: &ChildInfo,
458		key: &StorageKey,
459	) -> sp_blockchain::Result<Option<StorageData>>;
460
461	/// Given a block's `Hash` and a key `prefix` and a child storage key,
462	/// returns a `KeysIter` that iterates matching storage keys in that block.
463	fn child_storage_keys(
464		&self,
465		hash: Block::Hash,
466		child_info: ChildInfo,
467		prefix: Option<&StorageKey>,
468		start_key: Option<&StorageKey>,
469	) -> sp_blockchain::Result<KeysIter<B::State, Block>>;
470
471	/// Given a block's `Hash`, a key and a child storage key, return the hash under the key in that
472	/// block.
473	fn child_storage_hash(
474		&self,
475		hash: Block::Hash,
476		child_info: &ChildInfo,
477		key: &StorageKey,
478	) -> sp_blockchain::Result<Option<Block::Hash>>;
479
480	/// Given a block's `Hash` and a key, return the closest merkle value.
481	fn closest_merkle_value(
482		&self,
483		hash: Block::Hash,
484		key: &StorageKey,
485	) -> sp_blockchain::Result<Option<MerkleValue<Block::Hash>>>;
486
487	/// Given a block's `Hash`, a key and a child storage key, return the closest merkle value.
488	fn child_closest_merkle_value(
489		&self,
490		hash: Block::Hash,
491		child_info: &ChildInfo,
492		key: &StorageKey,
493	) -> sp_blockchain::Result<Option<MerkleValue<Block::Hash>>>;
494}
495
496/// Specify the desired trie cache context when calling [`Backend::state_at`].
497///
498/// This is used to determine the size of the local trie cache.
499#[derive(Debug, Clone, Copy)]
500pub enum TrieCacheContext {
501	/// This is used when calling [`Backend::state_at`] in a trusted context.
502	///
503	/// A trusted context is for example the building or importing of a block.
504	/// In this case the local trie cache can grow unlimited and all the cached data
505	/// will be propagated back to the shared trie cache. It is safe to let the local
506	/// cache grow to hold the entire data, because importing and building blocks is
507	/// bounded by the block size limit.
508	Trusted,
509	/// This is used when calling [`Backend::state_at`] in from untrusted context.
510	///
511	/// The local trie cache will be bounded by its preconfigured size.
512	Untrusted,
513}
514
515impl From<CallContext> for TrieCacheContext {
516	fn from(call_context: CallContext) -> Self {
517		match call_context {
518			CallContext::Onchain => TrieCacheContext::Trusted,
519			CallContext::Offchain => TrieCacheContext::Untrusted,
520		}
521	}
522}
523
524/// Client backend.
525///
526/// Manages the data layer.
527///
528/// # State Pruning
529///
530/// While an object from `state_at` is alive, the state
531/// should not be pruned. The backend should internally reference-count
532/// its state objects.
533///
534/// The same applies for live `BlockImportOperation`s: while an import operation building on a
535/// parent `P` is alive, the state for `P` should not be pruned.
536///
537/// # Block Pruning
538///
539/// Users can pin blocks in memory by calling `pin_block`. When
540/// a block would be pruned, its value is kept in an in-memory cache
541/// until it is unpinned via `unpin_block`.
542///
543/// While a block is pinned, its state is also preserved.
544///
545/// The backend should internally reference count the number of pin / unpin calls.
546pub trait Backend<Block: BlockT>: AuxStore + Send + Sync {
547	/// Associated block insertion operation type.
548	type BlockImportOperation: BlockImportOperation<Block, State = Self::State>;
549	/// Associated blockchain backend type.
550	type Blockchain: BlockchainBackend<Block>;
551	/// Associated state backend type.
552	type State: StateBackend<HashingFor<Block>>
553		+ Send
554		+ AsTrieBackend<
555			HashingFor<Block>,
556			TrieBackendStorage = <Self::State as StateBackend<HashingFor<Block>>>::TrieBackendStorage,
557		>;
558	/// Offchain workers local storage.
559	type OffchainStorage: OffchainStorage;
560
561	/// Begin a new block insertion transaction with given parent block id.
562	///
563	/// When constructing the genesis, this is called with all-zero hash.
564	fn begin_operation(&self) -> sp_blockchain::Result<Self::BlockImportOperation>;
565
566	/// Note an operation to contain state transition.
567	fn begin_state_operation(
568		&self,
569		operation: &mut Self::BlockImportOperation,
570		block: Block::Hash,
571	) -> sp_blockchain::Result<()>;
572
573	/// Commit block insertion.
574	fn commit_operation(
575		&self,
576		transaction: Self::BlockImportOperation,
577	) -> sp_blockchain::Result<()>;
578
579	/// Finalize block with given `hash`.
580	///
581	/// This should only be called if the parent of the given block has been finalized.
582	fn finalize_block(
583		&self,
584		hash: Block::Hash,
585		justification: Option<Justification>,
586	) -> sp_blockchain::Result<()>;
587
588	/// Append justification to the block with the given `hash`.
589	///
590	/// This should only be called for blocks that are already finalized.
591	fn append_justification(
592		&self,
593		hash: Block::Hash,
594		justification: Justification,
595	) -> sp_blockchain::Result<()>;
596
597	/// Returns reference to blockchain backend.
598	fn blockchain(&self) -> &Self::Blockchain;
599
600	/// Returns current usage statistics.
601	fn usage_info(&self) -> Option<UsageInfo>;
602
603	/// Returns a handle to offchain storage.
604	fn offchain_storage(&self) -> Option<Self::OffchainStorage>;
605
606	/// Pin the block to keep body, justification and state available after pruning.
607	/// Number of pins are reference counted. Users need to make sure to perform
608	/// one call to [`Self::unpin_block`] per call to [`Self::pin_block`].
609	fn pin_block(&self, hash: Block::Hash) -> sp_blockchain::Result<()>;
610
611	/// Unpin the block to allow pruning.
612	fn unpin_block(&self, hash: Block::Hash);
613
614	/// Returns true if state for given block is available.
615	fn have_state_at(&self, hash: Block::Hash, _number: NumberFor<Block>) -> bool {
616		self.state_at(hash, TrieCacheContext::Untrusted).is_ok()
617	}
618
619	/// Returns state backend with post-state of given block.
620	fn state_at(
621		&self,
622		hash: Block::Hash,
623		trie_cache_context: TrieCacheContext,
624	) -> sp_blockchain::Result<Self::State>;
625
626	/// Attempts to revert the chain by `n` blocks. If `revert_finalized` is set it will attempt to
627	/// revert past any finalized block, this is unsafe and can potentially leave the node in an
628	/// inconsistent state. All blocks higher than the best block are also reverted and not counting
629	/// towards `n`.
630	///
631	/// Returns the number of blocks that were successfully reverted and the list of finalized
632	/// blocks that has been reverted.
633	fn revert(
634		&self,
635		n: NumberFor<Block>,
636		revert_finalized: bool,
637	) -> sp_blockchain::Result<(NumberFor<Block>, HashSet<Block::Hash>)>;
638
639	/// Discard non-best, unfinalized leaf block.
640	fn remove_leaf_block(&self, hash: Block::Hash) -> sp_blockchain::Result<()>;
641
642	/// Insert auxiliary data into key-value store.
643	fn insert_aux<
644		'a,
645		'b: 'a,
646		'c: 'a,
647		I: IntoIterator<Item = &'a (&'c [u8], &'c [u8])>,
648		D: IntoIterator<Item = &'a &'b [u8]>,
649	>(
650		&self,
651		insert: I,
652		delete: D,
653	) -> sp_blockchain::Result<()> {
654		AuxStore::insert_aux(self, insert, delete)
655	}
656	/// Query auxiliary data from key-value store.
657	fn get_aux(&self, key: &[u8]) -> sp_blockchain::Result<Option<Vec<u8>>> {
658		AuxStore::get_aux(self, key)
659	}
660
661	/// Gain access to the import lock around this backend.
662	///
663	/// _Note_ Backend isn't expected to acquire the lock by itself ever. Rather
664	/// the using components should acquire and hold the lock whenever they do
665	/// something that the import of a block would interfere with, e.g. importing
666	/// a new block or calculating the best head.
667	fn get_import_lock(&self) -> &RwLock<()>;
668
669	/// Tells whether the backend requires full-sync mode.
670	fn requires_full_sync(&self) -> bool;
671}
672
673/// Mark for all Backend implementations, that are making use of state data, stored locally.
674pub trait LocalBackend<Block: BlockT>: Backend<Block> {}