lib.rs

#![no_std]

#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;

extern crate alloc;

// ===== MODULE DECLARATIONS =====
// These must be declared here so Rust knows to compile them as part of this crate.


const SYM_ADMIN: &str = "Admin";
const SYM_PLATFORM_FEE: &str = "platform_fee";
const SYM_REMAINDER_RECIPIENT: &str = "remainder";
pub use config::PERCENTAGE_DENOMINATOR;
mod admin;
// #[cfg(any())]
// mod admin_auth_audit_tests;
// #[cfg(any())]
// mod error_code_tests;
pub mod analytics;
pub mod audit;
mod balances;
mod batch_operations;
mod bets;
pub mod circuit_breaker;
mod config;
pub mod err;
mod force_resolve;
mod event_archive;
mod restore_archive;
mod lifecycle_validation;
pub mod events;
pub mod gov_registry;
mod fees;
mod gas;
mod governance;
mod markets;
mod monitoring;
mod oracles;
mod reentrancy_guard;
mod oracle_health;
mod reporting;
// #[cfg(any())]
// mod reporting_tests;
// #[cfg(any())]
// mod state_snapshot_reporting_tests;
// #[cfg(any())]
// mod require_auth_coverage_tests;
#[cfg(test)]
mod resolution_event_ordering_tests;

#[cfg(test)]
#[path = "tests/oracle_validation_tests.rs"]
mod oracle_validation_tests;
mod resolution;
pub mod storage;
mod deprecated;
pub use deprecated::{DeprecatedEntry, DeprecatedRegistry, MAX_REGISTRY_ENTRIES};
#[cfg(test)]
mod deprecated_tests;
pub mod types;
mod upgrade_manager;
mod utils;
mod validation;
// mod validation_tests; // disabled - API drift
mod versioning;
mod voting;
mod market_analytics;
mod performance_benchmarks;
mod disputes;
mod edge_cases;
mod extensions;
mod graceful_degradation;
mod market_id_generator;
mod metadata_limits;
mod queries;
mod recovery;
mod statistics;
mod tokens;
mod rate_limiter;
mod dispute_multisig;
mod event_topic_catalog;
pub mod event_topic_compat;
mod storage_tier_audit;
mod leaderboard;
mod lists;
mod audit_trail;
mod monitor;
mod capabilities;

#[cfg(test)]
mod override_audit_tests;
#[cfg(test)]
mod market_audit_tests;
#[cfg(test)]
mod test_audit_trail;
#[cfg(test)]
mod event_topic_compat_tests;
// #[cfg(any())]
// mod utils_tests;
// THis is the band protocol wasm std_reference.wasm
mod bandprotocol {
    soroban_sdk::contractimport!(file = "./std_reference.wasm");
}

#[cfg(test)]
mod arithmetic_overflow_tests;

pub mod timelock;

// #[cfg(any())]
// mod circuit_breaker_tests;
// #[cfg(test)]
// mod oracle_fallback_timeout_tests;

use bets::BetStorage;
// `BetStatus` is available at the crate root via `pub use types::*` below.
use gas::BudgetGuard;
use resolution::ResolutionOutcomeCache;
use storage::BalanceStorage;
// `CircuitBreaker`, `Error`, `EventEmitter`, `ClaimInfo` and the soroban_sdk
// prelude items are imported/re-exported once below; duplicating them here
// tripped E0252 "defined multiple times".

// #[cfg(any())]
// mod integration_test;

// #[cfg(any())]
// mod recovery_tests;

// property_based_tests disabled: broader API drift; see dispute_outcome_tally_property_tests

// #[cfg(any())]
// mod upgrade_manager_tests;
// #[cfg(any())]
// mod upgrade_manager_tests;
// `capability_bitmap_tests.rs` does not exist in the tree; the capability
// bitmap is covered by the unit tests inside `capabilities.rs`.
#[cfg(test)]
mod market_state_matrix_tests;
#[cfg(test)]
mod timelock_tests;

// #[cfg(any())]
// mod query_tests;

// #[cfg(test)]
// mod bet_cancellation_tests;
// #[cfg(any())]
// mod bet_tests;
// #[cfg(any())]
// mod gas_test;
// #[cfg(any())]
// mod gas_test;
// #[cfg(any())]
// mod gas_tracking_tests;
// #[cfg(any())]
// mod claim_idempotency_tests;

#[cfg(test)]
mod gas_regression_tests;

// All test modules disabled due to API drift - re-enable after fixing
// #[cfg(test)]
// mod balance_tests;

// #[cfg(test)]
// mod event_management_tests;

#[cfg(test)]
mod governance_tests;

#[cfg(any())]
mod category_tags_tests;
#[cfg(test)]
mod tie_resolution_tests;
#[cfg(test)]
mod force_resolve_tests;
// #[cfg(any())]
// mod statistics_tests;

// #[cfg(any())]
// mod resolution_delay_dispute_window_tests;

#[cfg(test)]
mod analytics_snapshot_tests;
#[cfg(test)]
mod property_based_tests;
mod analytics_snapshot;

#[cfg(test)]
mod max_participants_tests;

// dispute_stake_tests.rs extended for #553; enable when legacy setup is updated:
// #[cfg(test)]
// #[path = "tests/dispute_stake_tests.rs"]
// mod dispute_stake_tests;

#[cfg(test)]
#[path = "tests/fee_config_commit_reveal_tests.rs"]
mod fee_config_commit_reveal_tests;

// #[cfg(test)]
// mod event_creation_tests;

#[cfg(test)]
mod voting_snapshot_stability_tests;

// Re-export commonly used items
use admin::{
    AdminAnalyticsResult, AdminFunctions, AdminInitializer, AdminManager, AdminPermission,
    AdminRole, AdminSystemIntegration,
};
pub use admin::Severity;
pub use err::Error;
use crate::storage::{
    check_market_creation_rent, check_market_creation_rent_budget, DataKey, MARKET_TTL_LEDGERS,
};
// Backwards-compatible re-export for existing module paths.
pub mod errors {
    pub use crate::err::*;
}
// pub use queries::QueryManager;
// pub use audit_trail::{AuditAction, AuditRecord, AuditTrailHead, AuditTrailManager};
pub use types::*;


use crate::config::{
    ConfigManager, DEFAULT_PLATFORM_FEE_PERCENTAGE, MAX_PLATFORM_FEE_PERCENTAGE,
    MIN_PLATFORM_FEE_PERCENTAGE,
};
use crate::gas::GasTracker;
use crate::graceful_degradation::{OracleBackup, OracleHealth};
use crate::market_id_generator::MarketIdGenerator;
use alloc::format;
use soroban_sdk::{
    contract, contracterror, contractimpl, contracttype, panic_with_error, symbol_short,
    Address, BytesN, Env, Map, String, Symbol, Vec,
};
use crate::circuit_breaker::CircuitBreaker;
use crate::events::EventEmitter;
use crate::audit_trail::{AuditTrailManager, AuditAction};

/// Stores a market in the persistent storage tier and explicitly extends its
/// TTL so active markets cannot expire silently. Emits a storage-tier audit event.
fn store_market_with_retention(env: &Env, market_id: &Symbol, market: &Market) {
    env.storage().persistent().set(market_id, market);
    env.storage()
        .persistent()
        .extend_ttl(market_id, MARKET_TTL_LEDGERS, MARKET_TTL_LEDGERS);
    env.events().publish(
        (
            symbol_short!("storage"),
            symbol_short!("persist"),
            Symbol::new(env, "market"),
        ),
        market_id.clone(),
    );
}

impl From<crate::reentrancy_guard::GuardError> for Error {
    fn from(_err: crate::reentrancy_guard::GuardError) -> Self {
        Error::InvalidState
    }
}

impl From<crate::rate_limiter::RateLimiterError> for Error {
    fn from(err: crate::rate_limiter::RateLimiterError) -> Self {
        match err {
            crate::rate_limiter::RateLimiterError::RateLimitExceeded => Error::RateLimitExceeded,
            crate::rate_limiter::RateLimiterError::ConfigNotFound => Error::ConfigNotFound,
            crate::rate_limiter::RateLimiterError::Unauthorized => Error::Unauthorized,
            _ => Error::RateLimitExceeded,
        }
    }
}

// Short symbol keys (max length 9 for Soroban compatibility). These consts were
// dropped in the e5db2d8 lib.rs collapse but are still referenced by the storage
// helpers below; restored here.
const SYM_ALLOWED_ASSETS: &str = "allowed"; // was "allowed_assets" (14 chars)

const ORACLE_FAILURE_PRIMARY_THEN_FALLBACK_REASON: &str =
    "Primary oracle failed, fallback also failed";
const ORACLE_FAILURE_PRIMARY_ONLY_REASON: &str =
    "Primary oracle failed and no fallback configured";

/// Returns `true` once a market has passed its `end_time + resolution_timeout`.
fn resolution_timeout_reached(env: &Env, market: &Market) -> bool {
    let current_time = env.ledger().timestamp();
    current_time >= market.end_time.saturating_add(market.resolution_timeout)
}

/// Probe an oracle for an automatic result; `Err(OracleUnavailable)` when inactive.
fn automatic_oracle_result_unavailable(
    env: &Env,
    config: &OracleConfig,
) -> Result<String, Error> {
    if !config.is_active() {
        return Err(Error::OracleUnavailable);
    }
    Ok(String::from_str(env, "pending"))
}

/// Probe an oracle for an automatic result; returns the raw oracle result string.
fn get_oracle_result(env: &Env, config: &OracleConfig) -> Result<String, Error> {
    automatic_oracle_result_unavailable(env, config)
}

#[contract]
pub struct PredictifyHybrid;

// ===== CONTRACT IMPLEMENTATION =====

#[contractimpl]
impl PredictifyHybrid {
    /// Initializes the contract: sets the primary admin, platform fee, default
    /// runtime configuration, circuit breaker, rate limiter, and allowed assets.
    ///
    /// # Parameters
    /// * `admin` - The primary administrator address.
    /// * `platform_fee_percentage` - Optional platform fee in basis points; defaults to 2%.
    /// * `allowed_assets` - Optional custom allow-list of deposit assets.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidState`] if already initialized, [`Error::InvalidFeeConfig`]
    /// if the fee is out of bounds, or any subsystem initialization error.
    pub fn initialize(
        env: Env,
        admin: Address,
        platform_fee_percentage: Option<i128>,
        allowed_assets: Option<Vec<Address>>,
    ) -> Result<(), Error> {
        // Check for re-initialization attempt (critical security check)
        if env
            .storage()
            .persistent()
            .has(&Symbol::new(&env, SYM_PLATFORM_FEE))
        {
            return Err(Error::InvalidState);
        }

        // Determine platform fee (default 2% if not specified)
        let fee_percentage = platform_fee_percentage.unwrap_or(DEFAULT_PLATFORM_FEE_PERCENTAGE);

        // Validate fee percentage bounds (0-10%)
        if fee_percentage < MIN_PLATFORM_FEE_PERCENTAGE
            || fee_percentage > MAX_PLATFORM_FEE_PERCENTAGE
        {
            return Err(Error::InvalidFeeConfig);
        }

        // Initialize admin (includes re-initialization check)
        AdminInitializer::initialize(&env, &admin)?;

        // Initialize circuit breaker defaults required by write-gated entrypoints.
        match crate::circuit_breaker::CircuitBreaker::initialize(&env) {
            Ok(_) => (),
            Err(e) => panic_with_error!(env, e),
        }

        // Store platform fee configuration in persistent storage
        env.storage()
            .persistent()
            .set(&Symbol::new(&env, SYM_PLATFORM_FEE), &fee_percentage);

        // Store the default remainder recipient (admin) so payout remainders
        // can be allocated to a specific address instead of being lost.
        env.storage()
            .persistent()
            .set(&Symbol::new(&env, SYM_REMAINDER_RECIPIENT), &admin);

        // Seed default runtime configuration so validators and query paths have
        // deterministic bounds immediately after deployment.
        let mut default_config = ConfigManager::get_development_config(&env);
        default_config.fees.platform_fee_percentage = fee_percentage;
        match ConfigManager::store_config(&env, &default_config) {
            Ok(_) => (),
            Err(e) => panic_with_error!(env, e),
        }

        // Seed default gas regression limits for critical-path operations.
        // These ensure create_market and claim_winnings are always bounded
        // even before an admin explicitly calls set_limit.
        GasTracker::set_default_limits(&env);

        // Seed default gas regression limits for critical-path operations.
        // These ensure create_market and claim_winnings are always bounded
        // even before an admin explicitly calls set_limit.
        GasTracker::set_default_limits(&env);

        // Seed permissive-but-valid rate limits so admin entrypoints do not
        // fail before a custom policy is configured.
        match crate::rate_limiter::RateLimiter::new(env.clone()).init_rate_limiter(
            admin.clone(),
            crate::rate_limiter::RateLimitConfig {
                voting_limit: 10_000,
                dispute_limit: 1_000,
                oracle_call_limit: 1_000,
                bet_limit: 10_000,
                events_per_admin_limit: 1_000,
                time_window_seconds: 3_600,
                refill_mode: crate::rate_limiter::RefillMode::Linear,
            },
        ) {
            Ok(_) => (),
            Err(e) => panic_with_error!(env, Error::from(e)),
        }

        // Initialize allowed assets
        if let Some(assets) = allowed_assets {
            env.storage()
                .persistent()
                .set(&Symbol::new(&env, SYM_ALLOWED_ASSETS), &assets);
        } else {
            crate::tokens::TokenRegistry::initialize_with_defaults(&env);
        }

        // Emit contract initialized and platform fee events
        EventEmitter::emit_contract_initialized(&env, &admin, fee_percentage);
        EventEmitter::emit_platform_fee_set(&env, fee_percentage, &admin);

        Ok(())
    }

    fn stored_primary_admin(env: &Env) -> Result<Address, Error> {
        env.storage()
            .persistent()
            .get(&Symbol::new(env, SYM_ADMIN))
            .ok_or(Error::AdminNotSet)
    }

    fn require_primary_admin(env: &Env, admin: &Address) -> Result<(), Error> {
        admin.require_auth();

        if &Self::stored_primary_admin(env)? != admin {
            return Err(Error::Unauthorized);
        }

        Ok(())
    }

    fn require_primary_admin_or_panic(env: &Env, admin: &Address) {
        if let Err(error) = Self::require_primary_admin(env, admin) {
            panic_with_error!(env, error);
        }
    }

    fn require_initialized_admin_root(env: &Env, admin: &Address) -> Result<(), Error> {
        admin.require_auth();
        let _ = Self::stored_primary_admin(env)?;
        Ok(())
    }

    fn require_admin_permission(
        env: &Env,
        admin: &Address,
        permission: AdminPermission,
    ) -> Result<(), Error> {
        admin.require_auth();

        let stored_admin = Self::stored_primary_admin(env)?;
        if &stored_admin == admin {
            return Ok(());
        }

        AdminSystemIntegration::validate_admin_unified(env, admin, permission)
    }

    /// Deposits funds into the user's balance.
    pub fn deposit(
        env: Env,
        user: Address,
        asset: ReflectorAsset,
        amount: i128,
    ) -> Result<Balance, Error> {
        crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "deposit")?;
        balances::BalanceManager::deposit(&env, user, asset, amount)
    }

    /// Withdraws funds from the user's balance.
    pub fn withdraw(
        env: Env,
        user: Address,
        asset: ReflectorAsset,
        amount: i128,
    ) -> Result<Balance, Error> {
        crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "withdraw")?;
        if !crate::circuit_breaker::CircuitBreaker::are_withdrawals_allowed(&env)? {
            return Err(Error::CBOpen);
        }
        balances::BalanceManager::withdraw(&env, user, asset, amount)
    }

    /// Gets the current balance of a user for a specific asset (read-only).
    pub fn get_balance(env: Env, user: Address, asset: ReflectorAsset) -> Balance {
        storage::BalanceStorage::get_balance(&env, &user, &asset)
    }

    /// Distribute payouts to winning voters and bettors for a resolved market.
    ///
    /// This function iterates over all voters and bettors, calculates each winner's
    /// proportional share of the total pool (after platform fee), credits their balance,
    /// and emits a winnings-claimed event. A `BudgetGuard` is checked every 10 iterations
    /// to abort gracefully before the host CPU-instruction limit is reached.
    ///
    /// # Parameters
    /// * `env`       - Soroban environment
    /// * `market_id` - Symbol identifying the resolved market
    ///
    /// # Returns
    ///
    /// Returns a unique `Symbol` that serves as the market identifier for all future operations.
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::InvalidQuestion` - Question is empty, whitespace-only, or outside the supported length bounds
    /// - `Error::InvalidOutcomes` - Outcomes violate count, emptiness, duplicate, or ambiguity rules
    /// - `Error::InvalidDuration` - Duration is outside the supported bounds
    /// - Storage operations fail
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, String, Vec};
    /// # use predictify_hybrid::{PredictifyHybrid, OracleConfig, OracleType};
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    ///
    /// let question = String::from_str(&env, "Will Bitcoin reach $100,000 by 2024?");
    /// let outcomes = vec![
    ///     String::from_str(&env, "Yes"),
    ///     String::from_str(&env, "No")
    /// ];
    /// let oracle_config = OracleConfig {
    ///     oracle_type: OracleType::Reflector,
    ///     oracle_contract: Address::generate(&env),
    ///     asset_code: Some(String::from_str(&env, "BTC")),
    ///     threshold_value: Some(100000),
    /// };
    ///
    /// let market_id = PredictifyHybrid::create_market(
    ///     env.clone(),
    ///     admin,
    ///     question,
    ///     outcomes,
    ///     30, // 30 days duration
    ///     oracle_config
    /// );
    /// ```
    ///
    /// # Multi-Outcome Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, String, Vec};
    /// # use predictify_hybrid::{PredictifyHybrid, OracleConfig, OracleProvider};
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    ///
    /// // Create a 3-outcome market (e.g., match result)
    /// let question = String::from_str(&env, "Match result?");
    /// let outcomes = vec![
    ///     &env,
    ///     String::from_str(&env, "Team A"),
    ///     String::from_str(&env, "Team B"),
    ///     String::from_str(&env, "Draw"),
    /// ];
    /// let oracle_config = OracleConfig::new(
    ///     OracleProvider::Reflector,
    ///     String::from_str(&env, "BTC/USD"),
    ///     50_000_00,
    ///     String::from_str(&env, "gt"),
    /// );
    ///
    /// let market_id = PredictifyHybrid::create_market(
    ///     env.clone(),
    ///     admin,
    ///     question,
    ///     outcomes,
    ///     30,
    ///     oracle_config
    /// );
    /// ```
    ///
    /// # Market State
    ///
    /// New markets are created in `MarketState::Active` state, allowing immediate voting.
    /// The market will automatically transition to `MarketState::Ended` when the duration expires.
    ///
    /// # Oracle Resolution Policy
    ///
    /// - `oracle_config` is always the first automatic oracle consulted after market end.
    /// - `fallback_oracle_config`, when present, is consulted only after one failed primary attempt.
    /// - `resolution_timeout` is enforced per market from `end_time`; automatic oracle resolution stops at
    ///   `end_time + resolution_timeout`.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn create_market(
        env: Env,
        admin: Address,
        question: String,
        outcomes: Vec<String>,
        duration_days: u32,
        oracle_config: OracleConfig,
        fallback_oracle_config: Option<OracleConfig>,
        resolution_timeout: u64,
        min_pool_size: Option<i128>,
        bet_deadline_mins_before_end: Option<u64>,
        dispute_window_seconds: Option<u64>,
        dispute_stake_floor: Option<i128>,
        max_participants: Option<u32>,
    ) -> Symbol {
        if let Err(e) =
            crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "create_market")
        {
            panic_with_error!(env, e);
        }
        let gas_marker = GasTracker::start_tracking(&env);
        Self::require_primary_admin_or_panic(&env, &admin);

        // Rate limit market creation to prevent abuse
        // ConfigNotFound means rate limiting is not configured — skip the check
        if let Err(rate_err) = crate::rate_limiter::RateLimiter::new(env.clone())
            .rate_limit_admin_events(admin.clone())
        {
            if !matches!(rate_err, crate::rate_limiter::RateLimiterError::ConfigNotFound) {
                panic_with_error!(env, Error::from(rate_err));
            }
        }

        if let Err(e) = crate::validation::CreationValidator::validate_market_creation(
            &env,
            &question,
            &outcomes,
            &duration_days,
        ) {
            panic_with_error!(env, e);
        }

        // Validate oracle configuration
        if let Err(e) = oracle_config.validate(&env) {
            panic_with_error!(env, e);
        }
        if let Some(ref fallback) = fallback_oracle_config {
            if let Err(e) = fallback.validate(&env) {
                panic_with_error!(env, e);
            }
        }

        // Validate duration is positive and within acceptable range
        if duration_days == 0 {
            panic_with_error!(env, Error::InvalidDuration);
        }

        // Generate a unique collision-resistant market ID
        let market_id = MarketIdGenerator::generate_market_id(&env, &admin);

        // Calculate end time
        let seconds_per_day: u64 = 24 * 60 * 60;
        let duration_seconds: u64 = (duration_days as u64) * seconds_per_day;
        let end_time: u64 = env.ledger().timestamp() + duration_seconds;

        // Calculate bet deadline
        let bet_deadline = match bet_deadline_mins_before_end {
            Some(mins) => end_time.saturating_sub(mins * 60),
            None => 0,
        };

        let (has_fallback, fallback_cfg) = match &fallback_oracle_config {
            Some(c) => (true, c.clone()),
            None => (false, OracleConfig::none_sentinel(&env)),
        };
        let metadata_commitment =
            Market::compute_metadata_commitment(&env, &question, &outcomes, &oracle_config);
        // Create a new market
        let market = Market {
            admin: admin.clone(),
            question: question.clone(),
            outcomes: outcomes.clone(),
            end_time,
            oracle_config,
            metadata_commitment,
            has_fallback,
            fallback_oracle_config: fallback_cfg,
            resolution_timeout,
            oracle_result: None,
            votes: Map::new(&env),
            total_staked: 0,
            dispute_stakes: Map::new(&env),
            stakes: Map::new(&env),
            claimed: Map::new(&env),
            winning_outcomes: None,
            fee_collected: false,
            state: MarketState::Active,
            total_extension_days: 0,
            max_extension_days: 30,
            extension_history: Vec::new(&env),
            category: None,
            tags: Vec::new(&env),
            min_pool_size,
            bet_deadline,
            dispute_window_seconds: dispute_window_seconds.unwrap_or(86400),
            winnings_swept: false,
            timelock_config: timelock::MarketTimelockConfig::default(),
            dispute_stake_floor,
            max_participants,
        };

        // Pre-flight checks: ensure sufficient storage rent budget.
        //
        // This entrypoint returns `Symbol` rather than `Result`, so a failed
        // check is surfaced as a panic. Callers using `try_create_market`
        // observe `Error::InsufficientStorageRent` or
        // `Error::InsufficientStorageRentBudget` respectively.
        //
        // The aggregate check runs second and covers all three persistent
        // entries this entrypoint writes: the market record below, the
        // platform statistics record via `record_market_created`, and the
        // audit trail record via `append_record`.
        if let Err(e) = check_market_creation_rent(&env) {
            panic_with_error!(env, e);
        }
        if let Err(e) = check_market_creation_rent_budget(&env) {
            panic_with_error!(env, e);
        }

        // Store the market
        store_market_with_retention(&env, &market_id, &market);

        // Emit events
        EventEmitter::emit_market_created(&env, &market_id, &question, &outcomes, &admin, end_time);

        // Record statistics
        statistics::StatisticsManager::record_market_created(&env);

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::MarketCreated,
            admin.clone(),
            Map::new(&env),
            None,
        );

        // Per-market audit entry: MarketCreated
        {
            let mut details = Map::new(&env);
            details.set(
                Symbol::new(&env, "question"),
                question.clone(),
            );
            details.set(
                Symbol::new(&env, "end_time"),
                String::from_str(&env, &alloc::format!("{}", end_time)),
            );
            details.set(
                Symbol::new(&env, "dur_days"),
                String::from_str(&env, &alloc::format!("{}", duration_days)),
            );
            crate::audit::MarketAuditManager::append(
                &env,
                &market_id,
                crate::audit::MarketAuditAction::MarketCreated,
                admin.clone(),
                details,
            );
        }

        GasTracker::end_tracking(&env, symbol_short!("create"), gas_marker);
        market_id
    }

    /// Creates a new prediction event with specified parameters.
    ///
    /// This function allows authorized admins to create prediction events
    /// with specific descriptions, possible outcomes, and end times. Unlike `create_market`,
    /// this function accepts an absolute Unix timestamp for the end time.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `admin` - The administrator address (must be authorized)
    /// * `description` - The event description or question
    /// * `outcomes` - Vector of possible outcomes
    /// * `end_time` - Absolute Unix timestamp for when the event ends
    /// * `oracle_config` - Primary oracle configuration for automatic resolution
    /// * `fallback_oracle_config` - Optional backup oracle attempted only after one failed primary attempt
    /// * `resolution_timeout` - Per-event oracle deadline in seconds, measured from `end_time`
    ///
    /// # Returns
    ///
    /// Returns a unique `Symbol` serving as the event identifier.
    ///
    /// # Panics
    ///
    /// Panics if:
    /// - Caller is not the contract admin
    /// - validation fails (invalid description, outcomes, or end time)
    /// - `resolution_timeout` falls outside the supported bounds
    ///
    /// # Validation Rules
    ///
    /// - `description` follows the same non-empty and length policy as market questions
    /// - `outcomes` follow the same count, non-empty, duplicate, and ambiguity rules as market creation
    /// - `end_time` must be strictly greater than the current ledger timestamp
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn create_event(
        env: Env,
        admin: Address,
        description: String,
        outcomes: Vec<String>,
        end_time: u64,
        oracle_config: OracleConfig,
        fallback_oracle_config: Option<OracleConfig>,
        resolution_timeout: u64,
        visibility: EventVisibility,
        idempotency_key: Option<BytesN<32>>,
    ) -> Symbol {
        if let Err(e) =
            crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "create_event")
        {
            panic_with_error!(env, e);
        }
        let gas_marker = GasTracker::start_tracking(&env);
        Self::require_primary_admin_or_panic(&env, &admin);

        // Rate limit event creation to prevent abuse
        if let Err(rate_err) = crate::rate_limiter::RateLimiter::new(env.clone())
            .rate_limit_admin_events(admin.clone())
        {
            if !matches!(rate_err, crate::rate_limiter::RateLimiterError::ConfigNotFound) {
                panic_with_error!(env, Error::from(rate_err));
            }
        }

        // Validate shared event-creation invariants before mutating state.
        if let Err(e) = crate::validation::CreationValidator::validate_event_creation(
            &env,
            &description,
            &outcomes,
            &end_time,
        ) {
            panic_with_error!(env, e);
        }

        if end_time <= env.ledger().timestamp() {
            panic_with_error!(env, Error::InvalidDuration);
        }

        // Validate oracle configuration
        if let Err(e) = oracle_config.validate(&env) {
            panic_with_error!(env, e);
        }
        if let Some(ref fallback) = fallback_oracle_config {
            if let Err(e) = fallback.validate(&env) {
                panic_with_error!(env, e);
            }
        }

        // ═══ IDEMPOTENCY CHECK (before any state mutations) ═══
        // If a caller provides an idempotency key, check if this request has already been processed.
        // This prevents duplicate event-creation fee charges on retry scenarios.
        if let Some(ref key) = idempotency_key {
            let idem_key = DataKey::CreateEventIdem(admin.clone(), key.clone());
            if let Some(cached_event_id) = env.storage().persistent().get::<_, Symbol>(&idem_key) {
                // Duplicate request: return the cached event ID with an idempotency error.
                // The caller receives a clear signal that this request was already processed.
                panic_with_error!(env, Error::IdempotentBatchAlreadyApplied);
            }
        }

        // Generate a unique collision-resistant event ID (reusing market ID generator)
        let event_id = MarketIdGenerator::generate_market_id(&env, &admin);

        let (has_fallback, fallback_cfg) = match &fallback_oracle_config {
            Some(c) => (true, c.clone()),
            None => (false, OracleConfig::none_sentinel(&env)),
        };

        // Charge creation fee after validation
        let creation_fee_amount = match crate::fees::FeeManager::process_creation_fee(&env, &admin) {
            Ok(fee) => fee,
            Err(e) => panic_with_error!(env, e),
        };

        // Create a new event
        let event = Event {
            id: event_id.clone(),
            description: description.clone(),
            outcomes: outcomes.clone(),
            end_time,
            oracle_config,
            has_fallback,
            fallback_oracle_config: fallback_cfg,
            resolution_timeout,
            admin: admin.clone(),
            created_at: env.ledger().timestamp(),
            status: MarketState::Active,
            visibility,
            allowlist: Vec::new(&env),
        };

        // ═══ FEE COLLECTION ═══
        // Charge event creation fee (same as market creation).
        // This happens AFTER idempotency check, so duplicates don't incur fees.
        if let Err(fee_err) = crate::fees::FeeManager::process_creation_fee(&env, &admin) {
            panic_with_error!(env, fee_err);
        }

        // Store the event
        crate::storage::EventManager::store_event(&env, &event);

        // ═══ STORE IDEMPOTENCY KEY ═══
        // Record that this request (admin, key) has been processed.
        // TTL: PLACE_BETS_IDEM_TTL_LEDGERS (~7 days), after which the key expires.
        if let Some(key) = idempotency_key {
            let idem_key = DataKey::CreateEventIdem(admin.clone(), key);
            env.storage()
                .persistent()
                .set(&idem_key, &event_id);
            env.storage().persistent().extend_ttl(
                &idem_key,
                crate::storage::PLACE_BETS_IDEM_TTL_LEDGERS,
                crate::storage::PLACE_BETS_IDEM_TTL_LEDGERS,
            );
        }

        // Emit event created event
        EventEmitter::emit_event_created(
            &env,
            &event_id,
            &description,
            &outcomes,
            &admin,
            end_time,
            creation_fee_amount,
        );

        // Record statistics
        statistics::StatisticsManager::record_market_created(&env);

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::EventCreated,
            admin.clone(),
            Map::new(&env),
            None,
        );

        GasTracker::end_tracking(&env, symbol_short!("evt_crt"), gas_marker);
        event_id
    }

    /// Retrieves an event by its unique identifier.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `event_id` - Unique identifier of the event to retrieve
    ///
    /// # Returns
    ///
    /// Returns `Some(Event)` if found, or `None` otherwise.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_event(env: Env, event_id: Symbol) -> Option<Event> {
        crate::storage::EventManager::get_event(&env, &event_id).ok()
    }

    /// Allows users to vote on a market outcome by staking tokens.
    ///
    /// This function enables users to participate in prediction markets by voting
    /// for their predicted outcome and staking tokens to back their prediction.
    /// Users can only vote once per market, and votes cannot be changed after submission.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `user` - The address of the user casting the vote (must be authenticated)
    /// * `market_id` - Unique identifier of the market to vote on
    /// * `outcome` - The outcome the user is voting for (must match a market outcome)
    /// * `stake` - Amount of tokens to stake on this prediction (in base token units)
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketClosed` - Market voting period has ended
    /// - `Error::InvalidOutcome` - Outcome doesn't match any market outcomes
    /// - `Error::AlreadyVoted` - User has already voted on this market
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, String, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Vote "Yes" with 1000 token units stake
    /// PredictifyHybrid::vote(
    ///     env.clone(),
    ///     user,
    ///     market_id,
    ///     String::from_str(&env, "Yes"),
    ///     1000
    /// );
    /// ```
    ///
    /// # Token Staking
    ///
    /// The stake amount represents the user's confidence in their prediction.
    /// Higher stakes increase potential rewards but also increase risk.
    /// Stakes are locked until market resolution and cannot be withdrawn early.
    ///
    /// # Market State Requirements
    ///
    /// - Market must be in `Active` state
    /// - Current time must be before market end time
    /// - Market must not be cancelled or resolved
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn vote(env: Env, user: Address, market_id: Symbol, outcome: String, stake: i128) {
        let gas_marker = GasTracker::start_tracking(&env);
        user.require_auth();

        // Rate limit voting to prevent abuse
        if let Err(rate_err) = crate::rate_limiter::RateLimiter::new(env.clone())
            .rate_limit_voting(user.clone(), market_id.clone())
        {
            if !matches!(rate_err, crate::rate_limiter::RateLimiterError::ConfigNotFound) {
                panic_with_error!(env, Error::from(rate_err));
            }
        }

        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| {
                panic_with_error!(env, Error::MarketNotFound);
            });

        // Check if the market is still active
        if market.state != MarketState::Active {
            panic_with_error!(env, Error::InvalidState);
        }

        // Respect bet_deadline if set, otherwise use end_time
        let cutoff = if market.bet_deadline > 0 {
            market.bet_deadline
        } else {
            market.end_time
        };
        if env.ledger().timestamp() >= cutoff {
            panic_with_error!(env, Error::MarketClosed);
        }

        // Validate outcome
        let outcome_exists = market.outcomes.iter().any(|o| o == outcome);
        if !outcome_exists {
            panic_with_error!(env, Error::InvalidOutcome);
        }

        // Check if user already voted
        if market.votes.get(user.clone()).is_some() {
            panic_with_error!(env, Error::AlreadyVoted);
        }

        // Check participant cap
        if let Some(max) = market.max_participants {
            if market.votes.len() >= max {
                panic_with_error!(env, Error::MaxParticipantsReached);
            }
        }

        // Lock funds (transfer from user to contract)
        match bets::BetUtils::lock_funds(&env, &user, stake) {
            Ok(_) => {}
            Err(e) => panic_with_error!(env, e),
        }

        // Store the vote and stake
        market.votes.set(user.clone(), outcome.clone());
        market.stakes.set(user.clone(), stake);
        market.total_staked += stake;

        store_market_with_retention(&env, &market_id, &market);

        // Invalidate analytics cache so next read recomputes fresh stats.
        analytics::AnalyticsCache::new(&env).invalidate(&market_id);

        // Emit vote cast event
        EventEmitter::emit_vote_cast(&env, &market_id, &user, &outcome, stake);

        GasTracker::end_tracking(&env, symbol_short!("vote"), gas_marker);
    }

    /// Places a bet on a prediction market event by locking user funds.
    ///
    /// This function enables users to place bets on active prediction markets,
    /// selecting an outcome they predict will occur and locking funds as their wager.
    /// Bets are distinct from votes - bets represent financial wagers while votes
    /// participate in community resolution consensus.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `user` - The address of the user placing the bet (must be authenticated)
    /// * `market_id` - Unique identifier of the market to bet on
    /// * `outcome` - The outcome the user predicts will occur
    /// * `amount` - Amount of tokens to lock for this bet (in base token units)
    ///
    /// # Returns
    ///
    /// Returns the created `Bet` struct containing bet details on success.
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketClosed` - Market betting period has ended or market is not active
    /// - `Error::MarketResolved` - Market has already been resolved
    /// - `Error::InvalidOutcome` - Outcome doesn't match any market outcomes
    /// - `Error::AlreadyBet` - User has already placed a bet on this market
    /// - `Error::InsufficientStake` - Bet amount is below minimum (0.1 XLM)
    /// - `Error::InvalidInput` - Bet amount exceeds maximum (10,000 XLM)
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, String, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "btc_50k");
    ///
    /// // Place a bet of 1 XLM on "Yes" outcome
    /// let bet = PredictifyHybrid::place_bet(
    ///     env.clone(),
    ///     user,
    ///     market_id,
    ///     String::from_str(&env, "Yes"),
    ///     10_000_000 // 1.0 XLM in stroops
    /// );
    /// ```
    ///
    /// # Fund Locking
    ///
    /// When a bet is placed:
    /// 1. User's funds (XLM or Stellar tokens) are transferred to the contract
    /// 2. Funds remain locked until market resolution
    /// 3. Upon resolution:
    ///    - Winners receive proportional share of total bet pool (minus fees)
    ///    - Losers forfeit their locked funds
    ///    - Refunds issued if market is cancelled
    ///
    /// # Double Betting Prevention
    ///
    /// Users can only place ONE bet per market. Attempting to bet again will
    /// result in an `Error::AlreadyBet` error. This ensures fair distribution
    /// of rewards and prevents manipulation.
    ///
    /// # Market State Requirements
    ///
    /// - Market must be in `Active` state
    /// - Current time must be before market end time
    /// - Market must not be resolved or cancelled
    ///
    /// # Security
    ///
    /// - User authentication via `require_auth()`
    /// - Balance validation before fund transfer
    /// - Atomic fund locking with bet creation
    /// - Reentrancy protection via reentrancy guard (guard flag in storage)
    /// Places a bet on a specific outcome in a prediction market.
    ///
    /// This function allows users to place bets on markets with 2 or more outcomes.
    /// The outcome must be one of the valid outcomes defined when the market was created.
    /// Users can only place one bet per market.
    ///
    /// # Multi-Outcome Support
    ///
    /// - Validates that the selected outcome exists in the market's outcome list
    /// - Works with binary (2 outcomes) and multi-outcome (N outcomes) markets
    /// - Rejects invalid outcomes that don't match any market outcome
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `user` - The address of the user placing the bet (must be authenticated)
    /// * `market_id` - Unique identifier of the market to bet on
    /// * `outcome` - The outcome to bet on (must match one of the market's outcomes)
    /// * `amount` - Amount of tokens to bet (must meet minimum/maximum bet limits)
    ///
    /// # Returns
    ///
    /// Returns the created `Bet` struct containing bet details.
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketClosed` - Market is not active or has ended
    /// - `Error::InvalidOutcome` - Outcome doesn't match any market outcomes
    /// - `Error::AlreadyBet` - User has already placed a bet on this market
    /// - `Error::InsufficientStake` - Bet amount is below minimum
    /// - `Error::InvalidInput` - Bet amount exceeds maximum
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol, String};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Place bet on "Team A" outcome
    /// let bet = PredictifyHybrid::place_bet(
    ///     env.clone(),
    ///     user,
    ///     market_id,
    ///     String::from_str(&env, "Team A"),
    ///     10_0000000, // 10 XLM
    /// );
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn place_bet(
        env: Env,
        user: Address,
        market_id: Symbol,
        outcome: String,
        amount: i128,
        max_fee_bps: i128,
    ) -> crate::types::Bet {
        if let Err(e) =
            crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "betting")
        {
            panic_with_error!(env, e);
        }
        // Use the BetManager to handle the bet placement
        match bets::BetManager::place_bet(&env, user.clone(), market_id.clone(), outcome, amount, max_fee_bps) {
            Ok(bet) => {
                // Record statistics
                statistics::StatisticsManager::record_bet_placed(&env, &user, amount);
                // Invalidate analytics cache — staked amounts have changed.
                analytics::AnalyticsCache::new(&env).invalidate(&market_id);
                bet
            }
            Err(e) => panic_with_error!(env, e),
        }
    }

    /// Places multiple bets in a single atomic transaction.
    ///
    /// This function enables users to place multiple bets across different markets
    /// or outcomes in a single transaction, providing gas efficiency and atomicity.
    /// All bets must succeed or the entire transaction reverts.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `user` - The address of the user placing the bets (must be authenticated)
    /// * `bets` - Vector of tuples containing (market_id, outcome, amount) for each bet
    ///
    /// # Returns
    ///
    /// Returns a `Vec<Bet>` containing all successfully placed bets.
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - Any bet fails validation (market not found, closed, invalid outcome, etc.)
    /// - User has insufficient balance for the total amount
    /// - User has already bet on any of the markets
    /// - Any bet amount is below minimum or above maximum
    /// - The batch is empty or exceeds maximum batch size
    ///
    /// # Atomicity
    ///
    /// All bets are validated before any funds are locked. If any single bet
    /// fails validation, the entire transaction reverts with no state changes.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, String, Symbol, Vec};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    ///
    /// let bets = vec![
    ///     &env,
    ///     (
    ///         Symbol::new(&env, "btc_100k"),
    ///         String::from_str(&env, "yes"),
    ///         10_000_000i128  // 1.0 XLM
    ///     ),
    ///     (
    ///         Symbol::new(&env, "eth_5k"),
    ///         String::from_str(&env, "no"),
    ///         5_000_000i128   // 0.5 XLM
    ///     ),
    /// ];
    ///
    /// let placed_bets = PredictifyHybrid::place_bets(env.clone(), user, bets);
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn place_bets(
        env: Env,
        user: Address,
        bets: Vec<(Symbol, String, i128)>,
        max_fee_bps: i128,
        idempotency_key: soroban_sdk::BytesN<32>,
    ) -> Vec<crate::types::Bet> {
        if let Err(e) =
            crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "betting")
        {
            panic_with_error!(env, e);
        }
        match bets::BetManager::place_bets(&env, user, bets.clone(), max_fee_bps, idempotency_key) {
            Ok(placed_bets) => {
                // Invalidate analytics cache for every market touched by this batch.
                let cache = analytics::AnalyticsCache::new(&env);
                for (market_id, _, _) in bets.iter() {
                    cache.invalidate(&market_id);
                }
                placed_bets
            }
            Err(e) => panic_with_error!(env, e),
        }
    }

    /// Retrieves a user's bet on a specific market.
    ///
    /// This function provides read-only access to a user's bet details including
    /// the selected outcome, locked amount, and bet status.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market
    /// * `user` - Address of the user whose bet to retrieve
    ///
    /// # Returns
    ///
    /// Returns `Some(Bet)` if the user has placed a bet on this market,
    /// `None` if no bet exists.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "btc_50k");
    ///
    /// match PredictifyHybrid::get_bet(env.clone(), market_id, user) {
    ///     Some(bet) => {
    ///         // User has a bet
    ///         println!("Bet amount: {}", bet.amount);
    ///         println!("Selected outcome: {:?}", bet.outcome);
    ///         println!("Status: {:?}", bet.status);
    ///     },
    ///     None => {
    ///         // User has not placed a bet on this market
    ///     }
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_bet(env: Env, market_id: Symbol, user: Address) -> Option<crate::types::Bet> {
        bets::BetManager::get_bet(&env, &market_id, &user)
    }

    /// Checks if a user has already placed a bet on a specific market.
    ///
    /// This function provides a quick check to determine if a user has
    /// an existing bet on a market before attempting to place a new bet.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market
    /// * `user` - Address of the user to check
    ///
    /// # Returns
    ///
    /// Returns `true` if the user has already placed a bet, `false` otherwise.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "btc_50k");
    ///
    /// if PredictifyHybrid::has_user_bet(env.clone(), market_id.clone(), user.clone()) {
    ///     println!("User has already placed a bet on this market");
    /// } else {
    ///     println!("User can place a bet");
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn has_user_bet(env: Env, market_id: Symbol, user: Address) -> bool {
        bets::BetManager::has_user_bet(&env, &market_id, &user)
    }

    /// Retrieves betting statistics for a specific market.
    ///
    /// This function provides aggregate information about betting activity
    /// on a market, including total bets, locked amounts, and per-outcome totals.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market
    ///
    /// # Returns
    ///
    /// Returns `BetStats` with comprehensive betting statistics.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "btc_50k");
    ///
    /// let stats = PredictifyHybrid::get_market_bet_stats(env.clone(), market_id);
    /// println!("Total bets: {}", stats.total_bets);
    /// println!("Total locked: {} stroops", stats.total_amount_locked);
    /// println!("Unique bettors: {}", stats.unique_bettors);
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_market_bet_stats(env: Env, market_id: Symbol) -> crate::types::BetStats {
        bets::BetManager::get_market_bet_stats(&env, &market_id)
    }

    /// Cancels an active bet and refunds the user.
    ///
    /// This function allows users to cancel their active bets before the market
    /// deadline, receiving a full refund of their locked funds.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `user` - Address of the user cancelling the bet
    /// * `market_id` - Symbol identifying the market
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on successful cancellation and refund,
    /// or `Err(Error)` if cancellation fails.
    ///
    /// # Errors
    ///
    /// - `Error::NothingToClaim` - User has no bet on this market
    /// - `Error::MarketNotFound` - Market does not exist
    /// - `Error::MarketClosed` - Market deadline has passed
    /// - `Error::InvalidState` - Bet is not in Active status
    pub fn cancel_bet(env: Env, user: Address, market_id: Symbol) -> Result<(), Error> {
        bets::BetManager::cancel_bet(&env, user, market_id)
    }

    /// Calculate the payout amount for a user's bet on a resolved market.
    ///
    /// This function calculates how much a user will receive if they won their bet.
    /// For multi-outcome markets with ties, the payout is calculated based on
    /// the proportional share of the total pool split among all winners.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market
    /// * `user` - Address of the user to calculate payout for
    ///
    /// # Returns
    ///
    /// Returns `Ok(i128)` with the payout amount in base token units, or `Err(Error)` if calculation fails.
    /// Returns `Ok(0)` if the user didn't win or has no bet.
    ///
    /// # Errors
    ///
    /// - `Error::MarketNotFound` - Market doesn't exist
    /// - `Error::MarketNotResolved` - Market hasn't been resolved yet
    /// - `Error::NothingToClaim` - User has no bet on this market
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "resolved_market");
    /// # let user = Address::generate(&env);
    ///
    /// match PredictifyHybrid::calculate_bet_payout(env.clone(), market_id, user) {
    ///     Ok(payout) => println!("User will receive {} stroops", payout),
    ///     Err(e) => println!("Calculation failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Payout Calculation for Ties
    ///
    /// When multiple outcomes win (tie):
    /// - Total pool is split proportionally among all winners
    /// - Each winner's payout = (their_stake / total_winning_stakes) * total_pool * (1 - fee)
    /// - This ensures fair distribution even when outcomes are tied
    /// Calculates the payout amount for a user's bet on a resolved market.
    ///
    /// This function computes the payout based on:
    /// - Whether the user's bet outcome is a winning outcome
    /// - The user's stake relative to total winning stakes
    /// - The total pool size
    /// - Platform fees
    ///
    /// # Multi-Outcome Support
    ///
    /// For markets with multiple winning outcomes (ties):
    /// - Payouts are calculated proportionally across all winning outcomes
    /// - Total winning stakes = sum of all stakes on all winning outcomes
    /// - User's share = (user_stake / total_winning_stakes) * total_pool * (1 - fee)
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market
    /// * `user` - Address of the user whose payout to calculate
    ///
    /// # Returns
    ///
    /// Returns `Ok(i128)` with the payout amount in base token units if:
    /// - Market is resolved
    /// - User placed a bet
    /// - User's outcome is a winning outcome
    ///
    /// Returns `Err(Error)` if:
    /// - Market is not resolved
    /// - User has no bet
    /// - User's outcome did not win
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Calculate payout for user's winning bet
    /// match PredictifyHybrid::calculate_bet_payout(env.clone(), market_id, user) {
    ///     Ok(payout) => println!("Payout: {}", payout),
    ///     Err(e) => println!("Error: {:?}", e),
    /// }
    /// ```
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn calculate_bet_payout(env: Env, market_id: Symbol, user: Address) -> Result<i128, Error> {
        bets::BetManager::calculate_bet_payout(&env, &market_id, &user)
    }

    /// Calculates the implied probability for an outcome based on bet distribution.
    ///
    /// The implied probability indicates the market's collective prediction for
    /// an outcome based on the distribution of bets.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `market_id` - Unique identifier of the market
    /// * `outcome` - The outcome to calculate probability for
    ///
    /// # Returns
    ///
    /// Returns the implied probability as a percentage (0-100).
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol, String};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "btc_50k");
    ///
    /// let prob = PredictifyHybrid::get_implied_probability(
    ///     env.clone(),
    ///     market_id,
    ///     String::from_str(&env, "Yes")
    /// );
    /// println!("Implied probability for 'Yes': {}%", prob);
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_implied_probability(env: Env, market_id: Symbol, outcome: String) -> i128 {
        bets::BetAnalytics::calculate_implied_probability(&env, &market_id, &outcome)
    }

    /// Calculates the potential payout multiplier for an outcome.
    ///
    /// The multiplier indicates how much a bet would pay out relative to
    /// the bet amount if the selected outcome wins.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `market_id` - Unique identifier of the market
    /// * `outcome` - The outcome to calculate multiplier for
    ///
    /// # Returns
    ///
    /// Returns the payout multiplier scaled by 100 (e.g., 250 = 2.5x).
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol, String};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "btc_50k");
    ///
    /// let multiplier = PredictifyHybrid::get_payout_multiplier(
    ///     env.clone(),
    ///     market_id,
    ///     String::from_str(&env, "Yes")
    /// );
    /// let actual_multiplier = multiplier as f64 / 100.0;
    /// println!("Payout multiplier for 'Yes': {:.2}x", actual_multiplier);
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_payout_multiplier(env: Env, market_id: Symbol, outcome: String) -> i128 {
        bets::BetAnalytics::calculate_payout_multiplier(&env, &market_id, &outcome)
    }

    /// Allows users to claim their winnings from resolved prediction markets.
    ///
    /// This function enables users who voted for the winning outcome to claim
    /// their proportional share of the total market pool, minus platform fees.
    /// Users can only claim once per market, and only after the market is resolved.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `user` - The address of the user claiming winnings (must be authenticated)
    /// * `market_id` - Unique identifier of the resolved market
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::AlreadyClaimed` - User has already claimed winnings from this market
    /// - `Error::MarketNotResolved` - Market hasn't been resolved yet
    /// - `Error::NothingToClaim` - User didn't vote or voted for losing outcome
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let user = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "resolved_market");
    ///
    /// // Claim winnings from a resolved market
    /// PredictifyHybrid::claim_winnings(
    ///     env.clone(),
    ///     user,
    ///     market_id
    /// );
    /// ```
    ///
    /// # Payout Calculation
    ///
    /// Winnings are calculated using the formula:
    /// ```text
    /// user_payout = (user_stake * (100 - fee_percentage) / 100) * total_pool / winning_total
    /// ```
    ///
    /// Where:
    /// - `user_stake` - Amount the user staked on the winning outcome
    /// - `fee_percentage` - Platform fee (currently 2%)
    /// - `total_pool` - Sum of all stakes in the market
    /// - `winning_total` - Sum of stakes on the winning outcome
    ///
    /// # Market State Requirements
    ///
    /// - Market must be in `Resolved` state with a winning outcome set
    /// - User must have voted for the winning outcome
    /// - User must not have previously claimed winnings
    ///
    /// # Security & Testing
    ///
    /// - Fuzzed against state duplication where claiming double results in an explicit abort/fail.
    /// - Ensures payout formula distributes properly without rounding vulnerabilities.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    ///
    /// # Replay Protection
    ///
    /// This function uses a monotonically-increasing per-user, per-market nonce to prevent
    /// transaction replays. The caller must provide the `claim_nonce` parameter, which should
    /// match the current stored nonce for the (user, market_id) pair. After a successful claim,
    /// the nonce is incremented by 1, making any replay of the original transaction invalid.
    ///
    /// # Parameters
    ///
    /// - `user` - The user claiming their winnings
    /// - `market_id` - The market to claim from
    /// - `claim_nonce` - The unique nonce for this claim operation. Must match the current
    ///   stored nonce to pass validation. On first claim, this should be 0.
    pub fn claim_winnings(env: Env, user: Address, market_id: Symbol, claim_nonce: u64) {
        if let Err(e) =
            crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "claim_winnings")
        {
            panic_with_error!(env, e);
        }
        user.require_auth();
        let gas_marker = GasTracker::start_tracking(&env);

        // ===== REPLAY PROTECTION: VALIDATE NONCE =====
        // Ensure the provided nonce matches the expected nonce to prevent replays.
        // Each successful claim increments the stored nonce by 1.
        if let Err(e) = storage::ClaimNonceManager::validate_nonce(&env, &user, &market_id, claim_nonce) {
            panic_with_error!(env, e);
        }

        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| {
                panic_with_error!(env, Error::MarketNotFound);
            });

        // Check if user has claimed already (redundant safety check; nonce validation should prevent)
        if market
            .claimed
            .get(user.clone())
            .map(|info| info.is_claimed())
            .unwrap_or(false)
        {
            panic_with_error!(env, Error::AlreadyClaimed);
        }

        // Check if market is resolved
        let winning_outcomes = match &market.winning_outcomes {
            Some(outcomes) => outcomes,
            None => panic_with_error!(env, Error::MarketNotResolved),
        };

        // Enforce dispute window: payouts only after end_time + dispute_window_seconds
        if market.dispute_window_seconds > 0
            && env.ledger().timestamp() < market.end_time + market.dispute_window_seconds
        {
            panic_with_error!(env, Error::InvalidState);
        }

        // Get user's vote
        let user_outcome = market
            .votes
            .get(user.clone())
            .unwrap_or_else(|| panic_with_error!(env, Error::NothingToClaim));

        let user_stake = market.stakes.get(user.clone()).unwrap_or(0);

        // Calculate payout if user won (check if outcome is in winning outcomes)
        if winning_outcomes.contains(&user_outcome) {
            let summary = resolution::ResolutionOutcomeCache::require(&env, &market_id, &market)
                .unwrap_or_else(|e| panic_with_error!(env, e));
            let winning_total = summary.winning_total;

            if winning_total > 0 {
                // Retrieve dynamic platform fee percentage from configuration
                let cfg = match crate::config::ConfigManager::get_config(&env) {
                    Ok(c) => c,
                    Err(_) => panic_with_error!(env, Error::ConfigNotFound),
                };
                let fee_percent = cfg.fees.platform_fee_percentage;
                let user_share = (user_stake
                    .checked_mul(PERCENTAGE_DENOMINATOR as i128 - fee_percent as i128)
                    .unwrap_or_else(|| panic_with_error!(env, Error::InvalidInput)))
                    / (PERCENTAGE_DENOMINATOR as i128);
                let total_pool = summary.total_pool;
                let product = user_share
                    .checked_mul(total_pool)
                    .unwrap_or_else(|| panic_with_error!(env, Error::InvalidInput));
                let payout = product / winning_total;

                // Calculate fee amount for statistics
                // Payout is net of fee. Fee was deducted in user_share calculation.
                // Gross payout would be (user_stake * total_pool) / winning_total
                // Logic check:
                // user_share = user_stake * (1 - fee)
                // payout = user_share * pool / winning_total
                // payout = user_stake * (1-fee) * pool / winning_total
                // payout = (user_stake * pool / winning_total) - (user_stake * pool / winning_total * fee)
                // So Fee = (user_stake * pool / winning_total) * fee
                // Or Fee = Payout / (1 - fee) * fee ? No, division precision.
                // Simpler: Fee = (Payout * fee_percent) / (100 - fee_percent)?
                // Let's rely on explicit calculation if possible or approximation.
                // Actually, let's re-calculate gross to get fee.
                // Gross = (user_stake * total_pool) / winning_total.
                // Fee = Gross - Payout.

                let gross_share = (user_stake
                    .checked_mul(PERCENTAGE_DENOMINATOR)
                    .unwrap_or_else(|| panic_with_error!(env, Error::InvalidInput)))
                    / (PERCENTAGE_DENOMINATOR as i128);
                // Wait, user_stake * 100 / 100 = user_stake.
                // The math above used PERCENTAGE_DENOMINATOR (100).

                let product_gross = user_stake
                    .checked_mul(total_pool)
                    .unwrap_or_else(|| panic_with_error!(env, Error::InvalidInput));
                let gross_payout = product_gross / winning_total;
                let fee_amount = gross_payout - payout;

                statistics::StatisticsManager::record_winnings_claimed(&env, &user, payout);
                statistics::StatisticsManager::record_fees_collected(&env, fee_amount);

                // ===== INCREMENT NONCE ON SUCCESSFUL CLAIM =====
                // Increment and store the nonce to prevent replays of this specific claim.
                let new_nonce = storage::ClaimNonceManager::increment_nonce(&env, &user, &market_id);

                // Mark as claimed with the new nonce
                market
                    .claimed
                    .set(user.clone(), ClaimInfo::new(&env, payout, new_nonce));
                store_market_with_retention(&env, &market_id, &market);

                // Invalidate analytics cache — claimed map has changed.
                analytics::AnalyticsCache::new(&env).invalidate(&market_id);

                // Emit winnings claimed event
                EventEmitter::emit_winnings_claimed(&env, &market_id, &user, payout);

                // Credit tokens to user balance
                match storage::BalanceStorage::add_balance(
                    &env,
                    &user,
                    &types::ReflectorAsset::Stellar,
                    payout,
                ) {
                    Ok(_) => {}
                    Err(e) => panic_with_error!(env, e),
                }

                GasTracker::end_tracking(&env, symbol_short!("claim"), gas_marker);
                return;
            }
        }

        // ===== INCREMENT NONCE EVEN FOR ZERO PAYOUTS =====
        // If no winnings (user didn't win or zero payout), still increment nonce to prevent re-attempts.
        let new_nonce = storage::ClaimNonceManager::increment_nonce(&env, &user, &market_id);
        market.claimed.set(user.clone(), ClaimInfo::new(&env, 0, new_nonce));
        store_market_with_retention(&env, &market_id, &market);
        analytics::AnalyticsCache::new(&env).invalidate(&market_id);
        GasTracker::end_tracking(&env, symbol_short!("claim"), gas_marker);
    }

    /// Set the global claim period for resolved markets (admin only).
    ///
    /// Claims are allowed until `market.end_time + claim_period_seconds` unless overridden
    /// per market. After expiry, claims revert with `Error::ResolutionTimeoutReached`.
    /// Set governance-controlled minimum bet size in basis points of the market token.
    /// admin-only. 1 bps = 0.01%. Stored as a u32 (0..=10000).
    pub fn set_governance_min_bet_bps(env: Env, admin: Address, min_bet_bps: u32) {
        admin.require_auth();
        if min_bet_bps > 10_000 {
            panic_with_error!(env, Error::InvalidInput);
        }
        let stored_admin: Address = env
            .storage()
            .persistent()
            .get(&Symbol::new(&env, SYM_ADMIN))
            .unwrap_or_else(|| panic_with_error!(env, Error::AdminNotSet));
        if admin != stored_admin {
            panic_with_error!(env, Error::Unauthorized);
        }
        env.storage()
            .instance()
            .set(&Symbol::new(&env, "gov_min_bps"), &min_bet_bps);
    }

    /// Get the governance-set minimum bet bps (0 = not set).
    pub fn get_governance_min_bet_bps(env: Env) -> u32 {
        env.storage()
            .instance()
            .get(&Symbol::new(&env, "gov_min_bps"))
            .unwrap_or(0u32)
    }

    pub fn set_global_claim_period(env: Env, admin: Address, claim_period_seconds: u64) {
        admin.require_auth();

        if claim_period_seconds == 0 {
            panic_with_error!(env, Error::InvalidInput);
        }

        let stored_admin: Address = env
            .storage()
            .persistent()
            .get(&Symbol::new(&env, SYM_ADMIN))
            .unwrap_or_else(|| panic_with_error!(env, Error::AdminNotSet));

        if admin != stored_admin {
            panic_with_error!(env, Error::Unauthorized);
        }

        recovery::UnclaimedWinningsPolicy::set_global_claim_period(&env, claim_period_seconds);
        EventEmitter::emit_claim_period_updated(&env, &admin, claim_period_seconds);
    }

    /// Set a market-specific claim period override (admin only).
    ///
    /// The market-specific value overrides the global claim period for the given market.
    pub fn set_market_claim_period(
        env: Env,
        admin: Address,
        market_id: Symbol,
        claim_period_seconds: u64,
    ) {
        admin.require_auth();

        if claim_period_seconds == 0 {
            panic_with_error!(env, Error::InvalidInput);
        }

        let stored_admin: Address = env
            .storage()
            .persistent()
            .get(&Symbol::new(&env, SYM_ADMIN))
            .unwrap_or_else(|| panic_with_error!(env, Error::AdminNotSet));

        if admin != stored_admin {
            panic_with_error!(env, Error::Unauthorized);
        }

        if markets::MarketStateManager::get_market(&env, &market_id).is_err() {
            panic_with_error!(env, Error::MarketNotFound);
        }

        recovery::UnclaimedWinningsPolicy::set_market_claim_period(
            &env,
            &market_id,
            claim_period_seconds,
        );
        EventEmitter::emit_market_claim_period_updated(
            &env,
            &admin,
            &market_id,
            claim_period_seconds,
        );
    }

    /// Set treasury recipient for unclaimed winnings sweeps (admin only).
    ///
    /// **Deprecated**: This function now queues a timelocked treasury update
    /// instead of applying it immediately. Use `queue_treasury_update`,
    /// `apply_treasury_update`, and `cancel_treasury_update` for the full
    /// queue→apply→cancel lifecycle.
    ///
    /// The treasury address will only change after the configured timelock
    /// period has elapsed (default: 24 hours).
    pub fn set_treasury(env: Env, admin: Address, treasury: Address) {
        admin.require_auth();

        let stored_admin: Address = env
            .storage()
            .persistent()
            .get(&Symbol::new(&env, SYM_ADMIN))
            .unwrap_or_else(|| panic_with_error!(env, Error::AdminNotSet));

        if admin != stored_admin {
            panic_with_error!(env, Error::Unauthorized);
        }

        // Route through the timelocked path to prevent instant rotation
        match recovery::TreasuryTimelockManager::queue_update(&env, &admin, &treasury) {
            Ok(()) => {}
            Err(Error::PendingTreasuryUpdateExists) => {
                // Cancel the old one and queue the new one
                let _ = recovery::TreasuryTimelockManager::cancel_update(&env, &admin);
                recovery::TreasuryTimelockManager::queue_update(&env, &admin, &treasury)
                    .unwrap_or_else(|e| panic_with_error!(env, e));
            }
            Err(e) => panic_with_error!(env, e),
        }
    }

    /// Queue a treasury update for future activation (admin only).
    ///
    /// The treasury address will only change after the configured timelock
    /// period (default: 24 hours) has elapsed. This prevents surprise
    /// fee-recipient rotation.
    pub fn queue_treasury_update(
        env: Env,
        admin: Address,
        new_treasury: Address,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        recovery::TreasuryTimelockManager::queue_update(&env, &admin, &new_treasury)
    }

    /// Apply the queued treasury update after the timelock has expired.
    ///
    /// Can be called by the admin once the timelock period has elapsed.
    pub fn apply_treasury_update(env: Env, admin: Address) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        recovery::TreasuryTimelockManager::apply_update(&env, &admin)
    }

    /// Cancel a pending treasury update before the timelock expires (admin only).
    pub fn cancel_treasury_update(env: Env, admin: Address) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        recovery::TreasuryTimelockManager::cancel_update(&env, &admin)
    }

    /// Get the pending treasury update, if any (read-only query).
    pub fn get_pending_treasury_update(env: Env) -> Option<recovery::PendingTreasuryUpdate> {
        recovery::TreasuryTimelockManager::get_pending_update(&env)
    }

    /// Get the treasury timelock configuration (read-only query).
    pub fn get_treasury_timelock_config(env: Env) -> recovery::TreasuryTimelockConfig {
        recovery::TreasuryTimelockConfig::get_config(&env)
    }

    /// Set the treasury timelock delay (admin only).
    pub fn set_treasury_timelock_config(
        env: Env,
        admin: Address,
        timelock_seconds: u64,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        recovery::TreasuryTimelockConfig::set_config(&env, &admin, timelock_seconds)
    }

    /// Sweep unclaimed winning payouts after claim period expiry (admin only).
    ///
    /// If `burn` is true, swept funds are burned (no recipient balance credited).
    /// If `burn` is false, swept funds are credited to the configured treasury.
    pub fn sweep_unclaimed_winnings(
        env: Env,
        admin: Address,
        market_id: Symbol,
        burn: bool,
    ) -> Result<i128, Error> {
        admin.require_auth();

        let stored_admin: Address = env
            .storage()
            .persistent()
            .get(&Symbol::new(&env, SYM_ADMIN))
            .ok_or(Error::AdminNotSet)?;

        if admin != stored_admin {
            return Err(Error::Unauthorized);
        }

        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .ok_or(Error::MarketNotFound)?;

        let winning_outcomes = market
            .winning_outcomes
            .clone()
            .ok_or(Error::MarketNotResolved)?;

        if !recovery::UnclaimedWinningsPolicy::is_claim_window_expired(
            &env,
            &market_id,
            market.end_time,
        ) {
            return Err(Error::InvalidState);
        }

        // Idempotency guard: reject a repeat sweep so the treasury is never double-credited.
        if market.winnings_swept {
            return Err(Error::SweepAlreadyDone);
        }

        let fee_percent = crate::config::ConfigManager::get_config(&env)
            .map(|cfg| cfg.fees.platform_fee_percentage)
            .unwrap_or_else(|_| {
                // Use the short platform fee key (backwards-compat fallback to legacy long keys
                // is not possible here because Soroban restricts symbols to <=9 chars).
                // If you need to read old on-chain keys created with long symbols,
                // perform a storage migration on-chain (one-time) to move legacy values
                // under the new short key.
                let new_key = Symbol::new(&env, "platform_fee");
                env.storage().persistent().get(&new_key).unwrap_or(2)
            });

        if fee_percent < 0 || fee_percent > PERCENTAGE_DENOMINATOR {
            return Err(Error::InvalidFeeConfig);
        }

        let summary = resolution::ResolutionOutcomeCache::require(&env, &market_id, &market)?;
        let winning_total = summary.winning_total;
        if winning_total <= 0 {
            return Ok(0);
        }

        let bettors = bets::BetStorage::get_all_bets_for_market(&env, &market_id);
        let mut swept_total = 0i128;
        let total_pool = summary.total_pool;

        for (user, outcome) in market.votes.iter() {
            if !winning_outcomes.contains(&outcome) {
                continue;
            }

            if market
                .claimed
                .get(user.clone())
                .map(|info| info.is_claimed())
                .unwrap_or(false)
            {
                continue;
            }

            let user_stake = market.stakes.get(user.clone()).unwrap_or(0);
            if user_stake <= 0 {
                continue;
            }

            let user_share = user_stake
                .checked_mul(PERCENTAGE_DENOMINATOR as i128 - fee_percent as i128)
                .ok_or(Error::InvalidInput)?
                / (PERCENTAGE_DENOMINATOR as i128);
            let payout = user_share
                .checked_mul(total_pool)
                .ok_or(Error::InvalidInput)?
                / winning_total;

            if payout < 0 {
                return Err(Error::InvalidInput);
            }

            market
                .claimed
                .set(user.clone(), ClaimInfo::new(&env, payout, 0u64));
            swept_total = swept_total.checked_add(payout).ok_or(Error::InvalidInput)?;
        }

        for user in bettors.iter() {
            if market.votes.contains_key(user.clone()) {
                continue;
            }

            let Some(bet) = bets::BetStorage::get_bet(&env, &market_id, &user) else {
                continue;
            };

            if !winning_outcomes.contains(&bet.outcome) {
                continue;
            }

            if market
                .claimed
                .get(user.clone())
                .map(|info| info.is_claimed())
                .unwrap_or(false)
            {
                continue;
            }

            if bet.amount <= 0 {
                continue;
            }

            let user_share = bet
                .amount
                .checked_mul(PERCENTAGE_DENOMINATOR as i128 - fee_percent as i128)
                .ok_or(Error::InvalidInput)?
                / (PERCENTAGE_DENOMINATOR as i128);
            let payout = user_share
                .checked_mul(total_pool)
                .ok_or(Error::InvalidInput)?
                / winning_total;

            if payout < 0 {
                return Err(Error::InvalidInput);
            }

            market
                .claimed
                .set(user.clone(), ClaimInfo::new(&env, payout, 0u64));
            swept_total = swept_total.checked_add(payout).ok_or(Error::InvalidInput)?;
        }

        let recipient = if burn {
            None
        } else {
            let treasury = recovery::UnclaimedWinningsPolicy::get_treasury(&env)
                .ok_or(Error::ConfigNotFound)?;
            if swept_total > 0 {
                storage::BalanceStorage::add_balance(
                    &env,
                    &treasury,
                    &types::ReflectorAsset::Stellar,
                    swept_total,
                )?;
            }
            Some(treasury)
        };

        // Mark this market as swept so a second call returns SweepAlreadyDone.
        market.winnings_swept = true;
        store_market_with_retention(&env, &market_id, &market);
        EventEmitter::emit_unclaimed_winnings_swept(
            &env,
            &market_id,
            &admin,
            &recipient,
            swept_total,
            burn,
        );

        Ok(swept_total)
    }

    /// Retrieves complete market information by market identifier.
    ///
    /// This function provides read-only access to all market data including
    /// configuration, current state, voting results, stakes, and resolution status.
    /// It's the primary way to query market information for display or analysis.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to retrieve
    ///
    /// # Returns
    ///
    /// Returns `Some(Market)` if the market exists, `None` if not found.
    /// The `Market` struct contains:
    /// - Basic info: admin, question, outcomes, end_time
    /// - Oracle configuration and results
    /// - Voting data: votes, stakes, total_staked
    /// - Resolution data: winning_outcome, claimed status
    /// - State information: current state, extensions, fee collection
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// match PredictifyHybrid::get_market(env.clone(), market_id) {
    ///     Some(market) => {
    ///         // Market found - access market data
    ///         let question = market.question;
    ///         let state = market.state;
    ///         let total_staked = market.total_staked;
    ///     },
    ///     None => {
    ///         // Market not found
    ///     }
    /// }
    /// ```
    ///
    /// # Use Cases
    ///
    /// - **UI Display**: Show market details, voting status, and results
    /// - **Analytics**: Calculate market statistics and user positions
    /// - **Validation**: Check market state before performing operations
    /// - **Monitoring**: Track market progress and resolution status
    ///
    /// # Performance
    ///
    /// This is a read-only operation that doesn't modify contract state.
    /// It retrieves data from persistent storage with minimal computational overhead.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_market(env: Env, market_id: Symbol) -> Option<Market> {
        env.storage().persistent().get(&market_id)
    }

    /// Get the current claim nonce for a user on a specific market.
    ///
    /// This function retrieves the claim nonce used for replay protection. Clients should
    /// call this to determine what nonce to provide when calling `claim_winnings`.
    ///
    /// # Returns
    ///
    /// The current nonce (0 on first claim, incrementing by 1 on each subsequent claim).
    /// Clients should provide this exact value as the `claim_nonce` parameter to `claim_winnings`.
    pub fn get_claim_nonce(env: Env, user: Address, market_id: Symbol) -> u64 {
        storage::ClaimNonceManager::get_nonce(&env, &user, &market_id)
    }

    /// Verifies a client's expected metadata commitment against on-chain market metadata.
    ///
    /// The commitment is `sha256(canonical_xdr({ question, outcomes, oracle_config }))`.
    /// This helper returns `false` when the market is missing, when `expected` does not
    /// match the commitment stored at creation/update time, or when any committed field
    /// in storage was changed without refreshing the stored commitment.
    pub fn verify_market_metadata(env: Env, market_id: Symbol, expected: BytesN<32>) -> bool {
        let market: Option<Market> = env.storage().persistent().get(&market_id);
        match market {
            Some(market) => market.verify_metadata_commitment(&env, &expected),
            None => false,
        }
    }

    /// Manually resolves a prediction market by setting the winning outcome (admin only).
    ///
    /// This function allows contract administrators to manually resolve markets
    /// when automatic oracle resolution is not available or needs override.
    /// It's typically used for markets with subjective outcomes or when oracle
    /// data is unavailable or disputed.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the resolution (must be authorized)
    /// * `market_id` - Unique identifier of the market to resolve
    /// * `winning_outcome` - The outcome to be declared as the winner
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketClosed` - Market hasn't reached its end time yet
    /// - `Error::InvalidOutcome` - Winning outcome doesn't match any market outcomes
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, String, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Manually resolve market with "Yes" as winning outcome
    /// PredictifyHybrid::resolve_market_manual(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     String::from_str(&env, "Yes")
    /// );
    /// ```
    ///
    /// # Resolution Process
    ///
    /// 1. **Authentication**: Verifies caller is the contract admin
    /// 2. **Market Validation**: Ensures market exists and has ended
    /// 3. **Outcome Validation**: Confirms winning outcome is valid
    /// 4. **State Update**: Sets winning outcome and updates market state
    ///
    /// # Use Cases
    ///
    /// - **Subjective Markets**: Markets requiring human judgment
    /// - **Oracle Failures**: When automated oracles are unavailable
    /// - **Dispute Resolution**: Override disputed automatic resolutions
    /// - **Emergency Resolution**: Resolve markets in exceptional circumstances
    ///
    /// # Security
    ///
    /// This function requires admin privileges and should be used carefully.
    /// Manual resolutions should be transparent and follow established governance procedures.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.

    /// Check and enforce admin action cooldown for resolution functions.
    fn check_resolution_cooldown(env: &Env, admin: &Address, fn_name: &Symbol) -> Result<(), Error> {
        let cooldown_key = DataKey::ResolutionCooldownSeconds;
        let cooldown: u64 = env.storage().persistent().get(&cooldown_key).unwrap_or(0);
        if cooldown == 0 {
            return Ok(());
        }
        let now = env.ledger().timestamp();
        let last_key = DataKey::ResolutionAdminLastAction(fn_name.clone());
        let last_action: u64 = env.storage().persistent().get(&last_key).unwrap_or(0);
        if last_action > 0 && now < last_action.saturating_add(cooldown) {
            return Err(Error::AdminActionTimelocked);
        }
        env.storage().persistent().set(&last_key, &now);
        env.storage().persistent().extend_ttl(&last_key, 535680, 535680);
        Ok(())
    }

    /// Sets the cooldown period for resolution admin actions.
    pub fn set_resolution_cooldown(env: Env, admin: Address, seconds: u64) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        let key = DataKey::ResolutionCooldownSeconds;
        env.storage().persistent().set(&key, &seconds);
        env.storage().persistent().extend_ttl(&key, 535680, 535680);
        Ok(())
    }

    pub fn resolve_market_manual(
        env: Env,
        admin: Address,
        market_id: Symbol,
        winning_outcome: String,
    ) {
        let gas_marker = GasTracker::start_tracking(&env);
        Self::require_primary_admin_or_panic(&env, &admin);
        Self::check_resolution_cooldown(&env, &admin, &Symbol::new(&env, "resolve_market_manual")).unwrap_or_else(|e| panic_with_error!(env, e));

        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| {
                panic_with_error!(env, Error::MarketNotFound);
            });

        // Check if market has ended
        if env.ledger().timestamp() < market.end_time {
            panic_with_error!(env, Error::MarketClosed);
        }

        // Validate winning outcome
        let outcome_exists = market.outcomes.iter().any(|o| o == winning_outcome);
        if !outcome_exists {
            panic_with_error!(env, Error::InvalidOutcome);
        }

        // Capture old state for event
        let old_state = market.state.clone();

        // Set winning outcome(s) as a vector (single outcome for now, supports future multi-winner)
        let mut winning_outcomes_vec = Vec::new(&env);
        winning_outcomes_vec.push_back(winning_outcome.clone());
        market.winning_outcomes = Some(winning_outcomes_vec.clone());
        market.state = MarketState::Resolved;
        recovery::UnclaimedWinningsPolicy::set_claim_window_start_if_missing(
            &env,
            &market_id,
            env.ledger().timestamp(),
        );
        env.storage().persistent().set(&market_id, &market);

        // Resolve bets to mark them as won/lost
        let _ = bets::BetManager::resolve_market_bets(&env, &market_id, &winning_outcomes_vec);

        let _ = resolution::ResolutionOutcomeCache::refresh(&env, &market_id, &market);

        // Emit market resolved event (simplified to avoid segfaults)
        let oracle_result_str = market
            .oracle_result
            .clone()
            .unwrap_or_else(|| String::from_str(&env, "N/A"));
        let community_consensus_str = String::from_str(&env, "Manual");
        let resolution_method = String::from_str(&env, "Manual");

        // Emit events with defensive approach
        EventEmitter::emit_market_resolved(
            &env,
            &market_id,
            &winning_outcome,
            &oracle_result_str,
            &community_consensus_str,
            &resolution_method,
            100, // confidence score for manual resolution
        );

        // Emit state change event
        let reason = String::from_str(&env, "Manual resolution by admin");
        EventEmitter::emit_state_change_event(
            &env,
            &market_id,
            &old_state,
            &MarketState::Resolved,
            &reason,
        );

        // Automatically distribute payouts to winners after resolution
        let _ = Self::distribute_payouts(env.clone(), market_id.clone());

        // Invalidate analytics cache — market state and winning_outcomes have changed.
        analytics::AnalyticsCache::new(&env).invalidate(&market_id);

        // Per-market audit entry: MarketResolved
        {
            let mut details = Map::new(&env);
            details.set(
                Symbol::new(&env, "outcome"),
                winning_outcome.clone(),
            );
            details.set(
                Symbol::new(&env, "method"),
                String::from_str(&env, "Manual"),
            );
            crate::audit::MarketAuditManager::append(
                &env,
                &market_id,
                crate::audit::MarketAuditAction::MarketResolved,
                admin.clone(),
                details,
            );
        }

        GasTracker::end_tracking(&env, symbol_short!("res_man"), gas_marker);
    }

    /// Resolves a market with multiple winning outcomes (for tie cases).
    ///
    /// This function allows authorized administrators to resolve a market with
    /// multiple winners when there's a tie. The pool will be split proportionally
    /// among all winning outcomes based on stake distribution.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the resolution (must be authorized)
    /// * `market_id` - Unique identifier of the market to resolve
    /// * `winning_outcomes` - Vector of outcomes to be declared as winners (minimum 1, all must be valid)
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketClosed` - Market hasn't ended yet
    /// - `Error::InvalidOutcome` - One or more outcomes are not valid for this market
    /// - `Error::InvalidInput` - Empty outcomes vector
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol, String, Vec};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "sports_match");
    ///
    /// // Resolve with tie (Team A and Team B both win)
    /// let winning_outcomes = vec![
    ///     &env,
    ///     String::from_str(&env, "Team A"),
    ///     String::from_str(&env, "Team B"),
    /// ];
    ///
    /// PredictifyHybrid::resolve_market_with_ties(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     winning_outcomes
    /// );
    /// ```
    ///
    /// # Pool Split Logic
    ///
    /// When multiple outcomes win:
    /// - Total pool is split proportionally among all winners
    /// - Each winner receives: (their_stake / total_winning_stakes) * total_pool * (1 - fee)
    /// - This ensures fair distribution even when outcomes are tied
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn resolve_market_with_ties(
        env: Env,
        admin: Address,
        market_id: Symbol,
        winning_outcomes: Vec<String>,
    ) {
        Self::require_primary_admin_or_panic(&env, &admin);
        Self::check_resolution_cooldown(&env, &admin, &Symbol::new(&env, "resolve_market_with_ties")).unwrap_or_else(|e| panic_with_error!(env, e));

        // Validate outcomes vector is not empty
        if winning_outcomes.len() == 0 {
            panic_with_error!(env, Error::InvalidInput);
        }

        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| {
                panic_with_error!(env, Error::MarketNotFound);
            });

        // Check if market has ended
        if env.ledger().timestamp() < market.end_time {
            panic_with_error!(env, Error::MarketClosed);
        }

        // Validate all winning outcomes exist in market outcomes
        for outcome in winning_outcomes.iter() {
            let outcome_exists = market.outcomes.iter().any(|o| o == outcome);
            if !outcome_exists {
                panic_with_error!(env, Error::InvalidOutcome);
            }
        }

        // Capture old state for event
        let old_state = market.state.clone();

        // Set winning outcome(s) - supports multiple winners for ties
        market.winning_outcomes = Some(winning_outcomes.clone());
        market.state = MarketState::Resolved;
        recovery::UnclaimedWinningsPolicy::set_claim_window_start_if_missing(
            &env,
            &market_id,
            env.ledger().timestamp(),
        );
        env.storage().persistent().set(&market_id, &market);

        // Resolve bets to mark them as won/lost
        let _ = bets::BetManager::resolve_market_bets(&env, &market_id, &winning_outcomes);

        let _ = resolution::ResolutionOutcomeCache::refresh(&env, &market_id, &market);

        // Emit market resolved event
        let primary_outcome = winning_outcomes.get(0).unwrap().clone();
        let oracle_result_str = market
            .oracle_result
            .clone()
            .unwrap_or_else(|| String::from_str(&env, "N/A"));
        let community_consensus_str = String::from_str(&env, "Manual");
        let resolution_method = String::from_str(&env, "Manual");

        EventEmitter::emit_market_resolved(
            &env,
            &market_id,
            &primary_outcome,
            &oracle_result_str,
            &community_consensus_str,
            &resolution_method,
            100, // confidence score for manual resolution
        );

        // Emit state change event
        let reason = String::from_str(&env, "Manual resolution with ties by admin");
        EventEmitter::emit_state_change_event(
            &env,
            &market_id,
            &old_state,
            &MarketState::Resolved,
            &reason,
        );

        // Automatically distribute payouts (handles split pool for ties)
        let _ = Self::distribute_payouts(env.clone(), market_id.clone());

        // Invalidate analytics cache — market state and winning_outcomes have changed.
        analytics::AnalyticsCache::new(&env).invalidate(&market_id);

        // Per-market audit entry: MarketResolved (with ties)
        {
            let mut details = Map::new(&env);
            details.set(
                Symbol::new(&env, "outcome"),
                primary_outcome.clone(),
            );
            details.set(
                Symbol::new(&env, "method"),
                String::from_str(&env, "ManualTie"),
            );
            crate::audit::MarketAuditManager::append(
                &env,
                &market_id,
                crate::audit::MarketAuditAction::MarketResolved,
                admin.clone(),
                details,
            );
        }
    }

    /// Force-resolves a market bypassing time/state constraints, with idempotency-key
    /// replay protection and audit trail.
    ///
    /// This admin-only entrypoint resolves a market **regardless** of its current state
    /// or whether `end_time` has been reached. Every call must supply a non-empty `reason`
    /// and a unique `idempotency_key` (a string, e.g. a UUID) scoped to the market.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the force-resolve (must be authorised)
    /// * `market_id` - Unique identifier of the market to force-resolve
    /// * `winning_outcomes` - Vector of outcomes to declare as winners (minimum 1, all must be valid)
    /// * `reason` - Human-readable justification for the force-resolve (stored in audit trail)
    /// * `idempotency_key` - Unique caller-provided key (e.g. UUID) per market; prevents replay
    ///
    /// # Returns
    ///
    /// * `Ok(())` - Force-resolve succeeded
    /// * `Err(Error::Unauthorized)` - Caller is not the contract primary admin
    /// * `Err(Error::MarketNotFound)` - Market does not exist
    /// * `Err(Error::InvalidOutcome)` - One or more outcomes are invalid for this market
    /// * `Err(Error::InvalidInput)` - Empty outcomes vector
    /// * `Err(Error::ForceResolveReasonEmpty)` - Reason string is empty
    /// * `Err(Error::ForceResolveReplayed)` - Idempotency key has already been used
    ///
    /// # Events
    ///
    /// On first invocation emits a `ForceResolvedEvent` (topic `frc_rs`) and a state-change
    /// event. Repeated calls with the same `idempotency_key` are rejected as replays.
    pub fn force_resolve_market(
        env: Env,
        admin: Address,
        market_id: Symbol,
        winning_outcomes: Vec<String>,
        reason: String,
        idempotency_key: String,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        Self::check_resolution_cooldown(&env, &admin, &Symbol::new(&env, "force_resolve_market"))?;

        if reason.is_empty() {
            return Err(Error::ForceResolveReasonEmpty);
        }

        if winning_outcomes.len() == 0 {
            return Err(Error::InvalidInput);
        }

        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .ok_or(Error::MarketNotFound)?;

        for outcome in winning_outcomes.iter() {
            let outcome_exists = market.outcomes.iter().any(|o| o == outcome);
            if !outcome_exists {
                return Err(Error::InvalidOutcome);
            }
        }

        // Idempotency check — reject if this key was already consumed
        if force_resolve::ForceResolveManager::is_already_resolved(
            &env,
            &market_id,
            &idempotency_key,
        ) {
            return Err(Error::ForceResolveReplayed);
        }

        let old_state = market.state.clone();

        market.winning_outcomes = Some(winning_outcomes.clone());
        market.state = MarketState::Resolved;

        recovery::UnclaimedWinningsPolicy::set_claim_window_start_if_missing(
            &env,
            &market_id,
            env.ledger().timestamp(),
        );

        env.storage().persistent().set(&market_id, &market);

        force_resolve::ForceResolveManager::mark_resolved(
            &env,
            &market_id,
            &idempotency_key,
            &admin,
            &winning_outcomes,
        );

        let _ = bets::BetManager::resolve_market_bets(&env, &market_id, &winning_outcomes);
        let _ = resolution::ResolutionOutcomeCache::refresh(&env, &market_id, &market);

        let primary_outcome = winning_outcomes.get(0).unwrap().clone();

        // Emit force-resolved event
        EventEmitter::emit_force_resolved(
            &env,
            &market_id,
            &admin,
            &primary_outcome,
            &reason,
            &idempotency_key,
        );

        // Emit state change event
        EventEmitter::emit_state_change_event(
            &env,
            &market_id,
            &old_state,
            &MarketState::Resolved,
            &reason,
        );

        // Append immutable audit trail record
        let mut details = Map::new(&env);
        details.set(Symbol::new(&env, "reason"), reason);
        details.set(Symbol::new(&env, "old_state"), {
            let s = match old_state {
                MarketState::Active => "Active",
                MarketState::Ended => "Ended",
                MarketState::Disputed => "Disputed",
                MarketState::Resolved => "Resolved",
                MarketState::Closed => "Closed",
                MarketState::Cancelled => "Cancelled",
                MarketState::Archived => "Archived",
                MarketState::Restored => "Restored",
            };
            String::from_str(&env, s)
        });
        AuditTrailManager::append_record(
            &env,
            AuditAction::MarketForceResolved,
            admin.clone(),
            details,
            None,
        );

        // Per-market audit entry: MarketForceResolved
        {
            let mut per_market_details = Map::new(&env);
            per_market_details.set(
                Symbol::new(&env, "outcome"),
                primary_outcome.clone(),
            );
            per_market_details.set(
                Symbol::new(&env, "method"),
                String::from_str(&env, "Force"),
            );
            crate::audit::MarketAuditManager::append(
                &env,
                &market_id,
                crate::audit::MarketAuditAction::MarketForceResolved,
                admin.clone(),
                per_market_details,
            );
        }

        // Auto-distribute payouts
        let _ = Self::distribute_payouts(env.clone(), market_id);

        Ok(())
    }

    /// Fetches oracle result for a market from external oracle contracts.
    ///
    /// This function retrieves prediction results from configured oracle sources
    /// such as Reflector or Pyth networks. It's used to obtain objective data
    /// for market resolution when manual resolution is not appropriate.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to fetch oracle data for
    /// * `oracle_contract` - Address of the oracle contract to query
    ///
    /// # Returns
    ///
    /// Returns `Result<String, Error>` where:
    /// - `Ok(String)` - The oracle result as a string representation
    /// - `Err(Error)` - Specific error if operation fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketResolved` - Market already has oracle result set
    /// - `Error::MarketClosed` - Market hasn't reached its end time yet
    /// - Oracle-specific errors from the resolution module
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "btc_market");
    /// # let oracle_address = Address::generate(&env);
    ///
    /// match PredictifyHybrid::fetch_oracle_result(
    ///     env.clone(),
    ///     market_id,
    ///     oracle_address
    /// ) {
    ///     Ok(result) => {
    ///         // Oracle result retrieved successfully
    ///         println!("Oracle result: {}", result);
    ///     },
    ///     Err(e) => {
    ///         // Handle error
    ///         println!("Failed to fetch oracle result: {:?}", e);
    ///     }
    /// }
    /// ```
    ///
    /// # Oracle Integration
    ///
    /// This function integrates with various oracle types:
    /// - **Reflector**: For asset price data and market conditions
    /// - **Pyth**: For high-frequency financial data feeds
    /// - **Custom Oracles**: For specialized data sources
    ///
    /// # Market State Requirements
    ///
    /// - Market must exist and be past its end time
    /// - Market must not already have an oracle result
    /// - Automatic oracle resolution stops once `ledger.timestamp() >= end_time + resolution_timeout`
    /// - When `has_fallback` is `true`, the contract attempts the primary oracle once and then the fallback once
    /// - The market-stored oracle configuration controls ordering; the external `oracle_contract` argument is ignored
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn fetch_oracle_result(
        env: Env,
        market_id: Symbol,
        oracle_contract: Address,
    ) -> Result<String, Error> {
        let _ = oracle_contract;

        // Get the market from storage
        let mut market = env
            .storage()
            .persistent()
            .get::<Symbol, Market>(&market_id)
            .ok_or(Error::MarketNotFound)?;

        // Validate market state
        if market.oracle_result.is_some() {
            return Err(Error::MarketResolved);
        }

        // Check if market has ended
        let current_time = env.ledger().timestamp();
        if current_time < market.end_time {
            return Err(Error::MarketClosed);
        }

        if resolution_timeout_reached(&env, &market) {
            EventEmitter::emit_resolution_timeout(&env, &market_id, current_time);
            return Err(Error::ResolutionTimeoutReached);
        }

        match get_oracle_result(&env, &market.oracle_config) {
            Ok(outcome) => {
                market.oracle_result = Some(outcome.clone());
                env.storage().persistent().set(&market_id, &market);
                Ok(outcome)
            }
            Err(_) if market.has_fallback => {
                match get_oracle_result(&env, &market.fallback_oracle_config) {
                    Ok(outcome) => {
                        market.oracle_result = Some(outcome.clone());
                        env.storage().persistent().set(&market_id, &market);
                        EventEmitter::emit_fallback_used(
                            &env,
                            &market_id,
                            &market.oracle_config.oracle_address,
                            &market.fallback_oracle_config.oracle_address,
                        );
                        Ok(outcome)
                    }
                    Err(_) => {
                        EventEmitter::emit_manual_resolution_required(
                            &env,
                            &market_id,
                            &String::from_str(&env, "primary_and_fallback_failed"),
                        );
                        Err(Error::FallbackOracleUnavailable)
                    }
                }
            }
            Err(err) => {
                EventEmitter::emit_manual_resolution_required(
                    &env,
                    &market_id,
                    &String::from_str(&env, "primary_failed_no_fallback"),
                );
                Err(err)
            }
        }
    }

    /// Verifies and fetches event outcome from external oracle sources automatically.
    ///
    /// This function implements the complete oracle integration mechanism that:
    /// - Automatically fetches event outcomes from configured external data sources
    /// - Validates oracle responses and signatures/authority
    /// - Supports multiple oracle sources with consensus-based verification
    /// - Handles oracle failures gracefully with fallback mechanisms
    /// - Emits result verification events for transparency
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `caller` - The address initiating the verification (must be authenticated)
    /// * `market_id` - Unique identifier of the market to verify
    ///
    /// # Returns
    ///
    /// Returns `Result<OracleResult, Error>` where:
    /// - `Ok(OracleResult)` - Complete oracle verification result including:
    ///   - `outcome`: The determined outcome ("yes"/"no" or custom)
    ///   - `price`: The fetched price from oracle
    ///   - `threshold`: The configured threshold for comparison
    ///   - `confidence_score`: Statistical confidence (0-100)
    ///   - `is_verified`: Whether the result passed all validations
    ///   - `sources_count`: Number of oracle sources consulted
    /// - `Err(Error)` - Specific error if verification fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketNotReadyForVerification` - Market hasn't ended yet
    /// - `Error::OracleVerified` - Result already verified for this market
    /// - `Error::OracleUnavailable` - Oracle service is unavailable
    /// - `Error::OracleStale` - Oracle data is too old
    /// - `Error::OracleConsensusNotReached` - Multiple oracles disagree
    /// - `Error::InvalidOracleConfig` - Oracle not whitelisted/authorized
    /// - `Error::OracleAllSourcesFailed` - All oracle sources failed
    /// - `Error::InsufficientOracleSources` - No active oracle sources available
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let caller = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "btc_50k_2024");
    ///
    /// // Verify result for an ended market
    /// match PredictifyHybrid::verify_result(env.clone(), caller, market_id) {
    ///     Ok(result) => {
    ///         println!("Outcome: {}", result.outcome);
    ///         println!("Price: ${}", result.price / 100);
    ///         println!("Confidence: {}%", result.confidence_score);
    ///         println!("Sources consulted: {}", result.sources_count);
    ///         
    ///         if result.is_verified {
    ///             println!("Result is verified and authoritative");
    ///         }
    ///     },
    ///     Err(e) => {
    ///         println!("Verification failed: {:?}", e);
    ///     }
    /// }
    /// ```
    ///
    /// # Oracle Integration
    ///
    /// This function integrates with multiple oracle providers:
    /// - **Reflector**: Primary oracle for Stellar Network (production ready)
    /// - **Band Protocol**: Decentralized oracle network
    /// - **Custom Oracles**: Can be added via whitelist system
    ///
    /// # Multi-Oracle Consensus
    ///
    /// When multiple oracle sources are configured:
    /// 1. All active sources are queried in parallel
    /// 2. Responses are validated for freshness and authority
    /// 3. Consensus is calculated (default: 66% agreement required)
    /// 4. Confidence score reflects agreement level and price stability
    ///
    /// # Security Features
    ///
    /// - **Whitelist Validation**: Only whitelisted oracles are queried
    /// - **Authority Verification**: Oracle responses are validated for authenticity
    /// - **Staleness Protection**: Data older than 5 minutes is rejected
    /// - **Price Range Validation**: Ensures prices are within reasonable bounds
    /// - **Consensus Requirement**: Multiple sources must agree for high-value markets
    ///
    /// # Events Emitted
    ///
    /// - `OracleVerificationInitiated`: When verification begins
    /// - `OracleResultVerified`: When verification succeeds
    /// - `OracleVerificationFailed`: When verification fails
    /// - `OracleConsensusReached`: When multiple sources agree
    ///
    /// # Market State Requirements
    ///
    /// - Market must exist in storage
    /// - Market end time must have passed
    /// - Result must not already be verified
    /// - At least one active oracle source must be available
    #[deprecated(note = "Use fetch_oracle_result instead. This legacy stub will be removed in a future version.")]
    pub fn verify_result(
        env: Env,
        caller: Address,
        market_id: Symbol,
    ) -> Result<OracleResult, Error> {
        // Authenticate the caller
        caller.require_auth();

        DeprecatedRegistry::record_call(
            &env,
            &caller,
            &Symbol::new(&env, "verify_result"),
            &Symbol::new(&env, "fetch_oracle_result"),
        );

        // Use the OracleIntegrationManager to perform verification
        // Temporarily disabled due to oracles module being disabled
        // oracles::OracleIntegrationManager::verify_result(&env, &market_id, &caller)
        Err(Error::OracleUnavailable)
    }

    /// Verifies oracle result with retry logic for resilience.
    ///
    /// This function is similar to `verify_result` but includes automatic
    /// retry logic to handle transient oracle failures. Useful in production
    /// environments where network issues may cause temporary unavailability.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `caller` - The address initiating the verification
    /// * `market_id` - Unique identifier of the market to verify
    /// * `max_retries` - Maximum number of retry attempts (capped at 3)
    ///
    /// # Returns
    ///
    /// Returns `Result<OracleResult, Error>` - Same as `verify_result`
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let caller = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "btc_50k_2024");
    ///
    /// // Verify with up to 3 retries
    /// let result = PredictifyHybrid::verify_result_with_retry(
    ///     env.clone(),
    ///     caller,
    ///     market_id,
    ///     3
    /// );
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn verify_result_with_retry(
        env: Env,
        caller: Address,
        market_id: Symbol,
        max_retries: u32,
    ) -> Result<OracleResult, Error> {
        caller.require_auth();
        // Temporarily disabled due to oracles module being disabled
        // oracles::OracleIntegrationManager::verify_result_with_retry(
        //     &env,
        //     &market_id,
        //     &caller,
        //     max_retries,
        // )
        Err(Error::OracleUnavailable)
    }

    /// Retrieves a previously verified oracle result for a market.
    ///
    /// This function returns the stored oracle verification result for a market
    /// that has already been verified. Useful for checking verification status
    /// and retrieving historical verification data.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market
    ///
    /// # Returns
    ///
    /// Returns `Option<OracleResult>`:
    /// - `Some(OracleResult)` - The stored verification result
    /// - `None` - Market has not been verified yet
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "btc_50k_2024");
    ///
    /// match PredictifyHybrid::get_verified_result(env.clone(), market_id) {
    ///     Some(result) => {
    ///         println!("Market verified with outcome: {}", result.outcome);
    ///     },
    ///     None => {
    ///         println!("Market not yet verified");
    ///     }
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_verified_result(env: Env, market_id: Symbol) -> Option<OracleResult> {
        // Temporarily disabled due to oracles module being disabled
        // oracles::OracleIntegrationManager::get_oracle_result(&env, &market_id)
        None
    }

    /// Checks if a market's result has been verified via oracle.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `market_id` - Unique identifier of the market
    ///
    /// # Returns
    ///
    /// Returns `bool` - `true` if verified, `false` otherwise
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn is_result_verified(env: Env, market_id: Symbol) -> bool {
        // Temporarily disabled due to oracles module being disabled
        // oracles::OracleIntegrationManager::is_result_verified(&env, &market_id)
        false
    }

    /// Admin override for oracle result verification.
    ///
    /// Allows an authorized admin to manually set the verification result
    /// when automatic verification fails or produces incorrect results.
    /// This is a privileged operation requiring admin authorization.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `admin` - Admin address (must be authorized)
    /// * `market_id` - Market to override
    /// * `outcome` - The outcome to set ("yes"/"no" or custom)
    /// * `reason` - Reason for the manual override
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>`:
    /// - `Ok(())` - Override successful
    /// - `Err(Error::Unauthorized)` - Caller is not admin
    ///
    /// # Security
    ///
    /// This function should be used sparingly and only when:
    /// - Automatic oracle verification has failed repeatedly
    /// - Oracle data is known to be incorrect
    /// - Emergency situations requiring immediate resolution
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    /// Set the minimum oracle price-confidence threshold in basis points.
    /// Prices from oracles with confidence ratio above this threshold are rejected.
    /// `min_confidence_bps` = 0 disables the check.
    pub fn set_oracle_confidence_threshold(env: Env, admin: Address, min_confidence_bps: u32) {
        admin.require_auth();
        if min_confidence_bps > 10_000 {
            panic_with_error!(env, Error::InvalidInput);
        }
        env.storage()
            .instance()
            .set(&Symbol::new(&env, "oracle_conf_bps"), &min_confidence_bps);
    }

    /// Get the configured oracle confidence threshold in bps (0 = disabled).
    pub fn get_oracle_confidence_threshold(env: Env) -> u32 {
        env.storage()
            .instance()
            .get(&Symbol::new(&env, "oracle_conf_bps"))
            .unwrap_or(0u32)
    }

    /// Set configurable weight for a specific oracle source
    pub fn set_oracle_weight(
        env: Env,
        admin: Address,
        oracle: Address,
        weight: u32,
    ) -> Result<(), Error> {
        admin.require_auth();
        crate::oracles::OracleIntegrationManager::set_oracle_weight(&env, admin, oracle, weight)
    }

    /// Get configured weight for an oracle source, defaults to 1
    pub fn get_oracle_weight(env: Env, oracle: Address) -> u32 {
        crate::oracles::OracleIntegrationManager::get_oracle_weight(&env, &oracle)
    }

    pub fn admin_override_verification(
        env: Env,
        admin: Address,
        market_id: Symbol,
        outcome: String,
        reason: String,
        provided_nonce: u64,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        // Reject empty reason — every override must be justified
        if reason.is_empty() {
            return Err(Error::InvalidInput);
        }

        // Load the market
        let mut market = markets::MarketStateManager::get_market(&env, &market_id)?;

        // Capture the previous oracle result for the audit record and event
        let old_result = market
            .oracle_result
            .clone()
            .unwrap_or_else(|| String::from_str(&env, "none"));

        // Apply the override
        market.oracle_result = Some(outcome.clone());
        market.state = crate::types::MarketState::Resolved;
        markets::MarketStateManager::update_market(&env, &market_id, &market);

        // Append an immutable audit record
        // Validate and store the admin override nonce for replay protection
        let key = DataKey::AdminOverrideNonce;
        let mut stored_nonce: u64 = env
            .storage()
            .persistent()
            .get(&key)
            .unwrap_or(0);

        if provided_nonce <= stored_nonce {
            return Err(Error::ReplayedOverride);
        }

        // Update the nonce for this admin
        env.storage().persistent().set(&key, &provided_nonce);
        env.storage().persistent().extend_ttl(
            &key,
            env.storage().max_ttl(),
            env.storage().max_ttl(),
        );

        // Append an immutable audit record with the nonce for replay protection
        let mut details = Map::new(&env);
        details.set(Symbol::new(&env, "old_result"), old_result.clone());
        details.set(Symbol::new(&env, "new_result"), outcome.clone());
        details.set(Symbol::new(&env, "reason"), reason.clone());
        AuditTrailManager::append_record(
            &env,
            AuditAction::OracleVerificationOverride,
            admin.clone(),
            details,
            Some(provided_nonce),
        );

        // Emit the dedicated override event for off-chain monitors
        EventEmitter::emit_admin_override(&env, &market_id, &admin, &old_result, &outcome, &reason);

        Ok(())
    }

    /// Resolves a market automatically using oracle data and community consensus.
    ///
    /// This function implements the hybrid resolution algorithm that combines
    /// objective oracle data with community voting patterns to determine the
    /// final market outcome. It's the primary automated resolution mechanism.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to resolve
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Market resolved successfully
    /// - `Err(Error)` - Specific error if resolution fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketNotEnded` - Market hasn't reached its end time
    /// - `Error::MarketResolved` - Market is already resolved
    /// - `Error::InsufficientData` - Not enough data for resolution
    /// - Resolution-specific errors from the resolution module
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "ended_market");
    ///
    /// match PredictifyHybrid::resolve_market(env.clone(), market_id) {
    ///     Ok(()) => {
    ///         // Market resolved successfully
    ///         println!("Market resolved successfully");
    ///     },
    ///     Err(e) => {
    ///         // Handle resolution error
    ///         println!("Resolution failed: {:?}", e);
    ///     }
    /// }
    /// ```
    ///
    /// # Hybrid Resolution Algorithm
    ///
    /// The resolution process follows these steps:
    /// 1. **Data Collection**: Gather oracle data and community votes
    /// 2. **Consensus Analysis**: Analyze agreement between oracle and community
    /// 3. **Conflict Resolution**: Handle disagreements using weighted algorithms
    /// 4. **Final Determination**: Set winning outcome based on hybrid result
    /// 5. **State Update**: Update market state to resolved
    ///
    /// # Resolution Criteria
    ///
    /// - Market must be past its end time
    /// - Sufficient voting participation required
    /// - Oracle data must be available (if configured)
    /// - No active disputes that would prevent resolution
    ///
    /// # Post-Resolution
    ///
    /// After successful resolution:
    /// - Market state changes to `Resolved`
    /// - Winning outcome is set
    /// - Users can claim winnings
    /// - Market statistics are finalized
    ///
    /// # Event Ordering Contract
    ///
    /// On every successful resolution `resolve_market` emits exactly **three**
    /// resolution-signalling events in the following deterministic sequence:
    ///
    /// | # | Topic symbol    | Emitter                               | Description                      |
    /// |---|-----------------|---------------------------------------|----------------------------------|
    /// | 1 | `mkt_res`       | `EventEmitter::emit_market_resolved`  | Final outcome recorded           |
    /// | 2 | `st_chng`       | `EventEmitter::emit_state_change_event` | State transition to `Resolved` |
    /// | 3 | `idx_transition`| `ContractMonitor::emit_resolution_transition_hook` | Off-chain indexer hook |
    ///
    /// Off-chain consumers **must** handle these three events in the order
    /// listed above. The sequence is enforced by the order of calls inside
    /// `MarketResolutionManager::resolve_market` and is covered by a
    /// deterministic ordering test (see `resolution_event_ordering_tests`).
    #[deprecated(note = "Use resolve_market_manual or fetch_oracle_result + resolve_market_manual instead. This legacy stub will be removed in a future version.")]
    pub fn resolve_market(env: Env, caller: Address, market_id: Symbol) -> Result<(), Error> {
        // Authenticate the caller
        caller.require_auth();

        DeprecatedRegistry::record_call(
            &env,
            &caller,
            &Symbol::new(&env, "resolve_market"),
            &Symbol::new(&env, "resolve_market_manual"),
        );

        // Use the resolution module to resolve the market
        // Temporarily disabled due to resolution module being disabled
        // let _resolution = resolution::MarketResolutionManager::resolve_market(&env, &market_id)?;
        // For now, just return success

        statistics::StatisticsManager::record_market_resolved(&env);

        // Invalidate analytics cache — market state has changed.
        analytics::AnalyticsCache::new(&env).invalidate(&market_id);

        Ok(())
    }

    // =========================================================================
    // DEPRECATED-ENTRYPOINTS REGISTRY
    // =========================================================================

    /// Register a deprecated entrypoint in the on-chain registry.
    ///
    /// Adds a new entry to the deprecated-entrypoints registry so that any
    /// caller can discover which functions have been superseded and what the
    /// recommended replacement is.  The operation is idempotent: registering
    /// the same `entrypoint` a second time is a no-op.
    ///
    /// # Parameters
    ///
    /// * `env`         – Soroban environment.
    /// * `admin`       – Contract admin address; must satisfy
    ///                   [`AdminAccessControl::require_admin_auth`].
    /// * `entrypoint`  – Short symbol of the deprecated function name.
    /// * `replacement` – Short symbol of the recommended replacement.
    /// * `note`        – Optional migration hint (max 128 bytes UTF-8).
    ///
    /// # Errors
    ///
    /// * [`Error::Unauthorized`] – Caller is not the contract admin.
    /// * [`Error::AdminNotSet`]  – Contract has not been initialised.
    /// * [`Error::RegistryFull`] – Registry has reached its capacity limit.
    ///
    /// # Events
    ///
    /// Emits `("depr_reg", entrypoint)` on success.
    pub fn register_deprecated(
        env: Env,
        admin: Address,
        entrypoint: Symbol,
        replacement: Symbol,
        note: Option<String>,
    ) -> Result<(), Error> {
        DeprecatedRegistry::register(&env, &admin, entrypoint, replacement, note)
    }

    /// Remove a deprecated entrypoint from the on-chain registry.
    ///
    /// Intended for correcting mistaken registrations or tidying entries for
    /// functions that have been fully removed.  If the entry does not exist
    /// the call is a no-op.
    ///
    /// # Parameters
    ///
    /// * `env`        – Soroban environment.
    /// * `admin`      – Contract admin address.
    /// * `entrypoint` – Name of the entrypoint to remove.
    ///
    /// # Errors
    ///
    /// * [`Error::Unauthorized`] – Caller is not the contract admin.
    /// * [`Error::AdminNotSet`]  – Contract has not been initialised.
    ///
    /// # Events
    ///
    /// Emits `("depr_rem", entrypoint)` when an entry is actually removed.
    pub fn remove_deprecated(
        env: Env,
        admin: Address,
        entrypoint: Symbol,
    ) -> Result<(), Error> {
        DeprecatedRegistry::remove(&env, &admin, entrypoint)
    }

    /// Look up a single deprecated-entrypoint entry by name.
    ///
    /// Returns `Some(DeprecatedEntry)` if `entrypoint` is registered, or
    /// `None` if it is not.  This is a permissionless read.
    ///
    /// # Parameters
    ///
    /// * `env`        – Soroban environment.
    /// * `entrypoint` – Name of the entrypoint to look up.
    pub fn get_deprecated_entry(env: Env, entrypoint: Symbol) -> Option<DeprecatedEntry> {
        DeprecatedRegistry::get_entry(&env, &entrypoint)
    }

    /// Return all entries in the deprecated-entrypoints registry.
    ///
    /// Returns a `Vec<DeprecatedEntry>` (empty if nothing has been registered
    /// yet).  This is a permissionless read.
    ///
    /// # Parameters
    ///
    /// * `env` – Soroban environment.
    pub fn list_deprecated_entries(env: Env) -> Vec<DeprecatedEntry> {
        DeprecatedRegistry::list_entries(&env)
    }

    /// Return the number of entries in the deprecated-entrypoints registry.
    ///
    /// This is a permissionless read.
    ///
    /// # Parameters
    ///
    /// * `env` – Soroban environment.
    pub fn deprecated_entry_count(env: Env) -> u32 {
        DeprecatedRegistry::entry_count(&env)
    }

    /// Return `true` if the given entrypoint is listed as deprecated.
    ///
    /// This is a permissionless read.
    ///
    /// # Parameters
    ///
    /// * `env`        – Soroban environment.
    /// * `entrypoint` – Name of the entrypoint to check.
    pub fn is_deprecated(env: Env, entrypoint: Symbol) -> bool {
        DeprecatedRegistry::is_deprecated(&env, &entrypoint)
    }

    /// Retrieves comprehensive analytics about market resolution performance.
    ///
    /// This function provides detailed statistics about how markets are being
    /// resolved across the platform, including success rates, resolution methods,
    /// oracle performance, and community consensus patterns.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    ///
    /// # Returns
    ///
    /// Returns `Result<ResolutionAnalytics, Error>` where:
    /// - `Ok(ResolutionAnalytics)` - Complete resolution analytics data
    /// - `Err(Error)` - Error if analytics calculation fails
    ///
    /// The `ResolutionAnalytics` struct contains:
    /// - Total markets resolved
    /// - Resolution method breakdown (manual vs automatic)
    /// - Oracle accuracy statistics
    /// - Community consensus metrics
    /// - Average resolution time
    /// - Dispute frequency and outcomes
    ///
    /// # Errors
    ///
    /// This function may return:
    /// - `Error::InsufficientData` - Not enough resolved markets for analytics
    /// - Storage access errors
    /// - Calculation errors from the analytics module
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    ///
    /// match PredictifyHybrid::get_resolution_analytics(env.clone()) {
    ///     Ok(analytics) => {
    ///         // Access resolution statistics
    ///         let total_resolved = analytics.total_markets_resolved;
    ///         let oracle_accuracy = analytics.oracle_accuracy_rate;
    ///         let avg_resolution_time = analytics.average_resolution_time;
    ///         
    ///         println!("Resolved markets: {}", total_resolved);
    ///         println!("Oracle accuracy: {}%", oracle_accuracy);
    ///     },
    ///     Err(e) => {
    ///         println!("Analytics unavailable: {:?}", e);
    ///     }
    /// }
    /// ```
    ///
    /// # Use Cases
    ///
    /// - **Platform Monitoring**: Track overall resolution system health
    /// - **Oracle Evaluation**: Assess oracle performance and reliability
    /// - **Community Analysis**: Understand voting patterns and accuracy
    /// - **System Optimization**: Identify areas for improvement
    /// - **Governance Reporting**: Provide transparency to stakeholders
    ///
    /// # Analytics Metrics
    ///
    /// Key metrics included:
    /// - **Resolution Rate**: Percentage of markets successfully resolved
    /// - **Method Distribution**: Manual vs automatic resolution breakdown
    /// - **Accuracy Scores**: Oracle vs community prediction accuracy
    /// - **Time Metrics**: Average time from market end to resolution
    /// - **Dispute Analytics**: Frequency and resolution of disputes
    ///
    /// # Performance
    ///
    /// This function performs read-only analytics calculations and may take
    /// longer for platforms with many resolved markets. Results may be cached
    /// for performance optimization.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_resolution_analytics(env: Env) -> Result<resolution::MarketResolutionAnalytics, Error> {
        resolution::MarketResolutionAnalytics::calculate_resolution_analytics(&env)
    }

    /// Retrieves comprehensive analytics and statistics for a specific market.
    ///
    /// This function provides detailed statistical analysis of a market including
    /// participation metrics, voting patterns, stake distribution, and performance
    /// indicators. It's essential for market analysis and user interfaces.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to analyze
    ///
    /// # Returns
    ///
    /// Returns `Result<MarketStats, Error>` where:
    /// - `Ok(MarketStats)` - Complete market statistics and analytics
    /// - `Err(Error)` - Error if market not found or analysis fails
    ///
    /// The `MarketStats` struct contains:
    /// - Participation metrics (total voters, total stake)
    /// - Outcome distribution (stakes per outcome)
    /// - Market activity timeline
    /// - Consensus and confidence indicators
    /// - Resolution status and results
    ///
    /// # Errors
    ///
    /// This function returns:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - Calculation errors from the analytics module
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// match PredictifyHybrid::get_market_analytics(env.clone(), market_id) {
    ///     Ok(stats) => {
    ///         // Access market statistics
    ///         let total_participants = stats.total_participants;
    ///         let total_stake = stats.total_stake;
    ///         let leading_outcome = stats.leading_outcome;
    ///         
    ///         println!("Participants: {}", total_participants);
    ///         println!("Total stake: {}", total_stake);
    ///         println!("Leading outcome: {:?}", leading_outcome);
    ///     },
    ///     Err(e) => {
    ///         println!("Analytics unavailable: {:?}", e);
    ///     }
    /// }
    /// ```
    ///
    /// # Statistical Metrics
    ///
    /// Key analytics provided:
    /// - **Participation**: Number of unique voters and total stake
    /// - **Distribution**: Stake distribution across outcomes
    /// - **Confidence**: Market confidence indicators and consensus strength
    /// - **Activity**: Voting timeline and participation patterns
    /// - **Performance**: Market liquidity and engagement metrics
    ///
    /// # Use Cases
    ///
    /// - **UI Display**: Show market statistics to users
    /// - **Market Analysis**: Understand market dynamics and trends
    /// - **Risk Assessment**: Evaluate market confidence and volatility
    /// - **Performance Tracking**: Monitor market engagement over time
    /// - **Research**: Academic and commercial market research
    ///
    /// # Real-time Updates
    ///
    /// Statistics are calculated in real-time based on current market state.
    /// For active markets, analytics reflect the most current voting and staking data.
    /// For resolved markets, analytics include final resolution information.
    ///
    /// # Performance
    ///
    /// This function performs calculations on market data and may have
    /// computational overhead for markets with many participants. Consider
    /// caching results for frequently accessed markets.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_market_analytics(
        env: Env,
        market_id: Symbol,
    ) -> Result<markets::MarketStats, Error> {
        // Fast path: serve from the instance analytics cache when hot.
        // The cache is invalidated on every write (vote, bet, claim, resolve, dispute).
        if let Some(cached) = analytics::get_or_compute(&env, &market_id) {
            return Ok(cached);
        }

        // Slow path: market not found in persistent storage.
        Err(Error::MarketNotFound)
    }

    /// Returns a deterministic, versioned snapshot for a single market's analytics.
    ///
    /// The payload is encoded with Soroban XDR so off-chain analytics services can
    /// persist a stable byte stream without relying on host-side ordering.
    pub fn get_market_analytics_snapshot(
        env: Env,
        market_id: Symbol,
    ) -> Result<analytics_snapshot::AnalyticsSnapshotEnvelope, Error> {
        analytics_snapshot::AnalyticsSnapshotManager::get_snapshot(&env, market_id)
    }

    /// Dispute a market resolution
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn dispute_market(
        env: Env,
        user: Address,
        market_id: Symbol,
        stake: i128,
        reason: Option<String>,
    ) -> Result<(), Error> {
        user.require_auth();

        // Rate limit disputes to prevent abuse
        if let Err(rate_err) = crate::rate_limiter::RateLimiter::new(env.clone())
            .rate_limit_disputes(user.clone(), market_id.clone())
        {
            if matches!(rate_err, crate::rate_limiter::RateLimiterError::ConfigNotFound) {
                // No rate limit config — skip
            } else {
                return Err(Error::from(rate_err));
            }
        }

        let result = disputes::DisputeManager::process_dispute(&env, user.clone(), market_id.clone(), stake, reason);
        if result.is_ok() {
            // Invalidate analytics cache — dispute stakes have changed.
            analytics::AnalyticsCache::new(&env).invalidate(&market_id);

            // Per-market audit entry: DisputeFiled
            let details = Map::new(&env);
            crate::audit::MarketAuditManager::append(
                &env,
                &market_id,
                crate::audit::MarketAuditAction::DisputeFiled,
                user,
                details,
            );
        }
        result
    }

    /// Set the dispute stake cap for a user in a market (governance/admin only)
    pub fn set_dispute_stake_cap(
        env: Env,
        admin: Address,
        market_id: Symbol,
        user: Address,
        cap: i128,
    ) -> Result<(), Error> {
        Self::require_admin_permission(&env, &admin, AdminPermission::UpdateConfig)?;
        if cap < 0 {
            return Err(Error::InvalidInput);
        }
        disputes::DisputeManager::set_dispute_stake_cap(&env, &market_id, &user, cap)
    }

    /// Get the dispute stake cap for a user in a market
    pub fn get_dispute_stake_cap(
        env: Env,
        market_id: Symbol,
        user: Address,
    ) -> i128 {
        let cap_key = storage::DataKey::DisputeStakeCap(market_id, user);
        env.storage().persistent().get(&cap_key).unwrap_or(0)
    }

    /// Set the per-user cumulative dispute stake cap across all active disputes (admin only).
    ///
    /// This cap limits the total stake a user can commit to disputes
    /// across all markets that have active (unresolved) disputes.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `admin` - The admin address (must be authorized)
    /// * `user` - The user address the cap applies to
    /// * `cap` - The maximum cumulative stake allowed in stroops (0 = disabled)
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when:
    /// - `Error::Unauthorized` — caller is not the contract admin
    /// - `Error::InvalidInput` — cap value is invalid
    ///
    /// # Events
    ///
    /// Emits `dispute_cumulative_stake_cap_set` event on success.
    pub fn set_dispute_cumulative_stake_cap(
        env: Env,
        admin: Address,
        user: Address,
        cap: i128,
    ) -> Result<(), Error> {
        if cap < 0 {
            return Err(Error::InvalidInput);
        }
        Self::require_admin_permission(&env, &admin, AdminPermission::UpdateConfig)?;
        disputes::DisputeManager::set_dispute_cumulative_stake_cap(&env, &admin, &user, cap)
    }

    /// Get the per-user cumulative dispute stake cap.
    ///
    /// Returns 0 if no cap is set (cap is disabled).
    pub fn get_dispute_cumulative_stake_cap(env: Env, user: Address) -> i128 {
        disputes::DisputeManager::get_dispute_cumulative_stake_cap(&env, &user)
    }

    /// Vote on a dispute
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn vote_on_dispute(
        env: Env,
        user: Address,
        market_id: Symbol,
        dispute_id: Symbol,
        vote: bool,
        stake: i128,
        reason: Option<String>,
    ) -> Result<(), Error> {
        user.require_auth();

        // Rate limit dispute votes to prevent abuse
        if let Err(rate_err) = crate::rate_limiter::RateLimiter::new(env.clone())
            .rate_limit_disputes(user.clone(), market_id.clone())
        {
            if matches!(rate_err, crate::rate_limiter::RateLimiterError::ConfigNotFound) {
                // No rate limit config — skip
            } else {
                return Err(Error::from(rate_err));
            }
        }

        let result = disputes::DisputeManager::vote_on_dispute(
            &env, user, market_id.clone(), dispute_id, vote, stake, reason,
        );
        if result.is_ok() {
            // Invalidate analytics cache — dispute stakes have changed.
            analytics::AnalyticsCache::new(&env).invalidate(&market_id);
        }
        result
    }

    /// Resolve a dispute (admin only)
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn resolve_dispute(
        env: Env,
        admin: Address,
        market_id: Symbol,
    ) -> Result<disputes::DisputeResolution, Error> {
        Self::require_primary_admin(&env, &admin)?;

        let result = disputes::DisputeManager::resolve_dispute(&env, market_id.clone(), admin.clone());
        if result.is_ok() {
            // Per-market audit entry: DisputeResolved
            let details = Map::new(&env);
            crate::audit::MarketAuditManager::append(
                &env,
                &market_id,
                crate::audit::MarketAuditAction::DisputeResolved,
                admin,
                details,
            );
        }
        result
    }

    /// Sets the maximum capacity of resolved/expired disputes to retain in history (admin only).
    pub fn set_history_cap(
        env: Env,
        admin: Address,
        cap: u32,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        disputes::DisputeManager::set_history_cap(&env, admin, cap)
    }

    /// Sets the global anti-grief minimum stake floor (admin only).
    pub fn set_anti_grief_floor(
        env: Env,
        admin: Address,
        floor: i128,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        disputes::DisputeManager::set_anti_grief_floor(&env, admin, floor)
    }

    /// Collect fees from a market (admin only)
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn collect_fees(env: Env, admin: Address, market_id: Symbol) -> Result<i128, Error> {
        if let Err(e) =
            crate::circuit_breaker::CircuitBreaker::require_write_allowed(&env, "collect_fees")
        {
            return Err(e);
        }
        Self::require_primary_admin(&env, &admin)?;

        let result = fees::FeeManager::collect_fees(&env, admin.clone(), market_id.clone());
        if let Ok(amount) = result {
            // Per-market audit entry: FeesCollected
            let mut details = Map::new(&env);
            details.set(
                Symbol::new(&env, "amount"),
                String::from_str(&env, &alloc::format!("{}", amount)),
            );
            crate::audit::MarketAuditManager::append(
                &env,
                &market_id,
                crate::audit::MarketAuditAction::FeesCollected,
                admin,
                details,
            );
            Ok(amount)
        } else {
            result
        }
    }

    // ===== PER-MARKET AUDIT LOG READ ENTRYPOINTS =====

    /// Returns a reverse-chronological page of audit entries for `market_id`.
    ///
    /// Each entry records a key state change: market creation, resolution,
    /// dispute filing/resolution, or fee collection. Entries are immutable once
    /// written and are keyed by market so off-chain clients can efficiently stream
    /// the history for a single market without scanning the global audit trail.
    ///
    /// # Parameters
    ///
    /// * `env`       - The Soroban environment.
    /// * `market_id` - The market whose audit log to query.
    /// * `limit`     - Maximum number of entries to return; capped at 100.
    ///
    /// # Returns
    ///
    /// A `Vec<MarketAuditEntry>` ordered newest-first (index `total_entries` → 1).
    /// Returns an empty vector when the market has no audit entries.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "btc_50k");
    /// let entries = PredictifyHybrid::get_market_audit_log(env, market_id, 10);
    /// for entry in entries.iter() {
    ///     // entry.index, entry.action, entry.actor, entry.timestamp, entry.details
    /// }
    /// ```
    pub fn get_market_audit_log(
        env: Env,
        market_id: Symbol,
        limit: u32,
    ) -> Vec<crate::audit::MarketAuditEntry> {
        crate::audit::MarketAuditManager::get_entries(&env, &market_id, limit)
    }

    /// Returns a single audit entry for `market_id` by its 1-based `index`.
    ///
    /// # Parameters
    ///
    /// * `env`       - The Soroban environment.
    /// * `market_id` - The market whose audit log to query.
    /// * `index`     - 1-based entry index (`1` == oldest, `total_entries` == newest).
    ///
    /// # Returns
    ///
    /// `Some(MarketAuditEntry)` when found; `None` when `index` is 0, out of range,
    /// or the market has no entries.
    pub fn get_market_audit_entry(
        env: Env,
        market_id: Symbol,
        index: u32,
    ) -> Option<crate::audit::MarketAuditEntry> {
        crate::audit::MarketAuditManager::get_entry(&env, &market_id, index)
    }

    /// Returns the head (total entry count) of the per-market audit log.
    ///
    /// Clients can read this first to learn valid index bounds before calling
    /// [`get_market_audit_entry`] for individual entries.
    ///
    /// # Parameters
    ///
    /// * `env`       - The Soroban environment.
    /// * `market_id` - The market to query.
    ///
    /// # Returns
    ///
    /// `Some(MarketAuditHead)` when the market has at least one entry; `None` otherwise.
    pub fn get_market_audit_head(
        env: Env,
        market_id: Symbol,
    ) -> Option<crate::audit::MarketAuditHead> {
        crate::audit::MarketAuditManager::get_head(&env, &market_id)
    }

    /// Automatically distribute payouts to all winners after market resolution.
    ///
    /// This function automatically calculates and distributes winnings to all users
    /// who bet on the winning outcome, eliminating the need for manual claiming.
    /// It handles edge cases like no winners, all winners, and prevents double payouts.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the resolved market
    ///
    /// # Returns
    ///
    /// Returns `Result<i128, Error>` where:
    /// - `Ok(total_distributed)` - Total amount distributed to winners
    /// - `Err(Error)` - Error if distribution fails
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketNotResolved` - Market hasn't been resolved yet
    /// - `Error::MarketResolved` - Payouts have already been distributed
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "resolved_market");
    ///
    /// match PredictifyHybrid::distribute_payouts(env.clone(), market_id) {
    ///     Ok(total) => println!("Distributed {} stroops to winners", total),
    ///     Err(e) => println!("Distribution failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Payout Calculation
    ///
    /// Payouts are calculated using the formula:
    /// ```text
    /// user_payout = (user_stake * (100 - fee_percentage) / 100) * total_pool / winning_total
    /// ```
    ///
    /// # Edge Cases
    ///
    /// - **No Winners**: If no users bet on the winning outcome, no payouts are made
    /// - **All Winners**: If all users bet on the winning outcome, they receive proportional shares
    /// - **Double Payout Prevention**: Users who already claimed are skipped
    ///
    /// # Security & Testing
    ///
    /// - Tested for invariants using `proptest` to ensure:
    ///   - Total distributed `<= total pool` mathematically strictly.
    ///   - Fees are deducted predictably and exactly.
    ///   - Split pools evenly and proportionately distribute to tie winners without underflow.
    ///   - Failsafes prevent re-distribution.
    ///
    /// # Events
    ///
    /// This function emits `WinningsClaimedEvent` for each user who receives a payout.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    pub fn distribute_payouts(env: Env, market_id: Symbol) -> Result<i128, Error> {
        // ── Circuit breaker guard ──────────────────────────────────────────────
        if let Err(e) = CircuitBreaker::require_write_allowed(&env, "distribute_payouts") {
            return Err(e);
        }

        // ── Load market ────────────────────────────────────────────────────────
        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| {
                panic_with_error!(env, Error::MarketNotFound);
            });

        // ── Require resolved ───────────────────────────────────────────────────
        let winning_outcomes = match &market.winning_outcomes {
            Some(outcomes) => outcomes,
            None => return Err(Error::MarketNotResolved),
        };

        // ── Load bettor registry ───────────────────────────────────────────────
        let bettors = BetStorage::get_all_bets_for_market(&env, &market_id);

        // ── Platform fee (basis points, default 200 = 2%) ─────────────────────
        let fee_percent: i128 = env
            .storage()
            .persistent()
            .get(&Symbol::new(&env, "platform_fee"))
            .unwrap_or(200);

        // ── Short-circuit: check whether any unclaimed winners exist ───────────
        let mut has_unclaimed_winners = false;

        // Check voters
        for (user, outcome) in market.votes.iter() {
            if winning_outcomes.contains(&outcome) {
                if !market
                    .claimed
                    .get(user.clone())
                    .map(|info| info.is_claimed())
                    .unwrap_or(false)
                {
                    has_unclaimed_winners = true;
                    break;
                }
            }
        }

        // Check bettors (only if no unclaimed voters found yet)
        if !has_unclaimed_winners {
            for user in bettors.iter() {
                if let Some(bet) = BetStorage::get_bet(&env, &market_id, &user) {
                    if winning_outcomes.contains(&bet.outcome)
                        && !market
                            .claimed
                            .get(user.clone())
                            .map(|info| info.is_claimed())
                            .unwrap_or(false)
                    {
                        has_unclaimed_winners = true;
                        break;
                    }
                }
            }
        }

        if !has_unclaimed_winners {
            return Ok(0);
        }

        // ── Resolution summary (winning totals & pool size) ────────────────────
        let summary = ResolutionOutcomeCache::require(&env, &market_id, &market)?;
        let winning_total = summary.winning_total;
        if winning_total == 0 {
            return Ok(0);
        }

        let total_pool = summary.total_pool;
        let fee_denominator = 10_000i128;
        let mut total_distributed: i128 = 0;

        // ── Budget guard: abort before host runs out of CPU instructions ───────
        // Threshold of 100 000 instructions gives enough headroom to finish the
        // current iteration and write the updated market back to storage.
        let budget_guard = BudgetGuard::new(&env, 100_000);

        // ── 1. Distribute to Voters ────────────────────────────────────────────
        let mut voter_count = 0u32;
        for (user, outcome) in market.votes.iter() {
            if winning_outcomes.contains(&outcome) {
                // Skip already-claimed voters
                if market
                    .claimed
                    .get(user.clone())
                    .map(|info| info.is_claimed())
                    .unwrap_or(false)
                {
                    voter_count += 1;
                    if voter_count % 10 == 0 {
                        budget_guard.check()?;
                    }
                    continue;
                }

                let user_stake = market.stakes.get(user.clone()).unwrap_or(0);
                if user_stake > 0 {
                    let user_share = (user_stake
                        .checked_mul(fee_denominator - fee_percent)
                        .ok_or(Error::InvalidInput)?)
                        / fee_denominator;

                    let payout = (user_share
                        .checked_mul(total_pool)
                        .ok_or(Error::InvalidInput)?)
                        / winning_total;

                    if payout >= 0 {
                        market
                            .claimed
                            .set(user.clone(), ClaimInfo::new(&env, payout, 0u64));

                        if payout > 0 {
                            total_distributed = total_distributed
                                .checked_add(payout)
                                .ok_or(Error::InvalidInput)?;

                            BalanceStorage::add_balance(
                                &env,
                                &user,
                                &ReflectorAsset::Stellar,
                                payout,
                            )?;

                            EventEmitter::emit_winnings_claimed(
                                &env,
                                &market_id,
                                &user,
                                payout,
                            );
                        }
                    }
                }
            }

            voter_count += 1;
            if voter_count % 10 == 0 {
                budget_guard.check()?;
            }
        }

        // ── 2. Distribute to Bettors ───────────────────────────────────────────
        let mut bettor_count = 0u32;
        for user in bettors.iter() {
            if let Some(mut bet) = BetStorage::get_bet(&env, &market_id, &user) {
                if winning_outcomes.contains(&bet.outcome) {
                    // If already claimed via the voter path, just mark status Won
                    if market
                        .claimed
                        .get(user.clone())
                        .map(|info| info.is_claimed())
                        .unwrap_or(false)
                    {
                        bet.status = BetStatus::Won;
                        let _ = BetStorage::store_bet(&env, &bet);
                    } else if bet.amount > 0 {
                        let user_share = (bet.amount
                            .checked_mul(fee_denominator - fee_percent)
                            .ok_or(Error::InvalidInput)?)
                            / fee_denominator;

                        let payout = (user_share
                            .checked_mul(total_pool)
                            .ok_or(Error::InvalidInput)?)
                            / winning_total;

                        if payout > 0 {
                            market
                                .claimed
                                .set(user.clone(), ClaimInfo::new(&env, payout, 0u64));

                            total_distributed = total_distributed
                                .checked_add(payout)
                                .ok_or(Error::InvalidInput)?;

                            bet.status = BetStatus::Won;
                            let _ = BetStorage::store_bet(&env, &bet);

                            match BalanceStorage::add_balance(
                                &env,
                                &user,
                                &ReflectorAsset::Stellar,
                                payout,
                            ) {
                                Ok(_) => {}
                                Err(e) => panic_with_error!(env, e),
                            }

                            EventEmitter::emit_winnings_claimed(
                                &env,
                                &market_id,
                                &user,
                                payout,
                            );
                        }
                    }
                } else {
                    // Losing bet — mark as Lost
                    if matches!(bet.status, BetStatus::Active) {
                        bet.status = BetStatus::Lost;
                        let _ = BetStorage::store_bet(&env, &bet);
                    }
                }
            }

            bettor_count += 1;
            if bettor_count % 10 == 0 {
                budget_guard.check()?;
            }
        }

        // ── Final budget check before the storage write ────────────────────────
        budget_guard.check()?;

        // ── Persist updated claim map ──────────────────────────────────────────
        env.storage().persistent().set(&market_id, &market);

        Ok(total_distributed)
    }

    // ===== EVENT ARCHIVE AND HISTORICAL QUERY =====

    /// Mark a resolved or cancelled event (market) as archived. Admin only.
    /// Market must be in Resolved or Cancelled state. Returns InvalidState if not
    /// eligible, AlreadyClaimed if already archived.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn archive_event(env: Env, admin: Address, market_id: Symbol) -> Result<(), Error> {
        crate::event_archive::EventArchive::archive_event(&env, &admin, &market_id)
    }

    /// Remove the oldest `count` archived entries to free capacity (admin only).
    ///
    /// Returns the number of entries actually removed. `count` is capped at 30.
    ///
    /// # Errors
    /// * `Unauthorized` - Caller is not admin
    pub fn prune_archive(env: Env, admin: Address, count: u32, cursor: Option<crate::event_archive::PruneCursor>) -> Result<(u32, crate::event_archive::PruneCursor), Error> {
        crate::event_archive::EventArchive::prune_archive(&env, &admin, count, cursor)
    }

    /// Return the current number of entries in the event archive.
    pub fn archive_size(env: Env) -> u32 {
        crate::event_archive::EventArchive::archive_size(&env)
    }

    /// Query events by creation time range. Returns public metadata only (no votes/stakes).
    /// Paginated: cursor is start index, limit capped at 30. Returns (entries, next_cursor).
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn query_events_history(
        env: Env,
        from_ts: u64,
        to_ts: u64,
        cursor: u32,
        limit: u32,
    ) -> (Vec<EventHistoryEntry>, u32) {
        crate::event_archive::EventArchive::query_events_history(
            &env, from_ts, to_ts, cursor, limit,
        )
    }

    /// Query events by resolution status (e.g. Resolved, Cancelled). Paginated.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn query_events_by_status(
        env: Env,
        status: MarketState,
        cursor: u32,
        limit: u32,
    ) -> (Vec<EventHistoryEntry>, u32) {
        crate::event_archive::EventArchive::query_events_by_resolution_status(
            &env, status, cursor, limit,
        )
    }

    /// Query events by category (oracle feed_id). Paginated.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn query_events_by_category(
        env: Env,
        category: String,
        cursor: u32,
        limit: u32,
    ) -> (Vec<EventHistoryEntry>, u32) {
        crate::event_archive::EventArchive::query_events_by_category(&env, &category, cursor, limit)
    }

    /// Query archived events directly. Returns public metadata only (no votes/stakes).
    ///
    /// Archived events keep their terminal `Resolved`/`Cancelled` state
    /// (non-destructive archive), so they remain discoverable via
    /// `query_events_by_status` too. This entrypoint is the explicit "show me the
    /// archive" view, ordered by `archived_at`.
    ///
    /// * `reverse = false` - oldest archived first
    /// * `reverse = true`  - newest archived first
    ///
    /// Paginated: `cursor` is a zero-based offset into the archive ordering,
    /// `limit` is capped at 30. Returns `(entries, next_cursor)`; advance until
    /// `next_cursor == cursor` to finish.
    ///
    /// # Events
    ///
    /// Read-only query paths emit no events.
    pub fn query_archived_events(
        env: Env,
        reverse: bool,
        cursor: u32,
        limit: u32,
    ) -> (Vec<EventHistoryEntry>, u32) {
        crate::event_archive::EventArchive::query_archived_events(&env, reverse, cursor, limit)
    }

    /// Set the platform fee percentage (admin only).
    ///
    /// This function allows the admin to update the platform fee percentage
    /// within the allowed limits (0-10%). The fee is applied to winning payouts.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address (must be authorized)
    /// * `fee_percentage` - New fee percentage in basis points (e.g., 200 = 2%)
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Fee percentage updated successfully
    /// - `Err(Error)` - Error if update fails
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::InvalidFeeConfig` - Fee percentage is outside valid range (0-10%)
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    ///
    /// // Set platform fee to 2.5% (250 basis points)
    /// match PredictifyHybrid::set_platform_fee(env.clone(), admin, 250) {
    ///     Ok(()) => println!("Fee updated successfully"),
    ///     Err(e) => println!("Fee update failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Fee Limits
    ///
    /// - Minimum fee: 0% (0 basis points)
    /// - Maximum fee: 10% (1000 basis points)
    /// - Default fee: 2% (200 basis points)
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn set_platform_fee(env: Env, admin: Address, fee_percentage: i128) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        // Validate fee percentage (0-10%)
        if fee_percentage < 0 || fee_percentage > 1000 {
            return Err(Error::InvalidFeeConfig);
        }

        // Update fee in legacy storage
        let fee_key = Symbol::new(&env, "platform_fee");
        env.storage().persistent().set(&fee_key, &fee_percentage);

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::FeeConfigUpdated,
            admin.clone(),
            Map::new(&env),
            None,
        );

        Ok(())
    }

    /// Commit a hash of the new fee configuration (admin only)
    pub fn commit_fee_config(env: Env, admin: Address, hash: BytesN<32>) -> Result<(), Error> {
        fees::FeeManager::commit_fee_config(&env, admin, hash)
    }

    /// Reveal and apply a committed fee configuration (admin only)
    pub fn reveal_fee_config(env: Env, admin: Address, new_config: fees::FeeConfig) -> Result<fees::FeeConfig, Error> {
        fees::FeeManager::update_fee_config(&env, admin, new_config)
    }

    /// Set global minimum and maximum bet limits (admin only).
    /// Applies to all events that do not have per-event limits.
    /// Rejects if min > max or outside absolute bounds (MIN_BET_AMOUNT..=MAX_BET_AMOUNT).
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn set_global_bet_limits(
        env: Env,
        admin: Address,
        min_bet: i128,
        max_bet: i128,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        let limits = crate::types::BetLimits { min_bet, max_bet };
        crate::bets::set_global_bet_limits(&env, &limits)?;
        let scope = Symbol::new(&env, "global");
        EventEmitter::emit_bet_limits_updated(&env, &admin, &scope, min_bet, max_bet);

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::BetLimitsUpdated,
            admin.clone(),
            Map::new(&env),
            None,
        );

        Ok(())
    }

    /// Set per-event minimum and maximum bet limits (admin only).
    /// Overrides global limits for the given market.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn set_event_bet_limits(
        env: Env,
        admin: Address,
        market_id: Symbol,
        min_bet: i128,
        max_bet: i128,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        let limits = BetLimits { min_bet, max_bet };
        crate::bets::set_event_bet_limits(&env, &market_id, &limits)?;
        EventEmitter::emit_bet_limits_updated(&env, &admin, &market_id, min_bet, max_bet);
        Ok(())
    }

    /// Get effective bet limits for a market (per-event if set, else global, else defaults).
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_effective_bet_limits(env: Env, market_id: Symbol) -> BetLimits {
        crate::bets::get_effective_bet_limits(&env, &market_id)
    }

    /// Set the per-market maximum single-bet cap (admin only).
    ///
    /// Once set, any individual bet whose `amount` exceeds `cap` is rejected with
    /// [`Error::BetExceedsCap`].  The cap is checked after, and in addition to, the
    /// global/per-event `max_bet` in [`BetLimits`].
    ///
    /// Pass `cap = 0` to remove the cap (equivalent to calling
    /// [`remove_market_max_bet_cap`]).  Any other value must satisfy
    /// `0 < cap <= MAX_BET_AMOUNT`.
    ///
    /// # Parameters
    ///
    /// - `admin`     – Must be the primary admin address
    /// - `market_id` – Identifies the target market
    /// - `cap`       – Maximum single-bet amount in base token units (stroops)
    ///
    /// # Errors
    ///
    /// - [`Error::Unauthorized`] when `admin` is not the primary admin
    /// - [`Error::InvalidInput`] when `cap` is negative or exceeds [`MAX_BET_AMOUNT`]
    ///
    /// # Events
    ///
    /// Emits a `bet_limits_updated` event scoped to `market_id` so that indexers
    /// can track cap changes.
    pub fn set_market_max_bet_cap(
        env: Env,
        admin: Address,
        market_id: Symbol,
        cap: i128,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        // cap == 0 is treated as "remove the cap"
        if cap == 0 {
            crate::bets::remove_market_max_bet_cap(&env, &market_id);
        } else {
            crate::bets::set_market_max_bet_cap(&env, &market_id, cap)?;
        }
        // Emit so indexers can observe
        EventEmitter::emit_bet_limits_updated(&env, &admin, &market_id, 0, cap);

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::BetLimitsUpdated,
            admin.clone(),
            Map::new(&env),
            None,
        );

        Ok(())
    }

    /// Get the per-market max single-bet cap, or `None` if no cap is configured.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_market_max_bet_cap(env: Env, market_id: Symbol) -> Option<i128> {
        crate::bets::get_market_max_bet_cap(&env, &market_id)
    }

    /// Remove the per-market max single-bet cap (admin only).
    ///
    /// After removal, bets on this market are bounded only by the global/per-event
    /// [`BetLimits`] `max_bet` (or [`MAX_BET_AMOUNT`] when no limits are configured).
    ///
    /// # Errors
    ///
    /// - [`Error::Unauthorized`] when `admin` is not the primary admin
    ///
    /// # Events
    ///
    /// Emits a `bet_limits_updated` event with `max_bet = 0` to signal removal.
    pub fn remove_market_max_bet_cap(
        env: Env,
        admin: Address,
        market_id: Symbol,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        crate::bets::remove_market_max_bet_cap(&env, &market_id);
        EventEmitter::emit_bet_limits_updated(&env, &admin, &market_id, 0, 0);
        Ok(())
    }

    pub fn set_max_participants(
        env: Env,
        admin: Address,
        market_id: Symbol,
        max_participants: Option<u32>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| panic_with_error!(&env, Error::MarketNotFound));
        market.max_participants = max_participants;
        env.storage().persistent().set(&market_id, &market);
        Ok(())
    }

    /// Set global oracle validation config (admin only).
    ///
    /// - `max_staleness_secs`: maximum allowed age in seconds.
    /// - `max_confidence_bps`: maximum confidence interval in basis points.
    /// Per-event overrides, if set, take precedence over this global config.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn set_oracle_val_cfg_global(
        env: Env,
        admin: Address,
        max_staleness_secs: u64,
        max_confidence_bps: u32,
        max_deviation_bps: Option<u32>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        crate::admin::OracleAdminCooldownManager::enforce_cooldown(&env, &admin)?;

        let config = GlobalOracleValidationConfig {
            max_staleness_secs,
            max_confidence_bps,
            max_deviation_bps,
            max_deviation_z_multiple: None,
            history_size: None,
            auto_pause_duration_secs: None,
        };
        crate::oracles::OracleValidationConfigManager::set_global_config(&env, &config)?;

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::OracleConfigUpdated,
            admin.clone(),
            Map::new(&env),
            None,
        );

        Ok(())
    }

    /// Set per-event oracle validation config (admin only).
    ///
    /// Overrides global validation settings for the given market.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn set_oracle_val_cfg_event(
        env: Env,
        admin: Address,
        market_id: Symbol,
        max_staleness_secs: u64,
        max_confidence_bps: u32,
        max_deviation_bps: Option<u32>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        crate::admin::OracleAdminCooldownManager::enforce_cooldown(&env, &admin)?;

        let config = EventOracleValidationConfig {
            max_staleness_secs,
            max_confidence_bps,
            max_deviation_bps,
            max_deviation_z_multiple: None,
            history_size: None,
            auto_pause_duration_secs: None,
        };
        crate::oracles::OracleValidationConfigManager::set_event_config(&env, &market_id, &config)?;

        let mut details = Map::new(&env);
        details.set(
            Symbol::new(&env, "market_id"),
            String::from_str(&env, "market_updated"),
        );

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::OracleConfigUpdated,
            admin.clone(),
            details,
            None,
        );

        Ok(())
    }

    /// Get effective oracle validation config for a market.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_oracle_val_cfg_effective(
        env: Env,
        market_id: Symbol,
    ) -> GlobalOracleValidationConfig {
        crate::oracles::OracleValidationConfigManager::get_effective_config(&env, &market_id)
    }

    /// Withdraw collected platform fees (admin only).
    ///
    /// This function allows the admin to withdraw fees that have been collected
    /// from market payouts. Fees are accumulated across all markets and can be
    /// withdrawn by the admin.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address (must be authorized)
    /// * `amount` - Amount to withdraw (in stroops). If 0, withdraws all available fees.
    ///
    /// # Returns
    ///
    /// Returns `Result<i128, Error>` where:
    /// - `Ok(amount_withdrawn)` - Amount successfully withdrawn
    /// - `Err(Error)` - Error if withdrawal fails
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::NoFeesToCollect` - No fees available to withdraw
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    ///
    /// // Withdraw all available fees
    /// match PredictifyHybrid::withdraw_collected_fees(env.clone(), admin, 0) {
    ///     Ok(amount) => println!("Withdrew {} stroops", amount),
    ///     Err(e) => println!("Withdrawal failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn withdraw_collected_fees(env: Env, admin: Address, amount: i128) -> Result<i128, Error> {
        Self::require_primary_admin(&env, &admin)?;

        // Route through the timelocked fee withdrawal manager to enforce
        // the withdrawal schedule (timelock + cap). This prevents the admin
        // from bypassing the schedule by calling this entrypoint directly.
        fees::FeeWithdrawalManager::withdraw_fees(&env, &admin, amount)
    }

    /// Extends the deadline of an active market by a specified number of days (admin only).
    ///
    /// This function allows contract administrators to extend the voting/betting period
    /// of active markets. Extensions can be used to allow more time for participation,
    /// respond to unforeseen circumstances, or adjust to market conditions. The function
    /// enforces maximum extension limits and validates market state before applying changes.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the extension (must be authorized)
    /// * `market_id` - Unique identifier of the market to extend
    /// * `additional_days` - Number of days to add to the current end time
    /// * `reason` - Explanation for why the extension is needed
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Market deadline extended successfully
    /// - `Err(Error)` - Specific error if extension fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketResolved` - Cannot extend a resolved market
    /// - `Error::InvalidDuration` - Extension would exceed maximum allowed limit
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol, String};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Extend market by 7 days
    /// match PredictifyHybrid::extend_deadline(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     7,
    ///     String::from_str(&env, "Low participation - extending to allow more votes")
    /// ) {
    ///     Ok(()) => println!("Market deadline extended successfully"),
    ///     Err(e) => println!("Extension failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Extension Rules
    ///
    /// - Market must be in Active or Ended state (not Resolved, Closed, or Cancelled)
    /// - Total extensions cannot exceed `max_extension_days` (default 30 days)
    /// - Extensions are recorded in market's extension history
    /// - Admin must pay extension fee if configured
    ///
    /// # Security
    ///
    /// This function requires admin authentication and should be used carefully.
    /// Excessive extensions may affect user trust and market integrity. All
    /// extensions are logged with timestamps and reasons for transparency.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn extend_deadline(
        env: Env,
        admin: Address,
        market_id: Symbol,
        additional_days: u32,
        reason: String,
    ) -> Result<(), Error> {
        admin.require_auth();

        // Verify admin
        let stored_admin: Address =
            match env.storage().persistent().get(&Symbol::new(&env, "Admin")) {
                Some(admin_addr) => admin_addr,
                None => panic_with_error!(env, Error::AdminNotSet),
            };

        if admin != stored_admin {
            return Err(Error::Unauthorized);
        }

        // Delegate to ExtensionManager for core logic, fee handling, and events
        crate::extensions::ExtensionManager::extend_market_duration(
            &env,
            admin,
            market_id,
            additional_days,
            reason,
        )
        .unwrap_or_else(|e| panic_with_error!(env, e));

        Ok(())
    }

    /// Updates the description/question of a market (admin only, before betting starts).
    ///
    /// This function allows contract administrators to update the market question
    /// or description before any bets have been placed. This ensures that market
    /// parameters can be corrected or clarified without affecting existing user
    /// commitments or predictions.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the update (must be authorized)
    /// * `market_id` - Unique identifier of the market to update
    /// * `new_description` - The updated market question or description
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Market description updated successfully
    /// - `Err(Error)` - Specific error if update fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketResolved` - Cannot update a resolved market
    /// - `Error::BetsAlreadyPlaced` - Cannot update after bets have been placed
    /// - `Error::InvalidQuestion` - New description is empty or invalid
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol, String};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Update market description
    /// match PredictifyHybrid::update_event_description(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     String::from_str(&env, "Will Bitcoin reach $100,000 by December 31, 2024?")
    /// ) {
    ///     Ok(()) => println!("Market description updated successfully"),
    ///     Err(e) => println!("Update failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Update Rules
    ///
    /// - Market must be in Active state
    /// - No bets can have been placed yet
    /// - Market must not be resolved
    /// - New description must be non-empty and meet length requirements
    ///
    /// # Security
    ///
    /// This function requires admin authentication and validates that no user
    /// funds are at risk. Updates are only allowed before any betting activity
    /// to maintain fairness and transparency.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn update_event_description(
        env: Env,
        admin: Address,
        market_id: Symbol,
        new_description: String,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        // Validate new description using the same rules as creation-time inputs.
        if let Err(e) = crate::validation::CreationValidator::validate_event_description(
            &env,
            &new_description,
        ) {
            return Err(e);
        }

        // Get market
        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| panic_with_error!(env, Error::MarketNotFound));

        // Validate market state - cannot update resolved, closed, or cancelled markets
        if market.state != MarketState::Active {
            panic_with_error!(env, Error::MarketResolved);
        }

        // Check if any bets have been placed
        let bet_stats = bets::BetManager::get_market_bet_stats(&env, &market_id);
        if bet_stats.total_bets > 0 {
            panic_with_error!(env, Error::BetsAlreadyPlaced);
        }

        // Check if any votes have been placed
        if market.total_staked > 0 {
            panic_with_error!(env, Error::AlreadyVoted);
        }

        // Store old description for event
        let old_description = market.question.clone();

        // Update market description and refresh the metadata commitment so
        // clients with stale cached metadata fail verification.
        market.question = new_description.clone();
        market.refresh_metadata_commitment(&env);

        // Save market
        env.storage().persistent().set(&market_id, &market);

        // Emit description update event
        EventEmitter::emit_market_description_updated(
            &env,
            &market_id,
            &old_description,
            &new_description,
            &admin,
        );

        let mut details = Map::new(&env);
        details.set(
            Symbol::new(&env, "update"),
            String::from_str(&env, "description"),
        );
        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::MarketUpdated,
            admin.clone(),
            details,
            None,
        );

        Ok(())
    }

    /// Updates the outcomes of a market (admin only, before betting starts).
    ///
    /// This function allows contract administrators to update the available
    /// outcomes for a market before any bets have been placed. This ensures
    /// that market parameters can be corrected or adjusted without affecting
    /// existing user commitments.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the update (must be authorized)
    /// * `market_id` - Unique identifier of the market to update
    /// * `new_outcomes` - The updated list of possible outcomes
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Market outcomes updated successfully
    /// - `Err(Error)` - Specific error if update fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketResolved` - Cannot update a resolved market
    /// - `Error::BetsAlreadyPlaced` - Cannot update after bets have been placed
    /// - `Error::InvalidOutcomes` - New outcomes list is invalid (< 2 outcomes or empty strings)
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol, String, Vec};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Update market outcomes
    /// let new_outcomes = Vec::from_array(&env, [
    ///     String::from_str(&env, "Yes"),
    ///     String::from_str(&env, "No"),
    ///     String::from_str(&env, "Uncertain")
    /// ]);
    ///
    /// match PredictifyHybrid::update_event_outcomes(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     new_outcomes
    /// ) {
    ///     Ok(()) => println!("Market outcomes updated successfully"),
    ///     Err(e) => println!("Update failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Update Rules
    ///
    /// - Market must be in Active state
    /// - No bets can have been placed yet
    /// - Market must not be resolved
    /// - New outcomes must have at least 2 options
    /// - All outcome strings must be non-empty
    ///
    /// # Security
    ///
    /// This function requires admin authentication and validates that no user
    /// funds are at risk. Updates are only allowed before any betting activity
    /// to maintain fairness and transparency.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn update_event_outcomes(
        env: Env,
        admin: Address,
        market_id: Symbol,
        new_outcomes: Vec<String>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        // Validate new outcomes using the same rules as creation-time inputs.
        if let Err(e) = crate::validation::CreationValidator::validate_creation_outcomes(
            &env,
            &new_outcomes,
        ) {
            return Err(e);
        }

        // Get market
        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| panic_with_error!(env, Error::MarketNotFound));

        // Validate market state - cannot update resolved, closed, or cancelled markets
        if market.state != MarketState::Active {
            panic_with_error!(env, Error::MarketResolved);
        }

        // Check if any bets have been placed
        let bet_stats = bets::BetManager::get_market_bet_stats(&env, &market_id);
        if bet_stats.total_bets > 0 {
            panic_with_error!(env, Error::BetsAlreadyPlaced);
        }

        // Check if any votes have been placed
        if market.total_staked > 0 {
            panic_with_error!(env, Error::AlreadyVoted);
        }

        // Store old outcomes for event
        let old_outcomes = market.outcomes.clone();

        // Update market outcomes and refresh the commitment so stale clients
        // holding the old metadata commitment fail verification.
        market.outcomes = new_outcomes.clone();
        market.refresh_metadata_commitment(&env);

        // Save market
        env.storage().persistent().set(&market_id, &market);

        // Emit outcomes update event
        EventEmitter::emit_market_outcomes_updated(
            &env,
            &market_id,
            &old_outcomes,
            &new_outcomes,
            &admin,
        );

        let mut details = Map::new(&env);
        details.set(
            Symbol::new(&env, "update"),
            String::from_str(&env, "outcomes"),
        );
        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::MarketUpdated,
            admin.clone(),
            details,
            None,
        );

        Ok(())
    }

    /// Updates the category of a market (admin only, before betting starts).
    ///
    /// This function allows contract administrators to set or update the category
    /// for a market before any bets have been placed. Categories help clients
    /// filter and display markets by type (e.g., sports, crypto, politics).
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the update (must be authorized)
    /// * `market_id` - Unique identifier of the market to update
    /// * `category` - The new category (None to clear the category)
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Market category updated successfully
    /// - `Err(Error)` - Specific error if update fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketResolved` - Cannot update a resolved market
    /// - `Error::BetsAlreadyPlaced` - Cannot update after bets have been placed
    /// - `Error::InvalidInput` - `Some` with an empty category string, or other invalid optional payload
    /// - `Error::CategoryTooShort` / `Error::CategoryTooLong` - Category length outside configured bounds
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol, String};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Set market category
    /// match PredictifyHybrid::update_event_category(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     Some(String::from_str(&env, "sports"))
    /// ) {
    ///     Ok(()) => println!("Market category updated successfully"),
    ///     Err(e) => println!("Update failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn update_event_category(
        env: Env,
        admin: Address,
        market_id: Symbol,
        category: Option<String>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        // Get market
        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .ok_or(Error::MarketNotFound)?;

        // Validate market state - cannot update resolved, closed, or cancelled markets
        if market.state != MarketState::Active {
            return Err(Error::MarketResolved);
        }

        // Check if any bets have been placed
        let bet_stats = bets::BetManager::get_market_bet_stats(&env, &market_id);
        if bet_stats.total_bets > 0 {
            return Err(Error::BetsAlreadyPlaced);
        }

        // Check if any votes have been placed
        if market.total_staked > 0 {
            return Err(Error::AlreadyVoted);
        }

        crate::metadata_limits::validate_option_category_metadata(&category)?;

        // Store old category for event
        let old_category = market.category.clone();

        // Update market category
        market.category = category.clone();

        // Save market
        env.storage().persistent().set(&market_id, &market);

        // Emit category update event
        EventEmitter::emit_category_updated(&env, &market_id, &old_category, &category, &admin);

        let mut details = Map::new(&env);
        details.set(
            Symbol::new(&env, "update"),
            String::from_str(&env, "category"),
        );
        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::MarketUpdated,
            admin.clone(),
            details,
            None,
        );

        Ok(())
    }

    /// Updates the tags of a market (admin only, before betting starts).
    ///
    /// This function allows contract administrators to set or update tags
    /// for a market before any bets have been placed. Tags help clients
    /// filter and search markets by multiple dimensions.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address performing the update (must be authorized)
    /// * `market_id` - Unique identifier of the market to update
    /// * `tags` - The new list of tags (empty Vec to clear all tags)
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Market tags updated successfully
    /// - `Err(Error)` - Specific error if update fails
    ///
    /// # Errors
    ///
    /// This function returns specific errors:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketResolved` - Cannot update a resolved market
    /// - `Error::BetsAlreadyPlaced` - Cannot update after bets have been placed
    /// - `Error::InvalidInput` - Empty tag entry, duplicate tags, or other invalid list content
    /// - `Error::TagTooShort` / `Error::TagTooLong` - Tag length outside configured bounds
    /// - `Error::TooManyTags` - More than the maximum number of tags per market
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, Symbol, String, vec};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// // Set market tags
    /// let tags = vec![
    ///     &env,
    ///     String::from_str(&env, "bitcoin"),
    ///     String::from_str(&env, "crypto"),
    ///     String::from_str(&env, "price-prediction")
    /// ];
    ///
    /// match PredictifyHybrid::update_event_tags(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     tags
    /// ) {
    ///     Ok(()) => println!("Market tags updated successfully"),
    ///     Err(e) => println!("Update failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn update_event_tags(
        env: Env,
        admin: Address,
        market_id: Symbol,
        tags: Vec<String>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        crate::metadata_limits::validate_event_tags(&tags)?;

        // Get market
        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .ok_or(Error::MarketNotFound)?;

        // Validate market state - cannot update resolved, closed, or cancelled markets
        if market.state != MarketState::Active {
            return Err(Error::MarketResolved);
        }

        // Check if any bets have been placed
        let bet_stats = bets::BetManager::get_market_bet_stats(&env, &market_id);
        if bet_stats.total_bets > 0 {
            return Err(Error::BetsAlreadyPlaced);
        }

        // Check if any votes have been placed
        if market.total_staked > 0 {
            return Err(Error::AlreadyVoted);
        }

        // Store old tags for event
        let old_tags = market.tags.clone();

        // Update market tags
        market.tags = tags.clone();

        // Save market
        env.storage().persistent().set(&market_id, &market);

        // Emit tags update event
        EventEmitter::emit_tags_updated(&env, &market_id, &old_tags, &tags, &admin);

        let mut details = Map::new(&env);
        details.set(Symbol::new(&env, "update"), String::from_str(&env, "tags"));
        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::MarketUpdated,
            admin.clone(),
            details,
            None,
        );

        Ok(())
    }

    /// Query events by tags (paginated, bounded).
    ///
    /// Returns events that have ANY of the provided tags (OR logic).
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `tags` - Tags to filter by (events matching any tag are returned)
    /// * `cursor` - Pagination cursor
    /// * `limit` - Maximum results per page
    ///
    /// # Returns
    ///
    /// Tuple of (events, next_cursor)
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn query_events_by_tags(
        env: Env,
        tags: Vec<String>,
        cursor: u32,
        limit: u32,
    ) -> (Vec<EventHistoryEntry>, u32) {
        event_archive::EventArchive::query_events_by_tags(&env, &tags, cursor, limit)
    }

    /// Return a paginated page of market IDs.
    ///
    /// Avoids unbounded `Vec` returns by slicing the market index.
    /// Pass `next_cursor` from the previous response as `cursor` on the next
    /// call.  Iteration is complete when `items.len() < limit`.
    ///
    /// # Parameters
    ///
    /// * `env` - Soroban environment
    /// * `cursor` - Zero-based start index (0 for first page)
    /// * `limit` - Desired page size; capped server-side at 50
    ///
    /// # Returns
    ///
    /// `PagedMarketIds` with `items`, `next_cursor`, and `total_count`.
    ///
    /// # Errors
    ///
    /// Panics with `Error::ContractStateError` if the market index is corrupted.
    ///
    /// # Events
    ///
    /// Read-only; no events emitted.
    pub fn get_all_markets_paged(env: Env, cursor: u32, limit: u32) -> PagedMarketIds {
        crate::queries::QueryManager::get_all_markets_paged(&env, cursor, limit)
            .unwrap_or_else(|e| panic_with_error!(&env, e))
    }

    /// Return a paginated page of a user's bets across markets.
    ///
    /// Scans the market index slice `[cursor, cursor+limit)` and returns only
    /// markets where `user` has placed a bet.  Prevents gas exhaustion on
    /// large market lists.
    ///
    /// # Parameters
    ///
    /// * `env` - Soroban environment
    /// * `user` - Address to query
    /// * `cursor` - Zero-based start index into the market list
    /// * `limit` - Page size; capped server-side at 50
    ///
    /// # Returns
    ///
    /// `PagedUserBets` with `items`, `next_cursor`, and `total_count`.
    ///
    /// # Errors
    ///
    /// Panics with `Error::ContractStateError` if the market index is corrupted.
    ///
    /// # Events
    ///
    /// Read-only; no events emitted.
    pub fn query_user_bets_paged(
        env: Env,
        user: Address,
        cursor: u32,
        limit: u32,
    ) -> PagedUserBets {
        crate::queries::QueryManager::query_user_bets_paged(&env, user, cursor, limit)
            .unwrap_or_else(|e| panic_with_error!(&env, e))
    }

    /// Return partial contract state statistics for a market-list page.
    ///
    /// Processes only the market slice `[cursor, cursor+limit)`.  Callers
    /// accumulate results across pages to build a full aggregate.
    ///
    /// # Parameters
    ///
    /// * `env` - Soroban environment
    /// * `cursor` - Start index into the market list
    /// * `limit` - Page size; capped server-side at 50
    ///
    /// # Returns
    ///
    /// `(ContractStateQuery, next_cursor)` — partial stats and the cursor for
    /// the next call.
    ///
    /// # Errors
    ///
    /// Panics with `Error::ContractStateError` if the market index is corrupted.
    ///
    /// # Events
    ///
    /// Read-only; no events emitted.
    pub fn query_contract_state_paged(
        env: Env,
        cursor: u32,
        limit: u32,
    ) -> (ContractStateQuery, u32) {
        crate::queries::QueryManager::query_contract_state_paged(&env, cursor, limit)
            .unwrap_or_else(|e| panic_with_error!(&env, e))
    }

    /// Cancel an event and automatically refund all placed bets (admin only).
    ///
    /// This function allows admins to cancel events before resolution and
    /// automatically refund all bets placed on the market. It validates
    /// cancellation conditions, updates market status, and processes refunds.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address (must be authorized)
    /// * `market_id` - Unique identifier of the market to cancel
    /// * `reason` - Optional reason for cancellation
    ///
    /// # Returns
    ///
    /// Returns `Result<i128, Error>` where:
    /// - `Ok(total_refunded)` - Total amount refunded to users
    /// - `Err(Error)` - Error if cancellation fails
    ///
    /// # Panics
    ///
    /// This function will panic with specific errors if:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    /// - `Error::MarketResolved` - Market has already been resolved
    /// - `Error::InvalidState` - Market is in an invalid state for cancellation
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, String, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// match PredictifyHybrid::cancel_event(
    ///     env.clone(),
    ///     admin,
    ///     market_id,
    ///     Some(String::from_str(&env, "Oracle data unavailable"))
    /// ) {
    ///     Ok(total) => println!("Refunded {} stroops", total),
    ///     Err(e) => println!("Cancellation failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Cancellation Conditions
    ///
    /// - Market must exist and be active
    /// - Market must not be resolved
    /// - Market must not already be cancelled
    /// - Only admin can cancel events
    ///
    /// # Refund Process
    ///
    /// 1. All active bets are identified
    /// 2. Funds are unlocked and returned to users
    /// 3. Bet status is updated to "Refunded"
    /// 4. Market state is updated to "Cancelled"
    /// 5. Cancellation and refund events are emitted
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn cancel_event(
        env: Env,
        admin: Address,
        market_id: Symbol,
        reason: Option<String>,
    ) -> Result<i128, Error> {
        Self::require_primary_admin(&env, &admin)?;

        // Get and validate market
        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .unwrap_or_else(|| {
                panic_with_error!(env, Error::MarketNotFound);
            });

        // Validate cancellation conditions
        if market.state == MarketState::Resolved {
            return Err(Error::MarketResolved);
        }

        if market.state == MarketState::Cancelled {
            // Already cancelled, return 0 refunded
            return Ok(0);
        }

        // Market must be active or ended (not resolved)
        if !matches!(market.state, MarketState::Active | MarketState::Ended) {
            return Err(Error::InvalidState);
        }

        // Capture old state for event
        let old_state = market.state.clone();

        // Update market state to cancelled
        market.state = MarketState::Cancelled;
        env.storage().persistent().set(&market_id, &market);

        // Refund all bets (batch of token transfers)
        let refund_result = bets::BetManager::refund_market_bets(&env, &market_id);
        refund_result?;

        // Calculate total refunded (sum of all bets)
        let total_refunded = market.total_staked;

        let mut details = Map::new(&env);
        if let Some(r) = &reason {
            details.set(Symbol::new(&env, "reason"), r.clone());
        }
        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::EventCancelled,
            admin.clone(),
            details,
            None,
        );

        // Emit cancellation event
        EventEmitter::emit_state_change_event(
            &env,
            &market_id,
            &old_state,
            &MarketState::Cancelled,
            &reason.unwrap_or_else(|| String::from_str(&env, "Event cancelled by admin")),
        );

        // Emit market closed event
        EventEmitter::emit_market_closed(&env, &market_id, &admin);

        Ok(total_refunded)
    }

    /// Refund all bets when oracle resolution fails or times out (automatic refund path).
    ///
    /// Callable when: market has ended, no oracle result, and either (1) resolution
    /// timeout has passed since market end, or (2) caller is admin (confirmed failure).
    /// Refunds full bet amount per user (no fee deduction). Marks market as cancelled and
    /// prevents further resolution. Emits refund events. Idempotent when already cancelled.
    ///
    /// The timeout gate is evaluated per market from `end_time + resolution_timeout`.
    /// Non-admin callers cannot trigger this path before that market-specific deadline.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn refund_on_oracle_failure(
        env: Env,
        caller: Address,
        market_id: Symbol,
    ) -> Result<i128, Error> {
        caller.require_auth();

        let mut market: Market = env
            .storage()
            .persistent()
            .get(&market_id)
            .ok_or(Error::MarketNotFound)?;

        if market.state == MarketState::Cancelled {
            return Ok(0);
        }
        if market.winning_outcomes.is_some() {
            return Err(Error::MarketResolved);
        }
        if market.oracle_result.is_some() {
            return Err(Error::MarketResolved);
        }
        let current_time = env.ledger().timestamp();
        if current_time < market.end_time {
            return Err(Error::MarketClosed);
        }

        let stored_admin: Option<Address> =
            env.storage().persistent().get(&Symbol::new(&env, "Admin"));
        let is_admin = stored_admin.as_ref().map_or(false, |a| a == &caller);
        let timeout_passed = resolution_timeout_reached(&env, &market);
        if !is_admin && !timeout_passed {
            return Err(Error::Unauthorized);
        }

        let old_state = market.state.clone();
        market.state = MarketState::Cancelled;
        env.storage().persistent().set(&market_id, &market);

        let refund_result = bets::BetManager::refund_market_bets(&env, &market_id);
        refund_result?;

        let total_refunded = market.total_staked;
        EventEmitter::emit_state_change_event(
            &env,
            &market_id,
            &old_state,
            &MarketState::Cancelled,
            &String::from_str(&env, "Refund on oracle failure/timeout"),
        );
        EventEmitter::emit_refund_on_oracle_failure(&env, &market_id, total_refunded);

        Ok(total_refunded)
    }

    /// Extend market duration (admin only)
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn extend_market(
        env: Env,
        admin: Address,
        market_id: Symbol,
        additional_days: u32,
        reason: String,
        _fee_amount: i128,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;

        extensions::ExtensionManager::extend_market_duration(
            &env,
            admin,
            market_id,
            additional_days,
            reason,
        )
    }

    /// Sets the admin-configurable cumulative extension cap (in days) that applies
    /// globally to all markets. A value of `0` disables the cap.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Unauthorized`] when the caller is not the primary admin.
    ///
    /// # Events
    ///
    /// Emits no events; purely a configuration write.
    pub fn set_cumulative_extension_cap(
        env: Env,
        admin: Address,
        cap_days: u32,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        let key = Symbol::new(&env, "cum_ext_cap");
        env.storage().persistent().set(&key, &cap_days);
        Ok(())
    }

    /// Returns the running cumulative extension total (in days) for a given market.
    /// Returns `0` when no extensions have been recorded yet.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_cumulative_extension_total(env: Env, market_id: Symbol) -> Result<u32, Error> {
        let key = crate::storage::DataKey::MarketExtensionTotal(market_id);
        Ok(env.storage().persistent().get(&key).unwrap_or(0u32))
    }

    // ===== STORAGE OPTIMIZATION FUNCTIONS =====

    /// Compress market data for storage optimization
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn compress_market_data(
        env: Env,
        market_id: Symbol,
    ) -> Result<storage::CompressedMarket, Error> {
        let market = match markets::MarketStateManager::get_market(&env, &market_id) {
            Ok(m) => m,
            Err(e) => return Err(e),
        };

        storage::StorageOptimizer::compress_market_data(&env, &market)
    }

    /// Clean up old market data based on age and state
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn cleanup_old_market_data(env: Env, market_id: Symbol) -> Result<bool, Error> {
        storage::StorageOptimizer::cleanup_old_market_data(&env, &market_id)
    }

    /// Migrate storage format from old to new format
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn migrate_storage_format(
        env: Env,
        from_format: storage::StorageFormat,
        to_format: storage::StorageFormat,
    ) -> Result<storage::StorageMigration, Error> {
        let result =
            storage::StorageOptimizer::migrate_storage_format(&env, from_format, to_format);

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::StorageMigrated,
            env.current_contract_address(),
            Map::new(&env),
            None,
        );

        result
    }

    /// Read-only recovery dry run for ops verification.
    ///
    /// Returns the recovery plan that `recover_market_state` would follow without
    /// executing any side effects. No admin authentication is required. Useful for
    /// pre-flight checks before executing a live recovery.
    ///
    /// # Parameters
    /// * `env` - The Soroban environment.
    /// * `market_id` - The market to analyse.
    ///
    /// # Returns
    /// A [`recovery::DryRunResult`] describing integrity status, detected issues,
    /// and planned recovery actions.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn recovery_dry_run(
        env: Env,
        market_id: Symbol,
    ) -> crate::recovery::DryRunResult {
        match crate::recovery::RecoveryManager::recovery_dry_run(&env, &market_id) {
            Ok(result) => result,
            Err(e) => panic_with_error!(env, e),
        }
    }


    /// Promote resolved market metadata from Temporary to Persistent storage
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    pub fn promote_market_to_persistent(
        env: Env,
        market_id: Symbol,
    ) -> Result<(), Error> {
        storage::StorageMigration::promote_market_to_persistent(&env, &market_id)
    }

    /// Demote scratch keys from Persistent to Temporary storage
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    pub fn demote_scratch_keys(
        env: Env,
        market_id: Symbol,
    ) -> Result<(), Error> {
        storage::StorageMigration::demote_scratch_keys(&env, &market_id)
    }

    /// Monitor storage usage and return statistics
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn monitor_storage_usage(env: Env) -> Result<storage::StorageUsageStats, Error> {
        storage::StorageOptimizer::monitor_storage_usage(&env)
    }

    /// Optimize storage layout for a specific market
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn optimize_storage_layout(env: Env, market_id: Symbol) -> Result<bool, Error> {
        storage::StorageOptimizer::optimize_storage_layout(&env, &market_id)
    }

    /// Get storage usage statistics
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_storage_usage_statistics(env: Env) -> Result<storage::StorageUsageStats, Error> {
        storage::StorageOptimizer::get_storage_usage_statistics(&env)
    }

    /// Validate storage integrity for a specific market
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_storage_integrity(
        env: Env,
        market_id: Symbol,
    ) -> Result<storage::StorageIntegrityResult, Error> {
        storage::StorageOptimizer::validate_storage_integrity(&env, &market_id)
    }

    /// Get storage configuration
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_storage_config(env: Env) -> storage::StorageConfig {
        storage::StorageOptimizer::get_storage_config(&env)
    }

    /// Update storage configuration
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn update_storage_config(env: Env, config: storage::StorageConfig) -> Result<(), Error> {
        storage::StorageOptimizer::update_storage_config(&env, &config)
    }

    /// Calculate storage cost for a market
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn calculate_storage_cost(env: Env, market_id: Symbol) -> Result<u64, Error> {
        let market = match markets::MarketStateManager::get_market(&env, &market_id) {
            Ok(m) => m,
            Err(e) => return Err(e),
        };

        Ok(storage::StorageUtils::calculate_storage_cost(&market))
    }

    /// Get storage efficiency score for a market
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_storage_efficiency_score(env: Env, market_id: Symbol) -> Result<u32, Error> {
        let market = match markets::MarketStateManager::get_market(&env, &market_id) {
            Ok(m) => m,
            Err(e) => return Err(e),
        };

        Ok(storage::StorageUtils::get_storage_efficiency_score(&market))
    }

    /// Get storage recommendations for a market
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_storage_recommendations(env: Env, market_id: Symbol) -> Result<Vec<String>, Error> {
        let market = match markets::MarketStateManager::get_market(&env, &market_id) {
            Ok(m) => m,
            Err(e) => return Err(e),
        };

        Ok(storage::StorageUtils::get_storage_recommendations(&market))
    }

    // ===== ERROR RECOVERY FUNCTIONS =====

    /// Recover from an error using appropriate recovery strategy
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn recover_from_error(
        env: Env,
        error: Error,
        context: errors::ErrorContext,
    ) -> Result<errors::ErrorRecovery, Error> {
        errors::ErrorHandler::recover_from_error(&env, error, context)
    }

    /// Validate error recovery configuration and state
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_error_recovery(
        env: Env,
        recovery: errors::ErrorRecovery,
    ) -> Result<bool, Error> {
        errors::ErrorHandler::validate_error_recovery(&env, &recovery)
    }

    /// Get current error recovery status and statistics
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_error_recovery_status(env: Env) -> Result<errors::ErrorRecoveryStatus, Error> {
        errors::ErrorHandler::get_error_recovery_status(&env)
    }

    /// Emit error recovery event for monitoring and logging
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn emit_error_recovery_event(env: Env, recovery: errors::ErrorRecovery) {
        errors::ErrorHandler::emit_error_recovery_event(&env, &recovery);
    }

    /// Validate resilience patterns configuration
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_resilience_patterns(
        env: Env,
        patterns: Vec<errors::ResiliencePattern>,
    ) -> Result<bool, Error> {
        errors::ErrorHandler::validate_resilience_patterns(&env, &patterns)
    }

    /// Document error recovery procedures and best practices
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn document_error_recovery(env: Env) -> Result<soroban_sdk::Map<String, String>, Error> {
        errors::ErrorHandler::document_error_recovery_procedures(&env)
    }

    // ===== EDGE CASE HANDLING ENTRY POINTS =====

    /// Handle zero stake scenario for a specific market
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn handle_zero_stake_scenario(env: Env, market_id: Symbol) -> Result<(), Error> {
        edge_cases::EdgeCaseHandler::handle_zero_stake_scenario(&env, market_id)
    }

    /// Implement tie-breaking mechanism for equal outcomes
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn implement_tie_breaking_mechanism(
        env: Env,
        outcomes: Vec<String>,
    ) -> Result<String, Error> {
        edge_cases::EdgeCaseHandler::implement_tie_breaking_mechanism(&env, outcomes)
    }

    /// Detect orphaned markets and return their IDs
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn detect_orphaned_markets(env: Env) -> Result<Vec<Symbol>, Error> {
        edge_cases::EdgeCaseHandler::detect_orphaned_markets(&env)
    }

    /// Handle partial resolution with incomplete data
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn handle_partial_resolution(
        env: Env,
        market_id: Symbol,
        partial_data: edge_cases::PartialData,
    ) -> Result<(), Error> {
        edge_cases::EdgeCaseHandler::handle_partial_resolution(&env, market_id, partial_data)
    }

    /// Validate edge case handling scenario
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_edge_case_handling(
        env: Env,
        scenario: edge_cases::EdgeCaseScenario,
    ) -> Result<(), Error> {
        edge_cases::EdgeCaseHandler::validate_edge_case_handling(&env, scenario)
    }

    /// Run comprehensive edge case testing scenarios
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn test_edge_case_scenarios(env: Env) -> Result<(), Error> {
        edge_cases::EdgeCaseHandler::test_edge_case_scenarios(&env)
    }

    /// Get comprehensive edge case statistics
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_edge_case_statistics(env: Env) -> Result<edge_cases::EdgeCaseStats, Error> {
        edge_cases::EdgeCaseHandler::get_edge_case_statistics(&env)
    }

    // ===== RECOVERY PUBLIC METHODS =====
    /// Initiates or performs recovery of a potentially corrupted market state. Only admin.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn recover_market_state(env: Env, admin: Address, market_id: Symbol) -> bool {
        admin.require_auth();
        if let Err(e) = crate::recovery::RecoveryManager::assert_is_admin(&env, &admin) {
            panic_with_error!(env, e);
        }
        let result = match crate::recovery::RecoveryManager::recover_market_state(
            &env, &admin, &market_id,
        ) {
            Ok(res) => res,
            Err(e) => panic_with_error!(env, e),
        };

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::ErrorRecovered,
            admin.clone(),
            Map::new(&env),
            None,
        );

        result
    }

    /// Executes partial refund mechanism for selected users in a failed/corrupted market. Only admin.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn partial_refund_mechanism(
        env: Env,
        admin: Address,
        market_id: Symbol,
        users: Vec<Address>,
    ) -> i128 {
        Self::require_primary_admin_or_panic(&env, &admin);
        let result = match crate::recovery::RecoveryManager::partial_refund_mechanism(
            &env, &admin, &market_id, &users,
        ) {
            Ok(total_refunded) => total_refunded,
            Err(e) => panic_with_error!(env, e),
        };

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::PartialRefundExecuted,
            admin.clone(),
            Map::new(&env),
            None,
        );

        result
    }

    /// Validates market state integrity; returns true if consistent.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_market_state_integrity(env: Env, market_id: Symbol) -> bool {
        match crate::recovery::RecoveryValidator::validate_market_state_integrity(&env, &market_id)
        {
            Ok(_) => true,
            Err(_) => false,
        }
    }

    /// Returns recovery status for a market.
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_recovery_status(env: Env, market_id: Symbol) -> String {
        crate::recovery::RecoveryManager::get_recovery_status(&env, &market_id)
            .unwrap_or_else(|_| String::from_str(&env, "unknown"))
    }

    /// Remove the oldest `count` completed recovery history entries for a market (admin only).
    ///
    /// Active (unresolved) recovery state is never pruned. `count` is capped at 30.
    ///
    /// # Errors
    /// * `Unauthorized` - Caller is not admin
    pub fn prune_recovery_history(
        env: Env,
        admin: Address,
        market_id: Symbol,
        count: u32,
    ) -> Result<u32, Error> {
        crate::recovery::RecoveryManager::prune_recovery_history(&env, &admin, &market_id, count)
    }

    // ===== PER-MARKET RECOVERY TIMELOCK ENTRYPOINTS =====

    /// Initiate a per-market recovery request with an admin timelock.
    ///
    /// Creates a pending recovery request for the specified market. The recovery
    /// action cannot be executed until the timelock period (default 24 hours) has
    /// elapsed. Only contract admins may call this function.
    ///
    /// # Arguments
    /// * `admin` - The admin initiating the recovery (must be authenticated)
    /// * `market_id` - The target market
    /// * `action` - The recovery action (ReconstructState, CancelMarket, or ForceResolve)
    /// * `reason` - Human-readable explanation for the recovery
    ///
    /// # Errors
    /// * `RecoveryAlreadyPending` - A recovery is already pending for this market
    /// * `MarketNotRecoverable` - Market is in a non-recoverable state
    /// * `InvalidRecoveryAction` - Action is invalid for the market's current state
    pub fn initiate_market_recovery(
        env: Env,
        admin: Address,
        market_id: Symbol,
        action: crate::recovery::PerMarketRecoveryAction,
        reason: String,
    ) -> crate::recovery::PendingMarketRecovery {
        Self::require_primary_admin_or_panic(&env, &admin);

        match crate::recovery::RecoveryTimelockConfig::initiate_recovery(
            &env,
            &admin,
            &market_id,
            &action,
            &reason,
        ) {
            Ok(request) => {
                crate::audit_trail::AuditTrailManager::append_record(
                    &env,
                    crate::audit_trail::AuditAction::ErrorRecovered,
                    admin.clone(),
                    Map::new(&env),
                    None,
                );
                request
            }
            Err(e) => panic_with_error!(env, e),
        }
    }

    /// Execute a pending per-market recovery request after the timelock has expired.
    ///
    /// This can only be called after the timelock period initiated by
    /// `initiate_market_recovery` has elapsed. Only contract admins may call this.
    ///
    /// # Arguments
    /// * `admin` - The admin executing the recovery (must be authenticated)
    /// * `market_id` - The target market
    ///
    /// # Errors
    /// * `RecoveryRequestNotFound` - No pending request for this market
    /// * `RecoveryTimelockActive` - The timelock has not yet expired
    pub fn execute_market_recovery(env: Env, admin: Address, market_id: Symbol) -> bool {
        Self::require_primary_admin_or_panic(&env, &admin);

        match crate::recovery::RecoveryTimelockConfig::execute_recovery(&env, &admin, &market_id)
        {
            Ok(success) => {
                crate::audit_trail::AuditTrailManager::append_record(
                    &env,
                    crate::audit_trail::AuditAction::ErrorRecovered,
                    admin.clone(),
                    Map::new(&env),
                    None,
                );
                success
            }
            Err(e) => panic_with_error!(env, e),
        }
    }

    /// Cancel a pending per-market recovery request.
    ///
    /// Removes the pending request so the recovery action will not be executed.
    /// Only contract admins may call this.
    ///
    /// # Arguments
    /// * `admin` - The admin cancelling the recovery (must be authenticated)
    /// * `market_id` - The target market
    ///
    /// # Errors
    /// * `RecoveryRequestNotFound` - No pending request for this market
    pub fn cancel_market_recovery(env: Env, admin: Address, market_id: Symbol) {
        Self::require_primary_admin_or_panic(&env, &admin);

        match crate::recovery::RecoveryTimelockConfig::cancel_recovery(
            &env,
            &admin,
            &market_id,
        ) {
            Ok(()) => {
                crate::audit_trail::AuditTrailManager::append_record(
                    &env,
                    crate::audit_trail::AuditAction::ErrorRecovered,
                    admin.clone(),
                    Map::new(&env),
                    None,
                );
            }
            Err(e) => panic_with_error!(env, e),
        }
    }

    /// Returns the pending recovery request for a market, if any.
    ///
    /// Read-only query; no authentication required.
    pub fn get_pending_market_recovery(
        env: Env,
        market_id: Symbol,
    ) -> Option<crate::recovery::PendingMarketRecovery> {
        crate::recovery::RecoveryTimelockConfig::get_pending(&env, &market_id)
    }

    /// Returns the current recovery timelock configuration.
    ///
    /// Read-only query; no authentication required.
    pub fn get_recovery_timelock_config(env: Env) -> crate::recovery::RecoveryTimelockConfig {
        crate::recovery::RecoveryTimelockConfig::get_config(&env)
    }

    // ===== VERSIONING FUNCTIONS =====

    /// Track contract version for versioning system
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn track_contract_version(env: Env, version: versioning::Version) -> Result<(), Error> {
        versioning::VersionManager::new(&env).track_contract_version(&env, version)
    }

    /// Migrate data between contract versions
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn migrate_data_between_versions(
        env: Env,
        old_version: versioning::Version,
        new_version: versioning::Version,
    ) -> Result<versioning::VersionMigration, Error> {
        versioning::VersionManager::new(&env).migrate_data_between_versions(
            &env,
            old_version,
            new_version,
        )
    }

    /// Validate version compatibility
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_version_compatibility(
        env: Env,
        old_version: versioning::Version,
        new_version: versioning::Version,
    ) -> Result<bool, Error> {
        versioning::VersionManager::new(&env).validate_version_compatibility(
            &env,
            &old_version,
            &new_version,
        )
    }

    /// Upgrade to a specific version
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn upgrade_to_version(env: Env, target_version: versioning::Version) -> Result<(), Error> {
        versioning::VersionManager::new(&env).upgrade_to_version(&env, target_version)
    }

    /// Rollback to a specific version
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn rollback_to_version(env: Env, target_version: versioning::Version) -> Result<(), Error> {
        versioning::VersionManager::new(&env).rollback_to_version(&env, target_version)
    }

    /// Get version history
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_version_history(env: Env) -> Result<versioning::VersionHistory, Error> {
        versioning::VersionManager::new(&env).get_version_history(&env)
    }

    /// Test version migration
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn test_version_migration(
        env: Env,
        migration: versioning::VersionMigration,
    ) -> Result<bool, Error> {
        versioning::VersionManager::new(&env).test_version_migration(&env, migration)
    }

    // ===== MONITORING FUNCTIONS =====

    /// Monitor market health for a specific market
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn monitor_market_health(
        env: Env,
        market_id: Symbol,
    ) -> Result<monitoring::MarketHealthMetrics, Error> {
        monitoring::ContractMonitor::monitor_market_health(&env, market_id)
    }

    /// Monitor oracle health for a specific oracle provider
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn monitor_oracle_health(
        env: Env,
        oracle: OracleProvider,
    ) -> Result<monitoring::OracleHealthMetrics, Error> {
        monitoring::ContractMonitor::monitor_oracle_health(&env, oracle)
    }

    /// Monitor fee collection performance
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn monitor_fee_collection(
        env: Env,
        timeframe: monitoring::TimeFrame,
    ) -> Result<monitoring::FeeCollectionMetrics, Error> {
        monitoring::ContractMonitor::monitor_fee_collection(&env, timeframe)
    }

    /// Monitor dispute resolution performance
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn monitor_dispute_resolution(
        env: Env,
        market_id: Symbol,
    ) -> Result<monitoring::DisputeResolutionMetrics, Error> {
        monitoring::ContractMonitor::monitor_dispute_resolution(&env, market_id)
    }

    /// Get comprehensive contract performance metrics
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_contract_performance_metrics(
        env: Env,
        timeframe: monitoring::TimeFrame,
    ) -> Result<monitoring::PerformanceMetrics, Error> {
        monitoring::ContractMonitor::get_contract_performance_metrics(&env, timeframe)
    }

    /// Emit monitoring alert
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn emit_monitoring_alert(
        env: Env,
        alert: monitoring::MonitoringAlert,
    ) -> Result<(), Error> {
        monitoring::ContractMonitor::emit_monitoring_alert(&env, alert)
    }

    /// Validate monitoring data integrity
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_monitoring_data(
        env: Env,
        data: monitoring::MonitoringData,
    ) -> Result<bool, Error> {
        monitoring::ContractMonitor::validate_monitoring_data(&env, &data)
    }

    /// Return all alerts in the bounded monitoring queue (oldest first).
    ///
    /// Clients should also check [`is_monitor_overflow`] to detect whether any
    /// alerts were silently evicted since the last admin reset.
    pub fn get_monitor_alerts(env: Env) -> Vec<monitoring::MonitoringAlert> {
        monitoring::ContractMonitor::get_alerts(&env)
    }

    /// Return `true` if at least one alert has been evicted from the queue due to
    /// overflow since the last [`clear_monitor_overflow`] call.
    pub fn is_monitor_overflow(env: Env) -> bool {
        monitoring::ContractMonitor::is_overflow(&env)
    }

    /// Reset the monitoring overflow flag.  Only the contract admin may call this.
    ///
    /// # Errors
    ///
    /// - [`Error::AdminNotSet`] – no admin has been initialised.
    /// - [`Error::Unauthorized`] – `admin` does not match the stored admin address.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn clear_monitor_overflow(env: Env, admin: Address) -> Result<(), Error> {
        monitoring::ContractMonitor::clear_overflow(&env, &admin)
    }

    // ===== ORACLE FALLBACK FUNCTIONS =====

    /// Get oracle data with backup if primary fails.
    ///
    /// The helper always attempts `primary_oracle` first. It attempts `backup_oracle`
    /// only after a failed primary call, and it aborts before any oracle call once
    /// `ledger.timestamp() >= end_time + resolution_timeout`.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_oracle_with_backup(
        env: Env,
        market_id: Symbol,
        oracle_contract: Address,
        primary_oracle: OracleProvider,
        backup_oracle: OracleProvider,
    ) -> Result<String, Error> {
        // Get market info
        let market = env
            .storage()
            .persistent()
            .get::<Symbol, Market>(&market_id)
            .ok_or(Error::MarketNotFound)?;

        // Check if market ended
        let current_time = env.ledger().timestamp();
        if current_time < market.end_time {
            return Err(Error::MarketClosed);
        }
        if resolution_timeout_reached(&env, &market) {
            EventEmitter::emit_resolution_timeout(&env, &market_id, current_time);
            return Err(Error::ResolutionTimeoutReached);
        }

        // Try to get price with backup
        let backup = OracleBackup::new(primary_oracle, backup_oracle);
        match backup.get_price(&env, &oracle_contract, &market.oracle_config.feed_id) {
            Ok(price) => {
                // Simple comparison logic
                let threshold = market.oracle_config.threshold;
                let comparison = &market.oracle_config.comparison;

                let result = if comparison == &String::from_str(&env, "gt") {
                    if price > threshold {
                        "yes"
                    } else {
                        "no"
                    }
                } else if comparison == &String::from_str(&env, "lt") {
                    if price < threshold {
                        "yes"
                    } else {
                        "no"
                    }
                } else {
                    if price == threshold {
                        "yes"
                    } else {
                        "no"
                    }
                };

                Ok(String::from_str(&env, result))
            }
            Err(_) => {
                // Both oracles failed
                let reason = String::from_str(&env, "primary_and_fallback_failed");
                events::EventEmitter::emit_manual_resolution_required(&env, &market_id, &reason);
                Err(Error::FallbackOracleUnavailable)
            }
        }
    }

    /// Check if oracle is working
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn check_oracle_status(
        env: Env,
        oracle: OracleProvider,
        oracle_contract: Address,
    ) -> String {
        let health = graceful_degradation::monitor_oracle_health(&env, oracle, &oracle_contract);
        match health {
            OracleHealth::Working => String::from_str(&env, "working"),
            OracleHealth::Degraded => String::from_str(&env, "degraded"),
            OracleHealth::Broken => String::from_str(&env, "broken"),
        }
    }

    // ===== MULTI-ADMIN MANAGEMENT FUNCTIONS =====

    /// Add a new admin with specified role (SuperAdmin only)
    ///
    /// The caller must satisfy Soroban `require_auth()`. Access is granted to the
    /// stored primary admin and, after multi-admin migration, any delegated admin
    /// with `AdminPermission::Emergency`.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn add_admin(
        env: Env,
        current_admin: Address,
        new_admin: Address,
        role: AdminRole,
    ) -> Result<(), Error> {
        Self::require_admin_permission(&env, &current_admin, AdminPermission::Emergency)?;
        AdminManager::add_admin(&env, &current_admin, &new_admin, role)
    }

    /// Remove an admin from the system (SuperAdmin only)
    ///
    /// The caller must satisfy Soroban `require_auth()`. Access is granted to the
    /// stored primary admin and, after multi-admin migration, any delegated admin
    /// with `AdminPermission::Emergency`.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn remove_admin(
        env: Env,
        current_admin: Address,
        admin_to_remove: Address,
    ) -> Result<(), Error> {
        Self::require_admin_permission(&env, &current_admin, AdminPermission::Emergency)?;
        AdminManager::remove_admin(&env, &current_admin, &admin_to_remove)
    }

    /// Update an admin's role (SuperAdmin only)
    ///
    /// The caller must satisfy Soroban `require_auth()`. Access is granted to the
    /// stored primary admin and, after multi-admin migration, any delegated admin
    /// with `AdminPermission::Emergency`.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn update_admin_role(
        env: Env,
        current_admin: Address,
        target_admin: Address,
        new_role: AdminRole,
    ) -> Result<(), Error> {
        Self::require_admin_permission(&env, &current_admin, AdminPermission::Emergency)?;
        AdminManager::update_admin_role(&env, &current_admin, &target_admin, new_role)
    }

    /// Validate admin permission for specific action
    ///
    /// The caller must satisfy Soroban `require_auth()`, and the contract must
    /// already have an initialized primary admin in persistent storage.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_admin_permission(
        env: Env,
        admin: Address,
        permission: AdminPermission,
    ) -> Result<(), Error> {
        Self::require_initialized_admin_root(&env, &admin)?;
        AdminManager::validate_admin_permission(&env, &admin, permission)
    }

    /// Get all admin roles in the system
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_admin_roles(env: Env) -> Map<Address, AdminRole> {
        AdminManager::get_admin_roles(&env)
    }

    /// Get comprehensive admin analytics
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_admin_analytics(env: Env) -> AdminAnalyticsResult {
        admin::EnhancedAdminAnalytics::get_admin_analytics(&env)
    }

    /// Migrate from single-admin to multi-admin system
    ///
    /// Only the stored primary admin can trigger the one-way migration into the
    /// delegated multi-admin storage layout.
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn migrate_to_multi_admin(env: Env, admin: Address) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        admin::AdminSystemIntegration::migrate_to_multi_admin(&env)
    }

    /// Check if multi-admin migration is complete
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn is_multi_admin_migrated(env: Env) -> bool {
        admin::AdminSystemIntegration::is_migrated(&env)
    }

    /// Check role permissions against a specific permission
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn check_role_permissions(env: Env, role: AdminRole, permission: AdminPermission) -> bool {
        AdminManager::check_role_permissions(&env, role, permission)
    }

    // ===== CONTRACT UPGRADE METHODS =====

    /// Upgrade the contract to new Wasm bytecode
    ///
    /// This function allows authorized admins to upgrade the contract to a new
    /// version by replacing the Wasm bytecode. It includes comprehensive validation,
    /// version checking, and event logging.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `admin` - The admin performing the upgrade (must be authorized)
    /// * `new_wasm_hash` - Hash of the new Wasm bytecode to deploy
    ///
    /// # Returns
    ///
    /// * `Ok(())` if upgrade succeeds
    /// * `Err(Error)` if authorization fails or upgrade is incompatible
    ///
    /// # Security
    ///
    /// - Requires Soroban `require_auth()` from the caller
    /// - Requires the caller to match the stored primary admin in persistent storage
    /// - Validates WASM hash chain to prevent out-of-order/forked upgrades
    /// - Validates version compatibility
    /// - Performs safety checks before upgrade
    /// - Logs all upgrade attempts for audit trail
    ///
    /// # Parameters
    ///
    /// * `env` - Soroban environment
    /// * `admin` - Admin performing the upgrade (must be authorized)
    /// * `new_wasm_hash` - Hash of new Wasm bytecode to deploy
    /// * `expected_predecessor` - Expected current WASM hash (for chain verification)
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Address, BytesN};
    /// # let env = Env::default();
    /// # let admin = Address::generate(&env);
    /// # let new_wasm_hash = BytesN::from_array(&env, &[1u8; 32]);
    /// # let current_hash = BytesN::from_array(&env, &[0u8; 32]);
    ///
    /// // Perform upgrade with admin authorization and chain verification
    /// admin.require_auth();
    /// PredictifyHybrid::upgrade_contract(env, admin, new_wasm_hash, current_hash)?;
    /// # Ok::<(), predictify_hybrid::errors::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    /// Returns [`Error::UpgradeChainMismatch`] if the expected predecessor does not match the current WASM hash.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn upgrade_contract(
        env: Env,
        admin: Address,
        new_wasm_hash: soroban_sdk::BytesN<32>,
        expected_predecessor: soroban_sdk::BytesN<32>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        let result = upgrade_manager::UpgradeManager::upgrade_contract(
            &env,
            &admin,
            new_wasm_hash,
            expected_predecessor,
        );

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::ContractUpgraded,
            admin.clone(),
            Map::new(&env),
            None,
        );

        result
    }

    /// Broadcasts an emergency notice to off-chain clients by emitting an AdminBroadcast event.
    pub fn admin_broadcast(
        env: Env,
        admin: Address,
        severity: crate::admin::Severity,
        message_hash: soroban_sdk::BytesN<32>,
        reason: String,
    ) -> Result<(), Error> {
        crate::admin::AdminFunctions::admin_broadcast(&env, &admin, severity, message_hash, reason)
    }

    /// Rollback contract to previous version
    ///
    /// Reverts the contract to a previous Wasm version. This is a critical
    /// recovery mechanism for failed upgrades.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `admin` - The admin performing the rollback (must be authorized)
    /// * `rollback_wasm_hash` - Hash of the Wasm bytecode to rollback to
    ///
    /// # Returns
    ///
    /// * `Ok(())` if rollback succeeds
    /// * `Err(Error)` if authorization fails or rollback is invalid
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn rollback_upgrade(
        env: Env,
        admin: Address,
        rollback_wasm_hash: soroban_sdk::BytesN<32>,
    ) -> Result<(), Error> {
        Self::require_primary_admin(&env, &admin)?;
        let result =
            upgrade_manager::UpgradeManager::rollback_upgrade(&env, &admin, rollback_wasm_hash);

        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::UpgradeRolledBack,
            admin.clone(),
            Map::new(&env),
            None,
        );

        result
    }

    /// Get current contract version
    ///
    /// Returns the currently active contract version information.
    ///
    /// # Returns
    ///
    /// * `Ok(Version)` - Current contract version
    /// * `Err(Error)` - If version cannot be retrieved
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_contract_version(env: Env) -> Result<versioning::Version, Error> {
        upgrade_manager::UpgradeManager::get_contract_version(&env)
    }

    /// Return the current capability bitmap for the contract version.
    ///
    /// Clients can call this to probe which features are supported without
    /// maintaining a client-side version-to-capability lookup table.
    ///
    /// Returns a `u64` bitmask where each bit corresponds to a `CAPABILITY_*`
    /// constant defined in the [`versioning`] module.
    pub fn capabilities(env: Env) -> u64 {
        crate::capabilities::capabilities(&env)
    }

    /// Check if upgrade is available
    ///
    /// Checks if there are approved upgrade proposals ready for execution.
    ///
    /// # Returns
    ///
    /// * `Ok(bool)` - True if upgrade is available
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn check_upgrade_available(env: Env) -> Result<bool, Error> {
        upgrade_manager::UpgradeManager::check_upgrade_available(&env)
    }

    /// Get upgrade history
    ///
    /// Retrieves complete history of all contract upgrades.
    ///
    /// # Returns
    ///
    /// * `Ok(Vec<UpgradeRecord>)` - List of all upgrade records
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_upgrade_history(env: Env) -> Result<Vec<upgrade_manager::UpgradeRecord>, Error> {
        upgrade_manager::UpgradeManager::get_upgrade_history(&env)
    }

    /// Get upgrade statistics
    ///
    /// Calculates and returns comprehensive upgrade statistics.
    ///
    /// # Returns
    ///
    /// * `Ok(UpgradeStats)` - Upgrade statistics and analytics
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_upgrade_statistics(env: Env) -> Result<upgrade_manager::UpgradeStats, Error> {
        upgrade_manager::UpgradeManager::get_upgrade_statistics(&env)
    }

    /// Validate upgrade compatibility
    ///
    /// Performs comprehensive validation of an upgrade proposal without
    /// executing the upgrade. Useful for testing and validation.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `proposal` - The upgrade proposal to validate
    ///
    /// # Returns
    ///
    /// * `Ok(CompatibilityCheckResult)` - Detailed compatibility analysis
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_upgrade_compatibility(
        env: Env,
        proposal: upgrade_manager::UpgradeProposal,
    ) -> Result<upgrade_manager::CompatibilityCheckResult, Error> {
        upgrade_manager::UpgradeManager::validate_upgrade_compatibility(&env, &proposal)
    }

    /// Test upgrade safety
    ///
    /// Performs dry-run validation of an upgrade proposal without executing.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment
    /// * `proposal` - The upgrade proposal to test
    ///
    /// # Returns
    ///
    /// * `Ok(bool)` - True if upgrade would succeed
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn test_upgrade_safety(
        env: Env,
        proposal: upgrade_manager::UpgradeProposal,
    ) -> Result<bool, Error> {
        upgrade_manager::UpgradeManager::test_upgrade_safety(&env, &proposal)
    }

    // ===== MARKET ANALYTICS FUNCTIONS =====

    /// Get comprehensive market statistics for data analysis and insights
    ///
    /// This function provides detailed statistics about a specific market including
    /// participation metrics, stake distribution, outcome analysis, and performance
    /// indicators. It's essential for market monitoring and user interfaces.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to analyze
    ///
    /// # Returns
    ///
    /// Returns `Result<MarketStatistics, Error>` where:
    /// - `Ok(MarketStatistics)` - Complete market statistics and analytics
    /// - `Err(Error)` - Error if market not found or analysis fails
    ///
    /// # Errors
    ///
    /// This function returns:
    /// - `Error::MarketNotFound` - Market with given ID doesn't exist
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// match PredictifyHybrid::get_market_analytics_statistics(env.clone(), market_id) {
    ///     Ok(stats) => {
    ///         println!("Total participants: {}", stats.total_participants);
    ///         println!("Total stake: {}", stats.total_stake);
    ///         println!("Consensus strength: {}%", stats.consensus_strength);
    ///     },
    ///     Err(e) => println!("Analytics unavailable: {:?}", e),
    /// }
    /// ```
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_market_analytics_statistics(
        env: Env,
        market_id: Symbol,
    ) -> Result<market_analytics::MarketStatistics, Error> {
        market_analytics::MarketAnalyticsManager::get_market_statistics(&env, market_id)
    }

    /// Get voting analytics and participation metrics for a market
    ///
    /// This function provides detailed analysis of voting patterns, participation
    /// trends, and community engagement within a specific market. It's useful
    /// for understanding market dynamics and user behavior.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to analyze
    ///
    /// # Returns
    ///
    /// Returns `Result<VotingAnalytics, Error>` where:
    /// - `Ok(VotingAnalytics)` - Complete voting analytics and metrics
    /// - `Err(Error)` - Error if market not found or analysis fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// match PredictifyHybrid::get_voting_analytics(env.clone(), market_id) {
    ///     Ok(analytics) => {
    ///         println!("Total votes: {}", analytics.total_votes);
    ///         println!("Unique voters: {}", analytics.unique_voters);
    ///     },
    ///     Err(e) => println!("Voting analytics unavailable: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_voting_analytics(
        env: Env,
        market_id: Symbol,
    ) -> Result<market_analytics::VotingAnalytics, Error> {
        market_analytics::MarketAnalyticsManager::get_voting_analytics(&env, market_id)
    }

    /// Get oracle performance statistics for a specific oracle provider
    ///
    /// This function provides comprehensive performance metrics for oracle providers,
    /// including accuracy rates, response times, uptime statistics, and reliability
    /// scores. It's essential for oracle monitoring and optimization.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `oracle` - The oracle provider to analyze
    ///
    /// # Returns
    ///
    /// Returns `Result<OraclePerformanceStats, Error>` where:
    /// - `Ok(OraclePerformanceStats)` - Complete oracle performance statistics
    /// - `Err(Error)` - Error if oracle data unavailable
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::{PredictifyHybrid, OracleProvider};
    /// # let env = Env::default();
    ///
    /// match PredictifyHybrid::get_oracle_performance_stats(env.clone(), OracleProvider::Reflector) {
    ///     Ok(stats) => {
    ///         println!("Oracle accuracy: {}%", stats.accuracy_rate);
    ///         println!("Uptime: {}%", stats.uptime_percentage);
    ///         println!("Reliability score: {}", stats.reliability_score);
    ///     },
    ///     Err(e) => println!("Oracle stats unavailable: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_oracle_performance_stats(
        env: Env,
        oracle: OracleProvider,
    ) -> Result<market_analytics::OraclePerformanceStats, Error> {
        market_analytics::MarketAnalyticsManager::get_oracle_performance_stats(&env, oracle)
    }

    /// Get fee analytics and revenue tracking for a specific timeframe
    ///
    /// This function provides comprehensive fee collection analytics including
    /// revenue tracking, fee distribution analysis, and collection efficiency
    /// metrics. It's essential for financial monitoring and optimization.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `timeframe` - The time period for fee analysis
    ///
    /// # Returns
    ///
    /// Returns `Result<FeeAnalytics, Error>` where:
    /// - `Ok(FeeAnalytics)` - Complete fee analytics and revenue data
    /// - `Err(Error)` - Error if fee data unavailable
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::{PredictifyHybrid, TimeFrame};
    /// # let env = Env::default();
    ///
    /// match PredictifyHybrid::get_fee_analytics(env.clone(), TimeFrame::Month) {
    ///     Ok(analytics) => {
    ///         println!("Total fees collected: {}", analytics.total_fees_collected);
    ///         println!("Collection rate: {}%", analytics.fee_collection_rate);
    ///     },
    ///     Err(e) => println!("Fee analytics unavailable: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_fee_analytics(
        env: Env,
        timeframe: market_analytics::TimeFrame,
    ) -> Result<market_analytics::FeeAnalytics, Error> {
        market_analytics::MarketAnalyticsManager::get_fee_analytics(&env, timeframe)
    }

    /// Get dispute analytics and resolution metrics for a market
    ///
    /// This function provides detailed analysis of dispute patterns, resolution
    /// efficiency, and dispute-related metrics for a specific market. It's
    /// essential for understanding dispute dynamics and improving resolution processes.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to analyze
    ///
    /// # Returns
    ///
    /// Returns `Result<DisputeAnalytics, Error>` where:
    /// - `Ok(DisputeAnalytics)` - Complete dispute analytics and metrics
    /// - `Err(Error)` - Error if market not found or analysis fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// match PredictifyHybrid::get_dispute_analytics(env.clone(), market_id) {
    ///     Ok(analytics) => {
    ///         println!("Total disputes: {}", analytics.total_disputes);
    ///         println!("Success rate: {}%", analytics.dispute_success_rate);
    ///     },
    ///     Err(e) => println!("Dispute analytics unavailable: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_dispute_analytics(
        env: Env,
        market_id: Symbol,
    ) -> Result<market_analytics::DisputeAnalytics, Error> {
        market_analytics::MarketAnalyticsManager::get_dispute_analytics(&env, market_id)
    }

    /// Get participation metrics for a specific market
    ///
    /// This function provides comprehensive participation analysis including
    /// user engagement, retention rates, and activity patterns for a specific
    /// market. It's essential for understanding user behavior and market health.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_id` - Unique identifier of the market to analyze
    ///
    /// # Returns
    ///
    /// Returns `Result<ParticipationMetrics, Error>` where:
    /// - `Ok(ParticipationMetrics)` - Complete participation metrics and analysis
    /// - `Err(Error)` - Error if market not found or analysis fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let market_id = Symbol::new(&env, "market_1");
    ///
    /// match PredictifyHybrid::get_participation_metrics(env.clone(), market_id) {
    ///     Ok(metrics) => {
    ///         println!("Total participants: {}", metrics.total_participants);
    ///         println!("Engagement score: {}", metrics.engagement_score);
    ///         println!("Retention rate: {}%", metrics.retention_rate);
    ///     },
    ///     Err(e) => println!("Participation metrics unavailable: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_participation_metrics(
        env: Env,
        market_id: Symbol,
    ) -> Result<market_analytics::ParticipationMetrics, Error> {
        market_analytics::MarketAnalyticsManager::get_participation_metrics(&env, market_id)
    }

    /// Get market comparison analytics for multiple markets
    ///
    /// This function provides comparative analysis across multiple markets,
    /// including performance rankings, comparative metrics, and market insights.
    /// It's essential for understanding market trends and performance patterns.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `markets` - Vector of market identifiers to compare
    ///
    /// # Returns
    ///
    /// Returns `Result<MarketComparisonAnalytics, Error>` where:
    /// - `Ok(MarketComparisonAnalytics)` - Complete comparative analytics
    /// - `Err(Error)` - Error if analysis fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, Symbol, vec};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let markets = vec![
    /// #     &env,
    /// #     Symbol::new(&env, "market_1"),
    /// #     Symbol::new(&env, "market_2"),
    /// # ];
    ///
    /// match PredictifyHybrid::get_market_comparison_analytics(env.clone(), markets) {
    ///     Ok(comparison) => {
    ///         println!("Total markets: {}", comparison.total_markets);
    ///         println!("Average participation: {}", comparison.average_participation);
    ///         println!("Success rate: {}%", comparison.success_rate);
    ///     },
    ///     Err(e) => println!("Comparison analytics unavailable: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_market_comparison_analytics(
        env: Env,
        markets: Vec<Symbol>,
    ) -> Result<market_analytics::MarketComparisonAnalytics, Error> {
        market_analytics::MarketAnalyticsManager::get_market_comparison_analytics(&env, markets)
    }

    // ===== PERFORMANCE BENCHMARK FUNCTIONS =====

    /// Benchmark gas usage for a specific function with given inputs
    ///
    /// This function measures the gas consumption and execution time for a specific
    /// contract function with provided inputs. It's essential for performance
    /// optimization and gas cost analysis.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `function` - Name of the function to benchmark
    /// * `inputs` - Vector of input parameters for the function
    ///
    /// # Returns
    ///
    /// Returns `Result<BenchmarkResult, Error>` where:
    /// - `Ok(BenchmarkResult)` - Complete benchmark results including gas usage and execution time
    /// - `Err(Error)` - Error if benchmarking fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, String, vec};
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    /// # let inputs = vec![&env, String::from_str(&env, "test_input")];
    ///
    /// match PredictifyHybrid::benchmark_gas_usage(
    ///     env.clone(),
    ///     String::from_str(&env, "create_market"),
    ///     inputs
    /// ) {
    ///     Ok(result) => {
    ///         println!("Gas usage: {}", result.gas_usage);
    ///         println!("Execution time: {}", result.execution_time);
    ///         println!("Performance score: {}", result.performance_score);
    ///     },
    ///     Err(e) => println!("Benchmark failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn benchmark_gas_usage(
        env: Env,
        function: String,
        inputs: Vec<String>,
    ) -> Result<performance_benchmarks::BenchmarkResult, Error> {
        performance_benchmarks::PerformanceBenchmarkManager::benchmark_gas_usage(
            &env, function, inputs,
        )
    }

    /// Benchmark storage usage for a specific operation
    ///
    /// This function measures storage consumption and performance for various
    /// storage operations including read, write, and delete operations.
    /// It's essential for storage optimization and cost analysis.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `operation` - Storage operation configuration to benchmark
    ///
    /// # Returns
    ///
    /// Returns `Result<BenchmarkResult, Error>` where:
    /// - `Ok(BenchmarkResult)` - Complete storage benchmark results
    /// - `Err(Error)` - Error if benchmarking fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::{PredictifyHybrid, StorageOperation};
    /// # let env = Env::default();
    /// # let operation = StorageOperation {
    /// #     operation_type: String::from_str(&env, "write"),
    /// #     data_size: 1024,
    /// #     key_count: 10,
    /// #     value_count: 10,
    /// #     operation_count: 100,
    /// # };
    ///
    /// match PredictifyHybrid::benchmark_storage_usage(env.clone(), operation) {
    ///     Ok(result) => {
    ///         println!("Storage usage: {}", result.storage_usage);
    ///         println!("Gas usage: {}", result.gas_usage);
    ///     },
    ///     Err(e) => println!("Storage benchmark failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn benchmark_storage_usage(
        env: Env,
        operation: performance_benchmarks::StorageOperation,
    ) -> Result<performance_benchmarks::BenchmarkResult, Error> {
        performance_benchmarks::PerformanceBenchmarkManager::benchmark_storage_usage(
            &env, operation,
        )
    }

    /// Benchmark oracle call performance for a specific oracle provider
    ///
    /// This function measures the performance characteristics of oracle calls
    /// including response time, gas usage, and reliability metrics.
    /// It's essential for oracle performance monitoring and optimization.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `oracle` - The oracle provider to benchmark
    ///
    /// # Returns
    ///
    /// Returns `Result<BenchmarkResult, Error>` where:
    /// - `Ok(BenchmarkResult)` - Complete oracle performance benchmark results
    /// - `Err(Error)` - Error if benchmarking fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::{PredictifyHybrid, OracleProvider};
    /// # let env = Env::default();
    ///
    /// match PredictifyHybrid::benchmark_oracle_call_performance(
    ///     env.clone(),
    ///     OracleProvider::Reflector
    /// ) {
    ///     Ok(result) => {
    ///         println!("Oracle response time: {}", result.execution_time);
    ///         println!("Oracle gas usage: {}", result.gas_usage);
    ///     },
    ///     Err(e) => println!("Oracle benchmark failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn benchmark_oracle_performance(
        env: Env,
        oracle: OracleProvider,
    ) -> Result<performance_benchmarks::BenchmarkResult, Error> {
        performance_benchmarks::PerformanceBenchmarkManager::benchmark_oracle_call_performance(
            &env, oracle,
        )
    }

    /// Benchmark batch operations performance
    ///
    /// This function measures the performance of batch operations including
    /// gas efficiency, execution time, and throughput characteristics.
    /// It's essential for batch operation optimization and scalability analysis.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `operations` - Vector of batch operations to benchmark
    ///
    /// # Returns
    ///
    /// Returns `Result<BenchmarkResult, Error>` where:
    /// - `Ok(BenchmarkResult)` - Complete batch operation benchmark results
    /// - `Err(Error)` - Error if benchmarking fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::{Env, vec};
    /// # use predictify_hybrid::{PredictifyHybrid, BatchOperation};
    /// # let env = Env::default();
    /// # let operations = vec![
    /// #     &env,
    /// #     BatchOperation {
    /// #         operation_type: String::from_str(&env, "batch_vote"),
    /// #         batch_size: 100,
    /// #         operation_count: 10,
    /// #         data_size: 1024,
    /// #     }
    /// # ];
    ///
    /// match PredictifyHybrid::benchmark_batch_operations(env.clone(), operations) {
    ///     Ok(result) => {
    ///         println!("Batch execution time: {}", result.execution_time);
    ///         println!("Batch gas usage: {}", result.gas_usage);
    ///     },
    ///     Err(e) => println!("Batch benchmark failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn benchmark_batch_operations(
        env: Env,
        operations: Vec<performance_benchmarks::BatchOperation>,
    ) -> Result<performance_benchmarks::BenchmarkResult, Error> {
        performance_benchmarks::PerformanceBenchmarkManager::benchmark_batch_operations(
            &env, operations,
        )
    }

    /// Benchmark scalability with large markets and user counts
    ///
    /// This function measures the contract's performance under high load
    /// scenarios with large numbers of markets and users. It's essential
    /// for scalability testing and performance validation.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `market_size` - Number of markets to simulate
    /// * `user_count` - Number of users to simulate
    ///
    /// # Returns
    ///
    /// Returns `Result<BenchmarkResult, Error>` where:
    /// - `Ok(BenchmarkResult)` - Complete scalability benchmark results
    /// - `Err(Error)` - Error if benchmarking fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::PredictifyHybrid;
    /// # let env = Env::default();
    ///
    /// match PredictifyHybrid::benchmark_scalability(env.clone(), 1000, 10000) {
    ///     Ok(result) => {
    ///         println!("Scalability test completed");
    ///         println!("Total gas usage: {}", result.gas_usage);
    ///         println!("Total execution time: {}", result.execution_time);
    ///     },
    ///     Err(e) => println!("Scalability benchmark failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn benchmark_scalability(
        env: Env,
        market_size: u32,
        user_count: u32,
    ) -> Result<performance_benchmarks::BenchmarkResult, Error> {
        performance_benchmarks::PerformanceBenchmarkManager::benchmark_scalability(
            &env,
            market_size,
            user_count,
        )
    }

    /// Generate comprehensive performance report
    ///
    /// This function creates a detailed performance report including metrics,
    /// recommendations, and optimization opportunities based on benchmark results.
    /// It's essential for performance analysis and optimization planning.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `benchmark_suite` - The benchmark suite to generate report for
    ///
    /// # Returns
    ///
    /// Returns `Result<PerformanceReport, Error>` where:
    /// - `Ok(PerformanceReport)` - Complete performance report with analysis
    /// - `Err(Error)` - Error if report generation fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::{PredictifyHybrid, PerformanceBenchmarkSuite};
    /// # let env = Env::default();
    /// # let suite = PerformanceBenchmarkSuite::default(); // Placeholder
    ///
    /// match PredictifyHybrid::generate_performance_report(env.clone(), suite) {
    ///     Ok(report) => {
    ///         println!("Performance report generated");
    ///         println!("Overall score: {}", report.performance_metrics.overall_performance_score);
    ///         println!("Recommendations: {}", report.recommendations.len());
    ///     },
    ///     Err(e) => println!("Report generation failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn generate_performance_report(
        env: Env,
        benchmark_suite: performance_benchmarks::PerformanceBenchmarkSuite,
    ) -> Result<performance_benchmarks::PerformanceReport, Error> {
        performance_benchmarks::PerformanceBenchmarkManager::generate_performance_report(
            &env,
            benchmark_suite,
        )
    }

    /// Validate performance against thresholds
    ///
    /// This function validates performance metrics against predefined thresholds
    /// to ensure the contract meets performance requirements. It's essential
    /// for performance validation and quality assurance.
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `metrics` - Performance metrics to validate
    /// * `thresholds` - Performance thresholds to validate against
    ///
    /// # Returns
    ///
    /// Returns `Result<bool, Error>` where:
    /// - `Ok(true)` - Performance meets all thresholds
    /// - `Ok(false)` - Performance does not meet thresholds
    /// - `Err(Error)` - Error if validation fails
    ///
    /// # Example
    ///
    /// ```rust
    /// # use soroban_sdk::Env;
    /// # use predictify_hybrid::{PredictifyHybrid, PerformanceMetrics, PerformanceThresholds};
    /// # let env = Env::default();
    /// # let metrics = PerformanceMetrics::default(); // Placeholder
    /// # let thresholds = PerformanceThresholds::default(); // Placeholder
    ///
    /// match PredictifyHybrid::validate_performance_thresholds(env.clone(), metrics, thresholds) {
    ///     Ok(true) => println!("Performance meets all thresholds"),
    ///     Ok(false) => println!("Performance does not meet thresholds"),
    ///     Err(e) => println!("Validation failed: {:?}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when validation, authorization, storage, or subsystem checks fail.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn validate_performance_thresholds(
        env: Env,
        metrics: performance_benchmarks::PerformanceMetrics,
        thresholds: performance_benchmarks::PerformanceThresholds,
    ) -> Result<bool, Error> {
        performance_benchmarks::PerformanceBenchmarkManager::validate_performance_thresholds(
            &env, metrics, thresholds,
        )
    }
    /// Get platform-wide statistics
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    /// Verify SAC token decimals match declared value (admin only).
    ///
    /// This function performs a critical security check on SAC tokens to prevent
    /// denomination mistakes that have caused real on-chain losses. It verifies that
    /// the token's on-chain decimals() value matches what was declared during registration.
    ///
    /// This can be called:
    /// - Automatically during token registration (via add_global_verified/add_event_verified)
    /// - Manually by admin as part of periodic audits or security reviews
    ///
    /// # Parameters
    ///
    /// * `env` - The Soroban environment for blockchain operations
    /// * `admin` - The administrator address (must be authorized)
    /// * `token_contract` - Address of the token contract to verify
    /// * `declared_decimals` - The decimals value that was declared during registration
    ///
    /// # Returns
    ///
    /// Returns `Result<(), Error>` where:
    /// - `Ok(())` - Decimals match (token is safe)
    /// - `Err(Error::TokenDecimalsMismatch)` - Mismatch detected (token rejected)
    /// - `Err(Error::Unauthorized)` - Caller is not admin
    ///
    /// # Cross-Contract Call
    ///
    /// This function performs a cross-contract call to the token contract's
    /// `decimals()` function using the Soroban token interface.
    ///
    /// # Security Notes
    ///
    /// - Verifies via on-chain decimals() call (cannot be spoofed)
    /// - Mismatch indicates potential token misconfiguration
    /// - Rejected tokens cannot be used for betting/payouts
    /// - All registration paths should use verified variants
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let token_contract = Address::from_string("GBUQW...");
    /// PredictifyHybrid::re_verify_token(&env, &admin, &token_contract, 7)?;
    /// // Returns Ok if decimals match, TokenDecimalsMismatch error otherwise
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error`] when:
    /// - `Error::Unauthorized` - Caller is not the contract admin
    /// - `Error::TokenDecimalsMismatch` - On-chain decimals don't match declared value
    /// - Other errors from cross-contract call or storage operations
    ///
    /// # Events
    ///
    /// Emits audit trail record of verification attempt (success or failure).
    pub fn re_verify_token(
        env: Env,
        admin: Address,
        token_contract: Address,
        declared_decimals: u32,
    ) -> Result<(), Error> {
        // Verify admin authorization
        Self::require_primary_admin(&env, &admin)?;

        // Create temporary asset for verification
        let asset = crate::tokens::Asset {
            contract: token_contract.clone(),
            symbol: Symbol::new(&env, "TEMP"),
            decimals: declared_decimals,
        };

        // Perform decimals verification via cross-contract call
        crate::tokens::verify_token_decimals(&env, &asset)?;

        // Record verification in audit trail
        crate::audit_trail::AuditTrailManager::append_record(
            &env,
            crate::audit_trail::AuditAction::TokenVerified,
            admin.clone(),
            Map::new(&env),
            None,
        );

        Ok(())
    }

    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_platform_statistics(env: Env) -> PlatformStatistics {
        statistics::StatisticsManager::get_platform_stats(&env)
    }

    /// Get user-specific statistics
    ///
    /// # Errors
    ///
    /// This entrypoint surfaces contract errors via panic in internal calls.
    ///
    /// # Events
    ///
    /// State-changing paths may emit events through internal managers; read-only query paths emit no events.
    pub fn get_user_statistics(env: Env, user: Address) -> UserStatistics {
        statistics::StatisticsManager::get_user_stats(&env, &user)
    }

    /// Get dashboard statistics with versioning for client compatibility
    ///
    /// Provides comprehensive platform-level metrics optimized for dashboard display,
    /// including version information for managing client updates.
    ///
    /// # Returns
    ///
    /// * `DashboardStatisticsV1` - Versioned dashboard statistics with:
    ///   - API version (always 1)
    ///   - Platform statistics
    ///   - Active user count
    ///   - Total value locked
    ///   - Query timestamp
    ///
    /// # Errors
    ///
    /// Returns contract error if market traversal fails.
    ///
    /// # Events
    ///
    /// This is a read-only query; no events are emitted.
    pub fn get_dashboard_statistics(env: Env) -> Result<types::DashboardStatisticsV1, Error> {
        queries::QueryManager::get_dashboard_statistics(&env)
    }

    /// Get market statistics optimized for dashboard display
    ///
    /// Returns comprehensive per-market metrics including participant count,
    /// volume, consensus strength, and volatility for dashboard visualization.
    ///
    /// # Parameters
    ///
    /// * `market_id` - The market to query
    ///
    /// # Returns
    ///
    /// * `MarketStatisticsV1` - Market metrics with:
    ///   - Participant count
    ///   - Total volume
    ///   - Average stake
    ///   - Consensus strength (0-10000)
    ///   - Volatility (0-10000)
    ///   - Market state and question
    ///
    /// # Errors
    ///
    /// * `Error::MarketNotFound` - Market doesn't exist
    ///
    /// # Events
    ///
    /// Read-only query; no events emitted.
    pub fn get_market_statistics(
        env: Env,
        market_id: Symbol,
    ) -> Result<types::MarketStatisticsV1, Error> {
        queries::QueryManager::get_market_statistics(&env, market_id)
    }

    /// Get category statistics for filtered dashboard views
    ///
    /// Provides aggregated metrics for all markets in a specific category,
    /// enabling category-filtered dashboard displays and analytics.
    ///
    /// # Parameters
    ///
    /// * `category` - Category name to query
    ///
    /// # Returns
    ///
    /// * `CategoryStatisticsV1` - Category metrics with:
    ///   - Market count
    ///   - Total volume
    ///   - Participant count
    ///   - Resolved market count
    ///   - Average market volume
    ///
    /// # Events
    ///
    /// Read-only query; no events emitted.
    pub fn get_category_statistics(
        env: Env,
        category: String,
    ) -> Result<types::CategoryStatisticsV1, Error> {
        queries::QueryManager::get_category_statistics(&env, category)
    }

    /// Get top users by total winnings (leaderboard query)
    ///
    /// Returns the top N users ranked by total winnings claimed,
    /// useful for leaderboard and achievement displays.
    ///
    /// # Parameters
    ///
    /// * `limit` - Maximum number of results (capped at 50 for gas safety)
    ///
    /// # Returns
    ///
    /// * `Vec<UserLeaderboardEntryV1>` - Top users sorted by winnings (descending)
    ///
    /// # Notes
    ///
    /// Due to contract storage scanning limitations, large deployments should
    /// consider off-chain indexing for leaderboard queries.
    ///
    /// # Events
    ///
    /// Read-only query; no events emitted.
    pub fn get_top_users_by_winnings(
        env: Env,
        limit: u32,
    ) -> Result<Vec<types::UserLeaderboardEntryV1>, Error> {
        queries::QueryManager::get_top_users_by_winnings(&env, limit)
    }

    /// Get top users by win rate (skill-based leaderboard)
    ///
    /// Returns the top N users ranked by win rate percentage,
    /// with a minimum bet requirement to filter high-variance winners.
    ///
    /// # Parameters
    ///
    /// * `limit` - Maximum number of results (capped at 50)
    /// * `min_bets` - Minimum bets required for inclusion (e.g., 10)
    ///
    /// # Returns
    ///
    /// * `Vec<UserLeaderboardEntryV1>` - Top users sorted by win rate (descending)
    ///
    /// # Events
    ///
    /// Read-only query; no events emitted.
    pub fn get_top_users_by_win_rate(
        env: Env,
        limit: u32,
        min_bets: u64,
    ) -> Result<Vec<types::UserLeaderboardEntryV1>, Error> {
        queries::QueryManager::get_top_users_by_win_rate(&env, limit, min_bets)
    }

    /// Admin-initiated circuit-breaker resume: Open → HalfOpen with cooldown.
    ///
    /// Moves the circuit breaker from `Open` to `HalfOpen` and records the
    /// current ledger timestamp as the cooldown start.  Probe requests are not
    /// counted toward the success threshold until `recovery_timeout` seconds have
    /// elapsed.  After `half_open_max_requests` consecutive probe successes the
    /// breaker auto-closes; any failure during the probe window re-opens it.
    ///
    /// # Errors
    ///
    /// - `Error::Unauthorized` — caller is not an authorised admin.
    /// - `Error::CBError` — breaker is not currently `Open`.
    pub fn request_resume(env: Env, admin: Address) -> Result<(), Error> {
        admin.require_auth();
        crate::circuit_breaker::CircuitBreaker::request_resume(&env, &admin)
    }

    /// Return a versioned, XDR-stable snapshot of current platform statistics.
    ///
    /// The returned [`reporting::SnapshotEnvelope`] contains the current
    /// [`reporting::PlatformStats`] serialised with `to_xdr`, tagged with
    /// [`reporting::SNAPSHOT_SCHEMA_VERSION`] and the current ledger timestamp.
    ///
    /// # Errors
    ///
    /// - `Error::ContractStateError` — market index is missing or corrupted.
    pub fn get_snapshot_envelope(env: Env) -> Result<reporting::SnapshotEnvelope, Error> {
        reporting::ReportingManager::get_snapshot_envelope(&env)
    }

    /// Accumulate dispute fees. Called after each dispute resolution to add
    /// `fee_amount` to the running cumulative total. Returns the new total.
    pub fn accumulate_dispute_fee(env: Env, caller: Address, fee_amount: i128) -> i128 {
        caller.require_auth();
        if fee_amount < 0 {
            panic_with_error!(env, Error::InvalidInput);
        }
        let key = Symbol::new(&env, "cum_disp_fee");
        let current: i128 = env.storage().instance().get(&key).unwrap_or(0i128);
        let new_total = current.checked_add(fee_amount)
            .unwrap_or_else(|| panic_with_error!(env, Error::Overflow));
        env.storage().instance().set(&key, &new_total);
        new_total
    }

    /// Get the cumulative dispute fee total accumulated so far.
    pub fn get_cumulative_dispute_fee(env: Env) -> i128 {
        env.storage()
            .instance()
            .get(&Symbol::new(&env, "cum_disp_fee"))
            .unwrap_or(0i128)
    }

}