referrerpolicy=no-referrer-when-downgrade

pallet_contracts/
storage.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! This module contains routines for accessing and altering a contract related state.
19
20pub mod meter;
21
22use crate::{
23	exec::{AccountIdOf, Key},
24	weights::WeightInfo,
25	BalanceOf, CodeHash, CodeInfo, Config, ContractInfoOf, DeletionQueue, DeletionQueueCounter,
26	Error, TrieId, SENTINEL,
27};
28use alloc::vec::Vec;
29use codec::{Decode, Encode, MaxEncodedLen};
30use core::marker::PhantomData;
31use frame_support::{
32	storage::child::{self, ChildInfo},
33	weights::{Weight, WeightMeter},
34	CloneNoBound, DefaultNoBound,
35};
36use scale_info::TypeInfo;
37use sp_core::Get;
38use sp_io::KillStorageResult;
39use sp_runtime::{
40	traits::{Hash, Saturating, Zero},
41	BoundedBTreeMap, DispatchError, DispatchResult, RuntimeDebug,
42};
43
44use self::meter::Diff;
45
46/// Information for managing an account and its sub trie abstraction.
47/// This is the required info to cache for an account.
48#[derive(Encode, Decode, CloneNoBound, PartialEq, Eq, RuntimeDebug, TypeInfo, MaxEncodedLen)]
49#[scale_info(skip_type_params(T))]
50pub struct ContractInfo<T: Config> {
51	/// Unique ID for the subtree encoded as a bytes vector.
52	pub trie_id: TrieId,
53	/// The code associated with a given account.
54	pub code_hash: CodeHash<T>,
55	/// How many bytes of storage are accumulated in this contract's child trie.
56	storage_bytes: u32,
57	/// How many items of storage are accumulated in this contract's child trie.
58	storage_items: u32,
59	/// This records to how much deposit the accumulated `storage_bytes` amount to.
60	pub storage_byte_deposit: BalanceOf<T>,
61	/// This records to how much deposit the accumulated `storage_items` amount to.
62	storage_item_deposit: BalanceOf<T>,
63	/// This records how much deposit is put down in order to pay for the contract itself.
64	///
65	/// We need to store this information separately so it is not used when calculating any refunds
66	/// since the base deposit can only ever be refunded on contract termination.
67	storage_base_deposit: BalanceOf<T>,
68	/// Map of code hashes and deposit balances.
69	///
70	/// Tracks the code hash and deposit held for locking delegate dependencies. Dependencies added
71	/// to the map can not be removed from the chain state and can be safely used for delegate
72	/// calls.
73	delegate_dependencies: BoundedBTreeMap<CodeHash<T>, BalanceOf<T>, T::MaxDelegateDependencies>,
74}
75
76impl<T: Config> ContractInfo<T> {
77	/// Constructs a new contract info **without** writing it to storage.
78	///
79	/// This returns an `Err` if an contract with the supplied `account` already exists
80	/// in storage.
81	pub fn new(
82		account: &AccountIdOf<T>,
83		nonce: u64,
84		code_hash: CodeHash<T>,
85	) -> Result<Self, DispatchError> {
86		if <ContractInfoOf<T>>::contains_key(account) {
87			return Err(Error::<T>::DuplicateContract.into())
88		}
89
90		let trie_id = {
91			let buf = (account, nonce).using_encoded(T::Hashing::hash);
92			buf.as_ref()
93				.to_vec()
94				.try_into()
95				.expect("Runtime uses a reasonable hash size. Hence sizeof(T::Hash) <= 128; qed")
96		};
97
98		let contract = Self {
99			trie_id,
100			code_hash,
101			storage_bytes: 0,
102			storage_items: 0,
103			storage_byte_deposit: Zero::zero(),
104			storage_item_deposit: Zero::zero(),
105			storage_base_deposit: Zero::zero(),
106			delegate_dependencies: Default::default(),
107		};
108
109		Ok(contract)
110	}
111
112	/// Returns the number of locked delegate dependencies.
113	pub fn delegate_dependencies_count(&self) -> usize {
114		self.delegate_dependencies.len()
115	}
116
117	/// Associated child trie unique id is built from the hash part of the trie id.
118	pub fn child_trie_info(&self) -> ChildInfo {
119		ChildInfo::new_default(self.trie_id.as_ref())
120	}
121
122	/// The deposit paying for the accumulated storage generated within the contract's child trie.
123	pub fn extra_deposit(&self) -> BalanceOf<T> {
124		self.storage_byte_deposit.saturating_add(self.storage_item_deposit)
125	}
126
127	/// Same as [`Self::extra_deposit`] but including the base deposit.
128	pub fn total_deposit(&self) -> BalanceOf<T> {
129		self.extra_deposit().saturating_add(self.storage_base_deposit)
130	}
131
132	/// Returns the storage base deposit of the contract.
133	pub fn storage_base_deposit(&self) -> BalanceOf<T> {
134		self.storage_base_deposit
135	}
136
137	/// Reads a storage kv pair of a contract.
138	///
139	/// The read is performed from the `trie_id` only. The `address` is not necessary. If the
140	/// contract doesn't store under the given `key` `None` is returned.
141	pub fn read(&self, key: &Key<T>) -> Option<Vec<u8>> {
142		child::get_raw(&self.child_trie_info(), key.hash().as_slice())
143	}
144
145	/// Returns `Some(len)` (in bytes) if a storage item exists at `key`.
146	///
147	/// Returns `None` if the `key` wasn't previously set by `set_storage` or
148	/// was deleted.
149	pub fn size(&self, key: &Key<T>) -> Option<u32> {
150		child::len(&self.child_trie_info(), key.hash().as_slice())
151	}
152
153	/// Update a storage entry into a contract's kv storage.
154	///
155	/// If the `new_value` is `None` then the kv pair is removed. If `take` is true
156	/// a [`WriteOutcome::Taken`] is returned instead of a [`WriteOutcome::Overwritten`].
157	///
158	/// This function also records how much storage was created or removed if a `storage_meter`
159	/// is supplied. It should only be absent for testing or benchmarking code.
160	pub fn write(
161		&self,
162		key: &Key<T>,
163		new_value: Option<Vec<u8>>,
164		storage_meter: Option<&mut meter::NestedMeter<T>>,
165		take: bool,
166	) -> Result<WriteOutcome, DispatchError> {
167		let hashed_key = key.hash();
168		self.write_raw(&hashed_key, new_value, storage_meter, take)
169	}
170
171	/// Update a storage entry into a contract's kv storage.
172	/// Function used in benchmarks, which can simulate prefix collision in keys.
173	#[cfg(feature = "runtime-benchmarks")]
174	pub fn bench_write_raw(
175		&self,
176		key: &[u8],
177		new_value: Option<Vec<u8>>,
178		take: bool,
179	) -> Result<WriteOutcome, DispatchError> {
180		self.write_raw(key, new_value, None, take)
181	}
182
183	fn write_raw(
184		&self,
185		key: &[u8],
186		new_value: Option<Vec<u8>>,
187		storage_meter: Option<&mut meter::NestedMeter<T>>,
188		take: bool,
189	) -> Result<WriteOutcome, DispatchError> {
190		let child_trie_info = &self.child_trie_info();
191		let (old_len, old_value) = if take {
192			let val = child::get_raw(child_trie_info, key);
193			(val.as_ref().map(|v| v.len() as u32), val)
194		} else {
195			(child::len(child_trie_info, key), None)
196		};
197
198		if let Some(storage_meter) = storage_meter {
199			let mut diff = meter::Diff::default();
200			match (old_len, new_value.as_ref().map(|v| v.len() as u32)) {
201				(Some(old_len), Some(new_len)) =>
202					if new_len > old_len {
203						diff.bytes_added = new_len - old_len;
204					} else {
205						diff.bytes_removed = old_len - new_len;
206					},
207				(None, Some(new_len)) => {
208					diff.bytes_added = new_len;
209					diff.items_added = 1;
210				},
211				(Some(old_len), None) => {
212					diff.bytes_removed = old_len;
213					diff.items_removed = 1;
214				},
215				(None, None) => (),
216			}
217			storage_meter.charge(&diff);
218		}
219
220		match &new_value {
221			Some(new_value) => child::put_raw(child_trie_info, key, new_value),
222			None => child::kill(child_trie_info, key),
223		}
224
225		Ok(match (old_len, old_value) {
226			(None, _) => WriteOutcome::New,
227			(Some(old_len), None) => WriteOutcome::Overwritten(old_len),
228			(Some(_), Some(old_value)) => WriteOutcome::Taken(old_value),
229		})
230	}
231
232	/// Sets and returns the contract base deposit.
233	///
234	/// The base deposit is updated when the `code_hash` of the contract changes, as it depends on
235	/// the deposit paid to upload the contract's code.
236	pub fn update_base_deposit(&mut self, code_info: &CodeInfo<T>) -> BalanceOf<T> {
237		let info_deposit =
238			Diff { bytes_added: self.encoded_size() as u32, items_added: 1, ..Default::default() }
239				.update_contract::<T>(None)
240				.charge_or_zero();
241
242		// Instantiating the contract prevents its code to be deleted, therefore the base deposit
243		// includes a fraction (`T::CodeHashLockupDepositPercent`) of the original storage deposit
244		// to prevent abuse.
245		let upload_deposit = T::CodeHashLockupDepositPercent::get().mul_ceil(code_info.deposit());
246
247		let deposit = info_deposit.saturating_add(upload_deposit);
248		self.storage_base_deposit = deposit;
249		deposit
250	}
251
252	/// Adds a new delegate dependency to the contract.
253	/// The `amount` is the amount of funds that will be reserved for the dependency.
254	///
255	/// Returns an error if the maximum number of delegate_dependencies is reached or if
256	/// the delegate dependency already exists.
257	pub fn lock_delegate_dependency(
258		&mut self,
259		code_hash: CodeHash<T>,
260		amount: BalanceOf<T>,
261	) -> DispatchResult {
262		self.delegate_dependencies
263			.try_insert(code_hash, amount)
264			.map_err(|_| Error::<T>::MaxDelegateDependenciesReached)?
265			.map_or(Ok(()), |_| Err(Error::<T>::DelegateDependencyAlreadyExists))
266			.map_err(Into::into)
267	}
268
269	/// Removes the delegate dependency from the contract and returns the deposit held for this
270	/// dependency.
271	///
272	/// Returns an error if the entry doesn't exist.
273	pub fn unlock_delegate_dependency(
274		&mut self,
275		code_hash: &CodeHash<T>,
276	) -> Result<BalanceOf<T>, DispatchError> {
277		self.delegate_dependencies
278			.remove(code_hash)
279			.ok_or(Error::<T>::DelegateDependencyNotFound.into())
280	}
281
282	/// Returns the delegate_dependencies of the contract.
283	pub fn delegate_dependencies(
284		&self,
285	) -> &BoundedBTreeMap<CodeHash<T>, BalanceOf<T>, T::MaxDelegateDependencies> {
286		&self.delegate_dependencies
287	}
288
289	/// Push a contract's trie to the deletion queue for lazy removal.
290	///
291	/// You must make sure that the contract is also removed when queuing the trie for deletion.
292	pub fn queue_trie_for_deletion(&self) {
293		DeletionQueueManager::<T>::load().insert(self.trie_id.clone());
294	}
295
296	/// Calculates the weight that is necessary to remove one key from the trie and how many
297	/// of those keys can be deleted from the deletion queue given the supplied weight limit.
298	pub fn deletion_budget(meter: &WeightMeter) -> (Weight, u32) {
299		let base_weight = T::WeightInfo::on_process_deletion_queue_batch();
300		let weight_per_key = T::WeightInfo::on_initialize_per_trie_key(1) -
301			T::WeightInfo::on_initialize_per_trie_key(0);
302
303		// `weight_per_key` being zero makes no sense and would constitute a failure to
304		// benchmark properly. We opt for not removing any keys at all in this case.
305		let key_budget = meter
306			.limit()
307			.saturating_sub(base_weight)
308			.checked_div_per_component(&weight_per_key)
309			.unwrap_or(0) as u32;
310
311		(weight_per_key, key_budget)
312	}
313
314	/// Delete as many items from the deletion queue possible within the supplied weight limit.
315	pub fn process_deletion_queue_batch(meter: &mut WeightMeter) {
316		if meter.try_consume(T::WeightInfo::on_process_deletion_queue_batch()).is_err() {
317			return
318		};
319
320		let mut queue = <DeletionQueueManager<T>>::load();
321		if queue.is_empty() {
322			return;
323		}
324
325		let (weight_per_key, budget) = Self::deletion_budget(&meter);
326		let mut remaining_key_budget = budget;
327		while remaining_key_budget > 0 {
328			let Some(entry) = queue.next() else { break };
329
330			#[allow(deprecated)]
331			let outcome = child::kill_storage(
332				&ChildInfo::new_default(&entry.trie_id),
333				Some(remaining_key_budget),
334			);
335
336			match outcome {
337				// This happens when our budget wasn't large enough to remove all keys.
338				KillStorageResult::SomeRemaining(keys_removed) => {
339					remaining_key_budget.saturating_reduce(keys_removed);
340					break
341				},
342				KillStorageResult::AllRemoved(keys_removed) => {
343					entry.remove();
344					// charge at least one key even if none were removed.
345					remaining_key_budget = remaining_key_budget.saturating_sub(keys_removed.max(1));
346				},
347			};
348		}
349
350		meter.consume(weight_per_key.saturating_mul(u64::from(budget - remaining_key_budget)))
351	}
352
353	/// Returns the code hash of the contract specified by `account` ID.
354	pub fn load_code_hash(account: &AccountIdOf<T>) -> Option<CodeHash<T>> {
355		<ContractInfoOf<T>>::get(account).map(|i| i.code_hash)
356	}
357}
358
359/// Information about what happened to the pre-existing value when calling [`ContractInfo::write`].
360#[cfg_attr(any(test, feature = "runtime-benchmarks"), derive(Debug, PartialEq))]
361pub enum WriteOutcome {
362	/// No value existed at the specified key.
363	New,
364	/// A value of the returned length was overwritten.
365	Overwritten(u32),
366	/// The returned value was taken out of storage before being overwritten.
367	///
368	/// This is only returned when specifically requested because it causes additional work
369	/// depending on the size of the pre-existing value. When not requested [`Self::Overwritten`]
370	/// is returned instead.
371	Taken(Vec<u8>),
372}
373
374impl WriteOutcome {
375	/// Extracts the size of the overwritten value or `0` if there
376	/// was no value in storage.
377	pub fn old_len(&self) -> u32 {
378		match self {
379			Self::New => 0,
380			Self::Overwritten(len) => *len,
381			Self::Taken(value) => value.len() as u32,
382		}
383	}
384
385	/// Extracts the size of the overwritten value or `SENTINEL` if there
386	/// was no value in storage.
387	///
388	/// # Note
389	///
390	/// We cannot use `0` as sentinel value because there could be a zero sized
391	/// storage entry which is different from a non existing one.
392	pub fn old_len_with_sentinel(&self) -> u32 {
393		match self {
394			Self::New => SENTINEL,
395			Self::Overwritten(len) => *len,
396			Self::Taken(value) => value.len() as u32,
397		}
398	}
399}
400
401/// Manage the removal of contracts storage that are marked for deletion.
402///
403/// When a contract is deleted by calling `seal_terminate` it becomes inaccessible
404/// immediately, but the deletion of the storage items it has accumulated is performed
405/// later by pulling the contract from the queue in the `on_idle` hook.
406#[derive(Encode, Decode, TypeInfo, MaxEncodedLen, DefaultNoBound, Clone)]
407#[scale_info(skip_type_params(T))]
408pub struct DeletionQueueManager<T: Config> {
409	/// Counter used as a key for inserting a new deleted contract in the queue.
410	/// The counter is incremented after each insertion.
411	insert_counter: u32,
412	/// The index used to read the next element to be deleted in the queue.
413	/// The counter is incremented after each deletion.
414	delete_counter: u32,
415
416	_phantom: PhantomData<T>,
417}
418
419/// View on a contract that is marked for deletion.
420struct DeletionQueueEntry<'a, T: Config> {
421	/// the trie id of the contract to delete.
422	trie_id: TrieId,
423
424	/// A mutable reference on the queue so that the contract can be removed, and none can be added
425	/// or read in the meantime.
426	queue: &'a mut DeletionQueueManager<T>,
427}
428
429impl<'a, T: Config> DeletionQueueEntry<'a, T> {
430	/// Remove the contract from the deletion queue.
431	fn remove(self) {
432		<DeletionQueue<T>>::remove(self.queue.delete_counter);
433		self.queue.delete_counter = self.queue.delete_counter.wrapping_add(1);
434		<DeletionQueueCounter<T>>::set(self.queue.clone());
435	}
436}
437
438impl<T: Config> DeletionQueueManager<T> {
439	/// Load the `DeletionQueueCounter`, so we can perform read or write operations on the
440	/// DeletionQueue storage.
441	fn load() -> Self {
442		<DeletionQueueCounter<T>>::get()
443	}
444
445	/// Returns `true` if the queue contains no elements.
446	fn is_empty(&self) -> bool {
447		self.insert_counter.wrapping_sub(self.delete_counter) == 0
448	}
449
450	/// Insert a contract in the deletion queue.
451	fn insert(&mut self, trie_id: TrieId) {
452		<DeletionQueue<T>>::insert(self.insert_counter, trie_id);
453		self.insert_counter = self.insert_counter.wrapping_add(1);
454		<DeletionQueueCounter<T>>::set(self.clone());
455	}
456
457	/// Fetch the next contract to be deleted.
458	///
459	/// Note:
460	/// we use the delete counter to get the next value to read from the queue and thus don't pay
461	/// the cost of an extra call to `sp_io::storage::next_key` to lookup the next entry in the map
462	fn next(&mut self) -> Option<DeletionQueueEntry<T>> {
463		if self.is_empty() {
464			return None
465		}
466
467		let entry = <DeletionQueue<T>>::get(self.delete_counter);
468		entry.map(|trie_id| DeletionQueueEntry { trie_id, queue: self })
469	}
470}
471
472#[cfg(test)]
473impl<T: Config> DeletionQueueManager<T> {
474	pub fn from_test_values(insert_counter: u32, delete_counter: u32) -> Self {
475		Self { insert_counter, delete_counter, _phantom: Default::default() }
476	}
477	pub fn as_test_tuple(&self) -> (u32, u32) {
478		(self.insert_counter, self.delete_counter)
479	}
480}