switchboard-on-demand 0.7.0

//! Oracle quote verification for creating and verifying oracle data quotes
//!
//! This module provides the `QuoteVerifier` which allows you to construct
//! a verifier with specific accounts and parameters, then use it to verify ED25519
//! instruction data and create validated `OracleQuote` instances.
//!
//! The verification process checks:
//! - ED25519 signature validity
//! - Oracle signing key authorization
//! - Slot hash verification against the sysvar
//! - Quote age validation against max_age parameter (requires clock sysvar)
//! - Oracle quote data integrity

use crate::prelude::*;
#[cfg(feature = "anchor")]
use anchor_lang::solana_program;
use anyhow::{bail, Error as AnyError};
use solana_program::account_info::AccountInfo;
use solana_program::sysvar::instructions::get_instruction_relative;
use crate::check_pubkey_eq;
use crate::check_p64_eq;
use core::ptr::read_unaligned;
#[allow(unused_imports)]
use crate::{ON_DEMAND_MAINNET_PID, ON_DEMAND_DEVNET_PID};

/// Maximum number of slots stored in the slot hash sysvar
const SYSVAR_SLOT_LEN: u64 = 512;


/// Oracle quote verifier with builder pattern for configuring and performing verification.
///
/// This verifier allows you to configure the required accounts step by step before
/// using it to verify oracle quotes. All required accounts must be set before
/// verification can be performed.
///
/// # Example
/// ```rust,ignore
/// let mut verifier = QuoteVerifier::new();
/// verifier
///     .queue(&queue_account)
///     .slothash_sysvar(&slothash_sysvar)
///     .ix_sysvar(&instructions_sysvar)
///     .clock(&clock)
///     .max_age(100);
///
/// let quote = verifier.load_and_verify(0)?;  // 0 for first instruction
///
/// // Access the raw buffer from the quote itself
/// if let Some(raw_data) = quote.raw_data() {
///     println!("Raw oracle data: {} bytes", raw_data.len());
/// }
/// ```
#[derive(Clone)]
pub struct QuoteVerifier<'info, 'a> {
    queue: Option<&'a AccountInfo<'info>>,
    slothash_sysvar: Option<&'a AccountInfo<'info>>,
    ix_sysvar: Option<&'a AccountInfo<'info>>,
    clock: Option<&'a solana_program::sysvar::clock::Clock>,
    max_age: u64,
    _phantom: core::marker::PhantomData<(&'a (), &'info ())>,
}

impl<'info, 'a> Default for QuoteVerifier<'info, 'a> {
    fn default() -> Self {
        Self::new()
    }
}

impl<'info, 'a> QuoteVerifier<'info, 'a> {
    /// Creates a new `QuoteVerifier` with default values.
    ///
    /// All account references are initially None and must be set before
    /// verification can be performed.
    #[inline(always)]
    pub fn new() -> Self {
        Self {
            queue: None,
            slothash_sysvar: None,
            ix_sysvar: None,
            clock: None,
            max_age: 0,
            _phantom: core::marker::PhantomData,
        }
    }

    /// Sets the oracle queue account for verification.
    ///
    /// The queue account contains the authorized oracle signing keys that will
    /// be used to validate the signatures in the oracle quote.
    ///
    /// # Arguments
    /// * `account` - Reference to the queue account or any type that can be converted to AccountInfo
    #[inline(always)]
    pub fn queue<T>(&mut self, account: &'a T) -> &mut Self
    where
        T: AsRef<AccountInfo<'info>>,
    {
        self.queue = Some(account.as_ref());
        self
    }

    /// Sets the slot hash sysvar account for verification.
    ///
    /// The slot hash sysvar is used to validate that the signed slot hash
    /// in the oracle quote corresponds to a valid historical slot.
    ///
    /// # Arguments
    /// * `sysvar` - Reference to the slot hash sysvar account
    #[inline(always)]
    pub fn slothash_sysvar<T>(&mut self, sysvar: &'a T) -> &mut Self
    where
        T: AsRef<AccountInfo<'info>>,
    {
        self.slothash_sysvar = Some(sysvar.as_ref());
        self
    }

    /// Sets the instructions sysvar account for verification.
    ///
    /// The instructions sysvar contains the ED25519 instruction data that
    /// will be parsed to extract the oracle signatures and quote data.
    ///
    /// # Arguments
    /// * `sysvar` - Reference to the instructions sysvar account
    #[inline(always)]
    pub fn ix_sysvar<T>(&mut self, sysvar: &'a T) -> &mut Self
    where
        T: AsRef<AccountInfo<'info>>,
    {
        self.ix_sysvar = Some(sysvar.as_ref());
        self
    }

    /// Sets the clock sysvar for freshness validation.
    ///
    /// The clock sysvar provides the current slot used to validate oracle quote age
    /// against the configured max_age parameter.
    ///
    /// # Arguments
    /// * `clock` - Reference to the clock sysvar or any type that can be converted to Clock
    #[inline(always)]
    pub fn clock<T>(&mut self, clock: &'a T) -> &mut Self
    where
        T: AsRef<solana_program::sysvar::clock::Clock>,
    {
        self.clock = Some(clock.as_ref());
        self
    }

    /// Sets the maximum age in slots for oracle quote freshness validation.
    ///
    /// Oracle quotes older than this many slots will be rejected during verification.
    /// This helps prevent replay attacks and ensures data freshness.
    ///
    /// # Arguments
    /// * `max_age` - Maximum age in slots (typically 100-500 slots)
    #[inline(always)]
    pub fn max_age(&mut self, max_age: u64) -> &mut Self {
        self.max_age = max_age;
        self
    }

    /// Verifies an oracle account containing oracle quote data.
    ///
    /// This method extracts the oracle quote data from an oracle account (skipping the
    /// 8-byte discriminator) and verifies it using the configured accounts.
    ///
    /// # Arguments
    /// * `oracle_account` - Account containing the oracle quote data
    ///
    /// # Returns
    /// * `Ok(OracleQuote)` - Successfully verified oracle quote
    /// * `Err(AnyError)` - Verification failed
    #[inline(always)]
    pub fn verify_account(&self, oracle_account: &AccountInfo<'a>) -> Result<OracleQuote<'a>, AnyError> {
        // # Safety
        //
        // This unsafe block is safe because:
        // - `oracle_account.data` is a valid `Rc<RefCell<&mut [u8]>>` provided by Solana runtime
        // - We verify the account has at least 8 bytes before reading the discriminator
        // - `read_unaligned` safely reads u64 from potentially unaligned memory
        // - Account data lifetime is guaranteed to outlive this function call
        unsafe {
            // Oracle account format: [discriminator(8)][length(2)][ed25519_data...]
            // Assert discriminator and read length, then pass the ed25519 data
            let data = &(*oracle_account.data.as_ptr());
            if data.len() < 8 {
                bail!("Oracle account too small: {} bytes, expected at least 8", data.len());
            }
            if read_unaligned(data.as_ptr() as *const u64) != QUOTE_DISCRIMINATOR_U64_LE {
                bail!("Invalid oracle account discriminator");
            }
            self.verify_delimited(&data[8..])
        }
    }

    /// Verifies raw ED25519 instruction data and creates a validated OracleQuote.
    ///
    /// This is the core verification method that performs all security checks:
    /// - Parses ED25519 signatures and extracts oracle indices
    /// - Validates oracle signing keys against the queue
    /// - Verifies slot hash against the sysvar
    /// - Validates quote age against max_age (requires clock sysvar)
    /// - Ensures oracle quote data integrity
    ///
    /// # Arguments
    /// * `data` - Raw ED25519 instruction data containing signatures and quote
    ///
    /// # Returns
    /// * `Ok(OracleQuote)` - Successfully verified and parsed oracle quote
    /// * `Err(AnyError)` - Verification failed with detailed error message
    ///
    /// # Errors
    /// - Clock sysvar not set
    /// - No signatures provided
    /// - Invalid oracle signing keys
    /// - Slot hash mismatch
    /// - Quote is too old (exceeds max_age slots)
    /// - Malformed instruction data
    #[inline(always)]
    pub fn verify_delimited<'data>(
        &self,
        data: &'data [u8],
    ) -> Result<OracleQuote<'data>, AnyError>
    where
        'data: 'a,
    {
        // # Safety
        //
        // This unsafe block is safe because:
        // - We verify `data` has at least 2 bytes before reading the length
        // - `read_unaligned` safely reads u16 from potentially unaligned memory
        // - The bounds check ensures we don't read beyond the data buffer
        // - Data slice is guaranteed valid for the function duration
        unsafe {
            if data.len() < 2 {
                bail!("Delimited data too small: {} bytes, expected at least 2", data.len());
            }
            let len = (data.as_ptr() as *const u16).read_unaligned() as usize;
            if len + 2 > data.len() {
                bail!("Invalid delimited length: {} exceeds buffer size {}", len + 2, data.len());
            }
            self.verify(&data[2..len + 2])
        }
    }

    /// Verifies oracle quote data and returns a validated OracleQuote
    pub fn verify<'data>(
        &self,
        data: &'data [u8],
    ) -> Result<OracleQuote<'data>, AnyError>
    where
        'data: 'a,
    {
        let (parsed_sigs, sig_count, oracle_idxs, recent_slot, version) =
            Ed25519Sysvar::parse_instruction(data)?;
        let queue = self.queue.ok_or_else(|| anyhow::anyhow!("Queue account not set"))?;
        let slothash_sysvar = self.slothash_sysvar.ok_or_else(|| anyhow::anyhow!("Slothash sysvar not set"))?;

        // Validate quote freshness - clock is required for all verifications
        let clock = self.clock.ok_or_else(|| anyhow::anyhow!("Clock sysvar not set"))?;
        if self.max_age > 0 && clock.slot.saturating_sub(recent_slot) > self.max_age {
            bail!("Quote is too old: recent_slot={}, current_slot={}, max_age={}",
                  recent_slot, clock.slot, self.max_age);
        }

        if sig_count == 0 {
            bail!("No signatures provided");
        }

        // Get queue data for oracle signing keys
        // Safely access queue data using RefCell borrow and try_from_bytes
        let queue_buf = queue.data.borrow();
        if queue_buf.len() < 8 + std::mem::size_of::<QueueAccountData>() {
            bail!("Queue account too small: {} bytes", queue_buf.len());
        }
        let queue_data: &QueueAccountData = bytemuck::try_from_bytes(&queue_buf[8..])
            .map_err(|e| anyhow::anyhow!("Failed to deserialize queue data: {}", e))?;

        // Find the target slothash from the oracle quote
        let reference_sig = &parsed_sigs[0];
        let header = unsafe { reference_sig.quote_header() };

        // Find the target slothash from oracle quote and get corresponding hash from sysvar
        let target_slothash = &header.signed_slothash as *const _ as *const u64;
        let found_slothash = &Self::find_slothash_in_sysvar(recent_slot, slothash_sysvar)? as *const _ as *const u64;

        // Account keys validation (64 bytes) - use pre-computed expected data
        if crate::utils::is_devnet() {
            assert!(check_pubkey_eq(queue.owner, &ON_DEMAND_DEVNET_PID));
        } else {
            assert!(check_pubkey_eq(queue.owner, &ON_DEMAND_MAINNET_PID));
        }
        assert!(check_pubkey_eq(slothash_sysvar.key, &solana_program::sysvar::slot_hashes::ID));

        assert!(unsafe { check_p64_eq(found_slothash, target_slothash) });

        // Oracle signing key validation (32 bytes per oracle: actual should match expected)
        for i in 0..sig_count {
            // Branchless bounds check,  30 is max oracles in queue
            let oracle_idx = (oracle_idxs[i as usize] as usize) % 30;
            let expected_oracle_key = queue_data.ed25519_oracle_signing_keys[oracle_idx];
            let actual_oracle_key = unsafe { parsed_sigs[i as usize].pubkey() };
            assert!(unsafe { check_p64_eq(actual_oracle_key as *const _ as *const u64, &expected_oracle_key as *const _ as *const u64) });
        }

        // Continue with remaining processing...
        let reference_feed_infos = unsafe { reference_sig.feed_infos() };
        let feed_count = reference_feed_infos.len();

        Ok(OracleQuote::new(
            unsafe { reference_sig.quote_header() },
            sig_count,
            reference_feed_infos,
            feed_count as u8,
            oracle_idxs,
            recent_slot,
            version,
            Some(data),
        ))
    }

    /// Loads and verifies an ED25519 instruction from the instructions sysvar with age validation.
    ///
    /// This method extracts instruction data from the instructions sysvar at the specified
    /// index, validates that it comes from the ED25519 program, checks the quote age against
    /// the current slot using the configured max_age, and then verifies the oracle quote data.
    ///
    /// # Arguments
    /// * `instruction_idx` - Index of the instruction to load from the sysvar (typically 0 for first instruction)
    ///
    /// # Returns
    /// * `Ok(OracleQuote)` - Successfully loaded and verified oracle quote
    /// * `Err(AnyError)` - Failed to load or verify the instruction
    ///
    /// # Errors
    /// - Instruction not found at the specified index
    /// - Instruction is not from the ED25519 program
    /// - Quote is too old (exceeds max_age slots)
    /// - Verification of the quote data fails
    #[inline(always)]
    pub fn load_and_verify(&self, instruction_idx: i64) -> Result<OracleQuote<'a>, AnyError> {
        use crate::Instructions;
        use solana_program::ed25519_program::ID as ED25519_PROGRAM_ID;
        use solana_program::sysvar::instructions::ID as INSTRUCTIONS_SYSVAR_ID;

        let ix_sysvar = self.ix_sysvar.ok_or_else(|| anyhow::anyhow!("Instructions sysvar not set"))?;
        let _clock = self.clock.ok_or_else(|| anyhow::anyhow!("Clock sysvar not set"))?;

        // Extract instruction data and validate program ID using the existing helper
        let (program_id, data) = Instructions::extract_ix_data(ix_sysvar, instruction_idx as usize)
            .map_err(|e| anyhow::anyhow!("Failed to extract instruction data: {:?}", e))?;

        // Validate accounts and program ID
        assert!(
            check_pubkey_eq(ix_sysvar.key, &INSTRUCTIONS_SYSVAR_ID) &&
            check_pubkey_eq(program_id, &ED25519_PROGRAM_ID)
        );

        // Verify the instruction data
        self.verify(data)
    }

    /// Finds and returns a specific slot hash from the slot hash sysvar.
    ///
    /// This function searches through the slot hash sysvar to find the hash
    /// corresponding to the target slot. It uses an optimized search starting
    /// from an estimated position and working backwards.
    ///
    /// # Arguments
    /// * `target_slot` - The slot number to find the hash for
    /// * `slothash_sysvar` - Reference to the slot hash sysvar account
    ///
    /// # Returns
    /// * `Ok([u8; 32])` - The 32-byte hash for the target slot
    /// * `Err(AnyError)` - Slot not found in the sysvar
    ///
    /// # Performance
    /// Uses an estimated starting position based on slot ordering to minimize
    /// the number of entries that need to be checked.
    fn find_slothash_in_sysvar(
        target_slot: u64,
        slothash_sysvar: &AccountInfo,
    ) -> Result<[u8; 32], AnyError> {
        let slothash_data = slothash_sysvar.data.borrow();

        // Verify sysvar has minimum required size for SlotHash array
        if slothash_data.len() < 8 {
            bail!("Slothash sysvar too small: {} bytes", slothash_data.len());
        }

        // # Safety
        //
        // This transmute is safe because:
        // - SlotHash is a POD type with known layout (u64 + [u8; 32])
        // - We skip the 8-byte sysvar header before transmuting
        // - The Solana runtime guarantees proper alignment and initialization of sysvar data
        // - The slice length is determined by the actual data size
        let slot_data: &[SlotHash] = unsafe { std::mem::transmute(&slothash_data[8..]) };

        let mut estimated_idx = ((slot_data[0].slot - target_slot) % SYSVAR_SLOT_LEN) as usize;

        // Optimized search with early termination
        loop {
            let slot_entry = &slot_data[estimated_idx];
            if slot_entry.slot == target_slot {
                return Ok(slot_entry.hash);
            }
            if estimated_idx == 0 {
                break;
            }
            estimated_idx -= 1;
        }
        bail!("Slot not found in slothash sysvar");
    }

}

/// Convenience function for extracting the most recent ED25519 instruction from the instructions sysvar.
///
/// This function retrieves the instruction immediately preceding the current one,
/// which should contain the ED25519 signature data. It handles the type coercion
/// from Anchor's Sysvar wrapper to AccountInfo for easier usage in programs.
///
/// # Arguments
/// * `ix_sysvar` - Reference to the instructions sysvar (can be wrapped in various types)
///
/// # Returns
/// * `Ok(Instruction)` - The ED25519 instruction with signature data
/// * `Err(ProgramError)` - Failed to retrieve the instruction
///
/// # Example
/// ```rust,ignore
/// let ed25519_ix = get_ed25519_instruction(&ctx.accounts.instructions)?;
/// // Process the instruction data...
/// ```
#[inline(always)]
pub fn get_ed25519_instruction<'a, T>(
    ix_sysvar: &T,
) -> Result<solana_program::instruction::Instruction, solana_program::program_error::ProgramError>
where
    T: AsRef<AccountInfo<'a>>,
{
    get_instruction_relative(-1, ix_sysvar.as_ref())
}