👋Getting Started: Price Feed

This section explains the basics of building a SEDA Oracle Program and how to use it from any supported network using the PriceFeed example.

Quickstart

The easiest way to start building a SEDA Oracle Program is by using the seda-request-starter-kit. This starter kit offers a streamlined setup process and comes with the essential tools and structure to help you create and deploy your first Oracle Program on the SEDA network.

To get started, clone the repository and install the required dependencies:

git clone https://github.com/sedaprotocol/seda-request-starter-kit.git
cd seda-request-starter-kit
bun install

Building the Oracle Program

The PriceFeed Oracle Program is divided into 2 phases:

1. Execution: it fetches the price of an asset pair (e.g., BTC-USDT) from an external source and processes this data.

2. Tally: it calculates the median among all executions reports.

This will illustrate the basic mechanics of how data is processed and aggregated within the SEDA network.

Step 1: Entrypoint

To begin, the Oracle Program logic lives in the src folder, where main.rs serves as the entry point for your Oracle Program.

src/main.rs

use execution_phase::execution_phase;
use seda_sdk_rs::oracle_program;
use tally_phase::tally_phase;

mod execution_phase;
mod tally_phase;

#[oracle_program]
impl PriceFeed {
    fn execute() {
        execution_phase().unwrap();
    }

    fn tally() {
        tally_phase().unwrap();
    }
}

This setup initializes the PriceFeed Oracle Program, invoking the execution and tally phases that make up the data request.

Step 2: Execution Phase

The execution phase is where the Oracle Program fetches data and performs computation on the fetched data. In this case, it fetches the price for a specified asset pair from a given data source.

Read Inputs

The user triggering the Data Request can specify a set of inputs that can be used in the data request to add more dynamic execution and templating. In the following example we start by reading the input parameters using Process::get_inputs():

src/execution_phase.rs

pub fn execution_phase() -> Result<()> {
    // Retrieve the input parameters for the data request (DR).
    // Expected to be in the format "symbolA-symbolB" (e.g., "BTC-USDT").
    let dr_inputs_raw = String::from_utf8(Process::get_inputs())?;

    // Log the asset pair being fetched as part of the Execution Standard Out.
    println!("Fetching price for pair: {}", dr_inputs_raw);

    // Split the input string into symbolA and symbolB.
    // Example: "ETH-USDC" will be split into "ETH" and "USDC".
    let dr_inputs: Vec<&str> = dr_inputs_raw.split("-").collect();
    let symbol_a = dr_inputs.get(0).expect("format should be tokenA-tokenB");
    let symbol_b = dr_inputs.get(1).expect("format should be tokenA-tokenB");
		
    // ...    
}

In this example, we assume the input is a UTF-8 encoded string. We log the asset pair being fetched to include this information in the data request execution. The input string is then split to extract the symbols needed for this specific API.

Fetch and Compute Data

Next, let's add the logic to fetch data from an external API and perform some calculations:

src/execution_phase.rs

use seda_sdk_rs::http_fetch;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct PriceFeedResponse {
    price: String,
}

pub fn execution_phase() -> Result<()> {
    // ....

    let response = http_fetch(
        format!(
            "https://api.binance.com/api/v3/ticker/price?symbol={}{}",
            symbol_a.to_uppercase(),
            symbol_b.to_uppercase()
        ),
        None,
    );

    // Check if the HTTP request was successfully fulfilled.
    if !response.is_ok() {
        // Handle the case where the HTTP request failed or was rejected.
        eprintln!(
            "HTTP Response was rejected: {} - {}",
            response.status,
            String::from_utf8(response.bytes)?
        );

        // Report the failure to the SEDA network with an error code of 1.
        Process::error("Error while fetching price feed".as_bytes());

        return Ok(());
    }

    // Parse the API response as defined earlier.
    let data = serde_json::from_slice::<PriceFeedResponse>(&response.bytes)?;
    
    // Convert to integer (and multiply by 1e6 to avoid losing precision).
    let price: f32 = data.price.parse()?;
    println!("Fetched price: {}", price);

    let result = (price * 1000000f32) as u128;
    println!("Reporting: {}", result);
    
    // ....
}

Here's a breakdown of the logic:

1. Fetch Data: Perform an HTTP request to fetch the price for the asset pair using the httpFetch function. The URL is constructed dynamically based on the asset symbols.

2. Parse Response: The API response is parsed into a PriceFeedResponse object. This allows us to easily extract the price data from the response.

3. Perform Calculations: The fetched price, which is a floating-point number, is multiplied by 1e6 to avoid precision loss and then converted into a u128 integer.

For more information about fetching external data, please refer to the detailed guide Fetching Open Data.

Report Results & Error Handling

Finally, we need to report the result and indicate that the Process has ended successfully using the Process::success() call. Since Process only works with Bytes, we convert our result to bytes using result.to_le_bytes().

If there are any errors during the process, they can be handled using the Process::error() call. Additionally, println!() and eprintln!() can be used to log errors for debugging purposes.

src/execution_phase.rs

use anyhow::Result;
use seda_sdk_rs::{http_fetch, Process};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct PriceFeedResponse {
    price: String,
}

pub fn execution_phase() -> Result<()> {
    // ...
	
    // Make an HTTP request to a price feed API to get the price for the symbol pair.
    let response = http_fetch(
        format!(
            "https://api.binance.com/api/v3/ticker/price?symbol={}{}",
            symbol_a.to_uppercase(),
            symbol_b.to_uppercase()
        ),
        None,
    );

    // Check if the HTTP request was successfully fulfilled.
    if !response.is_ok() {
        // Handle the case where the HTTP request failed or was rejected.
        eprintln!(
            "HTTP Response was rejected: {} - {}",
            response.status,
            String::from_utf8(response.bytes)?
        );

        // Report the failure to the SEDA network with an error code of 1.
        Process::error("Error while fetching price feed".as_bytes());

        return Ok(());
    }

    // Parse the API response as defined earlier.
    let data = serde_json::from_slice::<PriceFeedResponse>(&response.bytes)?;

    // Convert to integer (and multiply by 1e6 to avoid losing precision).
    let price: f32 = data.price.parse()?;
    println!("Fetched price: {}", price);

    let result = (price * 1000000f32) as u128;
    println!("Reporting: {}", result);

    // Report the successful result back to the SEDA network.
    Process::success(&result.to_le_bytes());
}

Here's a summary of what's happening:

1. Error Handling: We check if the HTTP request was successful. If not, we log the error and use Process::error() to report the issue to the SEDA network.

2. Parse and Validate: We parse the API response into a PriceFeedResponse object and ensure that the price data can be correctly converted to a float.

3. Report the Result: If everything is successful, we multiply the float by 1e6 to convert it into an integer and use Process::success() to report the result back to the SEDA network.

This completes the execution phase, ensuring that errors are handled gracefully and results are accurately processed.

Step 3: Tally Phase

The tally phase is where the results collected during the execution phase are aggregated to reach a consensus. This phase processes the data gathered by multiple Overlay Nodes to produce a single result that can be returned to the blockchain.

In this example, we calculate the median price from the results obtained during the execution phase to provide a final output. Here's how we can implement this logic:

src/tally_phase.rs

use anyhow::Result;
use seda_sdk_rs::{get_reveals, Process};

/**
 * Executes the tally phase within the SEDA network.
 * This phase aggregates the results (e.g., price data) revealed during the execution phase,
 * calculates the median value, and submits it as the final result.
 * Note: The number of reveals depends on the replication factor set in the data request parameters.
 */
pub fn tally_phase() -> Result<()> {
    // Tally inputs can be retrieved from Process.getInputs(), though it is unused in this example.
    // let tally_inputs = Process::get_inputs();

    // Retrieve consensus reveals from the tally phase.
    let reveals = get_reveals()?;
    let mut prices: Vec<u128> = Vec::new();

    // Iterate over each reveal, parse its content as an unsigned integer (u128), and store it in the prices array.
    for reveal in reveals {
        let price_bytes_slice: [u8; 16] = match reveal.body.reveal.try_into() {
            Ok(value) => value,
            Err(_err) => {
                // We should always handle a reveal body with care and not exit/panic when parsing went wrong
                // It's better to skip that reveal
                eprintln!("Reveal body could not be casted to u128");
                continue;
            }
        };

        let price = u128::from_le_bytes(price_bytes_slice);
        println!("Received price: {}", price);
        
        prices.push(price);
    }

    if prices.len() == 0 {
        // If no valid prices were revealed, report an error indicating no consensus.
        Process::error("No consensus among revealed results".as_bytes());
        return Ok(());
    }

    // If there are valid prices revealed, calculate the median price from price reports.
    let final_price = median(prices);

    // Report the successful result in the tally phase, encoding the result as bytes.
    // Encoding result with big endian to decode from EVM contracts.
    Process::success(&final_price.to_be_bytes());

    Ok(())
}

fn median(mut nums: Vec<u128>) -> u128 {
    // ...
}

Explanation:

1. Retrieve Results: The tallyPhase gathers the execution results using seda_sdk_rs::get_reveals(). These results are parsed into unsigned integers (u128) and stored for further analysis.

2. Consensus Check: Before proceeding, it verifies that there are enough price data points from the execution phase to move forward with aggregation.

3. Aggregate Data: The parsed prices are used to calculate the median, a robust statistical measure that minimizes the impact of outliers and provides a reliable data representation.

4. Result Reporting: If the median calculation is successful, the final result is reported using Process::success(). If no valid results are available or consensus is not achieved, an error is logged using Process::error().

Now that the Oracle Program is implemented, we can generate the WebAssembly artifacts. This process compiles your code and places the resulting .wasm files in the build directory. After building, you'll have the necessary artifacts to deploy your Oracle Program on the SEDA network.

To build the Oracle Program, run the following command:

bun run build

This process completes the PriceFeed Oracle Program. In the next chapters we will be showcasing how to deploy and trigger Data Requests.