pallet_oracle_runtime_api/
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//! Runtime API definition for the oracle pallet.
19//!
20//! This crate provides runtime APIs that allow external clients to query oracle data
21//! from the blockchain. The APIs are designed to be efficient and provide access to
22//! both individual oracle values and complete datasets.
23//!
24//! ## Overview
25//!
26//! The oracle runtime API enables off-chain applications, wallets, and other blockchain
27//! clients to retrieve oracle data without needing to parse storage directly. This
28//! abstraction provides a clean interface for accessing oracle information and ensures
29//! compatibility across different runtime versions.
30//!
31//! The API supports querying data from specific oracle providers and retrieving all
32//! available oracle data, making it suitable for various use cases such as price
33//! feeds, data monitoring, and external integrations.
34
35#![cfg_attr(not(feature = "std"), no_std)]
36// The `too_many_arguments` warning originates from `decl_runtime_apis` macro.
37#![allow(clippy::too_many_arguments)]
38// The `unnecessary_mut_passed` warning originates from `decl_runtime_apis` macro.
39#![allow(clippy::unnecessary_mut_passed)]
40
41use codec::Codec;
42use sp_std::prelude::Vec;
43
44sp_api::decl_runtime_apis! {
45	/// Runtime API for querying oracle data from the blockchain.
46	///
47	/// This trait provides methods to retrieve oracle data without requiring direct
48	/// storage access. It's designed to be called from external clients, RPC nodes,
49	/// and other blockchain infrastructure components that need access to oracle
50	/// information.
51	///
52	/// The API is generic over three type parameters:
53	/// - `ProviderId`: Identifies the oracle provider or data source
54	/// - `Key`: The oracle key identifying the specific data feed
55	/// - `Value`: The oracle data value type
56	pub trait OracleApi<ProviderId, Key, Value> where
57		ProviderId: Codec,
58		Key: Codec,
59		Value: Codec,
60	{
61		/// Retrieves a specific oracle value for a given provider and key.
62		///
63		/// Returns the current oracle value if available, or `None` if no data exists
64		/// for the specified provider and key combination.
65		///
66		/// # Parameters
67		///
68		/// * `provider_id`: The oracle provider identifier
69		/// * `key`: The oracle key identifying the data feed
70		///
71		/// # Returns
72		///
73		/// Returns `Some(value)` if oracle data exists, `None` otherwise.
74		fn get_value(provider_id: ProviderId, key: Key) -> Option<Value>;
75
76		/// Retrieves all oracle values for a specific provider.
77		///
78		/// Returns a vector of key-value pairs containing all available oracle data
79		/// from the specified provider. Each pair contains the oracle key and its
80		/// corresponding value (if available).
81		///
82		/// # Parameters
83		///
84		/// * `provider_id`: The oracle provider identifier
85		///
86		/// # Returns
87		///
88		/// Returns a vector of `(Key, Option<Value>)` pairs representing all oracle
89		/// data available from the specified provider.
90		fn get_all_values(provider_id: ProviderId) -> Vec<(Key, Option<Value>)>;
91	}
92}
pallet_oracle_runtime_api/lib.rs

pallet_oracle_runtime_api/
lib.rs
