referrerpolicy=no-referrer-when-downgrade

pallet_oracle/
lib.rs

1// This file is part of Substrate.
2
3// Copyright (C) 2020-2025 Acala Foundation.
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//! # Oracle
19//!
20//! A pallet that provides a decentralized and trustworthy way to bring external, off-chain data
21//! onto the blockchain.
22//!
23//! ## Pallet API
24//!
25//! See the [`pallet`] module for more information about the interfaces this pallet exposes,
26//! including its configuration trait, dispatchables, storage items, events and errors.
27//!
28//! ## Overview
29//!
30//! The Oracle pallet enables blockchain applications to access real-world data through a
31//! decentralized network of trusted data providers. It's designed to be flexible and can handle
32//! various types of external data such as cryptocurrency prices, weather data, sports scores, or
33//! any other off-chain information that needs to be brought on-chain.
34//!
35//! The pallet operates on a permissioned model where only authorized oracle operators can submit
36//! data. This ensures data quality and prevents spam while maintaining decentralization through
37//! multiple independent operators. The system aggregates data from multiple sources using
38//! configurable algorithms, typically taking the median to resist outliers and manipulation
39//! attempts.
40//!
41//! ### Key Concepts
42//!
43//! * **Oracle Operators**: A set of trusted accounts authorized to submit data. Managed through the
44//!   [`SortedMembers`] trait, allowing integration with membership pallets.
45//! * **Data Feeds**: Key-value pairs where keys identify the data type (e.g., currency pair) and
46//!   values contain the actual data (e.g., price).
47//! * **Data Aggregation**: Configurable algorithms to combine multiple operator inputs into a
48//!   single trusted value, with median aggregation provided by default.
49//! * **Timestamped Data**: All submitted data includes timestamps for freshness tracking.
50//!
51//! ## Low Level / Implementation Details
52//!
53//! ### Design Goals
54//!
55//! The oracle system aims to provide:
56//! - **Decentralization**: Multiple independent data providers prevent single points of failure
57//! - **Data Quality**: Aggregation mechanisms filter out outliers and malicious data
58//! - **Flexibility**: Configurable data types and aggregation strategies
59//! - **Performance**: Efficient storage and retrieval of timestamped data
60//! - **Security**: Permissioned access with cryptographic verification of data integrity
61//!
62//! ### Design
63//!
64//! The pallet uses a dual-storage approach:
65//! - [`RawValues`]: Stores individual operator submissions with timestamps
66//! - [`Values`]: Stores the final aggregated values after processing
67//!
68//! This design allows for:
69//! - Historical tracking of individual operator submissions
70//! - Efficient access to final aggregated values
71//! - Clean separation between raw data and processed results
72//! - Easy integration with data aggregation algorithms
73
74#![cfg_attr(not(feature = "std"), no_std)]
75
76extern crate alloc;
77
78use codec::{Decode, Encode, MaxEncodedLen};
79
80use serde::{Deserialize, Serialize};
81
82use alloc::{vec, vec::Vec};
83use frame_support::{
84	dispatch::Pays,
85	ensure,
86	pallet_prelude::*,
87	traits::{ChangeMembers, Get, SortedMembers, Time},
88	weights::Weight,
89	PalletId, Parameter,
90};
91use frame_system::pallet_prelude::*;
92use scale_info::TypeInfo;
93use sp_runtime::{
94	traits::{AccountIdConversion, Member},
95	Debug, DispatchResult,
96};
97
98#[cfg(feature = "runtime-benchmarks")]
99mod benchmarking;
100
101mod default_combine_data;
102pub use default_combine_data::DefaultCombineData;
103pub mod traits;
104
105/// Items used by the exported macros, so callers don't need to depend on them.
106#[doc(hidden)]
107pub mod __private {
108	pub use alloc::{collections::btree_set::BTreeSet, vec::Vec};
109}
110pub use traits::{CombineData, DataFeeder, DataProvider, DataProviderExtended, OnNewData};
111#[cfg(test)]
112mod mock;
113#[cfg(test)]
114mod tests;
115pub mod weights;
116
117pub use pallet::*;
118pub use weights::WeightInfo;
119
120#[cfg(feature = "runtime-benchmarks")]
121/// Helper trait for benchmarking oracle operations.
122pub trait BenchmarkHelper<OracleKey, OracleValue, L: Get<u32>> {
123	/// Returns a list of `(oracle_key, oracle_value)` pairs to be used for
124	/// benchmarking.
125	///
126	/// NOTE: User should ensure to at least submit two values, otherwise the
127	/// benchmark linear analysis might fail.
128	fn get_currency_id_value_pairs() -> BoundedVec<(OracleKey, OracleValue), L>;
129}
130
131#[cfg(feature = "runtime-benchmarks")]
132impl<OracleKey, OracleValue, L: Get<u32>> BenchmarkHelper<OracleKey, OracleValue, L> for () {
133	fn get_currency_id_value_pairs() -> BoundedVec<(OracleKey, OracleValue), L> {
134		BoundedVec::default()
135	}
136}
137
138#[frame_support::pallet]
139pub mod pallet {
140	use super::*;
141
142	pub(crate) type MomentOf<T, I = ()> = <<T as Config<I>>::Time as Time>::Moment;
143	pub(crate) type TimestampedValueOf<T, I = ()> =
144		TimestampedValue<<T as Config<I>>::OracleValue, MomentOf<T, I>>;
145
146	/// A wrapper for a value with a timestamp.
147	#[derive(
148		Encode,
149		Decode,
150		Debug,
151		Eq,
152		PartialEq,
153		Clone,
154		Copy,
155		Ord,
156		PartialOrd,
157		TypeInfo,
158		MaxEncodedLen,
159		Serialize,
160		Deserialize,
161	)]
162	pub struct TimestampedValue<Value, Moment> {
163		/// The value.
164		pub value: Value,
165		/// The timestamp.
166		pub timestamp: Moment,
167	}
168
169	#[pallet::config]
170	pub trait Config<I: 'static = ()>: frame_system::Config {
171		/// A hook to be called when new data is received.
172		///
173		/// This hook is triggered whenever an oracle operator successfully submits new data.
174		/// It allows other pallets to react to oracle updates, enabling real-time responses to
175		/// external data changes.
176		type OnNewData: OnNewData<Self::AccountId, Self::OracleKey, Self::OracleValue>;
177
178		/// The implementation to combine raw values into a single aggregated value.
179		///
180		/// This type defines how multiple oracle operator submissions are combined into a single
181		/// trusted value. Common implementations include taking the median (to resist outliers)
182		/// or weighted averages based on operator reputation.
183		type CombineData: CombineData<Self::OracleKey, TimestampedValueOf<Self, I>>;
184
185		/// The time provider for timestamping oracle data.
186		///
187		/// This type provides the current timestamp used to mark when oracle data was submitted.
188		/// Timestamps are crucial for determining data freshness and preventing stale data usage.
189		type Time: Time;
190
191		/// The key type for identifying oracle data feeds.
192		///
193		/// This type is used to uniquely identify different types of oracle data (e.g., currency
194		/// pairs, asset prices, weather data).
195		type OracleKey: Parameter + Member + MaxEncodedLen;
196
197		/// The value type for oracle data.
198		///
199		/// This type represents the actual data submitted by oracle operators (e.g., prices,
200		/// temperatures, scores).
201		type OracleValue: Parameter + Member + Ord + MaxEncodedLen;
202
203		/// The pallet ID.
204		///
205		/// Will be used to derive the pallet's account, which is used as the oracle account
206		/// when values are fed by root.
207		#[pallet::constant]
208		type PalletId: Get<PalletId>;
209
210		/// The source of oracle members.
211		///
212		/// This type provides the set of accounts authorized to submit oracle data.
213		/// Typically implemented by membership pallets to allow governance-controlled
214		/// management of oracle operators.
215		type Members: SortedMembers<Self::AccountId>;
216
217		/// Weight information for extrinsics in this pallet.
218		type WeightInfo: WeightInfo;
219
220		/// The maximum number of oracle operators that can feed data in a single block.
221		#[pallet::constant]
222		type MaxHasDispatchedSize: Get<u32>;
223
224		/// The maximum number of key-value pairs that can be submitted in a single extrinsic.
225		#[pallet::constant]
226		type MaxFeedValues: Get<u32>;
227
228		/// A helper trait for benchmarking oracle operations.
229		///
230		/// Provides sample data for benchmarking the oracle pallet, allowing accurate
231		/// weight calculations and performance testing.
232		#[cfg(feature = "runtime-benchmarks")]
233		type BenchmarkHelper: BenchmarkHelper<
234			Self::OracleKey,
235			Self::OracleValue,
236			Self::MaxFeedValues,
237		>;
238	}
239
240	#[pallet::error]
241	pub enum Error<T, I = ()> {
242		/// The sender is not a member of the oracle and does not have
243		/// permission to feed data.
244		NoPermission,
245		/// The oracle member has already fed data in the current block.
246		AlreadyFeeded,
247		/// Exceeds the maximum number of `HasDispatched` size.
248		ExceedsMaxHasDispatchedSize,
249	}
250
251	#[pallet::event]
252	#[pallet::generate_deposit(pub(crate) fn deposit_event)]
253	pub enum Event<T: Config<I>, I: 'static = ()> {
254		/// New data has been fed into the oracle.
255		NewFeedData {
256			/// The account that fed the data.
257			sender: T::AccountId,
258			/// The key-value pairs of the data that was fed.
259			values: Vec<(T::OracleKey, T::OracleValue)>,
260		},
261	}
262
263	/// The raw values for each oracle operator.
264	///
265	/// Maps `(AccountId, OracleKey)` to `TimestampedValue` containing the operator's submitted
266	/// value along with the timestamp when it was submitted. This storage maintains the complete
267	/// history of individual operator submissions, allowing for data aggregation and audit trails.
268	///
269	/// ## Storage Economics
270	///
271	/// No storage deposits are required as this data is considered essential for the oracle's
272	/// operation and data integrity. The storage cost is borne by the blockchain as part of the
273	/// oracle infrastructure.
274	#[pallet::storage]
275	#[pallet::getter(fn raw_values)]
276	pub type RawValues<T: Config<I>, I: 'static = ()> = StorageDoubleMap<
277		_,
278		Twox64Concat,
279		T::AccountId,
280		Twox64Concat,
281		T::OracleKey,
282		TimestampedValueOf<T, I>,
283	>;
284
285	/// The aggregated values for each oracle key.
286	///
287	/// Maps `OracleKey` to `TimestampedValue`.
288	#[pallet::storage]
289	#[pallet::getter(fn values)]
290	pub type Values<T: Config<I>, I: 'static = ()> =
291		StorageMap<_, Twox64Concat, <T as Config<I>>::OracleKey, TimestampedValueOf<T, I>>;
292
293	/// A set of accounts that have already fed data in the current block.
294	///
295	/// This storage item tracks which oracle operators have already submitted data in the
296	/// current block to enforce the "one submission per block" rule. This prevents spam and
297	/// ensures fair participation among oracle operators.
298	///
299	/// The storage is cleared at the end of each block in the `on_finalize` hook, resetting
300	/// the state for the next block.
301	#[pallet::storage]
302	pub(crate) type HasDispatched<T: Config<I>, I: 'static = ()> =
303		StorageValue<_, BoundedBTreeSet<T::AccountId, T::MaxHasDispatchedSize>, ValueQuery>;
304
305	#[pallet::pallet]
306	pub struct Pallet<T, I = ()>(PhantomData<(T, I)>);
307
308	#[pallet::hooks]
309	impl<T: Config<I>, I: 'static> Hooks<BlockNumberFor<T>> for Pallet<T, I> {
310		/// `on_initialize` to return the weight used in `on_finalize`.
311		fn on_initialize(_n: BlockNumberFor<T>) -> Weight {
312			T::WeightInfo::on_finalize()
313		}
314
315		fn on_finalize(_n: BlockNumberFor<T>) {
316			// cleanup for next block
317			<HasDispatched<T, I>>::kill();
318		}
319	}
320
321	#[pallet::view_functions]
322	impl<T: Config<I>, I: 'static> Pallet<T, I> {
323		/// Retrieve the aggregated oracle value for a specific key, including its timestamp.
324		pub fn get_value(key: T::OracleKey) -> Option<TimestampedValueOf<T, I>> {
325			Self::get(&key)
326		}
327
328		/// Retrieve every aggregated oracle value tracked by the pallet.
329		pub fn all_values() -> Vec<(T::OracleKey, TimestampedValueOf<T, I>)> {
330			<Values<T, I>>::iter().collect()
331		}
332	}
333
334	#[pallet::call]
335	impl<T: Config<I>, I: 'static> Pallet<T, I> {
336		/// Feeds external data values into the oracle system.
337		///
338		/// ## Dispatch Origin
339		///
340		/// The dispatch origin of this call must be a signed account that is either:
341		/// - A member of the oracle operators set (managed by [`SortedMembers`])
342		/// - The root origin
343		///
344		/// ## Details
345		///
346		/// This function allows authorized oracle operators to submit timestamped key-value pairs
347		/// into the oracle system. Each submitted value is immediately timestamped with the current
348		/// block time and stored in the [`RawValues`] storage. The system then attempts to
349		/// aggregate all raw values for each key using the configured [`CombineData`] trait
350		/// implementation, updating the final [`Values`] storage with the aggregated result.
351		///
352		/// Only one submission per oracle operator per block is allowed to prevent spam and ensure
353		/// fair participation. The function also triggers the [`OnNewData`] hook for each submitted
354		/// value, allowing other pallets to react to new oracle data.
355		///
356		/// ## Errors
357		///
358		/// - [`Error::NoPermission`]: The sender is not authorized to feed data
359		/// - [`Error::AlreadyFeeded`]: The sender has already fed data in the current block
360		/// - [`Error::ExceedsMaxHasDispatchedSize`]: Too many operators have fed data in this block
361		///
362		/// ## Events
363		///
364		/// - [`Event::NewFeedData`]: Emitted when data is successfully fed into the oracle
365		#[pallet::call_index(0)]
366		#[pallet::weight(T::WeightInfo::feed_values(values.len() as u32))]
367		pub fn feed_values(
368			origin: OriginFor<T>,
369			values: BoundedVec<(T::OracleKey, T::OracleValue), T::MaxFeedValues>,
370		) -> DispatchResultWithPostInfo {
371			let feeder = ensure_signed_or_root(origin.clone())?;
372
373			let who = Self::ensure_account(feeder)?;
374
375			// ensure account hasn't dispatched an updated yet
376			<HasDispatched<T, I>>::try_mutate(|set| {
377				set.try_insert(who.clone())
378					.map_err(|_| Error::<T, I>::ExceedsMaxHasDispatchedSize)?
379					.then_some(())
380					.ok_or(Error::<T, I>::AlreadyFeeded)
381			})?;
382
383			Self::do_feed_values(who, values.into());
384			Ok(Pays::No.into())
385		}
386	}
387}
388
389impl<T: Config<I>, I: 'static> Pallet<T, I> {
390	fn get_pallet_account() -> T::AccountId {
391		T::PalletId::get().into_account_truncating()
392	}
393
394	/// Reads the raw values for a given key from all oracle members.
395	pub fn read_raw_values(key: &T::OracleKey) -> Vec<TimestampedValueOf<T, I>> {
396		T::Members::sorted_members()
397			.iter()
398			.chain([Self::get_pallet_account()].iter())
399			.filter_map(|x| Self::raw_values(x, key))
400			.collect()
401	}
402
403	/// Returns the aggregated and timestamped value for a given key.
404	pub fn get(key: &T::OracleKey) -> Option<TimestampedValueOf<T, I>> {
405		Self::values(key)
406	}
407
408	fn combined(key: &T::OracleKey) -> Option<TimestampedValueOf<T, I>> {
409		let values = Self::read_raw_values(key);
410		T::CombineData::combine_data(key, values, Self::values(key))
411	}
412
413	fn ensure_account(who: Option<T::AccountId>) -> Result<T::AccountId, DispatchError> {
414		// ensure feeder is authorized
415		if let Some(who) = who {
416			ensure!(T::Members::contains(&who), Error::<T, I>::NoPermission);
417			Ok(who)
418		} else {
419			Ok(Self::get_pallet_account())
420		}
421	}
422
423	fn do_feed_values(who: T::AccountId, values: Vec<(T::OracleKey, T::OracleValue)>) {
424		let now = T::Time::now();
425		for (key, value) in &values {
426			let timestamped = TimestampedValue { value: value.clone(), timestamp: now };
427			RawValues::<T, I>::insert(&who, key, timestamped);
428
429			// Update `Values` storage if `combined` yielded result.
430			if let Some(combined) = Self::combined(key) {
431				<Values<T, I>>::insert(key, combined);
432			}
433
434			T::OnNewData::on_new_data(&who, key, value);
435		}
436		Self::deposit_event(Event::NewFeedData { sender: who, values });
437	}
438}
439
440impl<T: Config<I>, I: 'static> ChangeMembers<T::AccountId> for Pallet<T, I> {
441	fn change_members_sorted(
442		_incoming: &[T::AccountId],
443		outgoing: &[T::AccountId],
444		_new: &[T::AccountId],
445	) {
446		// remove values
447		for removed in outgoing {
448			let _ = RawValues::<T, I>::clear_prefix(removed, u32::MAX, None);
449		}
450	}
451
452	fn set_prime(_prime: Option<T::AccountId>) {
453		// nothing
454	}
455}
456
457impl<T: Config<I>, I: 'static> DataProvider<T::OracleKey, T::OracleValue> for Pallet<T, I> {
458	fn get(key: &T::OracleKey) -> Option<T::OracleValue> {
459		Self::get(key).map(|timestamped_value| timestamped_value.value)
460	}
461}
462impl<T: Config<I>, I: 'static> DataProviderExtended<T::OracleKey, TimestampedValueOf<T, I>>
463	for Pallet<T, I>
464{
465	fn get_all_values() -> impl Iterator<Item = (T::OracleKey, Option<TimestampedValueOf<T, I>>)> {
466		<Values<T, I>>::iter().map(|(k, v)| (k, Some(v)))
467	}
468}
469
470impl<T: Config<I>, I: 'static> DataFeeder<T::OracleKey, T::OracleValue, T::AccountId>
471	for Pallet<T, I>
472{
473	fn feed_value(
474		who: Option<T::AccountId>,
475		key: T::OracleKey,
476		value: T::OracleValue,
477	) -> DispatchResult {
478		Self::do_feed_values(Self::ensure_account(who)?, vec![(key, value)]);
479		Ok(())
480	}
481}