SOON Chain Integration Guide

PreviousOn-Chain Costs NextSvmBNB Chain Integration Guide

Last updated 21 days ago

SOON Chain Integration Guide

Description

APRO Oracle Data Pull is a pull mode oracle product for those who require low-latency data feed service.

Following process chart is how pull mode works:

This doc is the integration guide for projects on SOON Devnet.

Domains

Description

Devnet URL

Mainnet URL

REST Endpoint to query specific reports

Program IDs

Description

Devnet

Mainnet

Apro_SVM_Oracle

4Mvy4RKRyJMf4PHavvGUuTj9agoddUZ9atQoFma1tyMY

Sample_Client

HUJ8ouH6fVonhF1hPV6ENoLid5nbHfyZSpvfujw6X6Hm

Authentication

Headers

All routes require the following two headers for user authentication:

Header

Description

Authorization

The user’s unique identifier, provided as a UUID (Universally Unique IDentifier).

X-Authorization-Timestamp

The current timestamp, with precision up to milliseconds. The timestamp must closely synchronize with the server time, allowing a maximum discrepancy of 5 seconds (by default). For a value of 10 digits, it is multiplied directly by 1000 to milliseconds.

To get authorization, please contact our BD Team:

Email: bd@apro.com

API endpoints

Return a single report at a given timestamp

Endpoint

/api/soon/reports

Type

Description

Parameter(s)

HTTP GET

Returns a single report for a given timestamp.

feedID: A Data Streams feed ID.
timestamp: The Unix timestamp for the report.

Sample request

GET /api/soon/reports?feedID=<feedID>&timestamp=<timestamp>

Sample response

Return a single report with the latest timestamp

Endpoint

/api/soon/reports/latest

Type

Parameter(s)

HTTP GET

feedID: A Data Streams feed ID.

Sample request

GET /api/soon/reports/latest?feedID=<feedID>

Sample response

Return a report for multiple FeedIDs at a given timestamp

Endpoint

/api/soon/reports/bulk

Type

Description

Parameter(s)

HTTP GET

Return a report for multiple FeedIDs at a given timestamp.

feedIDs: A comma-separated list of Data Streams feed IDs.
timestamp: The Unix timestamp for the first report or the string 'latest' for getting the latest report.

Sample request

GET /api/soon/reports/bulk?feedIDs=<feedID1>,<feedID2>,...&timestamp=<timestamp>

GET /api/soon/reports/bulk?feedIDs=<feedID1>,<feedID2>,...&timestamp=latest

Sample response

Return multiple sequential reports for a single FeedID, starting at a given timestamp

Endpoint

/api/soon/reports/page

Type

Description

Parameter(s)

HTTP GET

Return multiple sequential reports for a single FeedID, starting at a given timestamp.

feedID: A Data Streams feed ID.
startTimestamp: The Unix timestamp for the first report.
limit (optional): The number of reports to return.

Sample request

GET /api/soon/reports/page?feedID=<FeedID>&startTimestamp=<StartTimestamp>&limit=<Limit>

Sample response

WebSocket Connection

Establish a streaming WebSocket connection that sends reports for the given feedID(s) after they are verified.

Endpoint

/api/soon/ws

Type

Parameter(s)

WebSocket

feedIDs: A comma-separated list of Data Streams feed IDs.

Sample request

GET /api/soon/ws?feedIDs=<feedID1>,<feedID2>,...

Sample response

Price Feed ID

Devnet:

Feed

Information

BTC/USD

ID: 0x0003665949c883f9e0f6f002eac32e00bd59dfe6c34e92a91c37d6a8322d6489
Decimals: 18
oracle_state_ID: 1

ETH/USD

ID: 0x0003555ace6b39aae1b894097d0a9fc17f504c62fea598fa206cc6f5088e6e45
Decimals: 18
oracle_state_ID: 2

SOL/USD

ID: 0x000343ec7f6691d6bf679978bab5c093fa45ee74c0baac6cc75649dc59cc21d3
Decimals: 18
oracle_state_ID: 3

BONK/USD

ID: 0x00032b250dddd30d526b4ae66d170e1ab204ab0567531798d3bbd09737f6c3c6
Decimals: 18
oracle_state_ID: 4

Mainnet:

Feed

Information

BTC/USD

ID: 0x0003665949c883f9e0f6f002eac32e00bd59dfe6c34e92a91c37d6a8322d6489
Decimals: 18
oracle_state_ID: 1

ETH/USD

ID: 0x0003555ace6b39aae1b894097d0a9fc17f504c62fea598fa206cc6f5088e6e45
Decimals: 18
oracle_state_ID: 2

Valueless_Test/USD

ID: 0x000369f643e4e5d9b9d04863249c07c15937d0b36af803dd8d213827b0badd5c
Decimals: 18
oracle_state_ID: 3

USDT/USD

ID: 0x00039a0c0be4e43cacda1599ac414205651f4a62b614b6be9e5318a182c33eb0
Decimals: 18
oracle_state_ID: 4

USDC/USD

ID: 0x00034b881a0c0fff844177f881a313ff894bfc6093d33b5514e34d7faa41b7ef
Decimals: 18
oracle_state_ID: 5

BONK/USD

ID: 0x00032b250dddd30d526b4ae66d170e1ab204ab0567531798d3bbd09737f6c3c6
Decimals: 18
oracle_state_ID: 10

SOL/USD

ID: 0x000343ec7f6691d6bf679978bab5c093fa45ee74c0baac6cc75649dc59cc21d3
Decimals: 18
oracle_state_ID: 11

Error response codes

Status Code

Description

400 Bad Request

This error is triggered when:

There is any missing/malformed query argument.
Required headers are missing or provided with incorrect values.

401 Unauthorized User

This error is triggered when:

Authentication fails, typically because the HMAC signature provided by the client doesn't match the one expected by the server.
A user requests access to a feed without the appropriate permission or that does not exist.

500 Internal Server

Indicates an unexpected condition encountered by the server, preventing it from fulfilling the request. This error typically points to issues on the server side.

206 Missing data (/bulk endpoint only)

Indicates that at least one feed ID data is missing from the report. E.g., you requested a report for feed IDs <feedID1>, <feedID2>, and <feedID3> at a given timestamp. If data for <feedID2> is missing from the report (not available yet at the specified timestamp), you get [<feedID1 data>, <feedID3 data>] and a 206 response.

Sample Integration Program

oracle_sdk:

use anchor_lang::prelude::*;
use anchor_lang::solana_program::hash::hash;
use anchor_lang::solana_program::instruction::Instruction;
use anchor_lang::solana_program::program::invoke;

pub const APRO_SVM_PROGRAM_ID: &str = "4Mvy4RKRyJMf4PHavvGUuTj9agoddUZ9atQoFma1tyMY";

pub fn load_price_feed_from_account_info(price_account_info: &AccountInfo) -> Result<PriceFeed> {
    let data = price_account_info.try_borrow_data()?;

    let mut price_feed_data = &data[8..];
    let price_feed = PriceFeed::deserialize(&mut price_feed_data)?;

    Ok(price_feed)
}

pub fn update_price<'info>(
    oracle_state: &AccountInfo<'info>,
    price_feed: &AccountInfo<'info>,
    payer: &AccountInfo<'info>,
    admin: &AccountInfo<'info>,
    system_program: &AccountInfo<'info>,
    oracle_program: &AccountInfo<'info>,
    feed_id: [u8; 32],
    valid_time_stamp: u128,
    observe_time_stamp: u128,
    native_fee: u128,
    apro_token_fee: u128,
    expire_at: u128,
    benchmark_price: u128,
    ask_price: u128,
    bid_price: u128,
    config_digest: [u8; 32],
    epoch_and_round: u128,
    extra_hash: [u8; 32],
    signatures: Vec<[u8; 64]>,
    recovery_ids: Vec<u8>,
) -> Result<()> {
    let ix = Instruction {
        program_id: *oracle_program.key,
        accounts: vec![
            AccountMeta::new_readonly(*oracle_state.key, false),
            AccountMeta::new(*price_feed.key, false),
            AccountMeta::new(*payer.key, true),
            AccountMeta::new(*admin.key, false),
            AccountMeta::new_readonly(*system_program.key, false),
        ],
        data: UpdatePriceArgs {
            feed_id,
            valid_time_stamp,
            observe_time_stamp,
            native_fee,
            apro_token_fee,
            expire_at,
            benchmark_price,
            ask_price,
            bid_price,
            config_digest,
            epoch_and_round,
            extra_hash,
            signatures,
            recovery_ids,
        }
        .data(),
    };

    invoke(
        &ix,
        &[
            oracle_state.clone(),
            price_feed.clone(),
            payer.clone(),
            admin.clone(),
            system_program.clone(),
            oracle_program.clone(),
        ],
    )?;

    Ok(())
}

#[derive(AnchorDeserialize, AnchorSerialize, Clone, Debug)]
pub struct PriceFeed {
    pub feed_id: [u8; 32],
    pub valid_time_stamp: u128,
    pub observe_time_stamp: u128,
    pub native_fee: u128,
    pub apro_token_fee: u128,
    pub expire_at: u128,
    pub benchmark_price: u128,
    pub ask_price: u128,
    pub bid_price: u128,
    pub config_digest: [u8; 32],
    pub epoch_and_round: u128,
    pub extra_hash: [u8; 32],
}

#[derive(AnchorSerialize, AnchorDeserialize)]
struct UpdatePriceArgs {
    feed_id: [u8; 32],
    valid_time_stamp: u128,
    observe_time_stamp: u128,
    native_fee: u128,
    apro_token_fee: u128,
    expire_at: u128,
    benchmark_price: u128,
    ask_price: u128,
    bid_price: u128,
    config_digest: [u8; 32],
    epoch_and_round: u128,
    extra_hash: [u8; 32],
    signatures: Vec<[u8; 64]>,
    recovery_ids: Vec<u8>,
}

impl UpdatePriceArgs {
    fn data(&self) -> Vec<u8> {
        let mut data = Vec::new();
        let preimage = "global:update_price".as_bytes();
        let hash = hash(preimage);
        let discriminator = &hash.to_bytes()[..8];
        data.extend_from_slice(discriminator);
        data.extend_from_slice(&AnchorSerialize::try_to_vec(self).unwrap());

        data
    }
}

Clients code:

use anchor_lang::prelude::*;
use oracle_sdk::{load_price_feed_from_account_info, update_price};

declare_id!("GzWu85MdbZtVBDcC4Xrmp1dWix7Qo52nUAkD2FjraJ6f");//modify by solana address -k

#[program]
pub mod oracle_client_example {
    use super::*;

    pub fn fetch_price(ctx: Context<FetchPrice>) -> Result<()> {
        //fetch price feed from oracle
        let price_feed = load_price_feed_from_account_info(&ctx.accounts.price_account)?;

        msg!("Price Feed Details:");
        msg!("Feed ID: {:?}", price_feed.feed_id);
        msg!("Valid Timestamp: {}", price_feed.valid_time_stamp);
        msg!("Observe Timestamp: {}", price_feed.observe_time_stamp);
        msg!("Benchmark Price: {}", price_feed.benchmark_price);
        msg!("Ask Price: {}", price_feed.ask_price);
        msg!("Bid Price: {}", price_feed.bid_price);

        let current_timestamp = Clock::get()?.unix_timestamp as u128;
        let staleness_threshold = 3600u128;

        //store the price in the price_result account
        let price_result = if current_timestamp - price_feed.valid_time_stamp <= staleness_threshold
        {
            PriceResult {
                price: price_feed.benchmark_price,
                is_valid: true,
            }
        } else {
            PriceResult {
                price: 0,
                is_valid: false,
            }
        };

        ctx.accounts.price_result.set_inner(price_result);

        Ok(())
    }

    pub fn update_oracle_price(
        ctx: Context<UpdateOraclePrice>,
        feed_id: [u8; 32],
        valid_time_stamp: u128,
        observe_time_stamp: u128,
        native_fee: u128,
        apro_token_fee: u128,
        expire_at: u128,
        benchmark_price: u128,
        ask_price: u128,
        bid_price: u128,
        config_digest: [u8; 32],
        epoch_and_round: u128,
        extra_hash: [u8; 32],
        signatures: Vec<[u8; 64]>,
        recovery_ids: Vec<u8>,
    ) -> Result<()> {
        //update the price feed through CPI
        update_price(
            &ctx.accounts.oracle_state.to_account_info(),
            &ctx.accounts.price_feed.to_account_info(),
            &ctx.accounts.payer.to_account_info(),
            &ctx.accounts.admin.to_account_info(),
            &ctx.accounts.system_program.to_account_info(),
            &ctx.accounts.oracle_program.to_account_info(),
            feed_id,
            valid_time_stamp,
            observe_time_stamp,
            native_fee,
            apro_token_fee,
            expire_at,
            benchmark_price,
            ask_price,
            bid_price,
            config_digest,
            epoch_and_round,
            extra_hash,
            signatures,
            recovery_ids,
        )?;
        Ok(())
    }
}

#[derive(Accounts)]
pub struct FetchPrice<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    /// CHECK: This account is owned by the Oracle program
    pub price_account: UncheckedAccount<'info>,
    #[account(
        init_if_needed,
        payer = payer,
        space = 8 + 16 + 1, // discriminator + price (u128) + is_valid
        seeds = [b"price_result", price_account.key().as_ref()],
        bump
    )]
    pub price_result: Account<'info, PriceResult>,
    pub system_program: Program<'info, System>,
}

#[derive(Accounts)]
pub struct UpdateOraclePrice<'info> {
    /// CHECK: This account is verified in the update_price function
    pub oracle_state: UncheckedAccount<'info>,
    /// CHECK: This account is verified in the update_price function
    #[account(mut)]
    pub price_feed: UncheckedAccount<'info>,
    #[account(mut)]
    pub payer: Signer<'info>,
    /// CHECK: This account is verified in the update_price function
    #[account(mut)]
    pub admin: UncheckedAccount<'info>,
    pub system_program: Program<'info, System>,
    /// CHECK: This account is verified in the update_price function
    pub oracle_program: UncheckedAccount<'info>,
}

#[account]
pub struct PriceResult {
    pub price: u128,
    pub is_valid: bool,
}

#[error_code]
pub enum ErrorCode {
    #[msg("Invalid account data length")]
    InvalidAccountDataLength,
}

PreviousOn-Chain Costs NextSvmBNB Chain Integration Guide

Last updated 21 days ago