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}