lib.rs

#![allow(deprecated)] // TODO: migrate Soroban events to #[contractevent].
#![no_std]
// Contributing? See CONTRIBUTING.md for error-numbering, event-topic, auth,
// pause, and storage/TTL conventions plus the PR checklist.

#[cfg(test)]
extern crate std;

use soroban_sdk::xdr::ToXdr;
use soroban_sdk::{
    contract, contracterror, contractimpl, contracttype, panic_with_error, symbol_short, Address,
    Bytes, BytesN, Env, Symbol, Vec,
};

/// Aggregated read of every pair-scoped storage slot (base fields).
#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PairInfo {
    pub registered: bool,
    pub fee_bps: u32,
    pub min_amount: i128,
    pub max_amount: i128,
    pub liquidity: i128,
    pub last_route_at: u64,
}

/// Extended aggregate read of every pair-scoped storage slot, including
/// cooldown, route count, and cumulative volume. See [`PairInfo`] for the
/// original (base) field set.
#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PairInfoExt {
    pub registered: bool,
    pub fee_bps: u32,
    pub min_amount: i128,
    pub max_amount: i128,
    pub liquidity: i128,
    pub last_route_at: u64,
    pub cooldown_secs: u64,
    pub route_count: u64,
    pub volume: i128,
}

/// Aggregated read of the queued admin handover: the proposed pending
/// admin and the earliest timestamp at which it may accept.
///
/// Returned by [`StableRouteRouter::get_pending_admin_info`] so watchers
/// get both slots from a single invocation. Both fields are `None` when
/// no transfer is queued.
#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PendingAdminInfo {
    /// Address proposed via `propose_admin_transfer`, if any.
    pub pending: Option<Address>,
    /// Earliest ledger timestamp at which the pending admin may call
    /// `accept_admin_transfer` (`propose` time + timelock), if queued.
    pub eta: Option<u64>,
}

/// Aggregated read of the protocol-wide limits that callers must respect
/// before submitting a transaction.
///
/// Every field mirrors a `pub const` in this module
/// ([`MAX_FEE_BPS`], [`BPS_DENOMINATOR`], [`MAX_BATCH_SIZE`],
/// [`MAX_COOLDOWN_SECS`]). Exposing them as a `#[contracttype]` lets an
/// on-chain caller or a client that did not compile against this crate
/// discover the enforced bounds in a single read via [`StableRouteRouter::get_limits`].
///
/// **Field order is part of the stable on-chain ABI** — do not reorder or
/// insert fields, as that would change the XDR encoding. New limits must be
/// appended. Documented in [`docs/abi.md`].
#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RouterLimits {
    /// Upper bound on the per-pair fee, in basis points. Mirrors [`MAX_FEE_BPS`].
    pub max_fee_bps: u32,
    /// Basis-point denominator (1 bps = 1 / `bps_denominator`). Mirrors [`BPS_DENOMINATOR`].
    pub bps_denominator: i128,
    /// Maximum number of entries in a single batch operation. Mirrors [`MAX_BATCH_SIZE`].
    pub max_batch_size: u32,
    /// Upper bound on the per-pair route cooldown, in seconds. Mirrors [`MAX_COOLDOWN_SECS`].
    pub max_cooldown_secs: u64,
}

/// Aggregated read of the contract's global (non-pair-scoped) configuration:
/// fee recipient, absolute fee bounds, liquidity oracle, and governance
/// timelock delay. Lets callers fetch the whole admin-configured surface in
/// a single invocation instead of five separate getter calls.
///
/// Every field reads its documented sane default when unset (see
/// [`DataKey`]'s sentinel conventions), so this view is safe to call before
/// any admin configuration has taken place.
#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct GlobalConfig {
    /// Mirrors [`StableRouteRouter::get_fee_recipient`]. `None` when unset.
    pub fee_recipient: Option<Address>,
    /// Mirrors [`StableRouteRouter::get_max_fee_absolute`]. `None` when no
    /// absolute ceiling is enforced.
    pub max_fee_absolute: Option<i128>,
    /// Mirrors [`StableRouteRouter::get_min_fee_absolute`]. `None` when no
    /// absolute floor is enforced.
    pub min_fee_absolute: Option<i128>,
    /// Mirrors [`StableRouteRouter::get_oracle`]. `None` when unset.
    pub oracle: Option<Address>,
    /// Mirrors [`StableRouteRouter::get_timelock`]. Defaults to `0`.
    pub timelock_secs: u64,
}

/// Storage keys used by the StableRoute router. Twenty-one variants total.
/// Most live in persistent storage; three hot-global singletons
/// ([`Admin`](DataKey::Admin), [`PendingAdmin`](DataKey::PendingAdmin),
/// [`Paused`](DataKey::Paused)) live in **instance** storage so they are
/// read together with the contract instance on every admin-gated or
/// pause-gated call, avoiding a separate persistent-storage hit.
///
/// See [`docs/storage.md`] for the authoritative reference: key shape,
/// value type, default-when-absent, reader/writer entrypoints, and TTL
/// classification (Static / Config / Hot).
///
/// ## Sentinel conventions
///
/// - Absent `bool`  → `false` (pair registration, paused, reentrancy lock).
/// - `i128::MAX`      → "unbounded" sentinel for `PairMaxAmount` and for
///   liquidity *inside `compute_route_fee` only*.
/// - `0`              → default for counters, fees, timestamps (as `u64`),
///   `PairMinAmount`, and cooldowns.
/// - Absent `Option`  → `None` (admin, pending admin, fee recipient,
///   last-route timestamp, max fee absolute, min fee absolute, oracle).
/// - `SchemaVersion`  → `1` when absent (the implicit pre-migration default).
#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum DataKey {
    /// Operational admin (singleton, `Address`, **instance** — hot global).
    /// Set once by `__constructor`; only changed by a two-step handover
    /// (`propose_admin_transfer` → `accept_admin_transfer`).
    /// Absent reads panic with `NotInitialized` (#2).
    Admin,
    /// `true` if `(source, destination)` is a recognised route.
    /// Keyed per-pair; stored as `bool` so callers can query without
    /// distinguishing "absent" from "false". Defaults to `false`.
    Pair(Symbol, Symbol),
    /// Per-pair fee in basis points (1 bps = 0.01 %). Stored as `u32`
    /// so the on-the-wire shape is fixed; values above `MAX_FEE_BPS`
    /// are rejected at write time. Defaults to `0` (free).
    PairFeeBps(Symbol, Symbol),
    /// Pending admin proposed via `propose_admin_transfer` (singleton,
    /// `Address`, **instance** — hot global). Two-step handover guards
    /// against locking the contract with a bad key. Absent ↔ `None` (no
    /// handover queued).
    PendingAdmin,
    /// `true` when the router is paused (singleton, `bool`, **instance**
    /// — hot global). Route-accounting (`compute_route_fee`), pair
    /// registration (`register_pair`, `register_pairs`), and fee setters
    /// (`set_pair_fee_bps`, `set_pair_fees_bps`) reject calls while
    /// paused. Admin/config setters (`set_pair_liquidity`,
    /// `set_pair_cooldown`, `set_pair_min_amount`, `set_pair_max_amount`,
    /// `set_fee_recipient`, `set_max_fee_absolute`,
    /// `set_min_fee_absolute`, `set_oracle`, `remove_oracle`), lifecycle
    /// entrypoints (`unregister_pair`, `purge_pair_metrics`), governance
    /// (`pause`, `unpause`, `set_timelock`, `propose_admin_transfer`,
    /// `cancel_admin_transfer`, `force_admin_transfer`,
    /// `accept_admin_transfer`), migration (`migrate_v1_to_v2`), and
    /// read-only queries (`quote_route`, getters, `version`) remain
    /// available so the admin can recover and integrators can keep
    /// planning routes. Defaults to `false` (not paused).
    Paused,
    /// Minimum routable amount per pair in source units (keyed per-pair,
    /// `i128`, persistent). `compute_route_fee` rejects amounts below the
    /// floor. Defaults to `0` (no floor).
    PairMinAmount(Symbol, Symbol),
    /// Maximum routable amount per pair in source units (keyed per-pair,
    /// `i128`, persistent). `compute_route_fee` rejects amounts above the
    /// ceiling. Defaults to `i128::MAX` (no ceiling).
    PairMaxAmount(Symbol, Symbol),
    /// Reported available liquidity in source units per pair (keyed
    /// per-pair, `i128`, persistent). Updated by an off-chain oracle
    /// (or the admin) via `set_pair_liquidity`; decremented on every
    /// successful `compute_route_fee`. Default is context-dependent:
    /// `get_pair_liquidity` returns `0` for absent, while
    /// `compute_route_fee` treats absent as `i128::MAX` (unbounded).
    /// An explicitly set `0` liquidity makes the pair non-routable
    /// in both `compute_route_fee` and `quote_route` via
    /// `InsufficientLiquidity`.
    PairLiquidity(Symbol, Symbol),
    /// Address that receives protocol fees on settlement (singleton,
    /// `Address`, persistent). Absent ↔ `None`.
    FeeRecipient,
    /// Protocol-wide lifetime counter of `compute_route_fee` invocations
    /// (singleton, `u64`, persistent). Incremented with `saturating_add`
    /// so it is monotonic and never panics. Defaults to `0`.
    TotalRoutesAllTime,
    /// Protocol-wide lifetime sum of fees collected by `compute_route_fee`
    /// (singleton, `i128`, persistent), owed to whoever holds
    /// `FeeRecipient` once distributed off-chain. Accumulated with
    /// `saturating_add` so it is monotonic and never panics on overflow.
    /// Defaults to `0`.
    RewardsAccrued,
    /// Ledger timestamp of the most recent `compute_route_fee` for a
    /// pair (keyed per-pair, `u64`, persistent). Used by the cooldown
    /// rate-limit gate. Absent reads as `None` (`Option`); `get_pair_info`
    /// flattens it to `0`.
    PairLastRouteAt(Symbol, Symbol),
    /// Per-pair lifetime counter of `compute_route_fee` invocations
    /// (keyed per-pair, `u64`, persistent). Incremented with
    /// `saturating_add` so it is monotonic and never panics on overflow.
    /// Defaults to `0`.
    PairRouteCount(Symbol, Symbol),
    /// Per-pair cumulative routed volume — sum of `amount` in source
    /// units (keyed per-pair, `i128`, persistent). Accumulated with
    /// `saturating_add` so it is monotonic and never panics on overflow.
    /// Defaults to `0`.
    PairVolume(Symbol, Symbol),
    /// On-chain storage schema version (singleton, `u32`, persistent).
    /// Distinct from `version()`. Defaults to `1` when absent (the
    /// implicit pre-migration layout). Advanced to `2` by
    /// `migrate_v1_to_v2`.
    SchemaVersion,
    /// Governance timelock delay in seconds (singleton, `u64`,
    /// persistent). When > 0, a proposed admin handover can only be
    /// accepted after the delay has elapsed. Defaults to `0` (instant)
    /// when unset, preserving prior behaviour.
    Timelock,
    /// Earliest ledger timestamp at which the currently pending admin
    /// transfer may be accepted — `propose_admin_transfer` time + delay
    /// (singleton, `u64`, persistent). Absent ↔ `None` (no handover
    /// queued).
    PendingAdminEta,
    /// Non-reentrancy guard (singleton, `bool`, persistent). Set to
    /// `true` before the write/event phase of `compute_route_fee` and
    /// cleared to `false` on exit. Defaults to `false`.
    ReentrancyLock,
    /// Per-pair cooldown in seconds between route accounting calls
    /// (keyed per-pair, `u64`, persistent). While non-zero,
    /// `compute_route_fee` rejects a call until at least this many
    /// seconds have elapsed since `PairLastRouteAt`. Capped at
    /// `MAX_COOLDOWN_SECS` (30 days). Defaults to `0` (disabled).
    PairCooldown(Symbol, Symbol),
    /// `true` when `(source, destination)` has an active dispute flag
    /// (keyed per-pair, `bool`, persistent). Set by `flag_pair_dispute`
    /// and cleared by `resolve_pair_dispute` or `unregister_pair`. While
    /// `true`, `quote_route` and `compute_route_fee` reject the pair with
    /// `PairDisputed`. Defaults to `false`.
    PairDisputed(Symbol, Symbol),
    /// Optional absolute per-route fee ceiling (singleton, `i128`,
    /// persistent). When set, the effective fee is `min(bps_fee, cap)`.
    /// Absent ↔ `None` (only the relative `MAX_FEE_BPS` bound applies).
    /// A stored value of 0 (from a pre-upgrade write) is treated as
    /// `None` by both `apply_fee_cap` and `get_max_fee_absolute`; zero
    /// caps are rejected at write time with `ZeroFeeCap` (#21).
    /// [`StableRouteRouter::clear_max_fee_absolute`] is the supported
    /// way to remove the cap entirely.
    MaxFeeAbsolute,
    /// Optional absolute per-route fee floor (singleton, `i128`,
    /// persistent). When set, the effective fee is `max(capped_fee, floor)`.
    /// Absent ↔ `None` (no absolute floor applies).
    MinFeeAbsolute,
    /// Scoped liquidity oracle address (singleton, `Address`,
    /// persistent). The oracle may call `set_pair_liquidity` and
    /// nothing else — it cannot set fees, pause, rotate admin, or
    /// upgrade. Absent ↔ `None` (no oracle configured — admin-only
    /// liquidity feed).
    Oracle,
}

/// Upper bound on the per-pair fee. 1 000 bps = 10 %. Tightening this
/// further is a governance decision; raising it is append-only safe
/// but should be deliberate.
pub const MAX_FEE_BPS: u32 = 1_000;
/// Basis-point denominator: 1 bps = 1/10_000.
pub const BPS_DENOMINATOR: i128 = 10_000;
/// Maximum number of entries in a single batch operation
/// (`register_pairs`, `set_pair_fees_bps`). Kept modest to bound
/// per-transaction gas costs.
pub const MAX_BATCH_SIZE: u32 = 100;
/// Upper bound on the per-pair route cooldown, in seconds (30 days).
/// `set_pair_cooldown` rejects any larger value so a fat-fingered or
/// malicious config write (e.g. `u64::MAX`) cannot permanently brick a
/// corridor by making `compute_route_fee`'s `last + cooldown` gate
/// unreachable. Ledger timestamps are seconds since epoch and are nowhere
/// near `u64::MAX - MAX_COOLDOWN_SECS`, so capping here also guarantees
/// the `last + cooldown` addition in `compute_route_fee` cannot overflow
/// `u64` for the foreseeable future.
pub const MAX_COOLDOWN_SECS: u64 = 2_592_000;

/// Ledger-count threshold below which a hot-state write (see
/// [`StableRouteRouter::bump_instance_ttl`]) renews the contract
/// instance's TTL. Assuming ~5s average ledger close time, this is
/// roughly 30 days. Kept well above [`INSTANCE_TTL_EXTEND_TO`]'s renewal
/// point is not required — the host clamps automatically — but choosing
/// a threshold this generous means the instance is topped up far before
/// it could ever approach archival.
pub const INSTANCE_TTL_THRESHOLD: u32 = 518_400;
/// Ledger count the contract instance's TTL is extended to whenever a
/// hot-state write triggers a renewal (see
/// [`StableRouteRouter::bump_instance_ttl`]). Assuming ~5s average
/// ledger close time, this is roughly 60 days.
pub const INSTANCE_TTL_EXTEND_TO: u32 = 1_036_800;

/// Typed contract errors. Codes are append-only — never reuse or
/// renumber a variant once it has shipped.
#[contracterror]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[repr(u32)]
pub enum RouterError {
    /// `init` was called but the admin address is already stored.
    AlreadyInitialized = 1,
    /// A read or write expected the admin to be set but it was not.
    NotInitialized = 2,
    /// `register_pair` was called with `source == destination`.
    SourceEqualsDestination = 3,
    /// `set_pair_fee_bps` was called with a value above [`MAX_FEE_BPS`].
    FeeBpsTooHigh = 4,
    /// `compute_route_fee` was called for a pair that was never registered.
    PairNotRegistered = 5,
    /// `compute_route_fee` was called with a non-positive amount.
    AmountMustBePositive = 6,
    /// `accept_admin_transfer` was called with no pending admin.
    NoPendingAdminTransfer = 7,
    /// `accept_admin_transfer` was called by a non-pending address.
    NotPendingAdmin = 8,
    /// A state-changing entrypoint was called while paused.
    ContractPaused = 9,
    /// Amount is below the configured PairMinAmount.
    AmountBelowMin = 10,
    /// Amount is above the configured PairMaxAmount.
    AmountAboveMax = 11,
    /// Reported pair liquidity is below the requested amount.
    InsufficientLiquidity = 12,
    /// `migrate_v1_to_v2` was called from a non-v1 schema.
    MigrationVersionMismatch = 13,
    /// `accept_admin_transfer` was called before the governance timelock
    /// delay elapsed.
    TimelockNotElapsed = 14,
    /// A non-reentrant entrypoint was entered while already locked.
    ReentrantCall = 15,
    /// Caller was neither the admin nor the scoped oracle.
    NotAuthorized = 16,
    /// Per-pair cooldown has not elapsed since the last route.
    RouteCooldownActive = 17,
    /// `register_pairs` or `set_pair_fees_bps` was called with a batch
    /// exceeding [`MAX_BATCH_SIZE`] entries.
    BatchTooLarge = 18,
    /// `register_pairs` or `set_pair_fees_bps` was called with an empty
    /// batch.
    EmptyBatch = 19,
    /// `set_pair_cooldown` was called with a value above
    /// [`MAX_COOLDOWN_SECS`].
    CooldownTooLarge = 20,
    /// `set_max_fee_absolute` was called with zero, which would make every
    /// route free. Use [`StableRouteRouter::clear_max_fee_absolute`] to
    /// remove the cap entirely.
    ZeroFeeCap = 21,
    /// `quote_route` or `compute_route_fee` was called for a pair with an
    /// active dispute flag (see [`StableRouteRouter::flag_pair_dispute`]).
    PairDisputed = 22,
}

/// StableRoute router contract — placeholder for routing logic.
/// In production this would integrate with path payments and liquidity data.
#[contract]
pub struct StableRouteRouter;

#[contractimpl]
impl StableRouteRouter {
    // ── Lifecycle ──────────────────────────────────────────────────────────
    // Contract construction, legacy init, and schema migration.

    /// Migrate the schema from v1 to v2. Admin-gated; panics with
    /// MigrationVersionMismatch on a non-v1 starting state. v2 readers
    /// default sensibly when their new slots are absent, so the body
    /// only stamps the new SchemaVersion.
    pub fn migrate_v1_to_v2(env: Env) {
        Self::require_admin(&env);
        let current: u32 = env
            .storage()
            .persistent()
            .get(&DataKey::SchemaVersion)
            .unwrap_or(1);
        if current != 1 {
            panic_with_error!(&env, RouterError::MigrationVersionMismatch);
        }
        env.storage()
            .persistent()
            .set(&DataKey::SchemaVersion, &2u32);
    }

    /// Deploy-time constructor — sets the operational admin **atomically**
    /// at contract instantiation.
    ///
    /// Running as the constructor closes the init front-running window:
    /// the admin slot is written in the same transaction that deploys the
    /// contract (`register(StableRouteRouter, (admin,))`), so there is no
    /// observable deployed-but-uninitialized state for an attacker to race
    /// a separate `init` call into. Requires `admin.require_auth()` and
    /// emits the `init` event for indexers.
    pub fn __constructor(env: Env, admin: Address) {
        admin.require_auth();
        env.storage().instance().set(&DataKey::Admin, &admin);
        Self::bump_instance_ttl(&env);
        env.events().publish((symbol_short!("init"),), admin);
    }

    /// Legacy initializer, retained for ABI compatibility only.
    ///
    /// The admin is now set by [`Self::__constructor`] at deploy time, so
    /// the slot is always populated and this entrypoint can never claim
    /// it. It unconditionally panics with
    /// [`RouterError::AlreadyInitialized`], preserving the historical
    /// `#1` semantics for any client still calling `init` post-deploy and
    /// guaranteeing an attacker can never seize the admin role via `init`.
    pub fn init(env: Env, admin: Address) {
        let _ = admin;
        panic_with_error!(&env, RouterError::AlreadyInitialized);
    }

    // ── Governance ────────────────────────────────────────────────────────
    // Pause control, governance timelock, and two-step admin handover.

    /// Resume after a pause. Admin-gated and idempotent.
    pub fn unpause(env: Env) {
        Self::require_admin(&env);
        env.storage().instance().set(&DataKey::Paused, &false);
        Self::bump_instance_ttl(&env);
        env.events().publish((symbol_short!("paused"),), false);
    }

    /// Admin pauses the router. All state-changing entrypoints will
    /// then panic with ContractPaused.
    pub fn pause(env: Env) {
        Self::require_admin(&env);
        env.storage().instance().set(&DataKey::Paused, &true);
        Self::bump_instance_ttl(&env);
        env.events().publish((symbol_short!("paused"),), true);
    }

    /// Admin sets the governance timelock delay (seconds). Applies to the
    /// **next** `propose_admin_transfer`; already-queued actions keep the
    /// eta they were stamped with. Pass 0 to disable (instant handover).
    ///
    /// Emits a `tlock_set` event containing the old and new delay values.
    ///
    /// # Events
    ///
    /// - Topic: `(symbol_short!("tlock_set"),)`
    /// - Payload: `(old_delay, new_delay): (u64, u64)`
    /// - When: fires when the governance timelock delay is modified by the admin.
    pub fn set_timelock(env: Env, delay_seconds: u64) {
        Self::require_admin(&env);
        let old_delay = Self::get_timelock(env.clone());
        env.storage()
            .persistent()
            .set(&DataKey::Timelock, &delay_seconds);
        env.events()
            .publish((symbol_short!("tlock_set"),), (old_delay, delay_seconds));
    }

    /// Cancel a pending handover, clearing both the pending admin and its
    /// queued eta. No-op (storage-wise) if none is pending.
    ///
    /// Emits a `cancelled` event carrying the pending admin and eta that
    /// were cleared (both `None` on a no-op cancellation) — the third leg
    /// of the propose (`queued`) / accept-or-force (`executed`) / cancel
    /// (`cancelled`) event trail, so every claim-state transition is
    /// observable on-chain, not just the two that previously had events.
    pub fn cancel_admin_transfer(env: Env) {
        Self::require_admin(&env);
        let pending: Option<Address> = env.storage().instance().get(&DataKey::PendingAdmin);
        let eta: Option<u64> = env.storage().persistent().get(&DataKey::PendingAdminEta);
        env.storage().instance().remove(&DataKey::PendingAdmin);
        env.storage().persistent().remove(&DataKey::PendingAdminEta);
        Self::bump_instance_ttl(&env);
        env.events()
            .publish((symbol_short!("cancelled"),), (pending, eta));
    }

    /// Step 2 of admin handover. The pending admin claims the role
    /// from their own key. Panics with NoPendingAdminTransfer if none
    /// is pending or NotPendingAdmin if the caller does not match.
    pub fn accept_admin_transfer(env: Env, caller: Address) {
        caller.require_auth();
        Self::require_pending_admin_and_timelock_elapsed(&env, &caller);
        Self::finalize_admin_transfer(&env, caller);
    }

    /// Step 1 of admin handover. Current admin proposes a new admin;
    /// the new admin must then accept via `accept_admin_transfer` once the
    /// governance timelock (if any) has elapsed.
    ///
    /// Stamps `PendingAdminEta = now + timelock` and emits a `queued`
    /// event carrying the new admin and the eta so watchers get a warning
    /// window before control can actually change hands.
    pub fn propose_admin_transfer(env: Env, new_admin: Address) {
        Self::require_admin(&env);
        let delay: u64 = env
            .storage()
            .persistent()
            .get(&DataKey::Timelock)
            .unwrap_or(0);
        let eta = env.ledger().timestamp().saturating_add(delay);
        env.storage()
            .instance()
            .set(&DataKey::PendingAdmin, &new_admin.clone());
        env.storage()
            .persistent()
            .set(&DataKey::PendingAdminEta, &eta);
        Self::bump_instance_ttl(&env);
        env.events()
            .publish((symbol_short!("queued"),), (new_admin, eta));
    }

    /// Force-complete an admin handover after the timelock has elapsed,
    /// without requiring the new admin to call `accept_admin_transfer`.
    ///
    /// Admin-gated. Requires that `propose_admin_transfer` was already
    /// called with the same `new_admin` and that the timelock delay has
    /// elapsed. Emits the same `executed` event as `accept_admin_transfer`
    /// so indexers can treat it identically.
    pub fn force_admin_transfer(env: Env, new_admin: Address) {
        Self::require_admin(&env);
        Self::require_pending_admin_and_timelock_elapsed(&env, &new_admin);
        Self::finalize_admin_transfer(&env, new_admin);
    }

    // ── Roles ─────────────────────────────────────────────────────────────
    // Protocol-wide role assignments (fee recipient, liquidity oracle).

    /// Admin sets the address that receives protocol fees at
    /// settlement time. The router itself never custodies funds.
    /// Emits a `recip_set` event carrying the new recipient address.
    pub fn set_fee_recipient(env: Env, recipient: Address) {
        Self::require_admin(&env);
        env.storage()
            .persistent()
            .set(&DataKey::FeeRecipient, &recipient);
        env.events()
            .publish((symbol_short!("recip_set"),), recipient);
    }

    /// Assign the contract's liquidity oracle.
    ///
    /// Admin-gated. Only the configured oracle may subsequently update
    /// pair liquidity values.
    pub fn set_oracle(env: Env, oracle: Address) {
        Self::require_admin(&env);
        env.storage().persistent().set(&DataKey::Oracle, &oracle);
        // Topic shortened to satisfy the 9-char `symbol_short!` limit.
        env.events().publish((symbol_short!("orac_set"),), oracle);
    }

    /// Remove the currently configured liquidity oracle.
    ///
    /// Admin-gated. After removal, no address is authorized to update
    /// liquidity until a new oracle is configured.
    pub fn remove_oracle(env: Env) {
        Self::require_admin(&env);
        let removed: Option<Address> = env.storage().persistent().get(&DataKey::Oracle);
        env.storage().persistent().remove(&DataKey::Oracle);
        env.events().publish((symbol_short!("orac_rm"),), removed);
    }

    // ── Pair config ───────────────────────────────────────────────────────
    // Register / unregister pairs, set per-pair fees, bounds, cooldown,
    // liquidity, and global fee cap / floor.

    /// Register `(source, destination)` as a recognised route.
    ///
    /// Admin-gated; rejects `source == destination`. Idempotent: a
    /// second call with the same pair simply re-asserts the entry and
    /// is a no-op from the caller's perspective, including on events —
    /// `pair_reg` fires only on the transition from unregistered to
    /// registered, never on a redundant re-assertion of an already
    /// registered pair.
    ///
    /// **Registration-first invariant:** `set_pair_fee_bps`,
    /// `set_pair_min_amount`, `set_pair_max_amount`, and
    /// `set_pair_liquidity` all require the pair to already be registered
    /// here, and panic with [`RouterError::PairNotRegistered`] (#5)
    /// otherwise. Always call `register_pair` before configuring a
    /// corridor's fee, bounds, or liquidity.
    pub fn register_pair(env: Env, source: Symbol, destination: Symbol) {
        Self::require_not_paused(&env);
        Self::require_admin(&env);
        if source == destination {
            panic_with_error!(&env, RouterError::SourceEqualsDestination);
        }
        let already_registered = Self::read_pair_registered(&env, &source, &destination);
        env.storage()
            .persistent()
            .set(&DataKey::Pair(source.clone(), destination.clone()), &true);
        if !already_registered {
            env.events()
                .publish((symbol_short!("pair_reg"),), (source, destination));
        }
    }

    /// Register multiple `(source, destination)` pairs in a single
    /// admin-gated call. Each entry is validated identically to
    /// [`Self::register_pair`] and gets its own `pair_reg` event, with the
    /// same no-duplicate-emission rule: an entry that is already registered
    /// re-asserts silently instead of re-firing the event.
    ///
    /// **All-or-nothing:** if any entry fails validation the entire
    /// transaction is rolled back (Soroban transactions are atomic), so
    /// callers must ensure every pair is valid before invoking this. The
    /// batch must contain at least one entry; an empty batch panics with
    /// [`RouterError::EmptyBatch`]. The batch is also capped at
    /// [`MAX_BATCH_SIZE`] entries to bound gas; exceeding it panics with
    /// [`RouterError::BatchTooLarge`].
    pub fn register_pairs(env: Env, pairs: Vec<(Symbol, Symbol)>) {
        Self::require_not_paused(&env);
        Self::require_admin(&env);
        if pairs.is_empty() {
            panic_with_error!(&env, RouterError::EmptyBatch);
        }
        if pairs.len() > MAX_BATCH_SIZE {
            panic_with_error!(&env, RouterError::BatchTooLarge);
        }
        for (source, destination) in pairs.iter() {
            if source == destination {
                panic_with_error!(&env, RouterError::SourceEqualsDestination);
            }
            let already_registered = Self::read_pair_registered(&env, &source, &destination);
            env.storage()
                .persistent()
                .set(&DataKey::Pair(source.clone(), destination.clone()), &true);
            if !already_registered {
                env.events()
                    .publish((symbol_short!("pair_reg"),), (source, destination));
            }
        }
    }

    /// Configure the minimum interval (in seconds) between successful routes
    /// for a pair.
    ///
    /// Admin-gated. A value of `0` disables rate limiting. Values greater than
    /// [`MAX_COOLDOWN_SECS`] are rejected with
    /// [`RouterError::CooldownTooLarge`].
    pub fn set_pair_cooldown(env: Env, source: Symbol, destination: Symbol, cooldown_secs: u64) {
        Self::require_admin(&env);
        if cooldown_secs > MAX_COOLDOWN_SECS {
            panic_with_error!(&env, RouterError::CooldownTooLarge);
        }
        Self::require_pair_registered(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairCooldown(source.clone(), destination.clone()),
            &cooldown_secs,
        );
        env.events().publish(
            (symbol_short!("cd_set"),),
            (source, destination, cooldown_secs),
        );
    }

    /// Admin flags `(source, destination)` as disputed. While disputed,
    /// [`Self::quote_route`] and [`Self::compute_route_fee`] reject the
    /// pair with [`RouterError::PairDisputed`] until
    /// [`Self::resolve_pair_dispute`] clears the flag. Requires the pair
    /// to already be registered.
    ///
    /// Idempotent on the event: flagging an already-disputed pair
    /// re-asserts the flag but does not re-emit `disp_set`.
    pub fn flag_pair_dispute(env: Env, source: Symbol, destination: Symbol) {
        Self::require_admin(&env);
        Self::require_pair_registered(&env, &source, &destination);
        let already_disputed = Self::read_pair_disputed(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairDisputed(source.clone(), destination.clone()),
            &true,
        );
        if !already_disputed {
            env.events()
                .publish((symbol_short!("disp_set"),), (source, destination, true));
        }
    }

    /// Admin clears a dispute flag, restoring normal routing and quoting
    /// for the pair.
    ///
    /// Idempotent: resolving a pair with no active dispute is a clean
    /// no-op that does not emit `disp_set`.
    pub fn resolve_pair_dispute(env: Env, source: Symbol, destination: Symbol) {
        Self::require_admin(&env);
        let was_disputed = Self::read_pair_disputed(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairDisputed(source.clone(), destination.clone()),
            &false,
        );
        if was_disputed {
            env.events()
                .publish((symbol_short!("disp_set"),), (source, destination, false));
        }
    }

    /// Configure an absolute upper bound on the fee charged for any route.
    ///
    /// Admin-gated. The computed fee is clamped to this value after the
    /// percentage-based calculation.
    pub fn set_max_fee_absolute(env: Env, max_fee: i128) {
        Self::require_admin(&env);
        Self::require_non_negative_fee(&env, max_fee);
        if max_fee == 0 {
            panic_with_error!(&env, RouterError::ZeroFeeCap);
        }
        env.storage()
            .persistent()
            .set(&DataKey::MaxFeeAbsolute, &max_fee);
        env.events().publish((symbol_short!("maxfee"),), max_fee);
    }

    /// Admin removes the absolute per-route fee ceiling, restoring the
    /// default behaviour where only the relative `MAX_FEE_BPS` bound
    /// applies.
    ///
    /// Idempotent: removing when no cap is configured is a clean no-op.
    /// Emits a `maxfee_clr` event carrying the previously configured cap
    /// (`None` on a no-op removal) so indexers can audit cap lifecycle
    /// changes. The distinct topic (`maxfee_clr` vs `maxfee`) ensures
    /// revocations are visually distinguishable from cap adjustments in
    /// the event stream.
    pub fn clear_max_fee_absolute(env: Env) {
        Self::require_admin(&env);
        let removed: Option<i128> = env.storage().persistent().get(&DataKey::MaxFeeAbsolute);
        env.storage().persistent().remove(&DataKey::MaxFeeAbsolute);
        env.events().publish((symbol_short!("mxfee_clr"),), removed);
    }

    /// Configure an absolute minimum fee charged for every successful route.
    ///
    /// Admin-gated. The computed fee is raised to this value whenever the
    /// percentage-based fee would be lower.
    pub fn set_min_fee_absolute(env: Env, min_fee: i128) {
        Self::require_admin(&env);
        Self::require_non_negative_fee(&env, min_fee);
        env.storage()
            .persistent()
            .set(&DataKey::MinFeeAbsolute, &min_fee);
        env.events().publish((symbol_short!("minfee"),), min_fee);
    }

    /// Update the available liquidity for a registered pair.
    ///
    /// Requires authentication by the configured oracle. The pair must already
    /// be registered.
    pub fn set_pair_liquidity(
        env: Env,
        caller: Address,
        source: Symbol,
        destination: Symbol,
        liquidity: i128,
    ) {
        caller.require_auth();
        let admin: Address = Self::load_admin(&env);
        let oracle: Option<Address> = env.storage().persistent().get(&DataKey::Oracle);
        if caller != admin && Some(caller.clone()) != oracle {
            panic_with_error!(&env, RouterError::NotAuthorized);
        }
        if liquidity < 0 {
            panic_with_error!(&env, RouterError::AmountMustBePositive);
        }
        Self::require_pair_registered(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairLiquidity(source.clone(), destination.clone()),
            &liquidity,
        );
        env.events().publish(
            (symbol_short!("liq_set"),),
            (source, destination, liquidity),
        );
    }

    /// Configure the maximum permitted route amount for a pair.
    ///
    /// Requires the pair to already be registered via
    /// [`Self::register_pair`]; rejects an unregistered pair with
    /// [`RouterError::PairNotRegistered`] (#5) so the maximum can never be
    /// configured for a corridor that was never (or no longer) enabled.
    /// Emits a `max_set` event carrying the pair and the new ceiling.
    pub fn set_pair_max_amount(env: Env, source: Symbol, destination: Symbol, max_amount: i128) {
        Self::require_admin(&env);
        if max_amount <= 0 {
            panic_with_error!(&env, RouterError::AmountMustBePositive);
        }
        Self::require_pair_registered(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairMaxAmount(source.clone(), destination.clone()),
            &max_amount,
        );
        env.events().publish(
            (symbol_short!("max_set"),),
            (source, destination, max_amount),
        );
    }

    /// Configure the minimum permitted route amount for a pair.
    ///
    /// Requires the pair to already be registered via
    /// [`Self::register_pair`]; rejects an unregistered pair with
    /// [`RouterError::PairNotRegistered`] (#5) so the minimum can never be
    /// configured for a corridor that was never (or no longer) enabled.
    /// Emits a `min_set` event carrying the pair and the new floor.
    pub fn set_pair_min_amount(env: Env, source: Symbol, destination: Symbol, min_amount: i128) {
        Self::require_admin(&env);
        if min_amount < 0 {
            panic_with_error!(&env, RouterError::AmountMustBePositive);
        }
        Self::require_pair_registered(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairMinAmount(source.clone(), destination.clone()),
            &min_amount,
        );
        env.events().publish(
            (symbol_short!("min_set"),),
            (source, destination, min_amount),
        );
    }

    /// Remove a registered pair from the router.
    ///
    /// Admin-gated and idempotent. Registration is removed and per-pair
    /// configuration is cleared, while historical routing metrics remain
    /// until explicitly purged.
    pub fn unregister_pair(env: Env, source: Symbol, destination: Symbol) {
        Self::require_admin(&env);
        env.storage()
            .persistent()
            .remove(&DataKey::Pair(source.clone(), destination.clone()));
        Self::clear_pair_config(&env, source.clone(), destination.clone());
        env.events().publish(
            (symbol_short!("unreg"),),
            (source.clone(), destination.clone()),
        );
        env.events()
            .publish((symbol_short!("cfg_clr"),), (source, destination));
    }

    /// Permanently remove all recorded routing metrics for a pair.
    ///
    /// Admin-gated. Clears the route count, cumulative volume, and last
    /// successful route timestamp.
    ///
    /// Publishes a `metr_rm` event **before** clearing so off-chain
    /// consumers can capture the pre-purge snapshot for auditability:
    ///
    /// # Events
    ///
    /// - Topic: `(symbol_short!("metr_rm"),)`
    /// - Payload: `(source, destination, route_count, volume):
    ///   (Symbol, Symbol, u64, i128)`
    /// - When: fires immediately before the three metrics slots are
    ///   removed. `route_count` and `volume` are the values that were
    ///   stored *before* the purge (defaulting to `0` when absent).
    pub fn purge_pair_metrics(env: Env, source: Symbol, destination: Symbol) {
        Self::require_admin(&env);
        let storage = env.storage().persistent();
        let route_count: u64 = storage
            .get(&DataKey::PairRouteCount(
                source.clone(),
                destination.clone(),
            ))
            .unwrap_or(0);
        let volume: i128 = storage
            .get(&DataKey::PairVolume(source.clone(), destination.clone()))
            .unwrap_or(0);
        storage.remove(&DataKey::PairRouteCount(
            source.clone(),
            destination.clone(),
        ));
        storage.remove(&DataKey::PairVolume(source.clone(), destination.clone()));
        storage.remove(&DataKey::PairLastRouteAt(
            source.clone(),
            destination.clone(),
        ));
        env.events().publish(
            (symbol_short!("metr_rm"),),
            (source.clone(), destination.clone(), route_count, volume),
        );
        env.events()
            .publish((symbol_short!("pair_mrst"),), (source, destination));
    }

    /// Configure the routing fee for a single registered pair.
    ///
    /// Admin-gated. The fee is expressed in basis points and must not exceed
    /// [`MAX_FEE_BPS`].
    pub fn set_pair_fee_bps(env: Env, source: Symbol, destination: Symbol, fee_bps: u32) {
        Self::require_not_paused(&env);
        Self::require_admin(&env);
        Self::require_valid_fee_bps(&env, fee_bps);
        Self::require_pair_registered(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairFeeBps(source.clone(), destination.clone()),
            &fee_bps,
        );
        env.events()
            .publish((symbol_short!("fee_set"),), (source, destination, fee_bps));
    }

    /// Configure routing fees for multiple registered pairs in a single call.
    ///
    /// Admin-gated. Each entry is validated independently and the transaction
    /// is atomic: if any entry is invalid, no fee changes are applied.
    pub fn set_pair_fees_bps(env: Env, entries: Vec<(Symbol, Symbol, u32)>) {
        Self::require_not_paused(&env);
        Self::require_admin(&env);
        if entries.is_empty() {
            panic_with_error!(&env, RouterError::EmptyBatch);
        }
        if entries.len() > MAX_BATCH_SIZE {
            panic_with_error!(&env, RouterError::BatchTooLarge);
        }
        for (source, destination, fee_bps) in entries.iter() {
            Self::require_valid_fee_bps(&env, fee_bps);
            Self::require_pair_registered(&env, &source, &destination);
            env.storage().persistent().set(
                &DataKey::PairFeeBps(source.clone(), destination.clone()),
                &fee_bps,
            );
            env.events()
                .publish((symbol_short!("fee_set"),), (source, destination, fee_bps));
        }
    }

    // ── Reads ─────────────────────────────────────────────────────────────
    // Pure getters and aggregate queries — no state mutations.

    /// Returns the router contract version.
    pub fn version(_env: Env) -> Symbol {
        symbol_short!("ROUTER_V2")
    }

    /// Read the persisted schema version, or 1 if absent (the implicit
    /// pre-migration default).
    pub fn get_schema_version(env: Env) -> u32 {
        env.storage()
            .persistent()
            .get(&DataKey::SchemaVersion)
            .unwrap_or(1)
    }

    /// Expose the protocol-wide limits that every caller must respect before
    /// submitting a transaction.
    ///
    /// Returns a [`RouterLimits`] snapshot mirroring the compile-time
    /// constants [`MAX_FEE_BPS`], [`BPS_DENOMINATOR`], [`MAX_BATCH_SIZE`], and
    /// [`MAX_COOLDOWN_SECS`]. This is the on-chain discovery surface: an
    /// on-chain caller or a client that did not compile against this crate
    /// can learn the enforced bounds from a single read instead of having to
    /// know the crate's `pub const`s.
    ///
    /// Read-only and auth-free; never touches storage.
    pub fn get_limits(_env: Env) -> RouterLimits {
        RouterLimits {
            max_fee_bps: MAX_FEE_BPS,
            bps_denominator: BPS_DENOMINATOR,
            max_batch_size: MAX_BATCH_SIZE,
            max_cooldown_secs: MAX_COOLDOWN_SECS,
        }
    }

    /// Returns true iff the router is currently paused.
    pub fn is_paused(env: Env) -> bool {
        Self::paused(&env)
    }

    /// Read the configured governance timelock delay, in seconds
    /// (0 when unset — handover is instant).
    pub fn get_timelock(env: Env) -> u64 {
        env.storage()
            .persistent()
            .get(&DataKey::Timelock)
            .unwrap_or(0)
    }

    /// Read the earliest timestamp at which the pending admin transfer may
    /// be accepted, or `None` when no transfer is queued.
    pub fn get_pending_admin_eta(env: Env) -> Option<u64> {
        env.storage().persistent().get(&DataKey::PendingAdminEta)
    }

    /// Read the pending admin if any.
    pub fn get_pending_admin(env: Env) -> Option<Address> {
        env.storage().instance().get(&DataKey::PendingAdmin)
    }

    /// Read both components of the queued admin handover in one call.
    ///
    /// Returns a consistent snapshot of the pending admin and its
    /// earliest acceptance timestamp (ETA). Both fields are `None`
    /// when no transfer is queued.
    pub fn get_pending_admin_info(env: Env) -> PendingAdminInfo {
        PendingAdminInfo {
            pending: env.storage().instance().get(&DataKey::PendingAdmin),
            eta: env.storage().persistent().get(&DataKey::PendingAdminEta),
        }
    }

    /// Returns the admin set at `init`, if any.
    pub fn get_admin(env: Env) -> Option<Address> {
        env.storage().instance().get(&DataKey::Admin)
    }

    /// Returns true iff the pair is registered AND has non-zero
    /// reported liquidity. Useful as a quick is-routable check.
    pub fn is_pair_active(env: Env, source: Symbol, destination: Symbol) -> bool {
        if !Self::read_pair_registered(&env, &source, &destination) {
            return false;
        }
        Self::read_pair_liquidity(&env, &source, &destination) > 0
    }

    /// Single round-trip aggregate read for the dashboard. Returns
    /// every per-pair slot in one shot.
    pub fn get_pair_info(env: Env, source: Symbol, destination: Symbol) -> PairInfo {
        let s = env.storage().persistent();
        PairInfo {
            registered: Self::read_pair_registered(&env, &source, &destination),
            fee_bps: Self::read_pair_fee_bps(&env, &source, &destination),
            min_amount: Self::read_pair_min(&env, &source, &destination),
            max_amount: Self::read_pair_max(&env, &source, &destination),
            liquidity: Self::read_pair_liquidity(&env, &source, &destination),
            last_route_at: s
                .get(&DataKey::PairLastRouteAt(source, destination))
                .unwrap_or(0),
        }
    }

    /// Extended aggregate read including newer per-pair slots that were
    /// added after the original [`PairInfo`] shipped. Returns every
    /// per-pair slot in a single round-trip so dashboards avoid issuing
    /// separate calls for cooldown, route count, and volume.
    ///
    /// Defaults follow the same sentinel conventions as the individual
    /// getters: cooldown 0 (disabled), route count 0, volume 0.
    pub fn get_pair_info_ext(env: Env, source: Symbol, destination: Symbol) -> PairInfoExt {
        let s = env.storage().persistent();
        PairInfoExt {
            registered: Self::read_pair_registered(&env, &source, &destination),
            fee_bps: Self::read_pair_fee_bps(&env, &source, &destination),
            min_amount: Self::read_pair_min(&env, &source, &destination),
            max_amount: Self::read_pair_max(&env, &source, &destination),
            liquidity: Self::read_pair_liquidity(&env, &source, &destination),
            last_route_at: s
                .get(&DataKey::PairLastRouteAt(
                    source.clone(),
                    destination.clone(),
                ))
                .unwrap_or(0),
            cooldown_secs: Self::read_pair_cooldown(&env, &source, &destination),
            route_count: s
                .get(&DataKey::PairRouteCount(
                    source.clone(),
                    destination.clone(),
                ))
                .unwrap_or(0),
            volume: s
                .get(&DataKey::PairVolume(source, destination))
                .unwrap_or(0),
        }
    }

    /// Returns the timestamp of the pair's most recent successful route.
    ///
    /// Returns `None` if the pair has never been routed.
    pub fn get_pair_last_route_at(env: Env, source: Symbol, destination: Symbol) -> Option<u64> {
        env.storage()
            .persistent()
            .get(&DataKey::PairLastRouteAt(source, destination))
    }

    /// Returns the cumulative number of successful routes executed by the
    /// router across all registered pairs.
    ///
    /// Returns `0` before any routes have been processed.
    pub fn get_pair_cooldown(env: Env, source: Symbol, destination: Symbol) -> u64 {
        Self::read_pair_cooldown(&env, &source, &destination)
    }

    /// Read the protocol-wide lifetime counter of route quotes.
    pub fn get_total_routes_all_time(env: Env) -> u64 {
        env.storage()
            .persistent()
            .get(&DataKey::TotalRoutesAllTime)
            .unwrap_or(0)
    }

    /// Read-only view of the protocol-wide lifetime sum of fees accrued by
    /// `compute_route_fee`, owed to `FeeRecipient` once distributed.
    ///
    /// Does not mutate storage. Returns `0` before any fee-bearing route
    /// has been processed.
    pub fn get_rewards_accrued(env: Env) -> i128 {
        env.storage()
            .persistent()
            .get(&DataKey::RewardsAccrued)
            .unwrap_or(0)
    }

    /// Returns the number of successful routes executed for the specified pair.
    ///
    /// Returns `0` if the pair has never been routed.
    pub fn get_pair_route_count(env: Env, source: Symbol, destination: Symbol) -> u64 {
        env.storage()
            .persistent()
            .get(&DataKey::PairRouteCount(source, destination))
            .unwrap_or(0)
    }

    /// Returns the cumulative routed volume recorded for the pair.
    ///
    /// Returns `0` if no successful routes have been executed.
    pub fn get_pair_volume(env: Env, source: Symbol, destination: Symbol) -> i128 {
        env.storage()
            .persistent()
            .get(&DataKey::PairVolume(source, destination))
            .unwrap_or(0)
    }

    /// Returns the configured fee recipient.
    ///
    /// Returns `None` if no recipient has been configured.
    pub fn get_fee_recipient(env: Env) -> Option<Address> {
        env.storage().persistent().get(&DataKey::FeeRecipient)
    }

    /// Returns the configured absolute fee ceiling.
    ///
    /// Returns `None` when no maximum fee cap is enforced.
    pub fn get_max_fee_absolute(env: Env) -> Option<i128> {
        Self::read_max_fee_cap(&env)
    }

    /// Returns the configured absolute fee floor.
    ///
    /// Returns `None` when no minimum fee is enforced.
    pub fn get_min_fee_absolute(env: Env) -> Option<i128> {
        env.storage().persistent().get(&DataKey::MinFeeAbsolute)
    }

    /// Returns the currently recorded available liquidity for the pair.
    ///
    /// When no liquidity has been configured, the pair is treated as having
    /// unlimited liquidity.
    pub fn get_pair_liquidity(env: Env, source: Symbol, destination: Symbol) -> i128 {
        Self::read_pair_liquidity(&env, &source, &destination)
    }

    /// Returns the currently configured liquidity oracle.
    ///
    /// Returns `None` if no oracle has been assigned.
    pub fn get_oracle(env: Env) -> Option<Address> {
        env.storage().persistent().get(&DataKey::Oracle)
    }

    /// Returns the configured maximum permitted route amount for the pair.
    ///
    /// When unset, the maximum defaults to an effectively unbounded value.
    pub fn get_pair_max_amount(env: Env, source: Symbol, destination: Symbol) -> i128 {
        Self::read_pair_max(&env, &source, &destination)
    }

    /// Returns the configured minimum permitted route amount for the pair.
    ///
    /// Returns `0` when no minimum has been configured.
    pub fn get_pair_min_amount(env: Env, source: Symbol, destination: Symbol) -> i128 {
        Self::read_pair_min(&env, &source, &destination)
    }

    /// Returns `true` if the pair is currently registered.
    ///
    /// Registration is independent of liquidity or routing activity.
    pub fn is_pair_registered(env: Env, source: Symbol, destination: Symbol) -> bool {
        Self::read_pair_registered(&env, &source, &destination)
    }

    /// Returns `true` if `(source, destination)` currently has an active
    /// dispute flag set via [`Self::flag_pair_dispute`].
    ///
    /// Does not mutate storage. Defaults to `false`.
    pub fn is_pair_disputed(env: Env, source: Symbol, destination: Symbol) -> bool {
        Self::read_pair_disputed(&env, &source, &destination)
    }

    /// Returns the configured routing fee for the pair, expressed in basis
    /// points.
    ///
    /// Returns `0` when no fee has been configured.
    pub fn get_pair_fee_bps(env: Env, source: Symbol, destination: Symbol) -> u32 {
        Self::read_pair_fee_bps(&env, &source, &destination)
    }

    /// Read-only aggregate of the contract's global configuration: fee
    /// recipient, absolute fee bounds, oracle, and timelock delay.
    ///
    /// Does not mutate storage. Every field reads its documented sane
    /// default (see [`GlobalConfig`]), so this is safe to call before any
    /// admin configuration has taken place.
    pub fn get_global_config(env: Env) -> GlobalConfig {
        GlobalConfig {
            fee_recipient: env.storage().persistent().get(&DataKey::FeeRecipient),
            max_fee_absolute: Self::read_max_fee_cap(&env),
            min_fee_absolute: env.storage().persistent().get(&DataKey::MinFeeAbsolute),
            oracle: env.storage().persistent().get(&DataKey::Oracle),
            timelock_secs: Self::get_timelock(env.clone()),
        }
    }

    // ── Routing ───────────────────────────────────────────────────────────
    // Fee quoting, route execution, and deterministic route tagging.

    /// Read-only quote of fee + net for a pair without writing the
    /// timestamp / counter. Useful as a planner-only hook.
    ///
    /// Follows the same liquidity rules as [`Self::compute_route_fee`]:
    /// an explicitly set `0` liquidity implies an inactive corridor
    /// and returns [`RouterError::InsufficientLiquidity`]. Absent
    /// liquidity retains the unbounded behavior.
    pub fn quote_route(
        env: Env,
        source: Symbol,
        destination: Symbol,
        amount: i128,
    ) -> (i128, i128) {
        if amount <= 0 {
            panic_with_error!(&env, RouterError::AmountMustBePositive);
        }
        Self::require_pair_registered(&env, &source, &destination);
        if Self::read_pair_disputed(&env, &source, &destination) {
            panic_with_error!(&env, RouterError::PairDisputed);
        }
        if matches!(
            env.storage()
                .persistent()
                .get::<_, i128>(&DataKey::PairLiquidity(source.clone(), destination.clone())),
            Some(0)
        ) {
            panic_with_error!(&env, RouterError::InsufficientLiquidity);
        }
        let fee_bps = Self::read_pair_fee_bps(&env, &source, &destination);
        let fee = amount
            .checked_mul(fee_bps as i128)
            .map(|n| n / BPS_DENOMINATOR)
            .unwrap_or(0);
        let fee = Self::apply_fee_cap(&env, fee);
        let fee = Self::apply_fee_floor(&env, fee);
        (fee, amount - fee)
    }

    /// Compute the fee in source units for routing `amount` through the
    /// `(source, destination)` pair.
    ///
    /// Rejects unregistered pairs with [`RouterError::PairNotRegistered`]
    /// and non-positive amounts with [`RouterError::AmountMustBePositive`]
    /// so off-chain callers always get a clear typed error instead of a
    /// silent zero. Math is integer division (truncating toward zero),
    /// matching every existing Stellar fee accounting precedent.
    ///
    /// Honours the emergency stop: while the router is paused this
    /// entrypoint panics with [`RouterError::ContractPaused`] so no route
    /// can be recorded (the `TotalRoutesAllTime` counter, the
    /// `PairLastRouteAt` stamp, and the `route` event are all gated). The
    /// read-only `quote_route` is intentionally left available while
    /// paused so integrators can keep planning routes for when the router
    /// resumes.
    ///
    /// # Checks/effects ordering
    ///
    /// Registered-pair, amount-bound, liquidity, and cooldown guards all
    /// pass before any route business effect is applied. Only after those
    /// checks does the function debit liquidity, update counters and
    /// timestamps, and emit route events.
    ///
    /// # Liquidity consumption
    ///
    /// After passing all pre-condition checks, the function debits `amount`
    /// from the stored `PairLiquidity` via saturating subtraction. If the
    /// liquidity slot is unset the decrement is skipped entirely, preserving
    /// the "no oracle configured" behavior. If liquidity is explicitly set
    /// to `0`, the function returns [`RouterError::InsufficientLiquidity`]
    /// before any state mutation. When a decrement does occur a `liq_used`
    /// event carrying `(source, destination, remaining_liquidity)` is
    /// emitted. The slot TTL is extended on each write.
    ///
    /// # Key-construction optimisation
    ///
    /// Each [`DataKey`] variant that is both *read* and *written* within
    /// this function — [`DataKey::PairLiquidity`],
    /// [`DataKey::PairLastRouteAt`], [`DataKey::PairRouteCount`], and
    /// [`DataKey::PairVolume`] — is constructed **once** into a local
    /// variable and then referenced by `&` for every subsequent storage
    /// operation. This replaces the previous pattern of calling
    /// `DataKey::Variant(source.clone(), destination.clone())` on every
    /// individual read and write, halving the number of [`Symbol`] clones
    /// for those hot paths.
    ///
    /// The fee calculation (`read_pair_fee_bps` -> arithmetic -> cap ->
    /// floor) is hoisted **before** the effects section so that the final
    /// use of `source` and `destination` — the `route` event emission —
    /// *moves* (consumes) them instead of cloning.
    pub fn compute_route_fee(env: Env, source: Symbol, destination: Symbol, amount: i128) -> i128 {
        // Acquire the reentrancy lock at the very start so that every exit
        // path — success or panic — can explicitly release it. This ensures
        // future refactors that add new checks after this point cannot
        // accidentally leak the lock.
        Self::enter_nonreentrant(&env);

        if Self::paused(&env) {
            Self::route_abort(&env, RouterError::ContractPaused);
        }
        if amount <= 0 {
            Self::route_abort(&env, RouterError::AmountMustBePositive);
        }

        if !Self::read_pair_registered(&env, &source, &destination) {
            Self::route_abort(&env, RouterError::PairNotRegistered);
        }
        if Self::read_pair_disputed(&env, &source, &destination) {
            Self::route_abort(&env, RouterError::PairDisputed);
        }
        let min_amount = Self::read_pair_min(&env, &source, &destination);
        if amount < min_amount {
            Self::route_abort(&env, RouterError::AmountBelowMin);
        }
        let max_amount = Self::read_pair_max(&env, &source, &destination);
        if amount > max_amount {
            Self::route_abort(&env, RouterError::AmountAboveMax);
        }
        // Construct the liquidity key once — shared between the initial
        // read (guard) and the post-route debit write below.
        let liq_key = DataKey::PairLiquidity(source.clone(), destination.clone());
        let liquidity: i128 = match env.storage().persistent().get(&liq_key) {
            Some(0) => Self::route_abort(&env, RouterError::InsufficientLiquidity),
            Some(v) => v,
            None => i128::MAX,
        };
        if amount > liquidity {
            Self::route_abort(&env, RouterError::InsufficientLiquidity);
        }

        // Construct the last-route-at key once — shared between the
        // cooldown read and the post-route timestamp write below.
        let route_at_key = DataKey::PairLastRouteAt(source.clone(), destination.clone());
        // Per-pair rate limit. A non-zero cooldown forces a minimum gap
        // between successive routes for the pair. The first route (no
        // recorded timestamp) is always allowed; cooldown == 0 disables
        // the check entirely, preserving the prior behaviour. Compare via
        // addition (last + cooldown) rather than subtraction to avoid any
        // u64 underflow. `last + cooldown` cannot overflow u64 either:
        // `set_pair_cooldown` rejects any `cooldown` above
        // `MAX_COOLDOWN_SECS` (30 days), and `last` is a ledger timestamp
        // (seconds since epoch) that would need to be within 30 days of
        // `u64::MAX` — many orders of magnitude beyond any plausible
        // ledger closing time — before this addition could wrap.
        let cooldown = Self::read_pair_cooldown(&env, &source, &destination);
        if cooldown > 0 {
            if let Some(last) = env.storage().persistent().get::<_, u64>(&route_at_key) {
                if env.ledger().timestamp() < last + cooldown {
                    Self::exit_nonreentrant(&env);
                    panic_with_error!(&env, RouterError::RouteCooldownActive);
                }
            }
        }

        // Pre-effects: compute fee before state mutations so that
        // `source` and `destination` can be moved (consumed) into the
        // final route-event payload below, avoiding two extra clones.
        // Fee depends only on fee_bps, cap, and floor — none of which
        // are mutated by the effects section, making this reorder safe.
        let fee_bps = Self::read_pair_fee_bps(&env, &source, &destination);
        // amount * fee_bps / 10_000, in i128 to avoid u32*i128 overflow on
        // amounts near i128::MAX. fee_bps is capped at MAX_FEE_BPS so the
        // multiplication is bounded.
        let fee = amount
            .checked_mul(fee_bps as i128)
            .map(|n| n / BPS_DENOMINATOR)
            .unwrap_or(0);
        let fee = Self::apply_fee_cap(&env, fee);
        let fee = Self::apply_fee_floor(&env, fee);

        // ── EFFECTS ──────────────────────────────────────────────────
        // Debit liquidity, write counters/timestamps, and emit events.
        // When no oracle has set a liquidity value the pair is treated as
        // unbounded — no decrement and no liq_used event are emitted.
        //
        // Key variables constructed above (`liq_key`, `route_at_key`,
        // `route_count_key`, `volume_key`) are reused by `&` reference
        // here instead of reconstructing them with fresh `.clone()` calls.
        if liquidity != i128::MAX {
            let remaining = liquidity.saturating_sub(amount);
            env.storage().persistent().set(&liq_key, &remaining);
            env.events().publish(
                (symbol_short!("liq_used"),),
                (source.clone(), destination.clone(), remaining),
            );
        }
        let total: u64 = env
            .storage()
            .persistent()
            .get(&DataKey::TotalRoutesAllTime)
            .unwrap_or(0);
        env.storage()
            .persistent()
            .set(&DataKey::TotalRoutesAllTime, &total.saturating_add(1));

        // A zero fee is not a rewards-state change: skip the write and
        // the event entirely rather than recording a no-op accrual.
        if fee > 0 {
            let accrued: i128 = env
                .storage()
                .persistent()
                .get(&DataKey::RewardsAccrued)
                .unwrap_or(0);
            let new_accrued = accrued.saturating_add(fee);
            env.storage()
                .persistent()
                .set(&DataKey::RewardsAccrued, &new_accrued);
            env.events()
                .publish((symbol_short!("rwd_accr"),), (fee, new_accrued));
        }

        // Construct the route-count key once — shared between read and write.
        let route_count_key = DataKey::PairRouteCount(source.clone(), destination.clone());
        let pair_count: u64 = env
            .storage()
            .persistent()
            .get(&route_count_key)
            .unwrap_or(0);
        env.storage()
            .persistent()
            .set(&route_count_key, &pair_count.saturating_add(1));

        // Construct the volume key once — shared between read and write.
        let volume_key = DataKey::PairVolume(source.clone(), destination.clone());
        let pair_volume: i128 = env.storage().persistent().get(&volume_key).unwrap_or(0);
        env.storage()
            .persistent()
            .set(&volume_key, &pair_volume.saturating_add(amount));

        env.storage()
            .persistent()
            .set(&route_at_key, &env.ledger().timestamp());

        // Last use of source/destination — moved (consumed) rather than
        // cloned, saving one Symbol clone pair on the hot path.
        env.events()
            .publish((symbol_short!("route"),), (source, destination, amount));

        Self::exit_nonreentrant(&env);
        fee
    }

    /// Compute a deterministic, direction-sensitive route identifier for a
    /// `(source, destination)` pair.
    ///
    /// The tag is `keccak256(xdr(source) || xdr(destination))`: a stable
    /// 32-byte digest that depends on the encoded inputs in order. Properties:
    ///
    /// - **Deterministic** — the same `(source, destination)` always hashes to
    ///   the same value, so an off-chain backend can recompute it and correlate
    ///   on-chain routes without storing a mapping.
    /// - **Direction-sensitive** — `source` is hashed before `destination`, so
    ///   `route_tag(USDC, EURC) != route_tag(EURC, USDC)`. Each leg of a pair
    ///   gets its own identifier.
    ///
    /// Returns the digest as a [`BytesN<32>`].
    pub fn route_tag(env: Env, source: Symbol, destination: Symbol) -> BytesN<32> {
        // Build the pre-image deterministically: the XDR encoding of `source`
        // followed by the XDR encoding of `destination`. Ordering the appends
        // this way is what makes the tag direction-sensitive.
        let mut buf = Bytes::new(&env);
        buf.append(&source.to_xdr(&env));
        buf.append(&destination.to_xdr(&env));
        env.crypto().keccak256(&buf).to_bytes()
    }

    // ── Upgrade ──────────────────────────────────────────────────────────
    // In-place WASM replacement.

    /// Replace the contract's WASM in-place so the router can be patched
    /// without losing pair state. Admin-gated; emits an `upgraded` event
    /// carrying the new hash so indexers and watchers can audit upgrades.
    ///
    /// ## Trade-off: not paused-gated
    ///
    /// An emergency pause should arguably still allow the admin to deploy a
    /// fix. We therefore skip the `ContractPaused` check — a paused router
    /// can be upgraded, which is consistent with fixing the bug that caused
    /// the pause. The admin can already unpause, so there is no escalation
    /// path through this exception.
    pub fn upgrade(env: Env, new_wasm_hash: BytesN<32>) {
        Self::require_admin(&env);
        env.events()
            .publish((symbol_short!("upgraded"),), &new_wasm_hash);
        env.deployer().update_current_contract_wasm(new_wasm_hash);
    }

    // ── Private helpers ──────────────────────────────────────────────────
    // Internal functions that never appear in the generated client ABI.

    /// Read the admin address from instance storage, panicking with
    /// [`RouterError::NotInitialized`] if absent.
    fn load_admin(env: &Env) -> Address {
        env.storage()
            .instance()
            .get(&DataKey::Admin)
            .unwrap_or_else(|| panic_with_error!(env, RouterError::NotInitialized))
    }

    /// Load the admin address, require its auth, and return it.
    ///
    /// Every admin-gated entrypoint calls this instead of repeating the
    /// six-line load-unwrap-require_auth block. Keeping it private
    /// ensures it never appears in the generated client ABI.
    fn require_admin(env: &Env) -> Address {
        let admin = Self::load_admin(env);
        admin.require_auth();
        admin
    }

    /// Renew the contract instance's TTL. Called after every write to a
    /// hot-global instance slot (`Admin`, `PendingAdmin`, `Paused`) so the
    /// instance — and therefore these singletons — never archives as long
    /// as the contract keeps receiving admin/pause/transfer traffic.
    fn bump_instance_ttl(env: &Env) {
        env.storage()
            .instance()
            .extend_ttl(INSTANCE_TTL_THRESHOLD, INSTANCE_TTL_EXTEND_TO);
    }

    /// Require that `(source, destination)` was previously registered via
    /// [`Self::register_pair`]; panics with
    /// [`RouterError::PairNotRegistered`] otherwise.
    ///
    /// Every per-pair config setter (`set_pair_fee_bps`,
    /// `set_pair_min_amount`, `set_pair_max_amount`, `set_pair_liquidity`)
    /// calls this after its own admin/sign validation so a config write can
    /// never create an orphan storage slot for a corridor an operator never
    /// registered. Reuses the same [`RouterError::PairNotRegistered`] (#5)
    /// that `compute_route_fee` and `quote_route` already raise, keeping
    /// one error code for "this pair does not exist" across the contract.
    fn require_pair_registered(env: &Env, source: &Symbol, destination: &Symbol) {
        if !Self::read_pair_registered(env, source, destination) {
            panic_with_error!(env, RouterError::PairNotRegistered);
        }
    }

    /// Require that a fee-bound value (the router's reward parameters —
    /// [`Self::set_max_fee_absolute`] and [`Self::set_min_fee_absolute`]
    /// both configure an absolute bound on the fee the router charges/earns
    /// per route) is not negative; panics with
    /// [`RouterError::AmountMustBePositive`] otherwise.
    ///
    /// Both setters previously repeated this exact `< 0` check inline. A
    /// negative fee bound would be nonsensical (a route could never be
    /// charged less than a negative amount), so this is enforced
    /// identically at both call sites via one shared helper.
    fn require_non_negative_fee(env: &Env, value: i128) {
        if value < 0 {
            panic_with_error!(env, RouterError::AmountMustBePositive);
        }
    }

    /// Acquire the reentrancy lock; panics [`RouterError::ReentrantCall`]
    /// if already held. Paired with [`Self::exit_nonreentrant`] on every
    /// return path so that a re-entrant invocation (for example via a
    /// future malicious token callback) is rejected instead of operating
    /// on partially-applied effects.
    fn enter_nonreentrant(env: &Env) {
        if env
            .storage()
            .persistent()
            .get(&DataKey::ReentrancyLock)
            .unwrap_or(false)
        {
            panic_with_error!(env, RouterError::ReentrantCall);
        }
        env.storage()
            .persistent()
            .set(&DataKey::ReentrancyLock, &true);
    }

    /// Release the reentrancy lock. Must be called before every return
    /// from a guarded entrypoint, including the success path, so that
    /// back-to-back calls work.
    fn exit_nonreentrant(env: &Env) {
        env.storage()
            .persistent()
            .set(&DataKey::ReentrancyLock, &false);
    }

    /// Release the reentrancy lock and panic with `err`. Consolidates the
    /// exit-then-panic pattern used on every guard-failure path of
    /// [`Self::compute_route_fee`] so the lock is never leaked on a
    /// rejection.
    fn route_abort(env: &Env, err: RouterError) -> ! {
        Self::exit_nonreentrant(env);
        panic_with_error!(env, err)
    }

    /// Read the paused flag from the instance-storage hot global.
    /// Single source of truth for the `Paused` sentinel (absent → `false`).
    fn paused(env: &Env) -> bool {
        env.storage()
            .instance()
            .get(&DataKey::Paused)
            .unwrap_or(false)
    }

    /// Panic with [`RouterError::ContractPaused`] when the router is paused.
    /// Shared by every state-changing, pause-gated entrypoint.
    fn require_not_paused(env: &Env) {
        if Self::paused(env) {
            panic_with_error!(env, RouterError::ContractPaused);
        }
    }

    /// Require that `fee_bps` does not exceed [`MAX_FEE_BPS`].
    /// Panics with [`RouterError::FeeBpsTooHigh`] if invalid.
    fn require_valid_fee_bps(env: &Env, fee_bps: u32) {
        if fee_bps > MAX_FEE_BPS {
            panic_with_error!(env, RouterError::FeeBpsTooHigh);
        }
    }

    /// Require that `expected` is the currently pending admin and that the
    /// governance timelock eta has elapsed; panics with
    /// [`RouterError::NoPendingAdminTransfer`] if no handover is pending,
    /// [`RouterError::NotPendingAdmin`] if `expected` does not match the
    /// pending admin, or [`RouterError::TimelockNotElapsed`] if the eta has
    /// not yet been reached. Shared precondition check of
    /// [`Self::accept_admin_transfer`] (self-accept) and
    /// [`Self::force_admin_transfer`] (admin-forced) — the two entrypoints
    /// that complete a proposed handover — which previously repeated this
    /// exact lookup/compare/timelock sequence inline.
    fn require_pending_admin_and_timelock_elapsed(env: &Env, expected: &Address) {
        let pending: Address = env
            .storage()
            .instance()
            .get(&DataKey::PendingAdmin)
            .unwrap_or_else(|| panic_with_error!(env, RouterError::NoPendingAdminTransfer));
        if &pending != expected {
            panic_with_error!(env, RouterError::NotPendingAdmin);
        }
        let eta: u64 = env
            .storage()
            .persistent()
            .get(&DataKey::PendingAdminEta)
            .unwrap_or(0);
        if env.ledger().timestamp() < eta {
            panic_with_error!(env, RouterError::TimelockNotElapsed);
        }
    }

    /// Finalise an admin handover: install `new_admin`, clear the pending
    /// slots, renew the instance TTL, and emit the `executed` event. Shared
    /// tail of [`Self::accept_admin_transfer`] and
    /// [`Self::force_admin_transfer`].
    fn finalize_admin_transfer(env: &Env, new_admin: Address) {
        env.storage().instance().set(&DataKey::Admin, &new_admin);
        env.storage().instance().remove(&DataKey::PendingAdmin);
        env.storage().persistent().remove(&DataKey::PendingAdminEta);
        Self::bump_instance_ttl(env);
        env.events()
            .publish((symbol_short!("executed"),), new_admin);
    }

    /// Read whether `(source, destination)` is a registered pair from
    /// persistent storage.
    ///
    /// Returns `false` when the slot is absent — the documented default for an
    /// unregistered pair. This is the single source of truth for the
    /// [`DataKey::Pair`] sentinel value.
    fn read_pair_registered(env: &Env, source: &Symbol, destination: &Symbol) -> bool {
        env.storage()
            .persistent()
            .get(&DataKey::Pair(source.clone(), destination.clone()))
            .unwrap_or(false)
    }

    /// Read whether `(source, destination)` currently has an active
    /// dispute flag. Single source of truth for the
    /// [`DataKey::PairDisputed`] sentinel value; shared by `quote_route`
    /// and `compute_route_fee` instead of each inlining its own storage
    /// read.
    fn read_pair_disputed(env: &Env, source: &Symbol, destination: &Symbol) -> bool {
        env.storage()
            .persistent()
            .get(&DataKey::PairDisputed(source.clone(), destination.clone()))
            .unwrap_or(false)
    }

    /// Read the per-pair fee in basis points from persistent storage.
    ///
    /// Returns `0` (free) when the slot is absent — the documented
    /// default for an unconfigured, registered pair. This is the single
    /// source of truth for the [`DataKey::PairFeeBps`] sentinel value.
    fn read_pair_fee_bps(env: &Env, source: &Symbol, destination: &Symbol) -> u32 {
        env.storage()
            .persistent()
            .get(&DataKey::PairFeeBps(source.clone(), destination.clone()))
            .unwrap_or(0)
    }

    /// Read the per-pair minimum routable amount from persistent storage.
    ///
    /// Returns `0` (no floor) when the slot is absent — the documented
    /// default. This is the single source of truth for the
    /// [`DataKey::PairMinAmount`] sentinel value.
    fn read_pair_min(env: &Env, source: &Symbol, destination: &Symbol) -> i128 {
        env.storage()
            .persistent()
            .get(&DataKey::PairMinAmount(source.clone(), destination.clone()))
            .unwrap_or(0)
    }

    /// Read the per-pair maximum routable amount from persistent storage.
    ///
    /// Returns `i128::MAX` (no ceiling — unbounded) when the slot is
    /// absent. This is the single source of truth for the
    /// [`DataKey::PairMaxAmount`] sentinel value.
    fn read_pair_max(env: &Env, source: &Symbol, destination: &Symbol) -> i128 {
        env.storage()
            .persistent()
            .get(&DataKey::PairMaxAmount(source.clone(), destination.clone()))
            .unwrap_or(i128::MAX)
    }

    /// Read the per-pair reported liquidity from persistent storage.
    ///
    /// Returns `0` (no liquidity configured) when the slot is absent —
    /// the documented default for getters and aggregate reads. Note that
    /// [`Self::compute_route_fee`] intentionally uses `i128::MAX` as its
    /// own unbounded sentinel (a context-dependent default, documented
    /// in the [`DataKey::PairLiquidity`] variant and `storage.md`).
    /// Callers needing the unbounded semantic should read the slot
    /// directly with `unwrap_or(i128::MAX)`.
    fn read_pair_liquidity(env: &Env, source: &Symbol, destination: &Symbol) -> i128 {
        env.storage()
            .persistent()
            .get(&DataKey::PairLiquidity(source.clone(), destination.clone()))
            .unwrap_or(0)
    }

    /// Read the per-pair route cooldown from persistent storage.
    ///
    /// Returns `0` (rate limit disabled) when the slot is absent — the
    /// documented default for an unconfigured pair. This is the single
    /// source of truth for the [`DataKey::PairCooldown`] sentinel value.
    fn read_pair_cooldown(env: &Env, source: &Symbol, destination: &Symbol) -> u64 {
        env.storage()
            .persistent()
            .get(&DataKey::PairCooldown(source.clone(), destination.clone()))
            .unwrap_or(0)
    }

    /// Read the stored absolute fee cap, normalising a pre-upgrade zero to
    /// `None`. A stored value of 0 is semantically equivalent to "no cap"
    /// (the write path now rejects zero), so both `apply_fee_cap` and the
    /// public getter agree on the effective state.
    fn read_max_fee_cap(env: &Env) -> Option<i128> {
        env.storage()
            .persistent()
            .get::<_, i128>(&DataKey::MaxFeeAbsolute)
            .filter(|cap| *cap > 0)
    }

    /// Clamp `fee` to the configured absolute ceiling when one is set.
    /// Both the relative `MAX_FEE_BPS` bound and this absolute bound apply;
    /// the tighter of the two wins. No-op when no absolute cap is configured
    /// (or when a pre-upgrade stored zero is normalised to `None`).
    fn apply_fee_cap(env: &Env, fee: i128) -> i128 {
        match Self::read_max_fee_cap(env) {
            Some(cap) => fee.min(cap),
            None => fee,
        }
    }

    /// Clamp `fee` to the configured absolute floor when one is set.
    /// Applies after the fee cap; if the floor exceeds the cap, the floor
    /// takes precedence. No-op when no absolute floor is configured.
    fn apply_fee_floor(env: &Env, fee: i128) -> i128 {
        match env
            .storage()
            .persistent()
            .get::<_, i128>(&DataKey::MinFeeAbsolute)
        {
            Some(floor) => fee.max(floor),
            None => fee,
        }
    }

    /// Clear all pair-scoped config that should not survive unregister + re-register.
    ///
    /// This intentionally excludes route counters, cumulative volume, and last-route timestamp;
    /// those operational-history slots are tracked separately from live pair configuration.
    fn clear_pair_config(env: &Env, source: Symbol, destination: Symbol) {
        let storage = env.storage().persistent();
        storage.remove(&DataKey::PairMinAmount(source.clone(), destination.clone()));
        storage.remove(&DataKey::PairMaxAmount(source.clone(), destination.clone()));
        storage.remove(&DataKey::PairLiquidity(source.clone(), destination.clone()));
        storage.remove(&DataKey::PairCooldown(source.clone(), destination.clone()));
        storage.remove(&DataKey::PairDisputed(source, destination));
    }

    /// Remove a registered pair from the router.
    ///
    /// Admin-gated and idempotent. Registration is removed and per-pair
    /// configuration is cleared, while historical routing metrics remain
    /// until explicitly purged.
    pub fn unregister_pair(env: Env, source: Symbol, destination: Symbol) {
        Self::require_admin(&env);
        env.storage()
            .persistent()
            .remove(&DataKey::Pair(source.clone(), destination.clone()));
        Self::clear_pair_config(&env, source.clone(), destination.clone());
        env.events().publish(
            (symbol_short!("unreg"),),
            (source.clone(), destination.clone()),
        );
        env.events()
            .publish((symbol_short!("cfg_clr"),), (source, destination));
    }

    /// Permanently remove all recorded routing metrics for a pair.
    ///
    /// Admin-gated. Clears the route count, cumulative volume, and last
    /// successful route timestamp.
    pub fn purge_pair_metrics(env: Env, source: Symbol, destination: Symbol) {
        Self::require_admin(&env);
        let storage = env.storage().persistent();
        storage.remove(&DataKey::PairRouteCount(
            source.clone(),
            destination.clone(),
        ));
        storage.remove(&DataKey::PairVolume(source.clone(), destination.clone()));
        storage.remove(&DataKey::PairLastRouteAt(
            source.clone(),
            destination.clone(),
        ));
        env.events()
            .publish((symbol_short!("pair_mrst"),), (source, destination));
    }

    /// Returns `true` if the pair is currently registered.
    ///
    /// Registration is independent of liquidity or routing activity.
    pub fn is_pair_registered(env: Env, source: Symbol, destination: Symbol) -> bool {
        Self::read_pair_registered(&env, &source, &destination)
    }

    /// Configure the routing fee for a single registered pair.
    ///
    /// Admin-gated. The fee is expressed in basis points and must not exceed
    /// [`MAX_FEE_BPS`].
    pub fn set_pair_fee_bps(env: Env, source: Symbol, destination: Symbol, fee_bps: u32) {
        Self::require_not_paused(&env);
        Self::require_admin(&env);
        if fee_bps > MAX_FEE_BPS {
            panic_with_error!(&env, RouterError::FeeBpsTooHigh);
        }
        Self::require_pair_registered(&env, &source, &destination);
        env.storage().persistent().set(
            &DataKey::PairFeeBps(source.clone(), destination.clone()),
            &fee_bps,
        );
        env.events()
            .publish((symbol_short!("fee_set"),), (source, destination, fee_bps));
    }

    /// Configure routing fees for multiple registered pairs in a single call.
    ///
    /// Admin-gated. Each entry is validated independently and the transaction
    /// is atomic: if any entry is invalid, no fee changes are applied.
    pub fn set_pair_fees_bps(env: Env, entries: Vec<(Symbol, Symbol, u32)>) {
        Self::require_not_paused(&env);
        Self::require_admin(&env);
        if entries.is_empty() {
            panic_with_error!(&env, RouterError::EmptyBatch);
        }
        if entries.len() > MAX_BATCH_SIZE {
            panic_with_error!(&env, RouterError::BatchTooLarge);
        }
        for (source, destination, fee_bps) in entries.iter() {
            if fee_bps > MAX_FEE_BPS {
                panic_with_error!(&env, RouterError::FeeBpsTooHigh);
            }
            Self::require_pair_registered(&env, &source, &destination);
            env.storage().persistent().set(
                &DataKey::PairFeeBps(source.clone(), destination.clone()),
                &fee_bps,
            );
            env.events()
                .publish((symbol_short!("fee_set"),), (source, destination, fee_bps));
        }
    }

    /// Returns the configured routing fee for the pair, expressed in basis
    /// points.
    ///
    /// Returns `0` when no fee has been configured.
    pub fn get_pair_fee_bps(env: Env, source: Symbol, destination: Symbol) -> u32 {
        Self::read_pair_fee_bps(&env, &source, &destination)
    }

    /// Compute the fee in source units for routing `amount` through the
    /// `(source, destination)` pair.
    ///
    /// Rejects unregistered pairs with [`RouterError::PairNotRegistered`]
    /// and non-positive amounts with [`RouterError::AmountMustBePositive`]
    /// so off-chain callers always get a clear typed error instead of a
    /// silent zero. Math is integer division (truncating toward zero),
    /// matching every existing Stellar fee accounting precedent.
    ///
    /// Honours the emergency stop: while the router is paused this
    /// entrypoint panics with [`RouterError::ContractPaused`] so no route
    /// can be recorded (the `TotalRoutesAllTime` counter, the
    /// `PairLastRouteAt` stamp, and the `route` event are all gated). The
    /// read-only `quote_route` is intentionally left available while
    /// paused so integrators can keep planning routes for when the router
    /// resumes.
    ///
    /// # Checks/effects ordering
    ///
    /// Registered-pair, amount-bound, liquidity, and cooldown guards all
    /// pass before any route business effect is applied. Only after those
    /// checks does the function debit liquidity, update counters and
    /// timestamps, and emit route events.
    ///
    /// # Liquidity consumption
    ///
    /// After passing all pre-condition checks, the function debits `amount`
    /// from the stored `PairLiquidity` via saturating subtraction. If the
    /// liquidity slot is unset the decrement is skipped entirely, preserving
    /// the "no oracle configured" behavior. If liquidity is explicitly set
    /// to `0`, the function returns [`RouterError::InsufficientLiquidity`]
    /// before any state mutation. When a decrement does occur a `liq_used`
    /// event carrying `(source, destination, remaining_liquidity)` is
    /// emitted. The slot TTL is extended on each write.
    ///
    /// # Key-construction optimisation
    ///
    /// Each [`DataKey`] variant that is both *read* and *written* within
    /// this function — [`DataKey::PairLiquidity`],
    /// [`DataKey::PairLastRouteAt`], [`DataKey::PairRouteCount`], and
    /// [`DataKey::PairVolume`] — is constructed **once** into a local
    /// variable and then referenced by `&` for every subsequent storage
    /// operation. This replaces the previous pattern of calling
    /// `DataKey::Variant(source.clone(), destination.clone())` on every
    /// individual read and write, halving the number of [`Symbol`] clones
    /// for those hot paths.
    ///
    /// The fee calculation (`read_pair_fee_bps` -> arithmetic -> cap ->
    /// floor) is hoisted **before** the effects section so that the final
    /// use of `source` and `destination` — the `route` event emission —
    /// *moves* (consumes) them instead of cloning.
    pub fn compute_route_fee(env: Env, source: Symbol, destination: Symbol, amount: i128) -> i128 {
        // Acquire the reentrancy lock at the very start so that every exit
        // path — success or panic — can explicitly release it. This ensures
        // future refactors that add new checks after this point cannot
        // accidentally leak the lock.
        Self::enter_nonreentrant(&env);

        if Self::paused(&env) {
            Self::route_abort(&env, RouterError::ContractPaused);
        }
        if amount <= 0 {
            Self::route_abort(&env, RouterError::AmountMustBePositive);
        }

        if !Self::read_pair_registered(&env, &source, &destination) {
            Self::route_abort(&env, RouterError::PairNotRegistered);
        }
        let min_amount = Self::read_pair_min(&env, &source, &destination);
        if amount < min_amount {
            Self::route_abort(&env, RouterError::AmountBelowMin);
        }
        let max_amount = Self::read_pair_max(&env, &source, &destination);
        if amount > max_amount {
            Self::route_abort(&env, RouterError::AmountAboveMax);
        }
        // Construct the liquidity key once — shared between the initial
        // read (guard) and the post-route debit write below.
        let liq_key = DataKey::PairLiquidity(source.clone(), destination.clone());
        let liquidity: i128 = match env.storage().persistent().get(&liq_key) {
            Some(0) => Self::route_abort(&env, RouterError::InsufficientLiquidity),
            Some(v) => v,
            None => i128::MAX,
        };
        if amount > liquidity {
            Self::route_abort(&env, RouterError::InsufficientLiquidity);
        }

        // Construct the last-route-at key once — shared between the
        // cooldown read and the post-route timestamp write below.
        let route_at_key = DataKey::PairLastRouteAt(source.clone(), destination.clone());
        // Per-pair rate limit. A non-zero cooldown forces a minimum gap
        // between successive routes for the pair. The first route (no
        // recorded timestamp) is always allowed; cooldown == 0 disables
        // the check entirely, preserving the prior behaviour. Compare via
        // addition (last + cooldown) rather than subtraction to avoid any
        // u64 underflow. `last + cooldown` cannot overflow u64 either:
        // `set_pair_cooldown` rejects any `cooldown` above
        // `MAX_COOLDOWN_SECS` (30 days), and `last` is a ledger timestamp
        // (seconds since epoch) that would need to be within 30 days of
        // `u64::MAX` — many orders of magnitude beyond any plausible
        // ledger closing time — before this addition could wrap.
        let cooldown = Self::read_pair_cooldown(&env, &source, &destination);
        if cooldown > 0 {
            if let Some(last) = env.storage().persistent().get::<_, u64>(&route_at_key) {
                if env.ledger().timestamp() < last + cooldown {
                    Self::exit_nonreentrant(&env);
                    panic_with_error!(&env, RouterError::RouteCooldownActive);
                }
            }
        }

        // Pre-effects: compute fee before state mutations so that
        // `source` and `destination` can be moved (consumed) into the
        // final route-event payload below, avoiding two extra clones.
        // Fee depends only on fee_bps, cap, and floor — none of which
        // are mutated by the effects section, making this reorder safe.
        let fee_bps = Self::read_pair_fee_bps(&env, &source, &destination);
        // amount * fee_bps / 10_000, in i128 to avoid u32*i128 overflow on
        // amounts near i128::MAX. fee_bps is capped at MAX_FEE_BPS so the
        // multiplication is bounded.
        let fee = amount
            .checked_mul(fee_bps as i128)
            .map(|n| n / BPS_DENOMINATOR)
            .unwrap_or(0);
        let fee = Self::apply_fee_cap(&env, fee);
        let fee = Self::apply_fee_floor(&env, fee);

        // ── EFFECTS ──────────────────────────────────────────────────
        // Debit liquidity, write counters/timestamps, and emit events.
        // When no oracle has set a liquidity value the pair is treated as
        // unbounded — no decrement and no liq_used event are emitted.
        //
        // Key variables constructed above (`liq_key`, `route_at_key`,
        // `route_count_key`, `volume_key`) are reused by `&` reference
        // here instead of reconstructing them with fresh `.clone()` calls.
        if liquidity != i128::MAX {
            let remaining = liquidity.saturating_sub(amount);
            env.storage().persistent().set(&liq_key, &remaining);
            env.events().publish(
                (symbol_short!("liq_used"),),
                (source.clone(), destination.clone(), remaining),
            );
        }
        let total: u64 = env
            .storage()
            .persistent()
            .get(&DataKey::TotalRoutesAllTime)
            .unwrap_or(0);
        env.storage()
            .persistent()
            .set(&DataKey::TotalRoutesAllTime, &total.saturating_add(1));

        // Construct the route-count key once — shared between read and write.
        let route_count_key = DataKey::PairRouteCount(source.clone(), destination.clone());
        let pair_count: u64 = env
            .storage()
            .persistent()
            .get(&route_count_key)
            .unwrap_or(0);
        env.storage()
            .persistent()
            .set(&route_count_key, &pair_count.saturating_add(1));

        // Construct the volume key once — shared between read and write.
        let volume_key = DataKey::PairVolume(source.clone(), destination.clone());
        let pair_volume: i128 = env
            .storage()
            .persistent()
            .get(&volume_key)
            .unwrap_or(0);
        env.storage()
            .persistent()
            .set(&volume_key, &pair_volume.saturating_add(amount));

        env.storage()
            .persistent()
            .set(&route_at_key, &env.ledger().timestamp());

        // Last use of source/destination — moved (consumed) rather than
        // cloned, saving one Symbol clone pair on the hot path.
        env.events()
            .publish((symbol_short!("route"),), (source, destination, amount));

        Self::exit_nonreentrant(&env);
        fee
    }

    /// Compute a deterministic, direction-sensitive route identifier for a
    /// `(source, destination)` pair.
    ///
    /// The tag is `keccak256(xdr(source) || xdr(destination))`: a stable
    /// 32-byte digest that depends on the encoded inputs in order. Properties:
    ///
    /// - **Deterministic** — the same `(source, destination)` always hashes to
    ///   the same value, so an off-chain backend can recompute it and correlate
    ///   on-chain routes without storing a mapping.
    /// - **Direction-sensitive** — `source` is hashed before `destination`, so
    ///   `route_tag(USDC, EURC) != route_tag(EURC, USDC)`. Each leg of a pair
    ///   gets its own identifier.
    ///
    /// Returns the digest as a [`BytesN<32>`].
    pub fn route_tag(env: Env, source: Symbol, destination: Symbol) -> BytesN<32> {
        // Build the pre-image deterministically: the XDR encoding of `source`
        // followed by the XDR encoding of `destination`. Ordering the appends
        // this way is what makes the tag direction-sensitive.
        let mut buf = Bytes::new(&env);
        buf.append(&source.to_xdr(&env));
        buf.append(&destination.to_xdr(&env));
        env.crypto().keccak256(&buf).to_bytes()
    }

    /// Replace the contract's WASM in-place so the router can be patched
    /// without losing pair state. Admin-gated; emits an `upgraded` event
    /// carrying the new hash so indexers and watchers can audit upgrades.
    ///
    /// ## Trade-off: not paused-gated
    ///
    /// An emergency pause should arguably still allow the admin to deploy a
    /// fix. We therefore skip the `ContractPaused` check — a paused router
    /// can be upgraded, which is consistent with fixing the bug that caused
    /// the pause. The admin can already unpause, so there is no escalation
    /// path through this exception.
    pub fn upgrade(env: Env, new_wasm_hash: BytesN<32>) {
        Self::require_admin(&env);
        env.events()
            .publish((symbol_short!("upgraded"),), &new_wasm_hash);
        env.deployer().update_current_contract_wasm(new_wasm_hash);
    }
}

/// Test-only mock that re-enters the router from a nested contract call.
///
/// The mock stays minimal on purpose: it exists only to simulate a malicious
/// callback path and trigger the router's reentrancy guard in a realistic
/// nested-call shape.
#[cfg(test)]
#[contract]
pub struct MaliciousReentryMock;

#[cfg(test)]
#[contractimpl]
impl MaliciousReentryMock {
    /// Call back into `compute_route_fee` on the target router.
    ///
    /// The test harness arranges for the router lock to already be held before
    /// this entrypoint runs, so the nested router call exercises the guard as a
    /// callback-style re-entry attempt.
    pub fn reenter(
        env: Env,
        router_id: Address,
        source: Symbol,
        destination: Symbol,
        amount: i128,
    ) {
        let router = StableRouteRouterClient::new(&env, &router_id);
        router.compute_route_fee(&source, &destination, &amount);
    }
}

#[cfg(test)]
mod test {
    use super::*;
    use proptest::prelude::*;
    use soroban_sdk::{
        symbol_short,
        testutils::{Address as _, Events, Ledger},
        IntoVal,
    };
    use std::any::Any;
    use std::string::{String, ToString};

    /// Register a USDC→EURC pair with `fee_bps` and unbounded liquidity,
    /// returning a ready client. Shared by the property tests below.
    fn setup_pair_with_fee(env: &Env, fee_bps: u32) -> StableRouteRouterClient<'_> {
        let (client, _admin) = setup_initialized(env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &fee_bps);
        client
    }

    fn panic_message(err: &(dyn Any + Send)) -> Option<String> {
        err.downcast_ref::<String>()
            .cloned()
            .or_else(|| err.downcast_ref::<&str>().map(|s| (*s).to_string()))
    }

    /// Mirrors `apply_fee_cap` — apply MaxFeeAbsolute if set.
    fn apply_fee_cap_mirror(fee: i128, max_fee_absolute: Option<i128>) -> i128 {
        match max_fee_absolute {
            Some(cap) if cap > 0 => fee.min(cap),
            _ => fee,
        }
    }

    /// Pure fee math extracted from `compute_route_fee` for property testing
    /// without needing a full Soroban environment per iteration.
    fn compute_fee_pure(amount: i128, fee_bps: u32, max_fee_absolute: Option<i128>) -> i128 {
        let fee = amount
            .checked_mul(fee_bps as i128)
            .map(|n| n / BPS_DENOMINATOR)
            .unwrap_or(0);
        apply_fee_cap_mirror(fee, max_fee_absolute)
    }

    proptest! {
        // Fixed case count keeps CI deterministic and fast.
        #![proptest_config(ProptestConfig { cases: 96, ..ProptestConfig::default() })]

        /// Invariant: the fee never exceeds the routed amount and is never
        /// negative, for any valid fee_bps and amount. `amount * fee_bps`
        /// stays well within i128 (amount < 1e24, fee_bps <= 1000).
        #[test]
        fn prop_fee_within_amount(
            amount in 1i128..1_000_000_000_000_000_000_000_000i128,
            fee_bps in 0u32..=MAX_FEE_BPS,
        ) {
            let env = Env::default();
            let client = setup_pair_with_fee(&env, fee_bps);
            let fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            prop_assert!(fee >= 0);
            prop_assert!(fee <= amount);
        }

        /// Invariant: a zero fee_bps always yields a zero fee.
        #[test]
        fn prop_zero_fee_bps_is_free(
            amount in 1i128..1_000_000_000_000_000_000i128,
        ) {
            let env = Env::default();
            let client = setup_pair_with_fee(&env, 0);
            let fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            prop_assert_eq!(fee, 0);
        }

        /// Invariant: `quote_route` reports the same fee as
        /// `compute_route_fee` for identical config, and fee + net == amount.
        #[test]
        fn prop_quote_matches_compute(
            amount in 1i128..1_000_000_000_000_000_000i128,
            fee_bps in 0u32..=MAX_FEE_BPS,
        ) {
            let env = Env::default();
            let client = setup_pair_with_fee(&env, fee_bps);
            let (quoted_fee, net) = client.quote_route(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            let computed_fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            prop_assert_eq!(quoted_fee, computed_fee);
            prop_assert_eq!(quoted_fee + net, amount);
        }

        #[test]
        fn prop_fee_never_exceeds_amount(
            amount in 1_i128..=i128::MAX,
            fee_bps in 0_u32..=MAX_FEE_BPS,
        ) {
            let env = Env::default();
            let client = setup_pair_with_fee(&env, fee_bps);
            let fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            prop_assert!(fee >= 0);
            prop_assert!(fee <= amount);
        }

        #[test]
        fn prop_overflow_fallback_is_zero(
            amount in (i128::MAX / MAX_FEE_BPS as i128 + 1)..=i128::MAX,
            fee_bps in 1_u32..=MAX_FEE_BPS,
        ) {
            // checked_mul must return None here → fee falls back to 0
            let overflows = amount.checked_mul(fee_bps as i128).is_none();
            prop_assume!(overflows);

            let env = Env::default();
            let client = setup_pair_with_fee(&env, fee_bps);
            let fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            prop_assert_eq!(fee, 0, "overflow fallback must be 0");
            prop_assert!(fee <= amount, "fallback fee must not exceed amount");
        }

        #[test]
        fn prop_zero_bps_yields_zero_fee(
            amount in 1_i128..=i128::MAX,
        ) {
            let env = Env::default();
            let client = setup_pair_with_fee(&env, 0);
            let fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            prop_assert_eq!(fee, 0, "zero fee_bps must produce zero fee");
        }

        /// Invariant: the contract's absolute-capped fee equals the pure
        /// reference math (`compute_fee_pure`) for any amount, fee_bps, and
        /// non-negative absolute cap. Exercises `apply_fee_cap` end to end
        /// against the extracted, environment-free fee model.
        #[test]
        fn prop_capped_fee_matches_pure_math(
            amount in 1i128..1_000_000_000_000_000_000_000_000i128,
            fee_bps in 0u32..=MAX_FEE_BPS,
            cap in 1i128..1_000_000_000_000_000_000i128,
        ) {
            let env = Env::default();
            let client = setup_pair_with_fee(&env, fee_bps);
            client.set_max_fee_absolute(&cap);
            let expected = compute_fee_pure(amount, fee_bps, Some(cap));
            let fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &amount,
            );
            prop_assert_eq!(fee, expected);
        }
    }

    /// Deploy the router with `admin` set atomically via the constructor
    /// (`register(StableRouteRouter, (admin,))`) — the front-run-safe path.
    fn setup_initialized(env: &Env) -> (StableRouteRouterClient<'_>, Address) {
        let (client, admin, _id) = setup_initialized_with_id(env);
        (client, admin)
    }

    /// Like [`setup_initialized`] but also returns the contract id so tests
    /// can reach into the contract's own storage via `env.as_contract`.
    fn setup_initialized_with_id(env: &Env) -> (StableRouteRouterClient<'_>, Address, Address) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &contract_id);
        (client, admin, contract_id)
    }

    /// Register a router without constructor args so legacy pre-init tests can
    /// assert uninitialized admin-gated entrypoints still fail cleanly.
    fn setup_uninitialized(env: &Env) -> StableRouteRouterClient<'_> {
        env.mock_all_auths();
        let contract_id = env.register(StableRouteRouter, ());
        StableRouteRouterClient::new(env, &contract_id)
    }

    #[test]
    fn test_version() {
        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let contract_id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(&env, &contract_id);
        let v = client.version();
        assert_eq!(v, symbol_short!("ROUTER_V2"));
    }

    #[test]
    fn test_route_tag() {
        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let contract_id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(&env, &contract_id);

        // Determinism: the same inputs hash to the same tag across calls.
        let tag_a = client.route_tag(&symbol_short!("USDC"), &symbol_short!("EURC"));
        let tag_b = client.route_tag(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert_eq!(tag_a, tag_b);

        // Direction sensitivity: (src, dst) differs from (dst, src).
        let reversed = client.route_tag(&symbol_short!("EURC"), &symbol_short!("USDC"));
        assert_ne!(tag_a, reversed);

        // Distinct pairs produce distinct tags.
        let other = client.route_tag(&symbol_short!("USDC"), &symbol_short!("XLM"));
        assert_ne!(tag_a, other);
    }

    #[test]
    fn test_init_persists_admin() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        assert_eq!(client.get_admin(), Some(admin));
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #1)")]
    fn test_init_rejects_double_init() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let other = Address::generate(&env);
        client.init(&other);
    }

    #[test]
    fn test_register_pair_round_trip() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert!(client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
        // Reverse direction is independent.
        assert!(!client.is_pair_registered(&symbol_short!("EURC"), &symbol_short!("USDC")));
    }

    #[test]
    fn test_register_pair_is_idempotent() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert!(client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
    }

    /// A re-registration of an already-registered pair must not re-emit
    /// `pair_reg`: exactly one `pair_reg` event across two calls on the
    /// same pair.
    #[test]
    fn test_register_pair_does_not_duplicate_event_on_reregistration() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.register_pair(&s, &d);
        assert_eq!(
            event_payloads(&env, symbol_short!("pair_reg")).len(),
            1,
            "re-registering an already-registered pair must not emit a second pair_reg event"
        );
    }

    /// Batch-registering a mix of one already-registered and one fresh pair
    /// emits `pair_reg` only for the genuinely new registration.
    #[test]
    fn test_register_pairs_does_not_duplicate_event_on_reregistration() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        let mut batch = Vec::new(&env);
        batch.push_back((s.clone(), d.clone()));
        batch.push_back((symbol_short!("XLM"), symbol_short!("USDC")));
        client.register_pairs(&batch);
        assert_eq!(
            event_payloads(&env, symbol_short!("pair_reg")).len(),
            2,
            "one pair_reg for register_pair plus one for the fresh entry in register_pairs; \
             the already-registered entry must not re-fire"
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #3)")]
    fn test_register_pair_rejects_identity() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("USDC"));
    }

    // --- dispute flag ---

    #[test]
    fn test_is_pair_disputed_defaults_to_false() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        assert!(!client.is_pair_disputed(&s, &d));
    }

    #[test]
    fn test_flag_pair_dispute_blocks_quote_and_compute() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.flag_pair_dispute(&s, &d);
        assert!(client.is_pair_disputed(&s, &d));

        let quote_result = client.try_quote_route(&s, &d, &1_000i128);
        assert!(quote_result.is_err(), "disputed pair must reject quote_route");

        let compute_result = client.try_compute_route_fee(&s, &d, &1_000i128);
        assert!(
            compute_result.is_err(),
            "disputed pair must reject compute_route_fee"
        );
    }

    #[test]
    fn test_resolve_pair_dispute_restores_routing() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.flag_pair_dispute(&s, &d);
        client.resolve_pair_dispute(&s, &d);
        assert!(!client.is_pair_disputed(&s, &d));
        // Routing works again once resolved.
        client.quote_route(&s, &d, &1_000i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #5)")]
    fn test_flag_pair_dispute_requires_registered_pair() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.flag_pair_dispute(&symbol_short!("USDC"), &symbol_short!("EURC"));
    }

    #[test]
    fn test_flag_pair_dispute_does_not_duplicate_event_on_reflag() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.flag_pair_dispute(&s, &d);
        client.flag_pair_dispute(&s, &d);
        assert_eq!(
            event_payloads(&env, symbol_short!("disp_set")).len(),
            1,
            "re-flagging an already-disputed pair must not emit a second disp_set event"
        );
    }

    #[test]
    fn test_resolve_pair_dispute_on_undisputed_pair_is_noop_without_event() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.resolve_pair_dispute(&s, &d);
        assert!(!client.is_pair_disputed(&s, &d));
        assert_eq!(
            event_payloads(&env, symbol_short!("disp_set")).len(),
            0,
            "resolving a pair with no active dispute must not emit disp_set"
        );
    }

    #[test]
    fn test_unregister_pair_clears_dispute_flag() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.flag_pair_dispute(&s, &d);
        client.unregister_pair(&s, &d);
        client.register_pair(&s, &d);
        assert!(
            !client.is_pair_disputed(&s, &d),
            "re-registering after unregister must not inherit a stale dispute flag"
        );
    }

    #[test]
    fn test_is_pair_registered_defaults_to_false() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert!(!client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("XLM")));
    }

    #[test]
    fn test_get_pair_fee_bps_defaults_to_zero() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC")),
            0
        );
    }

    #[test]
    fn test_set_pair_fee_bps_round_trip() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC")),
            50
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #4)")]
    fn test_set_pair_fee_bps_rejects_above_max() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &(MAX_FEE_BPS + 1),
        );
    }

    #[test]
    fn test_compute_route_fee_basic() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);
        // 1_000_000 * 50 / 10_000 = 5_000
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(fee, 5_000);
    }

    // --- rewards accrual ---

    #[test]
    fn test_rewards_accrued_defaults_to_zero() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert_eq!(client.get_rewards_accrued(), 0);
    }

    #[test]
    fn test_rewards_accrued_accumulates_across_routes() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &50u32);
        let fee1 = client.compute_route_fee(&s, &d, &1_000_000_i128);
        assert_eq!(client.get_rewards_accrued(), fee1);
        let fee2 = client.compute_route_fee(&s, &d, &2_000_000_i128);
        assert_eq!(client.get_rewards_accrued(), fee1 + fee2);
    }

    #[test]
    fn test_rewards_accrued_unaffected_by_zero_fee_route() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        // No fee_bps set — every route is free.
        let fee = client.compute_route_fee(&s, &d, &1_000_000_i128);
        assert_eq!(fee, 0);
        assert_eq!(client.get_rewards_accrued(), 0);
        assert_eq!(
            event_payloads(&env, symbol_short!("rwd_accr")).len(),
            0,
            "a zero-fee route must not emit rwd_accr"
        );
    }

    #[test]
    fn test_rewards_accrued_event_carries_fee_and_running_total() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &50u32);
        let fee = client.compute_route_fee(&s, &d, &1_000_000_i128);
        let payloads = event_payloads(&env, symbol_short!("rwd_accr"));
        assert_eq!(payloads.len(), 1, "one rwd_accr event for one fee-bearing route");
        let (emitted_fee, emitted_total): (i128, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
                .expect("rwd_accr payload decodes to (fee, running_total)");
        assert_eq!(emitted_fee, fee);
        assert_eq!(emitted_total, client.get_rewards_accrued());
    }

    /// Over-limit boundary: accrual must saturate at `i128::MAX` instead of
    /// panicking on overflow.
    #[test]
    fn test_rewards_accrued_saturates_instead_of_overflowing() {
        let env = Env::default();
        let (client, _admin, contract_id) = setup_initialized_with_id(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &50u32);
        env.as_contract(&contract_id, || {
            env.storage()
                .persistent()
                .set(&DataKey::RewardsAccrued, &(i128::MAX - 10));
        });
        client.compute_route_fee(&s, &d, &1_000_000_i128);
        assert_eq!(client.get_rewards_accrued(), i128::MAX);
    }

    #[test]
    fn test_compute_route_fee_is_zero_when_fee_unset() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(fee, 0);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #5)")]
    fn test_compute_route_fee_rejects_unregistered_pair() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_000_i128);
    }

    // --- reentrancy guard ---

    /// The normal success path must RELEASE the reentrancy lock, so two
    /// consecutive `compute_route_fee` calls on the same pair both succeed.
    /// If the lock leaked, the second call would panic with #16.
    #[test]
    fn test_compute_route_fee_releases_lock_for_consecutive_calls() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);

        let first = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        let second = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );

        assert_eq!(first, 5_000);
        assert_eq!(second, 5_000);
        assert_eq!(client.get_total_routes_all_time(), 2);
    }

    /// A malicious nested caller must not be able to re-enter
    /// `compute_route_fee` while the router lock is held.
    #[test]
    fn test_compute_route_fee_rejects_reentry_from_mock_callback() {
        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let router_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(&env, &router_id);
        let mock_id = env.register(MaliciousReentryMock, ());
        let mock = MaliciousReentryMockClient::new(&env, &mock_id);

        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);

        env.as_contract(&router_id, || {
            env.storage()
                .persistent()
                .set(&DataKey::ReentrancyLock, &true);
        });

        // The mock now performs the nested router call from a normal contract
        // invocation, matching the callback-driven shape we want to exercise.
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            mock.reenter(
                &router_id,
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &1_000_000_i128,
            );
        }));
        let panic = result.expect_err("nested router call should panic");
        let message = panic_message(&*panic).expect("panic payload should be printable");
        assert!(
            message.contains("Error(Contract, #15)"),
            "unexpected panic payload: {message}"
        );

        let lock_after: bool = env.as_contract(&router_id, || {
            env.storage()
                .persistent()
                .get(&DataKey::ReentrancyLock)
                .unwrap_or(false)
        });
        assert!(lock_after);

        env.as_contract(&router_id, || {
            env.storage()
                .persistent()
                .set(&DataKey::ReentrancyLock, &false);
        });
        assert_eq!(
            client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &1_000_000_i128
            ),
            5_000
        );
    }

    /// A successful route must leave the reentrancy lock cleared so
    /// sequential legitimate calls remain possible.
    #[test]
    fn test_compute_route_fee_clears_reentrancy_lock_after_success() {
        let env = Env::default();
        let (client, _admin, contract_id) = setup_initialized_with_id(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);

        let first = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(first, 5_000);

        let lock_after_first: bool = env.as_contract(&contract_id, || {
            env.storage()
                .persistent()
                .get(&DataKey::ReentrancyLock)
                .unwrap_or(false)
        });
        assert!(!lock_after_first);

        let second = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(second, 5_000);
        assert_eq!(client.get_total_routes_all_time(), 2);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_compute_route_fee_rejects_zero_amount() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &0i128);
    }

    #[test]
    fn test_schema_version_migration() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert_eq!(client.get_schema_version(), 1);
        client.migrate_v1_to_v2();
        assert_eq!(client.get_schema_version(), 2);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #13)")]
    fn test_schema_migration_rejects_second_run() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.migrate_v1_to_v2();
        client.migrate_v1_to_v2();
    }

    #[test]
    fn test_pause_and_unpause_round_trip() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert!(!client.is_paused());
        client.pause();
        assert!(client.is_paused());
        client.unpause();
        assert!(!client.is_paused());
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_register_pair_rejects_when_paused() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.pause();
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
    }

    /// The emergency stop must block route accounting: while paused,
    /// `compute_route_fee` panics with `ContractPaused` (#9) and never
    /// touches the counter / timestamp.
    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_compute_route_fee_rejects_when_paused() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);
        client.pause();
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
    }

    /// Routing resumes cleanly after an unpause, and no route was recorded
    /// during the paused window.
    #[test]
    fn test_compute_route_fee_resumes_after_unpause() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);
        client.pause();
        client.unpause();
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(fee, 5_000);
        assert_eq!(client.get_total_routes_all_time(), 1);
    }

    /// Read-only quotes stay available while paused (documented policy:
    /// block state-mutating routes, keep quotes open for planning).
    #[test]
    fn test_quote_route_allowed_while_paused() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &100u32);
        client.pause();
        assert_eq!(
            client.quote_route(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_000i128),
            (10, 990)
        );
    }

    #[test]
    fn test_admin_transfer_flow() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        assert_eq!(client.get_pending_admin(), Some(next_admin.clone()));
        client.accept_admin_transfer(&next_admin);
        assert_eq!(client.get_admin(), Some(next_admin));
        assert_eq!(client.get_pending_admin(), None);
    }

    #[test]
    fn test_cancel_admin_transfer_clears_pending_admin() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        client.cancel_admin_transfer();
        assert_eq!(client.get_pending_admin(), None);
        assert_eq!(client.get_pending_admin_eta(), None);
    }

    // --- get_pending_admin_info (aggregated claim-state view) ---

    /// Before any transfer is proposed, the aggregated view returns the
    /// same sane `None`/`None` default as the two individual getters.
    #[test]
    fn test_pending_admin_info_default_before_any_transfer() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert_eq!(
            client.get_pending_admin_info(),
            PendingAdminInfo {
                pending: None,
                eta: None
            }
        );
    }

    /// Once a transfer is queued, the aggregated view is a consistent
    /// snapshot of both individual getters.
    #[test]
    fn test_pending_admin_info_reflects_queued_transfer() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&100);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);

        let info = client.get_pending_admin_info();
        assert_eq!(info.pending, client.get_pending_admin());
        assert_eq!(info.eta, client.get_pending_admin_eta());
        assert_eq!(
            info,
            PendingAdminInfo {
                pending: Some(next_admin),
                eta: Some(1_100)
            }
        );
    }

    /// The aggregated view reverts to the default once the transfer
    /// completes (mirrors the individual-getter coverage in
    /// `test_admin_transfer_flow`).
    #[test]
    fn test_pending_admin_info_clears_after_accept() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        client.accept_admin_transfer(&next_admin);
        assert_eq!(
            client.get_pending_admin_info(),
            PendingAdminInfo {
                pending: None,
                eta: None
            }
        );
    }

    // --- #21: governance timelock ---

    /// Timelock defaults to 0 (instant handover) when unset.
    #[test]
    fn test_timelock_defaults_to_zero() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert_eq!(client.get_timelock(), 0);
    }

    #[test]
    fn test_set_timelock_emits_event() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);

        // 1. Zero-to-nonzero transition: old timelock is 0, new value nonzero
        client.set_timelock(&100);
        let payloads = event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(payloads.len(), 1, "should emit exactly one event");
        let event_data: (u64, u64) = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("tlock_set event data decodes");
        assert_eq!(event_data, (0, 100));

        // 2. Normal change: old timelock nonzero, new value nonzero
        client.set_timelock(&200);
        let payloads = event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(payloads.len(), 1, "should emit a second event");
        let event_data: (u64, u64) = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("tlock_set event data decodes");
        assert_eq!(event_data, (100, 200));

        // 3. Nonzero-to-zero transition: old timelock nonzero, new value 0
        client.set_timelock(&0);
        let payloads = event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(payloads.len(), 1, "should emit a third event");
        let event_data: (u64, u64) = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("tlock_set event data decodes");
        assert_eq!(event_data, (200, 0));
    }

    /// With a delay set, accepting the handover before the eta is rejected
    /// with TimelockNotElapsed (#14).
    #[test]
    #[should_panic(expected = "Error(Contract, #14)")]
    fn test_timelock_blocks_early_accept() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&100);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        assert_eq!(client.get_pending_admin_eta(), Some(1_100));
        client.accept_admin_transfer(&next_admin); // still at t=1_000
    }

    /// After the delay elapses, the handover executes normally. Also pins
    /// the exact-eta boundary: `t == eta` must succeed (the check is
    /// `t < eta`, not `t <= eta`).
    #[test]
    fn test_timelock_allows_accept_after_delay() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&100);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        env.ledger().set_timestamp(1_100);
        client.accept_admin_transfer(&next_admin);
        assert_eq!(client.get_admin(), Some(next_admin));
        assert_eq!(client.get_pending_admin_eta(), None);
    }

    // --- claim (admin-transfer) timelock boundaries ---

    /// Zero boundary: the default (unset) timelock is `0`, so accept
    /// succeeds at the exact same timestamp as the proposal — no implicit
    /// minimum delay.
    #[test]
    fn test_claim_zero_timelock_boundary_accepts_immediately() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        assert_eq!(client.get_pending_admin_eta(), Some(1_000));
        client.accept_admin_transfer(&next_admin); // no timestamp advance
        assert_eq!(client.get_admin(), Some(next_admin));
    }

    /// Tightens `test_timelock_allows_accept_after_delay`'s exact-eta
    /// success case from the other side: one second *before* eta must
    /// still be rejected with `TimelockNotElapsed` (#14), not just any
    /// earlier timestamp.
    #[test]
    #[should_panic(expected = "Error(Contract, #14)")]
    fn test_claim_timelock_boundary_one_second_early_still_blocked() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&100);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        env.ledger().set_timestamp(1_099); // eta - 1
        client.accept_admin_transfer(&next_admin);
    }

    /// Unguarded max boundary: unlike the per-pair cooldown (capped at
    /// `MAX_COOLDOWN_SECS`), `set_timelock` enforces no upper bound at all.
    /// An admin can set it to `u64::MAX`; `propose_admin_transfer`'s
    /// `saturating_add` then clamps (rather than panics on overflow) the
    /// eta to `u64::MAX`, which for all practical purposes permanently
    /// blocks every future handover for that pending admin, since no
    /// ledger timestamp will ever reach `u64::MAX`. Documented here as a
    /// deliberate note rather than a fix, per this issue's "note any
    /// unguarded boundary" scope.
    #[test]
    fn test_claim_timelock_max_value_is_unguarded_and_saturates_eta() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&u64::MAX);
        assert_eq!(
            client.get_timelock(),
            u64::MAX,
            "set_timelock enforces no upper bound"
        );
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        assert_eq!(
            client.get_pending_admin_eta(),
            Some(u64::MAX),
            "saturating_add clamps to u64::MAX instead of overflowing"
        );
    }

    /// Cancelling a queued transfer clears both the pending admin and eta.
    #[test]
    fn test_timelock_cancel_clears_queue() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&100);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        client.cancel_admin_transfer();
        assert_eq!(client.get_pending_admin(), None);
        assert_eq!(client.get_pending_admin_eta(), None);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #7)")]
    fn test_accept_admin_transfer_rejects_missing_pending_admin() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let caller = Address::generate(&env);
        client.accept_admin_transfer(&caller);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #8)")]
    fn test_accept_admin_transfer_rejects_wrong_pending_admin() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let pending = Address::generate(&env);
        let caller = Address::generate(&env);
        client.propose_admin_transfer(&pending);
        client.accept_admin_transfer(&caller);
    }

    // --- force_admin_transfer tests ---

    #[test]
    fn test_force_admin_transfer_success() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        client.force_admin_transfer(&next_admin);
        assert_eq!(client.get_admin(), Some(next_admin));
        assert_eq!(client.get_pending_admin(), None);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #7)")]
    fn test_force_admin_transfer_rejects_missing_pending_admin() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let next_admin = Address::generate(&env);
        client.force_admin_transfer(&next_admin);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #8)")]
    fn test_force_admin_transfer_rejects_wrong_pending_admin() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let pending = Address::generate(&env);
        let wrong = Address::generate(&env);
        client.propose_admin_transfer(&pending);
        client.force_admin_transfer(&wrong);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #14)")]
    fn test_force_admin_transfer_blocks_early_force() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&100);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        client.force_admin_transfer(&next_admin);
    }

    #[test]
    fn test_force_admin_transfer_allows_after_timelock() {
        let env = Env::default();
        env.ledger().set_timestamp(1_000);
        let (client, _admin) = setup_initialized(&env);
        client.set_timelock(&100);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        env.ledger().set_timestamp(1_100);
        client.force_admin_transfer(&next_admin);
        assert_eq!(client.get_admin(), Some(next_admin));
    }

    #[test]
    fn test_force_admin_transfer_emits_executed_event() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let next_admin = Address::generate(&env);
        client.propose_admin_transfer(&next_admin);
        client.force_admin_transfer(&next_admin);

        let executed_payloads = event_payloads(&env, symbol_short!("executed"));
        assert_eq!(executed_payloads.len(), 1);
        let event_admin: Address =
            soroban_sdk::TryFromVal::try_from_val(&env, &executed_payloads[0])
                .expect("executed event data decodes to admin address");
        assert_eq!(event_admin, next_admin);
    }

    #[test]
    fn test_fee_recipient_round_trip() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert_eq!(client.get_fee_recipient(), None);
        let recipient = Address::generate(&env);
        client.set_fee_recipient(&recipient);
        assert_eq!(client.get_fee_recipient(), Some(recipient));
    }

    #[test]
    fn test_unregister_pair_removes_registration() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.unregister_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert!(!client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
    }

    #[test]
    fn test_pair_lifecycle_events_have_exact_payloads_and_counts() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");

        let init_payloads = event_payloads(&env, symbol_short!("init"));
        assert_eq!(init_payloads.len(), 1, "constructor emits one init event");
        let init_admin: Address = soroban_sdk::TryFromVal::try_from_val(&env, &init_payloads[0])
            .expect("init event data decodes to admin address");
        assert_eq!(init_admin, admin);

        client.register_pair(&src, &dest);
        let pair_reg_payloads = event_payloads(&env, symbol_short!("pair_reg"));
        assert_eq!(
            pair_reg_payloads.len(),
            1,
            "register_pair emits one pair_reg event"
        );
        let pair_reg: (Symbol, Symbol) =
            soroban_sdk::TryFromVal::try_from_val(&env, &pair_reg_payloads[0])
                .expect("pair_reg event data decodes to pair tuple");
        assert_eq!(pair_reg, (src.clone(), dest.clone()));

        client.set_pair_fee_bps(&src, &dest, &25u32);
        let fee_set_payloads = event_payloads(&env, symbol_short!("fee_set"));
        assert_eq!(
            fee_set_payloads.len(),
            1,
            "set_pair_fee_bps emits one fee_set event"
        );
        let fee_set: (Symbol, Symbol, u32) =
            soroban_sdk::TryFromVal::try_from_val(&env, &fee_set_payloads[0])
                .expect("fee_set event data decodes to pair and fee");
        assert_eq!(fee_set, (src.clone(), dest.clone(), 25u32));

        client.set_pair_liquidity(&admin, &src, &dest, &1_000i128);
        let liq_set_payloads = event_payloads(&env, symbol_short!("liq_set"));
        assert_eq!(
            liq_set_payloads.len(),
            1,
            "set_pair_liquidity emits one liq_set event"
        );
        let liq_set: (Symbol, Symbol, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &liq_set_payloads[0])
                .expect("liq_set event data decodes to pair and liquidity");
        assert_eq!(liq_set, (src.clone(), dest.clone(), 1_000i128));

        client.set_pair_min_amount(&src, &dest, &50i128);
        let min_set_payloads = event_payloads(&env, symbol_short!("min_set"));
        assert_eq!(
            min_set_payloads.len(),
            1,
            "set_pair_min_amount emits one min_set event"
        );
        let min_set: (Symbol, Symbol, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &min_set_payloads[0])
                .expect("min_set event data decodes to pair and amount");
        assert_eq!(min_set, (src.clone(), dest.clone(), 50i128));

        client.set_pair_max_amount(&src, &dest, &10_000i128);
        let max_set_payloads = event_payloads(&env, symbol_short!("max_set"));
        assert_eq!(
            max_set_payloads.len(),
            1,
            "set_pair_max_amount emits one max_set event"
        );
        let max_set: (Symbol, Symbol, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &max_set_payloads[0])
                .expect("max_set event data decodes to pair and amount");
        assert_eq!(max_set, (src.clone(), dest.clone(), 10_000i128));

        client.set_fee_recipient(&admin);
        let recip_set_payloads = event_payloads(&env, symbol_short!("recip_set"));
        assert_eq!(
            recip_set_payloads.len(),
            1,
            "set_fee_recipient emits one recip_set event"
        );
        let recip_set: Address =
            soroban_sdk::TryFromVal::try_from_val(&env, &recip_set_payloads[0])
                .expect("recip_set event data decodes to address");
        assert_eq!(recip_set, admin);

        client.unregister_pair(&src, &dest);
        let unreg_payloads = event_payloads(&env, symbol_short!("unreg"));
        assert_eq!(
            unreg_payloads.len(),
            1,
            "unregister_pair emits one unreg event"
        );
        let unreg: (Symbol, Symbol) =
            soroban_sdk::TryFromVal::try_from_val(&env, &unreg_payloads[0])
                .expect("unreg event data decodes to pair tuple");
        assert_eq!(unreg, (src, dest));
    }

    #[test]
    fn test_unregister_never_registered_pair_is_clean_noop_with_event() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");

        assert!(!client.is_pair_registered(&src, &dest));
        client.unregister_pair(&src, &dest);

        let unreg_payloads = event_payloads(&env, symbol_short!("unreg"));
        assert_eq!(
            unreg_payloads.len(),
            1,
            "no-op unregister still documents one lifecycle event"
        );
        let unreg: (Symbol, Symbol) =
            soroban_sdk::TryFromVal::try_from_val(&env, &unreg_payloads[0])
                .expect("unreg event data decodes to pair tuple");
        assert_eq!(unreg, (src, dest));
        assert!(!client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
    }

    #[test]
    fn test_reregister_after_unregister_preserves_fee_and_clears_other_config() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");

        client.register_pair(&src, &dest);
        assert_eq!(
            event_payloads(&env, symbol_short!("pair_reg")).len(),
            1,
            "initial register should emit one pair_reg event"
        );
        client.set_pair_fee_bps(&src, &dest, &42u32);
        client.unregister_pair(&src, &dest);
        assert_eq!(
            event_payloads(&env, symbol_short!("unreg")).len(),
            1,
            "single unregister should emit one unreg event"
        );

        assert!(!client.is_pair_registered(&src, &dest));
        // Fee survives unregister; min/max/liquidity are cleared by clear_pair_config.
        assert_eq!(client.get_pair_fee_bps(&src, &dest), 42);

        client.register_pair(&src, &dest);
        assert_eq!(
            event_payloads(&env, symbol_short!("pair_reg")).len(),
            1,
            "re-register should emit one pair_reg event"
        );

        assert!(client.is_pair_registered(&src, &dest));
        assert_eq!(client.get_pair_fee_bps(&src, &dest), 42);
    }

    /// Documents the current, unchanged behavior: `unregister_pair` alone
    /// leaves `PairRouteCount`, `PairVolume`, and `PairLastRouteAt` intact,
    /// so a straight unregister + re-register cycle inherits prior metrics.
    #[test]
    fn test_unregister_then_reregister_preserves_metrics_by_default() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &src, &dest, 50u32);

        env.ledger().set_timestamp(777);
        client.compute_route_fee(&src, &dest, &1_000_i128);

        assert_eq!(client.get_pair_route_count(&src, &dest), 1);
        assert_eq!(client.get_pair_volume(&src, &dest), 1_000);
        assert_eq!(client.get_pair_last_route_at(&src, &dest), Some(777));

        client.unregister_pair(&src, &dest);
        client.register_pair(&src, &dest);

        assert!(client.is_pair_registered(&src, &dest));
        assert_eq!(
            client.get_pair_route_count(&src, &dest),
            1,
            "unregister_pair must not clear PairRouteCount"
        );
        assert_eq!(
            client.get_pair_volume(&src, &dest),
            1_000,
            "unregister_pair must not clear PairVolume"
        );
        assert_eq!(
            client.get_pair_last_route_at(&src, &dest),
            Some(777),
            "unregister_pair must not clear PairLastRouteAt"
        );
    }

    /// `purge_pair_metrics` is the explicit, opt-in reset: it clears all
    /// three metrics slots and emits a `pair_mrst` event with the pair.
    #[test]
    fn test_purge_pair_metrics_resets_counters_and_emits_event() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &src, &dest, 50u32);

        env.ledger().set_timestamp(999);
        client.compute_route_fee(&src, &dest, &2_000_i128);

        assert_eq!(client.get_pair_route_count(&src, &dest), 1);
        assert_eq!(client.get_pair_volume(&src, &dest), 2_000);
        assert_eq!(client.get_pair_last_route_at(&src, &dest), Some(999));

        client.purge_pair_metrics(&src, &dest);

        // Check the emitted events immediately after the triggering call,
        // before any further client invocation can roll the host event
        // buffer over to a later call's events.
        let metr_rm_payloads = event_payloads(&env, symbol_short!("metr_rm"));
        assert_eq!(
            metr_rm_payloads.len(),
            1,
            "purge_pair_metrics emits exactly one metr_rm event"
        );
        let decoded_rm: (Symbol, Symbol, u64, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &metr_rm_payloads[0])
                .expect("metr_rm event data decodes to (pair, route_count, volume)");
        assert_eq!(
            decoded_rm,
            (src.clone(), dest.clone(), 1, 2_000),
            "metr_rm event must carry the pre-purge route count and volume"
        );

        let payloads = event_payloads(&env, symbol_short!("pair_mrst"));
        assert_eq!(
            payloads.len(),
            1,
            "purge_pair_metrics emits exactly one pair_mrst event"
        );
        let decoded: (Symbol, Symbol) = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("pair_mrst event data decodes to pair tuple");
        assert_eq!(decoded, (src.clone(), dest.clone()));

        assert_eq!(client.get_pair_route_count(&src, &dest), 0);
        assert_eq!(client.get_pair_volume(&src, &dest), 0);
        assert_eq!(client.get_pair_last_route_at(&src, &dest), None);
    }

    /// `purge_pair_metrics` does not disturb registration or live config —
    /// only the three metrics slots.
    #[test]
    fn test_purge_pair_metrics_does_not_touch_registration_or_config() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &src, &dest, 50u32);
        client.set_pair_min_amount(&src, &dest, &10i128);
        client.set_pair_max_amount(&src, &dest, &1_000i128);

        client.compute_route_fee(&src, &dest, &500_i128);
        client.purge_pair_metrics(&src, &dest);

        assert!(client.is_pair_registered(&src, &dest));
        assert_eq!(client.get_pair_fee_bps(&src, &dest), 50);
        assert_eq!(client.get_pair_min_amount(&src, &dest), 10);
        assert_eq!(client.get_pair_max_amount(&src, &dest), 1_000);
    }

    /// `purge_pair_metrics` is admin-gated like every other mutating
    /// entrypoint: a non-admin caller's `require_auth()` must fail.
    #[test]
    #[should_panic]
    fn test_purge_pair_metrics_rejects_non_admin() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let stranger = Address::generate(&env);
        let client = setup_routable_pair(&env, &src, &dest, 50u32);
        client.compute_route_fee(&src, &dest, &500_i128);

        env.mock_auths(&[soroban_sdk::testutils::MockAuth {
            address: &stranger,
            invoke: &soroban_sdk::testutils::MockAuthInvoke {
                contract: &client.address,
                fn_name: "purge_pair_metrics",
                args: (src.clone(), dest.clone()).into_val(&env),
                sub_invokes: &[],
            },
        }]);
        client.purge_pair_metrics(&src, &dest);
    }

    /// `purge_pair_metrics` emits a `metr_rm` event with the correct
    /// pre-purge route count and cumulative volume even when those values
    /// are non-trivial (multiple routes, large volume).
    #[test]
    fn test_metr_rm_event_carrying_populated_metrics() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &src, &dest, 50u32);

        // Run two routes so the counters are > 1 and the volume is large.
        env.ledger().set_timestamp(100);
        client.compute_route_fee(&src, &dest, &1_000_i128);
        env.ledger().set_timestamp(200);
        client.compute_route_fee(&src, &dest, &3_000_i128);

        assert_eq!(client.get_pair_route_count(&src, &dest), 2);
        assert_eq!(client.get_pair_volume(&src, &dest), 4_000);
        assert_eq!(client.get_pair_last_route_at(&src, &dest), Some(200));

        client.purge_pair_metrics(&src, &dest);

        // The metr_rm event must carry the *pre-purge* values.
        let metr_rm_payloads = event_payloads(&env, symbol_short!("metr_rm"));
        assert_eq!(
            metr_rm_payloads.len(),
            1,
            "purge_pair_metrics emits exactly one metr_rm event"
        );
        let decoded: (Symbol, Symbol, u64, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &metr_rm_payloads[0])
                .expect("metr_rm event data decodes");
        assert_eq!(
            decoded,
            (src.clone(), dest.clone(), 2, 4_000),
            "metr_rm payload must contain the pre-purge route count and volume"
        );

        // After the purge the counters must be zero and the slots absent.
        assert_eq!(client.get_pair_route_count(&src, &dest), 0);
        assert_eq!(client.get_pair_volume(&src, &dest), 0);
        assert_eq!(client.get_pair_last_route_at(&src, &dest), None);
    }

    /// `purge_pair_metrics` emits a `metr_rm` event even when the pair has
    /// never been routed — the payload must carry zero/default values and
    /// must not panic.
    #[test]
    fn test_metr_rm_event_with_no_recorded_metrics() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &src, &dest, 50u32);

        // Do NOT call compute_route_fee — counters are at their defaults.
        assert_eq!(client.get_pair_route_count(&src, &dest), 0);
        assert_eq!(client.get_pair_volume(&src, &dest), 0);
        assert_eq!(client.get_pair_last_route_at(&src, &dest), None);

        client.purge_pair_metrics(&src, &dest);

        // The event must still be emitted with zero values.
        let metr_rm_payloads = event_payloads(&env, symbol_short!("metr_rm"));
        assert_eq!(
            metr_rm_payloads.len(),
            1,
            "purge_pair_metrics emits metr_rm even for an unrouted pair"
        );
        let decoded: (Symbol, Symbol, u64, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &metr_rm_payloads[0])
                .expect("metr_rm event data decodes");
        assert_eq!(
            decoded,
            (src.clone(), dest.clone(), 0, 0),
            "metr_rm payload must carry zeros when no metrics existed"
        );
    }

    #[test]
    fn test_pair_limits_liquidity_and_info_round_trip() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert!(!client.is_pair_active(&symbol_short!("USDC"), &symbol_short!("EURC")));

        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &25u32);
        client.set_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &10i128);
        client.set_pair_max_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_000i128);
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500i128,
        );

        assert_eq!(
            client.get_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC")),
            10
        );
        assert_eq!(
            client.get_pair_max_amount(&symbol_short!("USDC"), &symbol_short!("EURC")),
            1_000
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            500
        );
        assert!(client.is_pair_active(&symbol_short!("USDC"), &symbol_short!("EURC")));

        let info = client.get_pair_info(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert_eq!(
            info,
            PairInfo {
                registered: true,
                fee_bps: 25,
                min_amount: 10,
                max_amount: 1_000,
                liquidity: 500,
                last_route_at: 0,
            }
        );
    }

    #[test]
    fn test_quote_route_and_compute_route_update_counters() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &100u32);

        assert_eq!(
            client.quote_route(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_000i128),
            (10, 990)
        );
        assert_eq!(client.get_total_routes_all_time(), 0);

        assert_eq!(
            client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_000i128),
            10
        );
        assert_eq!(client.get_total_routes_all_time(), 1);
        assert_eq!(
            client.get_pair_last_route_at(&symbol_short!("USDC"), &symbol_short!("EURC")),
            Some(0)
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_quote_route_rejects_zero_amount() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.quote_route(&symbol_short!("USDC"), &symbol_short!("EURC"), &0i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #5)")]
    fn test_quote_route_rejects_unregistered_pair() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.quote_route(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_000i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #10)")]
    fn test_compute_route_fee_rejects_below_minimum() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &10i128);
        client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &9i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #11)")]
    fn test_compute_route_fee_rejects_above_maximum() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_max_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &10i128);
        client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &11i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #12)")]
    fn test_compute_route_fee_rejects_insufficient_liquidity() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &10i128,
        );
        client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &11i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_set_pair_liquidity_rejects_negative_value() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &-1i128,
        );
    }

    // --- #22: scoped oracle role ---

    /// The oracle (a non-admin) can update pair liquidity.
    #[test]
    fn test_oracle_can_update_liquidity() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
        assert_eq!(client.get_oracle(), Some(oracle.clone()));
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_liquidity(
            &oracle,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &777i128,
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            777
        );
    }

    /// Admin retains the ability to update liquidity directly.
    #[test]
    fn test_admin_can_still_update_liquidity() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &10i128,
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            10
        );
    }

    /// A caller that is neither admin nor oracle is rejected with
    /// NotAuthorized (#16).
    #[test]
    #[should_panic(expected = "Error(Contract, #16)")]
    fn test_random_caller_cannot_update_liquidity() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let stranger = Address::generate(&env);
        client.set_pair_liquidity(
            &stranger,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1i128,
        );
    }

    /// The oracle role is strictly scoped: the oracle cannot set the
    /// oracle (an admin-only governance action).
    #[test]
    #[should_panic]
    fn test_oracle_cannot_call_admin_entrypoint() {
        let env = Env::default();
        let admin = Address::generate(&env);
        let oracle = Address::generate(&env);
        env.mock_all_auths();
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(&env, &contract_id);
        client.set_oracle(&oracle);
        // Oracle attempts an admin-only action (pause). Authorize only the
        // oracle so admin.require_auth() must fail.
        env.mock_auths(&[soroban_sdk::testutils::MockAuth {
            address: &oracle,
            invoke: &soroban_sdk::testutils::MockAuthInvoke {
                contract: &contract_id,
                fn_name: "pause",
                args: ().into_val(&env),
                sub_invokes: &[],
            },
        }]);
        client.pause();
    }

    // --- oracle revocation (remove_oracle) ---

    /// End-to-end revocation flow: the oracle can update liquidity while
    /// configured, and is fully locked out after `remove_oracle`.
    #[test]
    fn test_oracle_can_update_before_removal_but_not_after() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));

        // Before removal the oracle drives the liquidity feed.
        client.set_pair_liquidity(
            &oracle,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500i128,
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            500
        );

        client.remove_oracle();
        assert_eq!(client.get_oracle(), None);

        // After removal the same key is rejected with NotAuthorized (#15).
        let err = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            client.set_pair_liquidity(
                &oracle,
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &999i128,
            )
        }));
        assert!(err.is_err());
        // The blocked call left the last accepted value untouched.
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            500
        );
    }

    /// A revoked oracle is rejected with exactly NotAuthorized (#15) —
    /// the same code any other stranger gets.
    #[test]
    #[should_panic(expected = "Error(Contract, #16)")]
    fn test_removed_oracle_rejected_with_not_authorized() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.remove_oracle();
        client.set_pair_liquidity(
            &oracle,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1i128,
        );
    }

    /// The admin keeps the liquidity feed after the oracle is revoked:
    /// the dual-auth check degrades to admin-only when the slot is absent.
    #[test]
    fn test_admin_can_still_update_liquidity_after_removal() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.remove_oracle();
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &42i128,
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            42
        );
    }

    /// Removal is idempotent: removing when a previous removal (or nothing)
    /// left the slot empty is a clean no-op and the getter stays None.
    #[test]
    fn test_remove_oracle_is_idempotent() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        // Remove when never set — clean no-op.
        assert_eq!(client.get_oracle(), None);
        client.remove_oracle();
        assert_eq!(client.get_oracle(), None);
        // Set, remove, then remove again — second removal is also a no-op.
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
        client.remove_oracle();
        client.remove_oracle();
        assert_eq!(client.get_oracle(), None);
    }

    /// `remove_oracle` emits one `orac_rm` event per call, carrying the
    /// previously configured oracle (`None` on a no-op removal).
    #[test]
    fn test_remove_oracle_emits_orac_rm_event() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
        client.remove_oracle();
        let payloads = event_payloads(&env, symbol_short!("orac_rm"));
        assert_eq!(payloads.len(), 1, "remove_oracle emits one orac_rm event");
        let removed: Option<Address> = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("orac_rm event data decodes to Option<Address>");
        assert_eq!(removed, Some(oracle));
    }

    /// A no-op removal still emits `orac_rm`, with `None` as the payload,
    /// so indexers observe every revocation attempt.
    #[test]
    fn test_remove_oracle_noop_emits_event_with_none() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.remove_oracle();
        let payloads = event_payloads(&env, symbol_short!("orac_rm"));
        assert_eq!(payloads.len(), 1);
        let removed: Option<Address> = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("orac_rm event data decodes to Option<Address>");
        assert_eq!(removed, None);
    }

    /// After removal the oracle can be set again (rotation to a fresh key
    /// once the incident is resolved).
    #[test]
    fn test_oracle_can_be_reconfigured_after_removal() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let compromised = Address::generate(&env);
        client.set_oracle(&compromised);
        client.remove_oracle();
        let fresh = Address::generate(&env);
        client.set_oracle(&fresh);
        assert_eq!(client.get_oracle(), Some(fresh.clone()));
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_liquidity(
            &fresh,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &7i128,
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            7
        );
    }

    /// `remove_oracle` is admin-gated: a caller without the admin's auth
    /// is rejected, so a compromised oracle cannot un-revoke itself or
    /// grief the admin by clearing the slot.
    #[test]
    #[should_panic]
    fn test_remove_oracle_requires_admin_auth() {
        let env = Env::default();
        let admin = Address::generate(&env);
        let oracle = Address::generate(&env);
        env.mock_all_auths();
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(&env, &contract_id);
        client.set_oracle(&oracle);
        // Authorize only the oracle so admin.require_auth() must fail.
        env.mock_auths(&[soroban_sdk::testutils::MockAuth {
            address: &oracle,
            invoke: &soroban_sdk::testutils::MockAuthInvoke {
                contract: &contract_id,
                fn_name: "remove_oracle",
                args: ().into_val(&env),
                sub_invokes: &[],
            },
        }]);
        client.remove_oracle();
    }

    /// Missing-admin path reuses NotInitialized (#2), like every other
    /// admin-gated entrypoint.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_remove_oracle_panics_when_uninitialized() {
        let env = Env::default();
        let (client, _admin, contract_id) = setup_initialized_with_id(&env);
        env.as_contract(&contract_id, || {
            env.storage().instance().remove(&DataKey::Admin);
        });
        client.remove_oracle();
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_set_pair_max_amount_rejects_zero() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.set_pair_max_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &0i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_set_pair_min_amount_rejects_negative_value() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        client.set_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &-1i128);
    }

    #[test]
    fn test_set_pair_min_amount_allows_zero_boundary() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_min_amount(&s, &d, &0i128);
        assert_eq!(client.get_pair_min_amount(&s, &d), 0);
    }

    #[test]
    fn test_set_pair_fee_bps_allows_zero_boundary() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &0u32);
        assert_eq!(client.get_pair_fee_bps(&s, &d), 0);
    }

    #[test]
    fn test_set_pair_fee_bps_allows_at_exact_max() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &MAX_FEE_BPS);
        assert_eq!(client.get_pair_fee_bps(&s, &d), MAX_FEE_BPS);
    }

    #[test]
    fn test_set_pair_cooldown_allows_at_exact_max() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_cooldown(&s, &d, &MAX_COOLDOWN_SECS);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #20)")]
    fn test_set_pair_cooldown_rejects_over_max() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_cooldown(&s, &d, &(MAX_COOLDOWN_SECS + 1));
    }

    // --- compute_route_fee side-effect tests ---

    /// Register `(source, destination)` and set its fee so that
    /// `compute_route_fee` clears every guard (pair registered, fee set,
    /// min/max unset → permissive, liquidity unset → defaults to i128::MAX).
    /// Returns the live client for chaining assertions.
    fn setup_routable_pair<'a>(
        env: &'a Env,
        source: &Symbol,
        destination: &Symbol,
        fee_bps: u32,
    ) -> StableRouteRouterClient<'a> {
        let (client, _admin) = setup_initialized(env);
        client.register_pair(source, destination);
        client.set_pair_fee_bps(source, destination, &fee_bps);
        client
    }

    /// Scan the test-host's current contract events and return the decoded
    /// `data` payloads of every event whose single topic matches `topic`.
    pub(crate) fn event_payloads(env: &Env, topic: Symbol) -> std::vec::Vec<soroban_sdk::Val> {
        use soroban_sdk::{
            xdr::{ContractEventBody, ScVal},
            TryFromVal, Val,
        };
        env.events()
            .all()
            .events()
            .iter()
            .filter_map(|event| {
                let ContractEventBody::V0(body) = &event.body;
                let topics = body.topics.as_slice();
                if topics.len() != 1 {
                    return None;
                }
                let ScVal::Symbol(raw_topic) = &topics[0] else {
                    return None;
                };
                let actual_topic =
                    Symbol::try_from_val(env, raw_topic).expect("event topic decodes to Symbol");
                if actual_topic == topic {
                    Some(Val::try_from_val(env, &body.data).expect("event data decodes to Val"))
                } else {
                    None
                }
            })
            .collect()
    }

    fn route_event_payloads(env: &Env) -> std::vec::Vec<soroban_sdk::Val> {
        event_payloads(env, symbol_short!("route"))
    }

    #[test]
    fn test_compute_route_fee_emits_route_event_with_payload() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let amount = 1_000_000_i128;
        let client = setup_routable_pair(&env, &src, &dest, 50u32);

        client.compute_route_fee(&src, &dest, &amount);

        // Exactly one `route` event, carrying (source, destination, amount).
        let payloads = route_event_payloads(&env);
        assert_eq!(payloads.len(), 1, "exactly one route event expected");
        let decoded: (Symbol, Symbol, i128) =
            soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
                .expect("route data decodes to (Symbol, Symbol, i128)");
        assert_eq!(decoded, (src, dest, amount));
    }

    #[test]
    fn test_compute_route_fee_stamps_pair_last_route_at() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &src, &dest, 50u32);

        // None before any route touches the pair.
        assert_eq!(client.get_pair_last_route_at(&src, &dest), None);

        env.ledger().set_timestamp(12345);
        client.compute_route_fee(&src, &dest, &1_000_i128);

        assert_eq!(client.get_pair_last_route_at(&src, &dest), Some(12345));
    }

    #[test]
    fn test_compute_route_fee_allows_at_exact_cooldown_boundary() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");

        let client = setup_routable_pair(&env, &src, &dest, 50);

        client.set_pair_cooldown(&src, &dest, &60);

        // First successful route at timestamp 100.
        env.ledger().set_timestamp(100);
        client.compute_route_fee(&src, &dest, &1_000_i128);

        // Exactly last + cooldown (100 + 60) must be allowed.
        env.ledger().set_timestamp(160);
        client.compute_route_fee(&src, &dest, &1_000_i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #17)")]
    fn test_compute_route_fee_rejects_before_cooldown_boundary() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");

        let client = setup_routable_pair(&env, &src, &dest, 50);

        client.set_pair_cooldown(&src, &dest, &60);

        // First successful route at timestamp 100.
        env.ledger().set_timestamp(100);
        client.compute_route_fee(&src, &dest, &1_000_i128);

        // One second before the boundary must still be rejected.
        env.ledger().set_timestamp(159);
        client.compute_route_fee(&src, &dest, &1_000_i128);
    }

    #[test]
    fn test_compute_route_fee_allows_after_cooldown_boundary() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");

        let client = setup_routable_pair(&env, &src, &dest, 50);

        client.set_pair_cooldown(&src, &dest, &60);

        // First successful route at timestamp 100.
        env.ledger().set_timestamp(100);
        client.compute_route_fee(&src, &dest, &1_000_i128);

        // After the boundary must also be allowed.
        env.ledger().set_timestamp(161);
        client.compute_route_fee(&src, &dest, &1_000_i128);
    }
    #[test]
    fn test_compute_route_fee_counter_is_global_across_pairs() {
        let env = Env::default();
        // Pair A.
        let a_src = symbol_short!("USDC");
        let a_dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &a_src, &a_dest, 50u32);
        // Pair B (different pair) registered on the same contract instance.
        let b_src = symbol_short!("XLM");
        let b_dest = symbol_short!("USDC");
        client.register_pair(&b_src, &b_dest);
        client.set_pair_fee_bps(&b_src, &b_dest, &50u32);

        assert_eq!(client.get_total_routes_all_time(), 0);
        client.compute_route_fee(&a_src, &a_dest, &1_000_i128);
        assert_eq!(client.get_total_routes_all_time(), 1);
        client.compute_route_fee(&b_src, &b_dest, &1_000_i128);
        // The lifetime counter is protocol-wide, not per-pair.
        assert_eq!(client.get_total_routes_all_time(), 2);
    }

    #[test]
    fn test_quote_route_does_not_mutate_counter_or_emit_route_event() {
        let env = Env::default();
        let src = symbol_short!("USDC");
        let dest = symbol_short!("EURC");
        let client = setup_routable_pair(&env, &src, &dest, 100u32);

        let routes_before = client.get_total_routes_all_time();
        let route_events_before = route_event_payloads(&env).len();

        let (fee, net) = client.quote_route(&src, &dest, &1_000_i128);
        assert_eq!((fee, net), (10, 990));

        // quote_route is read-only: counter unchanged, no new `route` event.
        assert_eq!(client.get_total_routes_all_time(), routes_before);
        assert_eq!(route_event_payloads(&env).len(), route_events_before);
    }

    // --- require_admin helper contract tests ---

    /// After the refactor, every admin-gated entrypoint must still reject a
    /// non-admin caller. We test `pause` as a representative; the helper is
    /// shared, so this covers all entrypoints structurally.
    #[test]
    #[should_panic]
    fn test_require_admin_rejects_unauthorized_caller() {
        let env = Env::default();
        let admin = Address::generate(&env);
        let attacker = Address::generate(&env);
        // Deploy with the real admin set atomically by the constructor.
        env.mock_all_auths();
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(&env, &contract_id);
        // Now call pause as the attacker — only the attacker is authorized,
        // so admin.require_auth() inside pause must fail.
        env.mock_auths(&[soroban_sdk::testutils::MockAuth {
            address: &attacker,
            invoke: &soroban_sdk::testutils::MockAuthInvoke {
                contract: &contract_id,
                fn_name: "pause",
                args: ().into_val(&env),
                sub_invokes: &[],
            },
        }]);
        client.pause(); // must panic: admin.require_auth() fails for attacker
    }

    // --- #20: init front-running hardening ---

    /// Deploy must be observable from the raw event buffer: a fresh
    /// `register(StableRouteRouter, (admin,))` should emit exactly one
    /// `init` event carrying the constructor's admin, and the admin must be
    /// readable immediately without any legacy `init` call.
    #[test]
    fn test_constructor_emits_single_init_event_with_admin_payload() {
        use soroban_sdk::{
            xdr::{ContractEventBody, ScVal},
            TryFromVal,
        };

        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(&env, &contract_id);

        let all_events = env.events().all();
        let events = all_events.events();
        assert_eq!(events.len(), 1, "constructor emits exactly one event");

        let ContractEventBody::V0(body) = &events[0].body;
        let topics = body.topics.as_slice();
        assert_eq!(topics.len(), 1, "init event has a single topic");

        let ScVal::Symbol(raw_topic) = &topics[0] else {
            panic!("constructor event topic decodes to a symbol");
        };
        let topic = Symbol::try_from_val(&env, raw_topic)
            .expect("constructor event topic decodes to Symbol");
        assert_eq!(topic, symbol_short!("init"));

        let init_admin: Address =
            TryFromVal::try_from_val(&env, &body.data).expect("init event data decodes to admin");
        assert_eq!(init_admin, admin);
        assert_eq!(client.get_admin(), Some(admin));
    }

    /// Even the original constructor admin cannot re-run legacy `init`
    /// after deploy; the constructor/init split is permanent and `init`
    /// must always preserve `AlreadyInitialized` (#1).
    #[test]
    #[should_panic(expected = "Error(Contract, #1)")]
    fn test_post_deploy_init_rejects_original_admin() {
        let env = Env::default();
        let (client, admin) = setup_initialized(&env);
        client.init(&admin);
    }

    /// Any other address is equally unable to seize the router with legacy
    /// `init`; once deployed, admin control can only change through the
    /// governed transfer flow.
    #[test]
    #[should_panic(expected = "Error(Contract, #1)")]
    fn test_post_deploy_init_rejects_different_address() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        let attacker = Address::generate(&env);
        client.init(&attacker);
    }

    // --- version surface stability ---

    /// `version()` is the fixed contract identity tag and must be entirely
    /// independent of `get_schema_version()`: migrating the storage schema
    /// from v1 to v2 advances the schema number but never the version tag.
    #[test]
    fn test_version_is_independent_of_schema_version() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        // Version tag and schema number start at known, distinct values.
        assert_eq!(client.version(), symbol_short!("ROUTER_V2"));
        assert_eq!(client.get_schema_version(), 1);

        client.migrate_v1_to_v2();

        // Schema advanced 1 -> 2, but the version tag is unchanged.
        assert_eq!(client.get_schema_version(), 2);
        assert_eq!(client.version(), symbol_short!("ROUTER_V2"));
    }

    /// The constructor requires an admin argument, so tests cannot create the
    /// old deployed-but-uninitialized state with zero constructor args.
    #[test]
    #[should_panic]
    fn test_constructor_rejects_missing_admin_arg() {
        let env = Env::default();
        let _client = setup_uninitialized(&env);
    }

    #[test]
    fn test_set_timelock_emits_event_on_change() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);

        // 1. Zero-to-nonzero transition: old timelock is 0, new value is nonzero, assert event payload reflects this
        client.set_timelock(&100u64);
        let payloads = event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(payloads.len(), 1);
        let decoded: (u64, u64) = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("tlock_set event data decodes to (u64, u64)");
        assert_eq!(decoded, (0, 100));

        // 2. Normal change (nonzero-to-nonzero transition)
        client.set_timelock(&200u64);
        let payloads2 = event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(payloads2.len(), 1);
        let decoded2: (u64, u64) = soroban_sdk::TryFromVal::try_from_val(&env, &payloads2[0])
            .expect("tlock_set event data decodes to (u64, u64)");
        assert_eq!(decoded2, (100, 200));

        // 3. Nonzero-to-zero transition: old timelock is nonzero, new value is 0, assert event payload reflects this
        client.set_timelock(&0u64);
        let payloads3 = event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(payloads3.len(), 1);
        let decoded3: (u64, u64) = soroban_sdk::TryFromVal::try_from_val(&env, &payloads3[0])
            .expect("tlock_set event data decodes to (u64, u64)");
        assert_eq!(decoded3, (200, 0));
    }

    #[test]
    fn test_set_timelock_unauthorized_emits_no_event() {
        let env = Env::default();
        let admin = Address::generate(&env);
        let contract_id = Address::generate(&env);
        env.mock_auths(&[soroban_sdk::testutils::MockAuth {
            address: &admin,
            invoke: &soroban_sdk::testutils::MockAuthInvoke {
                contract: &contract_id,
                fn_name: "__constructor",
                args: (admin.clone(),).into_val(&env),
                sub_invokes: &[],
            },
        }]);
        env.register_at(&contract_id, StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(&env, &contract_id);

        // We make an unauthorized call (no mock_all_auths called, and not signed by admin).
        let res = client.try_set_timelock(&100u64);
        assert!(res.is_err(), "Expected error/panic due to unauthorized call");

        let payloads = event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(payloads.len(), 0, "No event should be emitted on failed auth");
    }
}

/// Issue #14 — pause/unpause gating across state-changing entrypoints.
/// Covers the default-false flag, event emission, the `ContractPaused` (#9)
/// rejection on gated entrypoints, recovery after unpause, and idempotency.
#[cfg(test)]
mod pause_gating {
    use super::*;
    use soroban_sdk::{
        symbol_short,
        testutils::{Address as _, Events},
    };

    /// Deploy a router with all auths mocked.
    fn setup(env: &Env) -> StableRouteRouterClient<'_> {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(env, &id);
        client
    }

    #[test]
    fn test_is_paused_defaults_false_and_toggles() {
        let env = Env::default();
        let client = setup(&env);
        assert!(!client.is_paused());
        client.pause();
        assert!(client.is_paused());
        client.unpause();
        assert!(!client.is_paused());
    }

    #[test]
    fn test_pause_emits_event() {
        let env = Env::default();
        let client = setup(&env);
        client.pause();
        // pause() publishes a `paused` event; assert one was emitted.
        assert!(!env.events().all().events().is_empty());
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_register_pair_rejected_while_paused() {
        let env = Env::default();
        let client = setup(&env);
        client.pause();
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_set_pair_fee_bps_rejected_while_paused() {
        let env = Env::default();
        let client = setup(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.pause();
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &10u32);
    }

    #[test]
    fn test_gated_entrypoint_succeeds_after_unpause() {
        let env = Env::default();
        let client = setup(&env);
        client.pause();
        client.unpause();
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert!(client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
    }

    #[test]
    fn test_double_pause_and_double_unpause_idempotent() {
        let env = Env::default();
        let client = setup(&env);
        client.pause();
        client.pause();
        assert!(client.is_paused());
        client.unpause();
        client.unpause();
        assert!(!client.is_paused());
    }
}

/// Issue #15 — min/max amount and liquidity guards in `compute_route_fee`.
/// Covers at-bound acceptance, below-min (#10), above-max (#11), and
/// over-liquidity (#12) rejection, the unset sentinels, and negative
/// liquidity rejection (#6).
#[cfg(test)]
mod bounds_liquidity {
    use super::*;
    use soroban_sdk::{symbol_short, testutils::Address as _};

    /// Register a pair with all auths mocked; returns the client and pair ids.
    fn setup_pair(env: &Env) -> (StableRouteRouterClient<'_>, Address, Symbol, Symbol) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &id);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        (client, admin, s, d)
    }

    #[test]
    fn test_min_amount_at_bound_is_accepted() {
        let env = Env::default();
        let (client, _admin, s, d) = setup_pair(&env);
        client.set_pair_min_amount(&s, &d, &100i128);
        assert_eq!(client.get_pair_min_amount(&s, &d), 100);
        // Exactly at the floor is accepted (fee 0, no bps configured).
        assert_eq!(client.compute_route_fee(&s, &d, &100i128), 0);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #10)")]
    fn test_below_min_rejected() {
        let env = Env::default();
        let (client, _admin, s, d) = setup_pair(&env);
        client.set_pair_min_amount(&s, &d, &100i128);
        client.compute_route_fee(&s, &d, &99i128);
    }

    #[test]
    fn test_max_amount_at_bound_is_accepted() {
        let env = Env::default();
        let (client, _admin, s, d) = setup_pair(&env);
        client.set_pair_max_amount(&s, &d, &1_000i128);
        assert_eq!(client.get_pair_max_amount(&s, &d), 1_000);
        assert_eq!(client.compute_route_fee(&s, &d, &1_000i128), 0);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #11)")]
    fn test_above_max_rejected() {
        let env = Env::default();
        let (client, _admin, s, d) = setup_pair(&env);
        client.set_pair_max_amount(&s, &d, &1_000i128);
        client.compute_route_fee(&s, &d, &1_001i128);
    }

    #[test]
    fn test_liquidity_at_bound_is_accepted() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);
        client.set_pair_liquidity(&admin, &s, &d, &500i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), 500);
        // amount == reported liquidity is allowed.
        assert_eq!(client.compute_route_fee(&s, &d, &500i128), 0);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #12)")]
    fn test_above_liquidity_rejected() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);
        client.set_pair_liquidity(&admin, &s, &d, &500i128);
        client.compute_route_fee(&s, &d, &501i128);
    }

    #[test]
    fn test_unset_bounds_behave_as_unbounded() {
        let env = Env::default();
        let (client, _admin, s, d) = setup_pair(&env);
        // Defaults: min 0, max i128::MAX, liquidity unset => unbounded.
        assert_eq!(client.get_pair_min_amount(&s, &d), 0);
        assert_eq!(client.get_pair_max_amount(&s, &d), i128::MAX);
        assert_eq!(client.get_pair_liquidity(&s, &d), 0);
        assert_eq!(client.compute_route_fee(&s, &d, &1i128), 0);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_set_pair_liquidity_rejects_negative() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);
        client.set_pair_liquidity(&admin, &s, &d, &-1i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #12)")]
    fn test_explicit_zero_liquidity_rejected_in_compute_route_fee() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);
        client.set_pair_liquidity(&admin, &s, &d, &0i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), 0);
        client.compute_route_fee(&s, &d, &1i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #12)")]
    fn test_explicit_zero_liquidity_rejected_in_quote_route() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);
        client.set_pair_liquidity(&admin, &s, &d, &0i128);
        client.quote_route(&s, &d, &1i128);
    }

    #[test]
    fn test_absent_liquidity_remains_unbounded_in_compute_route_fee() {
        let env = Env::default();
        let (client, _admin, s, d) = setup_pair(&env);
        // Explicitly do NOT set liquidity.
        assert_eq!(client.get_pair_liquidity(&s, &d), 0);
        // Unset slot behaves as unbounded.
        assert_eq!(client.compute_route_fee(&s, &d, &1i128), 0);
    }

    #[test]
    fn test_top_up_pair_liquidity_success() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);

        // Initial liquidity should be 0 when get_pair_liquidity is called
        assert_eq!(client.get_pair_liquidity(&s, &d), 0);

        // Top up by 500
        client.top_up_pair_liquidity(&admin, &s, &d, &500i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), 500);

        // Top up by another 300
        client.top_up_pair_liquidity(&admin, &s, &d, &300i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), 800);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #16)")] // RouterError::NotAuthorized is 16
    fn test_top_up_pair_liquidity_unauthorized() {
        let env = Env::default();
        let (client, _admin, s, d) = setup_pair(&env);

        let unauthorized_caller = Address::generate(&env);
        client.top_up_pair_liquidity(&unauthorized_caller, &s, &d, &100i128);
    }

    #[test]
    fn test_top_up_pair_liquidity_authorized_by_oracle() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);

        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);

        // Oracle top up should succeed
        client.top_up_pair_liquidity(&oracle, &s, &d, &500i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), 500);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")] // AmountMustBePositive is 6
    fn test_top_up_pair_liquidity_rejects_zero() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);
        client.top_up_pair_liquidity(&admin, &s, &d, &0i128);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_top_up_pair_liquidity_rejects_negative() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);
        client.top_up_pair_liquidity(&admin, &s, &d, &-100i128);
    }

    #[test]
    fn test_top_up_pair_liquidity_sentinel_preservation() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);

        // Set to i128::MAX
        client.set_pair_liquidity(&admin, &s, &d, &i128::MAX);
        assert_eq!(client.get_pair_liquidity(&s, &d), i128::MAX);

        // Top up should keep it at i128::MAX
        client.top_up_pair_liquidity(&admin, &s, &d, &100i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), i128::MAX);
    }

    #[test]
    fn test_top_up_after_debit() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);

        // Set initial liquidity to 1000
        client.set_pair_liquidity(&admin, &s, &d, &1000i128);

        // Debit 400 by running a route (compute_route_fee debits liquidity by amount)
        client.compute_route_fee(&s, &d, &400i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), 600);

        // Top up by 200
        client.top_up_pair_liquidity(&admin, &s, &d, &200i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), 800);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #5)")] // RouterError::PairNotRegistered is 5
    fn test_top_up_pair_liquidity_unregistered_pair() {
        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(&env, &id);
        let s = symbol_short!("USDC");
        let d = symbol_short!("EURC");
        client.top_up_pair_liquidity(&admin, &s, &d, &100i128);
    }

    #[test]
    fn test_top_up_pair_liquidity_overflow_saturation() {
        let env = Env::default();
        let (client, admin, s, d) = setup_pair(&env);

        // Set to i128::MAX - 50
        client.set_pair_liquidity(&admin, &s, &d, &(i128::MAX - 50));
        assert_eq!(client.get_pair_liquidity(&s, &d), i128::MAX - 50);

        // Top up by 100, which overflows and saturates to i128::MAX
        client.top_up_pair_liquidity(&admin, &s, &d, &100i128);
        assert_eq!(client.get_pair_liquidity(&s, &d), i128::MAX);
    }
}

/// Issue #16 — fee-computation arithmetic at extreme amounts.
/// Exercises the `checked_mul` overflow path (returns 0), truncating integer
/// division, quote/compute parity, and the saturating route counter.
#[cfg(test)]
mod fee_arithmetic {
    use super::*;
    use soroban_sdk::{symbol_short, testutils::Address as _};

    /// Register a pair with wide bounds and liquidity so the boundary guards
    /// never pre-empt the arithmetic path under test.
    fn setup_pair(env: &Env) -> (StableRouteRouterClient<'_>, Symbol, Symbol) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &id);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_max_amount(&s, &d, &i128::MAX);
        client.set_pair_liquidity(&admin, &s, &d, &i128::MAX);
        (client, s, d)
    }

    #[test]
    fn test_overflow_path_returns_zero() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_pair_fee_bps(&s, &d, &2u32);
        // 2 * i128::MAX overflows checked_mul, so the fee defaults to 0
        // instead of panicking.
        assert_eq!(client.compute_route_fee(&s, &d, &i128::MAX), 0);
    }

    #[test]
    fn test_truncating_division_rounds_toward_zero() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_pair_fee_bps(&s, &d, &3u32);
        // 12_345 * 3 / 10_000 = 3.7035 -> truncates to 3.
        assert_eq!(client.compute_route_fee(&s, &d, &12_345i128), 3);
    }

    #[test]
    fn test_quote_matches_compute_fee() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_pair_fee_bps(&s, &d, &50u32);
        let (qfee, qnet) = client.quote_route(&s, &d, &1_000_000i128);
        let cfee = client.compute_route_fee(&s, &d, &1_000_000i128);
        assert_eq!(qfee, cfee);
        assert_eq!(qnet, 1_000_000 - qfee);
    }

    #[test]
    fn test_route_counter_increments_and_never_panics() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_pair_fee_bps(&s, &d, &10u32);
        assert_eq!(client.get_total_routes_all_time(), 0);
        client.compute_route_fee(&s, &d, &1_000i128);
        assert_eq!(client.get_total_routes_all_time(), 1);
        client.compute_route_fee(&s, &d, &1_000i128);
        assert_eq!(client.get_total_routes_all_time(), 2);
    }

    #[test]
    fn test_quote_route_net_equals_amount_minus_fee_at_zero_fee() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        // fee_bps defaults to 0 — no set_pair_fee_bps call.
        let (fee, net) = client.quote_route(&s, &d, &1_000_000i128);
        assert_eq!(fee, 0);
        assert_eq!(net, 1_000_000 - fee);
    }

    #[test]
    fn test_quote_route_net_equals_amount_minus_fee_at_max_fee_bps() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_pair_fee_bps(&s, &d, &MAX_FEE_BPS);
        let (fee, net) = client.quote_route(&s, &d, &1_000_000i128);
        assert_eq!(net, 1_000_000 - fee);
    }

    #[test]
    fn test_quote_and_compute_agree_across_fee_tiers() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        for fee_bps in [0u32, 100u32, MAX_FEE_BPS] {
            client.set_pair_fee_bps(&s, &d, &fee_bps);
            let (qfee, qnet) = client.quote_route(&s, &d, &1_000_000i128);
            let cfee = client.compute_route_fee(&s, &d, &1_000_000i128);
            assert_eq!(qfee, cfee, "fee mismatch at fee_bps={fee_bps}");
            assert_eq!(qnet, 1_000_000 - qfee, "net mismatch at fee_bps={fee_bps}");
        }
    }
}

/// Issue #17 — schema migration path and `get_schema_version` defaults.
/// Covers the default-of-1, the v1->v2 stamp, the double-migration guard
/// (#13), and the admin-auth requirement.
#[cfg(test)]
mod migration {
    use super::*;
    use soroban_sdk::testutils::{Address as _, MockAuth, MockAuthInvoke};
    use soroban_sdk::IntoVal;

    fn setup(env: &Env) -> StableRouteRouterClient<'_> {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(env, &id);
        client
    }

    #[test]
    fn test_schema_version_defaults_to_one() {
        let env = Env::default();
        let client = setup(&env);
        assert_eq!(client.get_schema_version(), 1);
    }

    #[test]
    fn test_migrate_advances_to_two() {
        let env = Env::default();
        let client = setup(&env);
        client.migrate_v1_to_v2();
        assert_eq!(client.get_schema_version(), 2);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #13)")]
    fn test_double_migrate_rejected() {
        let env = Env::default();
        let client = setup(&env);
        client.migrate_v1_to_v2();
        client.migrate_v1_to_v2();
    }

    #[test]
    #[should_panic]
    fn test_migrate_requires_admin_auth() {
        let env = Env::default();
        let admin = Address::generate(&env);
        let id = Address::generate(&env);
        env.mock_auths(&[MockAuth {
            address: &admin,
            invoke: &MockAuthInvoke {
                contract: &id,
                fn_name: "__constructor",
                args: (admin.clone(),).into_val(&env),
                sub_invokes: &[],
            },
        }]);
        env.register_at(&id, StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(&env, &id);
        client.migrate_v1_to_v2();
    }
}

/// Issue #18 — aggregate read surface: `get_pair_info` defaults/values,
/// `is_pair_active`, `quote_route` non-mutation + parity, and
/// `get_pair_last_route_at` before/after a route.
#[cfg(test)]
mod read_surface {
    use super::*;
    use soroban_sdk::{
        symbol_short,
        testutils::{Address as _, Ledger},
    };

    fn setup(env: &Env) -> (StableRouteRouterClient<'_>, Address) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &id);
        (client, admin)
    }

    #[test]
    fn test_pair_info_defaults_for_unconfigured_pair() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let info = client.get_pair_info(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert_eq!(
            info,
            PairInfo {
                registered: false,
                fee_bps: 0,
                min_amount: 0,
                max_amount: i128::MAX,
                liquidity: 0,
                last_route_at: 0,
            }
        );
    }

    #[test]
    fn test_pair_info_reflects_bare_registration_only() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        let info = client.get_pair_info(&s, &d);
        assert_eq!(
            info,
            PairInfo {
                registered: true,
                fee_bps: 0,
                min_amount: 0,
                max_amount: i128::MAX,
                liquidity: 0,
                last_route_at: 0,
            }
        );
    }

    #[test]
    fn test_pair_info_reflects_configuration() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &25u32);
        client.set_pair_min_amount(&s, &d, &10i128);
        client.set_pair_max_amount(&s, &d, &1_000i128);
        let admin = client.get_admin().expect("constructor stores admin");
        client.set_pair_liquidity(&admin, &s, &d, &500i128);
        let info = client.get_pair_info(&s, &d);
        assert!(info.registered);
        assert_eq!(info.fee_bps, 25);
        assert_eq!(info.min_amount, 10);
        assert_eq!(info.max_amount, 1_000);
        assert_eq!(info.liquidity, 500);
    }

    #[test]
    fn test_is_pair_active_requires_registration_and_liquidity() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        assert!(!client.is_pair_active(&s, &d));
        client.register_pair(&s, &d);
        // Registered but zero liquidity is still inactive.
        assert!(!client.is_pair_active(&s, &d));
        let admin = client.get_admin().expect("constructor stores admin");
        client.set_pair_liquidity(&admin, &s, &d, &1i128);
        assert!(client.is_pair_active(&s, &d));
    }

    #[test]
    fn test_quote_route_is_non_mutating_and_matches_compute() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &100u32);
        let (qfee, _net) = client.quote_route(&s, &d, &1_000i128);
        // Quote leaves the counter and timestamp untouched.
        assert_eq!(client.get_total_routes_all_time(), 0);
        assert_eq!(client.get_pair_last_route_at(&s, &d), None);
        // And reports the same fee compute_route_fee would.
        assert_eq!(qfee, client.compute_route_fee(&s, &d, &1_000i128));
    }

    #[test]
    fn test_last_route_at_none_before_some_after() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        env.ledger().set_timestamp(424_242);
        assert_eq!(client.get_pair_last_route_at(&s, &d), None);
        client.compute_route_fee(&s, &d, &1_000i128);
        assert_eq!(client.get_pair_last_route_at(&s, &d), Some(424_242));
    }

    // --- get_pair_info_ext ---

    #[test]
    fn test_pair_info_ext_defaults_for_unconfigured_pair() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        let ext = client.get_pair_info_ext(&s, &d);
        assert_eq!(
            ext,
            PairInfoExt {
                registered: false,
                fee_bps: 0,
                min_amount: 0,
                max_amount: i128::MAX,
                liquidity: 0,
                last_route_at: 0,
                cooldown_secs: 0,
                route_count: 0,
                volume: 0,
            }
        );
        // Sanity check: individual getters agree.
        assert_eq!(ext.registered, client.is_pair_registered(&s, &d));
        assert_eq!(ext.fee_bps, client.get_pair_fee_bps(&s, &d));
        assert_eq!(ext.min_amount, client.get_pair_min_amount(&s, &d));
        assert_eq!(ext.max_amount, client.get_pair_max_amount(&s, &d));
        assert_eq!(ext.liquidity, client.get_pair_liquidity(&s, &d));
        assert_eq!(ext.cooldown_secs, client.get_pair_cooldown(&s, &d));
        assert_eq!(ext.route_count, client.get_pair_route_count(&s, &d));
        assert_eq!(ext.volume, client.get_pair_volume(&s, &d));
    }

    /// Sentinel semantics: `i128::MAX` means "unbounded" for
    /// [`DataKey::PairMaxAmount`] and for liquidity inside
    /// `compute_route_fee`. When absent, the max-amount ceiling is
    /// effectively `i128::MAX` (no ceiling), so any amount passes the
    /// upper bound check, and the liquidity guard treats an unset
    /// `PairLiquidity` as unbounded — any amount can pass through.
    ///
    /// This test verifies that `read_pair_max` returns `i128::MAX` when
    /// absent, and that `compute_route_fee` accepts a near-max amount
    /// through an unconfigured registered pair (implicitly proving the
    /// `i128::MAX` sentinel acts as unbounded for both the max guard and
    /// the liquidity guard). It also asserts that once explicit finite
    /// liquidity is configured the [`RouterError::InsufficientLiquidity`]
    /// guard does fire, distinguishing the "unbounded" sentinel from
    /// genuine finite liquidity.
    #[test]
    fn test_i128_max_sentinel_means_unbounded() {
        let env = Env::default();
        let (client, admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));

        // 1) Read helpers return the documented sentinels when absent.
        assert_eq!(
            client.get_pair_max_amount(&s, &d),
            i128::MAX,
            "absent PairMaxAmount must default to i128::MAX (unbounded)"
        );
        assert_eq!(
            client.get_pair_min_amount(&s, &d),
            0,
            "absent PairMinAmount must default to 0 (no floor)"
        );
        assert_eq!(
            client.get_pair_liquidity(&s, &d),
            0,
            "absent PairLiquidity must default to 0 (no configured liquidity)"
        );
        assert_eq!(
            client.get_pair_fee_bps(&s, &d),
            0,
            "absent PairFeeBps must default to 0 (free)"
        );
        assert_eq!(
            client.get_pair_cooldown(&s, &d),
            0,
            "absent PairCooldown must default to 0 (disabled)"
        );

        // 2) Register the pair and prove `i128::MAX` acts as unbounded
        //    inside `compute_route_fee`.
        client.register_pair(&s, &d);

        // A route with a very large amount must succeed because both
        // max_amount (unset → i128::MAX) and liquidity (unset →
        // i128::MAX inside compute_route_fee) are unbounded.
        let large = i128::MAX - 1;
        let fee = client.compute_route_fee(&s, &d, &large);
        // With 0 bps the fee is zero; what matters is no panic.
        assert_eq!(fee, 0, "fee must be zero at 0 bps");

        // Route count incremented as side-effect.
        assert_eq!(client.get_pair_route_count(&s, &d), 1);

        // 3) Finite liquidity is enforced separately — see
        //    `test_finite_liquidity_rejects_route_above_cap`.
        client.set_pair_liquidity(&admin, &s, &d, &100i128);
        assert_eq!(
            client.get_pair_liquidity(&s, &d),
            100,
            "explicitly-set liquidity must be readable"
        );
    }

    /// Once liquidity is finite, amounts above it panic with #12.
    #[test]
    #[should_panic(expected = "Error(Contract, #12)")]
    fn test_finite_liquidity_rejects_route_above_cap() {
        let env = Env::default();
        let (client, admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_liquidity(&admin, &s, &d, &100i128);
        client.compute_route_fee(&s, &d, &1_000i128);
    }

    #[test]
    fn test_pair_info_ext_reflects_configuration() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        let admin = client.get_admin().expect("constructor stores admin");
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &25u32);
        client.set_pair_min_amount(&s, &d, &10i128);
        client.set_pair_max_amount(&s, &d, &1_000i128);
        client.set_pair_liquidity(&admin, &s, &d, &500i128);
        client.set_pair_cooldown(&s, &d, &120u64);

        let ext = client.get_pair_info_ext(&s, &d);
        assert!(ext.registered);
        assert_eq!(ext.fee_bps, 25);
        assert_eq!(ext.min_amount, 10);
        assert_eq!(ext.max_amount, 1_000);
        assert_eq!(ext.liquidity, 500);
        assert_eq!(ext.cooldown_secs, 120);
        assert_eq!(ext.route_count, 0);
        assert_eq!(ext.volume, 0);

        // Individual getters agree.
        assert_eq!(ext.cooldown_secs, client.get_pair_cooldown(&s, &d));
        assert_eq!(ext.route_count, client.get_pair_route_count(&s, &d));
        assert_eq!(ext.volume, client.get_pair_volume(&s, &d));
    }

    #[test]
    fn test_pair_info_ext_after_routing() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        let admin = client.get_admin().expect("constructor stores admin");
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &10u32);
        client.set_pair_liquidity(&admin, &s, &d, &1_000i128);

        // Route twice to accumulate count and volume.
        client.compute_route_fee(&s, &d, &200i128);
        client.compute_route_fee(&s, &d, &300i128);

        let ext = client.get_pair_info_ext(&s, &d);
        assert!(ext.registered);
        assert_eq!(ext.route_count, 2);
        assert_eq!(ext.volume, 500);
        // Liquidity was debited: 1_000 - 200 - 300 = 500.
        assert_eq!(ext.liquidity, 500);

        // Matches individual getters.
        assert_eq!(ext.route_count, client.get_pair_route_count(&s, &d));
        assert_eq!(ext.volume, client.get_pair_volume(&s, &d));
        assert_eq!(ext.liquidity, client.get_pair_liquidity(&s, &d));
    }

    #[test]
    fn test_pair_route_count_and_volume_stay_isolated_per_pair() {
        let env = Env::default();
        let (client, admin) = setup(&env);
        let (s1, d1) = (symbol_short!("USDC"), symbol_short!("EURC"));
        let (s2, d2) = (symbol_short!("XLM"), symbol_short!("USDC"));
        client.register_pair(&s1, &d1);
        client.register_pair(&s2, &d2);
        client.set_pair_liquidity(&admin, &s1, &d1, &1_000i128);
        client.set_pair_liquidity(&admin, &s2, &d2, &1_000i128);
        client.compute_route_fee(&s1, &d1, &100i128);
        client.compute_route_fee(&s1, &d1, &50i128);
        assert_eq!(client.get_pair_route_count(&s1, &d1), 2);
        assert_eq!(client.get_pair_volume(&s1, &d1), 150);
        assert_eq!(client.get_pair_route_count(&s2, &d2), 0);
        assert_eq!(client.get_pair_volume(&s2, &d2), 0);
        client.compute_route_fee(&s2, &d2, &777i128);
        assert_eq!(client.get_pair_route_count(&s1, &d1), 2);
        assert_eq!(client.get_pair_volume(&s1, &d1), 150);
        assert_eq!(client.get_pair_route_count(&s2, &d2), 1);
        assert_eq!(client.get_pair_volume(&s2, &d2), 777);
    }

    #[test]
    fn test_pair_volume_saturates_near_i128_max_without_panicking() {
        let env = Env::default();
        let (client, admin) = setup(&env);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_max_amount(&s, &d, &i128::MAX);
        client.set_pair_liquidity(&admin, &s, &d, &i128::MAX);
        let near_max = i128::MAX - 100;
        client.compute_route_fee(&s, &d, &near_max);
        assert_eq!(client.get_pair_volume(&s, &d), near_max);
        client.compute_route_fee(&s, &d, &1_000i128);
        assert_eq!(client.get_pair_volume(&s, &d), i128::MAX);
        assert_eq!(client.get_pair_route_count(&s, &d), 2);
    }

    #[test]
    fn test_pair_info_ext_matches_get_pair_info_base_fields() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let (s, d) = (symbol_short!("XLM"), symbol_short!("USDC"));
        let admin = client.get_admin().expect("constructor stores admin");
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &50u32);
        client.set_pair_min_amount(&s, &d, &5i128);
        client.set_pair_max_amount(&s, &d, &10_000i128);
        client.set_pair_liquidity(&admin, &s, &d, &2_000i128);

        let info = client.get_pair_info(&s, &d);
        let ext = client.get_pair_info_ext(&s, &d);
        // Base fields must be identical.
        assert_eq!(info.registered, ext.registered);
        assert_eq!(info.fee_bps, ext.fee_bps);
        assert_eq!(info.min_amount, ext.min_amount);
        assert_eq!(info.max_amount, ext.max_amount);
        assert_eq!(info.liquidity, ext.liquidity);
        assert_eq!(info.last_route_at, ext.last_route_at);
    }

    #[test]
    fn test_global_config_defaults_before_any_admin_configuration() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let config = client.get_global_config();
        assert_eq!(
            config,
            GlobalConfig {
                fee_recipient: None,
                max_fee_absolute: None,
                min_fee_absolute: None,
                oracle: None,
                timelock_secs: 0,
            }
        );
    }

    #[test]
    fn test_global_config_reflects_configured_values() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let recipient = Address::generate(&env);
        let oracle = Address::generate(&env);
        client.set_fee_recipient(&recipient);
        client.set_max_fee_absolute(&500i128);
        client.set_min_fee_absolute(&10i128);
        client.set_oracle(&oracle);
        client.set_timelock(&3_600u64);

        let config = client.get_global_config();
        assert_eq!(config.fee_recipient, Some(recipient));
        assert_eq!(config.max_fee_absolute, Some(500i128));
        assert_eq!(config.min_fee_absolute, Some(10i128));
        assert_eq!(config.oracle, Some(oracle));
        assert_eq!(config.timelock_secs, 3_600u64);
    }

    #[test]
    fn test_global_config_does_not_mutate_storage() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let before = client.get_global_config();
        // Calling the view twice must be side-effect free and stable.
        let after = client.get_global_config();
        assert_eq!(before, after);
    }
}

/// Issue #19 — negative authorization coverage. The shared `setup_initialized`
/// uses `mock_all_auths`, so no existing test proves a wrong/missing signer is
/// rejected. Each test here initialises with a scoped mock authorising only
/// `init`, then invokes an admin entrypoint with no matching auth and asserts
/// the call panics. A positive control confirms the call works with auth.
#[cfg(test)]
mod authorization {
    use super::*;
    use soroban_sdk::{
        symbol_short,
        testutils::{Address as _, MockAuth, MockAuthInvoke},
        IntoVal,
    };

    /// Register the constructor with only constructor auth for `admin`; later
    /// privileged calls are intentionally left unauthorised.
    fn setup_scoped(env: &Env) -> StableRouteRouterClient<'_> {
        let admin = Address::generate(env);
        let id = Address::generate(env);
        env.mock_auths(&[MockAuth {
            address: &admin,
            invoke: &MockAuthInvoke {
                contract: &id,
                fn_name: "__constructor",
                args: (admin.clone(),).into_val(env),
                sub_invokes: &[],
            },
        }]);
        env.register_at(&id, StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(env, &id);
        client
    }

    #[test]
    #[should_panic]
    fn test_register_pair_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
    }

    #[test]
    #[should_panic]
    fn test_unregister_pair_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.unregister_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
    }

    #[test]
    #[should_panic]
    fn test_set_pair_fee_bps_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &10u32);
    }

    #[test]
    #[should_panic]
    fn test_set_pair_liquidity_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        let caller = Address::generate(&env);
        client.set_pair_liquidity(
            &caller,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &10i128,
        );
    }

    #[test]
    #[should_panic]
    fn test_set_pair_min_amount_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &1i128);
    }

    #[test]
    #[should_panic]
    fn test_set_pair_max_amount_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_pair_max_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &1i128);
    }

    #[test]
    #[should_panic]
    fn test_set_fee_recipient_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_fee_recipient(&Address::generate(&env));
    }

    #[test]
    #[should_panic]
    fn test_pause_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.pause();
    }

    #[test]
    #[should_panic]
    fn test_unpause_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.unpause();
    }

    #[test]
    #[should_panic]
    fn test_propose_admin_transfer_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.propose_admin_transfer(&Address::generate(&env));
    }

    #[test]
    #[should_panic]
    fn test_migrate_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.migrate_v1_to_v2();
    }

    #[test]
    #[should_panic]
    fn test_set_max_fee_absolute_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_max_fee_absolute(&1000i128);
    }

    #[test]
    #[should_panic]
    fn test_set_min_fee_absolute_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_min_fee_absolute(&1000i128);
    }

    #[test]
    #[should_panic]
    fn test_clear_max_fee_absolute_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.clear_max_fee_absolute();
    }

    #[test]
    #[should_panic]
    fn test_set_pair_cooldown_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_pair_cooldown(&symbol_short!("USDC"), &symbol_short!("EURC"), &100u64);
    }

    #[test]
    #[should_panic]
    fn test_set_oracle_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.set_oracle(&Address::generate(&env));
    }

    #[test]
    fn test_set_timelock_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);

        // Attempting set_timelock by unauthorized caller should panic
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            client.set_timelock(&100u64);
        }));
        assert!(result.is_err(), "unauthorized set_timelock must panic");

        // Verify no tlock_set events were emitted
        let payloads = crate::test::event_payloads(&env, symbol_short!("tlock_set"));
        assert_eq!(
            payloads.len(),
            0,
            "no events should be emitted on failed auth"
        );
    }

    #[test]
    #[should_panic]
    fn test_cancel_admin_transfer_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.cancel_admin_transfer();
    }

    #[test]
    #[should_panic]
    fn test_force_admin_transfer_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.force_admin_transfer(&Address::generate(&env));
    }

    #[test]
    #[should_panic]
    fn test_upgrade_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        client.upgrade(&BytesN::from_array(&env, &[0; 32]));
    }

    #[test]
    #[should_panic]
    fn test_register_pairs_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        let pairs = Vec::from_slice(&env, &[(symbol_short!("USDC"), symbol_short!("EURC"))]);
        client.register_pairs(&pairs);
    }

    #[test]
    #[should_panic]
    fn test_set_pair_fees_bps_requires_admin() {
        let env = Env::default();
        let client = setup_scoped(&env);
        let entries = Vec::from_slice(
            &env,
            &[(symbol_short!("USDC"), symbol_short!("EURC"), 100u32)],
        );
        client.set_pair_fees_bps(&entries);
    }

    /// Positive control: with the admin's auth supplied, the call succeeds.
    #[test]
    fn test_admin_can_register_with_auth() {
        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(&env, &id);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert!(client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
    }
}

/// Issue #41 — absolute per-route fee ceiling. Both the relative MAX_FEE_BPS
/// and the optional absolute MaxFeeAbsolute apply; the tighter wins. The cap
/// is unset by default (backward compatible).
#[cfg(test)]
mod fee_cap {
    use super::*;
    use crate::test::event_payloads;
    use soroban_sdk::{symbol_short, testutils::Address as _};

    fn setup_pair(env: &Env) -> (StableRouteRouterClient<'_>, Symbol, Symbol) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(env, &id);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &100u32); // 1%
        (client, s, d)
    }

    #[test]
    fn test_no_absolute_cap_by_default() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        assert_eq!(client.get_max_fee_absolute(), None);
        // 1_000_000 * 1% = 10_000, unclamped.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 10_000);
    }

    #[test]
    fn test_fee_below_cap_is_unaffected() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_max_fee_absolute(&50_000i128);
        assert_eq!(client.get_max_fee_absolute(), Some(50_000));
        // 10_000 < 50_000 -> unchanged.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 10_000);
    }

    #[test]
    fn test_fee_above_cap_is_clamped() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_max_fee_absolute(&5_000i128);
        // Proportional fee 10_000 clamped down to the 5_000 ceiling.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 5_000);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #21)")]
    fn test_cap_of_zero_rejected() {
        let env = Env::default();
        let (client, _s, _d) = setup_pair(&env);
        client.set_max_fee_absolute(&0i128);
    }

    #[test]
    fn test_cap_of_one_clamps() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_max_fee_absolute(&1i128);
        // 1_000_000 * 1% = 10_000, clamped to 1.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 1);
    }

    #[test]
    fn test_quote_and_compute_agree_under_cap() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_max_fee_absolute(&5_000i128);
        let (qfee, qnet) = client.quote_route(&s, &d, &1_000_000i128);
        assert_eq!(qfee, 5_000);
        assert_eq!(qnet, 1_000_000 - 5_000);
        assert_eq!(qfee, client.compute_route_fee(&s, &d, &1_000_000i128));
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_negative_cap_rejected() {
        let env = Env::default();
        let (client, _s, _d) = setup_pair(&env);
        client.set_max_fee_absolute(&-1i128);
    }

    #[test]
    fn test_clear_max_fee_absolute_removes_cap() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_max_fee_absolute(&5_000i128);
        assert_eq!(client.get_max_fee_absolute(), Some(5_000));
        // Fee is clamped.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 5_000);
        client.clear_max_fee_absolute();
        assert_eq!(client.get_max_fee_absolute(), None);
        // Fee is no longer clamped — proportional 10_000 applies.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 10_000);
    }

    #[test]
    fn test_clear_max_fee_absolute_is_idempotent() {
        let env = Env::default();
        let (client, _s, _d) = setup_pair(&env);
        // Remove when never set — clean no-op.
        assert_eq!(client.get_max_fee_absolute(), None);
        client.clear_max_fee_absolute();
        assert_eq!(client.get_max_fee_absolute(), None);
        // Set, remove, then remove again — second removal is also a no-op.
        client.set_max_fee_absolute(&5_000i128);
        client.clear_max_fee_absolute();
        assert_eq!(client.get_max_fee_absolute(), None);
        client.clear_max_fee_absolute();
        assert_eq!(client.get_max_fee_absolute(), None);
    }

    #[test]
    fn test_clear_max_fee_absolute_emits_event() {
        let env = Env::default();
        let (client, _s, _d) = setup_pair(&env);
        client.set_max_fee_absolute(&5_000i128);
        client.clear_max_fee_absolute();
        let payloads = event_payloads(&env, symbol_short!("mxfee_clr"));
        assert_eq!(
            payloads.len(),
            1,
            "clear_max_fee_absolute emits one maxfee_clr event"
        );
        let removed: Option<i128> = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("maxfee_clr event data decodes to Option<i128>");
        assert_eq!(
            removed,
            Some(5_000),
            "event must carry the previously configured cap"
        );
    }

    /// A no-op removal still emits `maxfee_clr`, with `None` as the payload,
    /// so indexers observe every revocation attempt.
    #[test]
    fn test_clear_max_fee_absolute_noop_emits_event_with_none() {
        let env = Env::default();
        let (client, _s, _d) = setup_pair(&env);
        client.clear_max_fee_absolute();
        let payloads = event_payloads(&env, symbol_short!("mxfee_clr"));
        assert_eq!(payloads.len(), 1);
        let removed: Option<i128> = soroban_sdk::TryFromVal::try_from_val(&env, &payloads[0])
            .expect("maxfee_clr event data decodes to Option<i128>");
        assert_eq!(removed, None);
    }

    /// A stored zero (from a pre-upgrade write) must be treated as unset by
    /// both the fee computation path and the public getter, so that a
    /// previously-accepted zero cap does not continue silently zeroing fees
    /// after the upgrade.
    #[test]
    fn test_stored_zero_fee_cap_treated_as_unset_for_computation() {
        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let contract_id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(&env, &contract_id);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &100u32);
        // Directly write MaxFeeAbsolute = 0 into persistent storage,
        // bypassing the write-path guard that now rejects zero.
        env.as_contract(&contract_id, || {
            env.storage()
                .persistent()
                .set(&DataKey::MaxFeeAbsolute, &0i128);
        });
        // 1_000_000 * 1% = 10_000, and the stored zero cap must NOT clamp it.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 10_000);
    }

    /// The public getter must also normalise a stored zero to None, so
    /// off-chain systems and the fee computation agree on the effective cap.
    #[test]
    fn test_get_max_fee_absolute_normalises_stored_zero_to_none() {
        let env = Env::default();
        let (client, _s, _d) = setup_pair(&env);
        let contract_id = client.address.clone();
        // Write zero to MaxFeeAbsolute via storage, bypassing the write guard.
        env.as_contract(&contract_id, || {
            env.storage()
                .persistent()
                .set(&DataKey::MaxFeeAbsolute, &0i128);
        });
        assert_eq!(
            client.get_max_fee_absolute(),
            None,
            "stored zero must be normalised to None"
        );
    }
}

/// Absolute per-route fee floor. Applies after the fee cap; if floor > cap,
/// floor takes precedence. Unset by default (backward compatible).
#[cfg(test)]
mod test_i42_min_fee_floor {
    use super::*;
    use soroban_sdk::{symbol_short, testutils::Address as _};

    fn setup_pair(env: &Env) -> (StableRouteRouterClient<'_>, Symbol, Symbol) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(env, &id);
        let (s, d) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&s, &d);
        client.set_pair_fee_bps(&s, &d, &100u32); // 1%
        (client, s, d)
    }

    #[test]
    fn test_no_absolute_floor_by_default() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        assert_eq!(client.get_min_fee_absolute(), None);
        // 9_999 * 1% = 99.99 → truncates to 99, no floor applied.
        assert_eq!(client.compute_route_fee(&s, &d, &9_999i128), 99);
    }

    #[test]
    fn test_fee_above_floor_is_unaffected() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_min_fee_absolute(&50i128);
        assert_eq!(client.get_min_fee_absolute(), Some(50));
        // 99 > 50 → unchanged.
        assert_eq!(client.compute_route_fee(&s, &d, &9_999i128), 99);
    }

    #[test]
    fn test_fee_below_floor_is_raised() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_min_fee_absolute(&100i128);
        // Proportional fee 99 raised to the 100 floor.
        assert_eq!(client.compute_route_fee(&s, &d, &9_999i128), 100);
    }

    #[test]
    fn test_floor_exceeds_cap_floor_takes_precedence() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_max_fee_absolute(&50i128); // cap 50
        client.set_min_fee_absolute(&75i128); // floor 75 > cap 50
                                              // Floor takes precedence: fee is 75.
        assert_eq!(client.compute_route_fee(&s, &d, &1_000_000i128), 75);
    }

    #[test]
    fn test_quote_and_compute_agree_under_floor() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_min_fee_absolute(&100i128);
        let (qfee, qnet) = client.quote_route(&s, &d, &9_999i128);
        assert_eq!(qfee, 100);
        assert_eq!(qnet, 9_999 - 100);
        assert_eq!(qfee, client.compute_route_fee(&s, &d, &9_999i128));
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn test_negative_floor_rejected() {
        let env = Env::default();
        let (client, _s, _d) = setup_pair(&env);
        client.set_min_fee_absolute(&-1i128);
    }

    #[test]
    fn test_truncation_boundary_fee_bps_1() {
        let env = Env::default();
        let (client, s, d) = setup_pair(&env);
        client.set_pair_fee_bps(&s, &d, &1u32); // 0.01%
        client.set_min_fee_absolute(&1i128); // floor at 1
                                             // 9_999 * 1 / 10_000 = 0.9999 → truncates to 0, floor raises to 1.
        assert_eq!(client.compute_route_fee(&s, &d, &9_999i128), 1);
        // 10_000 *1 /10_000 =1 → exactly floor, unchanged.
        assert_eq!(client.compute_route_fee(&s, &d, &10_000i128), 1);
    }
}

#[cfg(test)]
mod test_batch {
    use super::*;
    use soroban_sdk::{symbol_short, testutils::Address as _, vec};

    fn setup(env: &Env) -> (StableRouteRouterClient<'_>, Address) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &id);
        (client, admin)
    }

    fn setup_without_admin(env: &Env) -> StableRouteRouterClient<'_> {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin,));
        env.as_contract(&id, || {
            env.storage().instance().remove(&DataKey::Admin);
        });
        StableRouteRouterClient::new(env, &id)
    }

    #[test]
    fn test_register_pairs_happy_path() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC")),
            (symbol_short!("XLM"), symbol_short!("USDC")),
            (symbol_short!("ETH"), symbol_short!("BTC")),
        ]);
        assert!(client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
        assert!(client.is_pair_registered(&symbol_short!("XLM"), &symbol_short!("USDC")));
        assert!(client.is_pair_registered(&symbol_short!("ETH"), &symbol_short!("BTC")));
    }

    #[test]
    fn test_register_pairs_single_entry_succeeds() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![&env, (symbol_short!("USDC"), symbol_short!("EURC"))]);
        assert!(client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #19)")]
    fn test_register_pairs_rejects_empty_batch() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![&env]);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #3)")]
    fn test_register_pairs_atomic_rollback_on_identity() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC")),
            (symbol_short!("XLM"), symbol_short!("XLM")),
            (symbol_short!("ETH"), symbol_short!("BTC")),
        ]);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_register_pairs_rejects_when_paused() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.pause();
        client.register_pairs(&vec![&env, (symbol_short!("USDC"), symbol_short!("EURC"))]);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #18)")]
    fn test_register_pairs_rejects_too_large_batch() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let mut pairs = std::vec::Vec::new();
        for i in 0..MAX_BATCH_SIZE + 1 {
            pairs.push((
                Symbol::new(&env, &std::format!("SRC{}", i)),
                Symbol::new(&env, &std::format!("DST{}", i)),
            ));
        }
        client.register_pairs(&Vec::from_slice(&env, &pairs));
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_register_pairs_panics_when_uninitialized() {
        let env = Env::default();
        let client = setup_without_admin(&env);
        client.register_pairs(&vec![&env, (symbol_short!("USDC"), symbol_short!("EURC"))]);
    }

    #[test]
    fn test_set_pair_fees_bps_happy_path() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC")),
            (symbol_short!("XLM"), symbol_short!("USDC")),
        ]);
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 25u32),
            (symbol_short!("XLM"), symbol_short!("USDC"), 50u32),
        ]);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC")),
            25
        );
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("XLM"), &symbol_short!("USDC")),
            50
        );
    }

    #[test]
    fn test_set_pair_fees_bps_single_entry_succeeds() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![&env, (symbol_short!("USDC"), symbol_short!("EURC"))]);
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 25u32),
        ]);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC")),
            25
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #19)")]
    fn test_set_pair_fees_bps_rejects_empty_batch() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.set_pair_fees_bps(&vec![&env]);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #4)")]
    fn test_set_pair_fees_bps_atomic_rollback_on_high_fee() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC")),
            (symbol_short!("XLM"), symbol_short!("USDC")),
        ]);
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 25u32),
            (symbol_short!("XLM"), symbol_short!("USDC"), MAX_FEE_BPS + 1),
        ]);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #5)")]
    fn test_set_pair_fees_bps_rejects_unregistered_pair() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 25u32),
        ]);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_set_pair_fees_bps_rejects_when_paused() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        client.register_pairs(&vec![&env, (symbol_short!("USDC"), symbol_short!("EURC"))]);
        client.pause();
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 25u32),
        ]);
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #18)")]
    fn test_set_pair_fees_bps_rejects_too_large_batch() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        let mut entries = std::vec::Vec::new();
        for i in 0..MAX_BATCH_SIZE + 1 {
            entries.push((
                Symbol::new(&env, &std::format!("SRC{}", i)),
                Symbol::new(&env, &std::format!("DST{}", i)),
                10u32,
            ));
        }
        client.set_pair_fees_bps(&Vec::from_slice(&env, &entries));
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_pair_fees_bps_panics_when_uninitialized() {
        let env = Env::default();
        let client = setup_without_admin(&env);
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 25u32),
        ]);
    }

    /// Boundary test: a batch of exactly MAX_BATCH_SIZE (100) entries is
    /// the largest accepted by `register_pairs`. Every pair is registered
    /// and queryable via `is_pair_registered`.
    #[test]
    fn test_register_pairs_exact_max_batch_size_succeeds() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        env.cost_estimate().disable_resource_limits();
        let mut pairs = std::vec::Vec::new();
        for i in 0..MAX_BATCH_SIZE {
            pairs.push((
                Symbol::new(&env, &std::format!("SRC{}", i)),
                Symbol::new(&env, &std::format!("DST{}", i)),
            ));
        }
        client.register_pairs(&Vec::from_slice(&env, &pairs));
        for i in 0..MAX_BATCH_SIZE {
            assert!(client.is_pair_registered(
                &Symbol::new(&env, &std::format!("SRC{}", i)),
                &Symbol::new(&env, &std::format!("DST{}", i)),
            ));
        }
    }

    /// Boundary test: a batch of exactly MAX_BATCH_SIZE (100) entries is
    /// the largest accepted by `set_pair_fees_bps`. All 100 fee entries
    /// are written and readable via `get_pair_fee_bps`.
    #[test]
    fn test_set_pair_fees_bps_exact_max_batch_size_succeeds() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        env.cost_estimate().disable_resource_limits();
        // Register all 100 pairs first.
        let mut pairs = std::vec::Vec::new();
        for i in 0..MAX_BATCH_SIZE {
            pairs.push((
                Symbol::new(&env, &std::format!("SRC{}", i)),
                Symbol::new(&env, &std::format!("DST{}", i)),
            ));
        }
        client.register_pairs(&Vec::from_slice(&env, &pairs));
        // Set fees for all 100 pairs.
        let mut entries = std::vec::Vec::new();
        for i in 0..MAX_BATCH_SIZE {
            entries.push((
                Symbol::new(&env, &std::format!("SRC{}", i)),
                Symbol::new(&env, &std::format!("DST{}", i)),
                10u32 + i,
            ));
        }
        client.set_pair_fees_bps(&Vec::from_slice(&env, &entries));
        for i in 0..MAX_BATCH_SIZE {
            assert_eq!(
                client.get_pair_fee_bps(
                    &Symbol::new(&env, &std::format!("SRC{}", i)),
                    &Symbol::new(&env, &std::format!("DST{}", i)),
                ),
                10u32 + i,
            );
        }
    }

    /// Boundary test: a batch of MAX_BATCH_SIZE + 1 (101) entries is
    /// rejected by `register_pairs` with `BatchTooLarge` (#18). The
    /// pre-registered pair remains registered, confirming atomic rollback.
    #[test]
    #[should_panic(expected = "Error(Contract, #18)")]
    fn test_register_pairs_batch_too_large_leaves_state_intact() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        // Pre-register a known pair.
        client.register_pairs(&vec![
            &env,
            (symbol_short!("SRC_PRE"), symbol_short!("DST_PRE")),
        ]);
        assert!(client.is_pair_registered(&symbol_short!("SRC_PRE"), &symbol_short!("DST_PRE"),));
        // Attempt MAX_BATCH_SIZE + 1 entries — must panic with #18.
        let mut pairs = std::vec::Vec::new();
        for i in 0..MAX_BATCH_SIZE + 1 {
            pairs.push((
                Symbol::new(&env, &std::format!("SRC{}", i)),
                Symbol::new(&env, &std::format!("DST{}", i)),
            ));
        }
        client.register_pairs(&Vec::from_slice(&env, &pairs));
    }

    /// Boundary test: a batch of MAX_BATCH_SIZE + 1 (101) entries is
    /// rejected by `set_pair_fees_bps` with `BatchTooLarge` (#18). The
    /// pre-set fee remains unchanged, confirming atomic rollback.
    #[test]
    #[should_panic(expected = "Error(Contract, #18)")]
    fn test_set_pair_fees_bps_batch_too_large_leaves_state_intact() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        // Register a pair and set its fee.
        client.register_pairs(&vec![
            &env,
            (symbol_short!("SRC_PRE"), symbol_short!("DST_PRE")),
        ]);
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("SRC_PRE"), symbol_short!("DST_PRE"), 42u32),
        ]);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("SRC_PRE"), &symbol_short!("DST_PRE"),),
            42,
        );
        // Attempt MAX_BATCH_SIZE + 1 entries — must panic with #18.
        let mut entries = std::vec::Vec::new();
        for i in 0..MAX_BATCH_SIZE + 1 {
            entries.push((
                Symbol::new(&env, &std::format!("SRC{}", i)),
                Symbol::new(&env, &std::format!("DST{}", i)),
                10u32,
            ));
        }
        client.set_pair_fees_bps(&Vec::from_slice(&env, &entries));
    }

    /// Boundary test: an empty batch for `register_pairs` panics with
    /// `EmptyBatch` (#19) and leaves pre-existing registration intact.
    #[test]
    #[should_panic(expected = "Error(Contract, #19)")]
    fn test_register_pairs_empty_batch_leaves_state_intact() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        // Pre-register a known pair.
        client.register_pairs(&vec![
            &env,
            (symbol_short!("SRC_PRE"), symbol_short!("DST_PRE")),
        ]);
        assert!(client.is_pair_registered(&symbol_short!("SRC_PRE"), &symbol_short!("DST_PRE"),));
        // Empty batch must panic with #19.
        client.register_pairs(&vec![&env]);
    }

    /// Boundary test: an empty batch for `set_pair_fees_bps` panics with
    /// `EmptyBatch` (#19) and leaves pre-existing fee config intact.
    #[test]
    #[should_panic(expected = "Error(Contract, #19)")]
    fn test_set_pair_fees_bps_empty_batch_leaves_state_intact() {
        let env = Env::default();
        let (client, _admin) = setup(&env);
        // Register a pair and set its fee.
        client.register_pairs(&vec![
            &env,
            (symbol_short!("SRC_PRE"), symbol_short!("DST_PRE")),
        ]);
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("SRC_PRE"), symbol_short!("DST_PRE"), 42u32),
        ]);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("SRC_PRE"), &symbol_short!("DST_PRE"),),
            42,
        );
        // Empty batch must panic with #19.
        client.set_pair_fees_bps(&vec![&env]);
    }
}

/// Issue #153: Test coverage for the version surface and NotInitialized paths.
///
/// This module validates that:
/// - `version()` is stable (`ROUTER_V2`) independent of schema version
/// - `get_schema_version()` returns 1 before any migration (default fallback)
/// - All admin-gated entrypoints panic with `NotInitialized` (#2) on uninitialized contracts
/// - Security invariants: no admin entrypoint succeeds before initialization
#[cfg(test)]
mod version_reads {
    use super::*;
    use soroban_sdk::{symbol_short, testutils::Address as _};

    // ========== Helper Setup Functions ==========

    /// Register a contract with admin set (initialized).
    fn setup_initialized(env: &Env) -> (StableRouteRouterClient<'_>, Address) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &contract_id);
        (client, admin)
    }

    /// Register a contract and then remove the admin from storage to simulate an
    /// uninitialized state (admin slot is empty). Used to test NotInitialized (#2) failures.
    fn setup_uninitialized(env: &Env) -> StableRouteRouterClient<'_> {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let contract_id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(env, &contract_id);
        // Remove the admin from storage to simulate uninitialized state.
        env.as_contract(&contract_id, || {
            env.storage().instance().remove(&DataKey::Admin);
        });
        client
    }

    // ========== Version Surface Tests ==========

    /// `version()` is the fixed contract identity tag; the version constant is stable
    /// across the contract's lifetime.
    #[test]
    fn test_version_returns_router_v2() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);
        assert_eq!(client.version(), symbol_short!("ROUTER_V2"));
    }

    /// `version()` is the fixed contract identity tag and must be entirely
    /// independent of `get_schema_version()`: migrating the storage schema from v1 to v2
    /// advances the schema number but never the version tag.
    #[test]
    fn test_version_constant_independent_of_schema_migration() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);

        // Both are at their initial values.
        assert_eq!(client.version(), symbol_short!("ROUTER_V2"));
        assert_eq!(client.get_schema_version(), 1u32);

        // Perform schema migration.
        client.migrate_v1_to_v2();

        // Schema advanced 1 → 2, but version tag remains `ROUTER_V2`.
        assert_eq!(client.get_schema_version(), 2u32);
        assert_eq!(client.version(), symbol_short!("ROUTER_V2"));
    }

    /// `get_schema_version()` returns 1 (the implicit pre-migration default) when no
    /// schema version has been persisted to storage yet.
    #[test]
    fn test_schema_version_defaults_to_one_when_uninitialized() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        assert_eq!(client.get_schema_version(), 1u32);
    }

    // ========== NotInitialized (#2) Failure Path Tests ==========

    // Every admin-gated entrypoint must panic with `NotInitialized` (#2) when called on a
    // contract that has not had its admin set. This test group validates the security
    // invariant: no admin action succeeds before initialization.

    /// `pause()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_pause_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.pause();
    }

    /// `unpause()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_unpause_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.unpause();
    }

    /// `register_pair()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_register_pair_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
    }

    /// `register_pairs()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_register_pairs_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.register_pairs(&soroban_sdk::Vec::from_slice(
            &env,
            &[(symbol_short!("USDC"), symbol_short!("EURC"))],
        ));
    }

    /// `set_pair_fee_bps()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_pair_fee_bps_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50u32);
    }

    /// `set_pair_fees_bps()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_pair_fees_bps_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.set_pair_fees_bps(&soroban_sdk::Vec::from_slice(
            &env,
            &[(symbol_short!("USDC"), symbol_short!("EURC"), 50u32)],
        ));
    }

    /// `set_pair_min_amount()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_pair_min_amount_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.set_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &10i128);
    }

    /// `set_pair_max_amount()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_pair_max_amount_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.set_pair_max_amount(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000i128,
        );
    }

    /// `set_pair_liquidity()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_pair_liquidity_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        let caller = Address::generate(&env);
        client.set_pair_liquidity(
            &caller,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500i128,
        );
    }

    /// `unregister_pair()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_unregister_pair_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.unregister_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
    }

    /// `propose_admin_transfer()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_propose_admin_transfer_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        let new_admin = Address::generate(&env);
        client.propose_admin_transfer(&new_admin);
    }

    /// `cancel_admin_transfer()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_cancel_admin_transfer_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.cancel_admin_transfer();
    }

    /// `set_fee_recipient()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_fee_recipient_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        let recipient = Address::generate(&env);
        client.set_fee_recipient(&recipient);
    }

    /// `set_timelock()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_timelock_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.set_timelock(&100u64);
    }

    /// `set_pair_cooldown()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_pair_cooldown_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.set_pair_cooldown(&symbol_short!("USDC"), &symbol_short!("EURC"), &60u64);
    }

    /// `set_oracle()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_oracle_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        let oracle = Address::generate(&env);
        client.set_oracle(&oracle);
    }

    /// `set_max_fee_absolute()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_set_max_fee_absolute_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.set_max_fee_absolute(&1_000i128);
    }

    /// `clear_max_fee_absolute()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_clear_max_fee_absolute_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.clear_max_fee_absolute();
    }

    /// `migrate_v1_to_v2()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_migrate_v1_to_v2_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        client.migrate_v1_to_v2();
    }

    /// `upgrade()` panics with `NotInitialized` (#2) when called on an uninitialized contract.
    #[test]
    #[should_panic(expected = "Error(Contract, #2)")]
    fn test_upgrade_panics_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);
        let dummy_hash = BytesN::from_array(&env, &[0u8; 32]);
        client.upgrade(&dummy_hash);
    }

    // ========== Security Invariant Validation ==========

    /// All read-only entrypoints (version, schema_version, pair queries) succeed on
    /// uninitialized contracts (no admin required for reads).
    #[test]
    fn test_read_only_operations_work_on_uninitialized_contract() {
        let env = Env::default();
        let client = setup_uninitialized(&env);

        // These all succeed because they are read-only (no admin check).
        assert_eq!(client.version(), symbol_short!("ROUTER_V2"));
        assert_eq!(client.get_schema_version(), 1u32);
        assert!(!client.is_paused());
        assert_eq!(client.get_admin(), None);
        assert_eq!(client.get_pending_admin(), None);
        assert_eq!(client.get_timelock(), 0u64);
        assert_eq!(client.get_pending_admin_eta(), None);
        assert_eq!(client.get_fee_recipient(), None);
        assert_eq!(client.get_oracle(), None);
        assert_eq!(client.get_max_fee_absolute(), None);
        assert!(!client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC")),
            0u32
        );
        assert_eq!(
            client.get_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC")),
            0i128
        );
        assert_eq!(
            client.get_pair_max_amount(&symbol_short!("USDC"), &symbol_short!("EURC")),
            i128::MAX
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            0i128
        );
    }

    /// Version and schema version are separate concepts: `version()` is stable,
    /// while `get_schema_version()` evolves with migrations. On an initialized but
    /// unmigrated contract, both are at their initial values.
    #[test]
    fn test_version_and_schema_version_are_separate_concepts() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);

        // Version is a constant, schema_version is a persistent value.
        let version = client.version();
        let schema = client.get_schema_version();

        assert_eq!(version, symbol_short!("ROUTER_V2"));
        assert_eq!(schema, 1u32);
        // These are distinct types and values - Symbol vs u32.
    }

    /// After initialization, admin-gated operations become available (they do not panic
    /// with NotInitialized). This test verifies the initialization unlocks admin gates.
    #[test]
    fn test_admin_operations_succeed_after_initialization() {
        let env = Env::default();
        let (client, _admin) = setup_initialized(&env);

        // These now succeed because initialization has set the admin.
        client.pause();
        assert!(client.is_paused());
        client.unpause();
        assert!(!client.is_paused());
    }
}

/// Issue #230 — Exhaustive paused-router sweep.
///
/// Enumerates **every** state-changing entrypoint and asserts its expected
/// behaviour while the router is paused. The policy is:
///
/// | Category | Entrypoints | Expected when paused |
/// |----------|-------------|----------------------|
/// | Route accounting | `compute_route_fee` | Rejected — `ContractPaused` (#9) |
/// | Pair registration | `register_pair`, `register_pairs` | Rejected — `ContractPaused` (#9) |
/// | Fee setters | `set_pair_fee_bps`, `set_pair_fees_bps` | Rejected — `ContractPaused` (#9) |
/// | Config setters | `set_pair_min_amount`, `set_pair_max_amount`, `set_pair_liquidity`, `set_pair_cooldown`, `set_fee_recipient`, `set_max_fee_absolute`, `set_oracle`, `remove_oracle` | Succeeds — governance/config ops are not blocked |
/// | Pair lifecycle | `unregister_pair`, `purge_pair_metrics` | Succeeds — admin cleanup must remain available |
/// | Migration | `migrate_v1_to_v2` | Succeeds — schema ops are not blocked |
/// | Governance | `pause` (idempotent), `unpause`, `set_timelock`, `propose_admin_transfer`, `cancel_admin_transfer`, `force_admin_transfer`, `accept_admin_transfer` | Succeeds — governance must work to recover |
/// | Upgrade | `upgrade` | Succeeds — documented trade-off; patch deployment must survive an emergency pause |
///
/// ### Fail-loudly invariant
///
/// If a **new** state-changing entrypoint is added without being enumerated
/// here the coverage drop will be caught by `cargo llvm-cov --fail-under-lines 95`.
/// All entrypoints that are currently missing a pause check are explicitly
/// documented in the "succeeds while paused" group below so the gap is
/// visible in code review and not hidden in untested branches.
#[cfg(test)]
mod test_i230_paused_sweep {
    use super::*;
    use soroban_sdk::{symbol_short, testutils::Address as _, vec, BytesN};
    use std::string::{String, ToString};

    // ── helpers ─────────────────────────────────────────────────────────────

    /// Deploy a fully initialised router with a pre-registered
    /// `USDC → EURC` pair plus liquidity so route guards never fire
    /// before the pause check. Returns `(client, admin, oracle)`.
    fn setup(env: &Env) -> (StableRouteRouterClient<'_>, Address, Address) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let oracle = Address::generate(env);
        let id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &id);

        // Register working pair so later per-pair setters don't fail on
        // PairNotRegistered before they even reach the pause check.
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        // Give it plenty of liquidity so compute_route_fee would pass
        // all route guards if the pair were accessible.
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_000_i128,
        );
        // Configure oracle role for tests that exercise set_pair_liquidity
        // via the oracle caller path.
        client.set_oracle(&oracle);

        (client, admin, oracle)
    }

    // ═══════════════════════════════════════════════════════════════════════
    // GROUP A — REJECTED while paused (ContractPaused #9)
    //
    // These five entrypoints have an explicit pause guard and must panic with
    // Error(Contract, #9) when the router is paused.
    // ═══════════════════════════════════════════════════════════════════════

    /// `compute_route_fee` — route accounting must be blocked while paused
    /// so no counter increment, timestamp, or route event leaks through.
    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_compute_route_fee_rejected_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_000_i128);
    }

    /// `register_pair` — new pair registration must be blocked while paused
    /// so the pair table cannot be modified during an emergency stop.
    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_register_pair_rejected_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        // XLM→USDC is a fresh pair that is not yet registered.
        client.register_pair(&symbol_short!("XLM"), &symbol_short!("USDC"));
    }

    /// `register_pairs` (batch) — same policy as `register_pair`; the
    /// pause check fires before the batch is iterated, so the whole
    /// batch is rejected atomically.
    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_register_pairs_rejected_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.register_pairs(&vec![&env, (symbol_short!("XLM"), symbol_short!("USDC"))]);
    }

    /// `set_pair_fee_bps` — fee writes must be blocked; the check fires
    /// before admin auth so no fee mutation occurs.
    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_set_pair_fee_bps_rejected_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &10u32);
    }

    /// `set_pair_fees_bps` (batch) — same policy as `set_pair_fee_bps`;
    /// the pause check fires before the batch loop.
    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn test_set_pair_fees_bps_rejected_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 10u32),
        ]);
    }

    // ═══════════════════════════════════════════════════════════════════════
    // GROUP B — SUCCEEDS while paused (no pause gate)
    //
    // The entrypoints below do not have a ContractPaused guard. This is
    // deliberate for the governance / recovery sub-group and an acknowledged
    // gap for the config-setter sub-group. Every sub-group is documented so
    // the absence of a check is visible rather than accidental.
    // ═══════════════════════════════════════════════════════════════════════

    // ── B1: Governance / recovery (pause gate intentionally absent) ─────────

    /// `pause` is idempotent and must succeed while already paused so an
    /// admin can re-assert the stopped state without unpausing first.
    #[test]
    fn test_pause_idempotent_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        assert!(client.is_paused());
        // Re-pausing while already paused must not panic.
        client.pause();
        assert!(client.is_paused());
    }

    /// `unpause` is the designated recovery entrypoint; it must succeed
    /// while paused (that is the only time it matters).
    #[test]
    fn test_unpause_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.unpause();
        assert!(!client.is_paused());
    }

    /// `set_timelock` — governance configuration must remain accessible
    /// while paused so the admin can adjust timelock policy during an
    /// emergency stop without needing to unpause first.
    #[test]
    fn test_set_timelock_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.set_timelock(&300_u64);
        assert_eq!(client.get_timelock(), 300);
    }

    /// `propose_admin_transfer` — admin rotation cannot be blocked by an
    /// emergency pause; the current admin must be able to rotate out even
    /// when the router is stopped.
    #[test]
    fn test_propose_admin_transfer_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        let next = Address::generate(&env);
        client.pause();
        client.propose_admin_transfer(&next);
        assert_eq!(client.get_pending_admin(), Some(next));
    }

    /// `cancel_admin_transfer` — cancelling a queued handover must work
    /// while paused so governance can be unwound during an incident.
    #[test]
    fn test_cancel_admin_transfer_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        let next = Address::generate(&env);
        client.propose_admin_transfer(&next);
        client.pause();
        client.cancel_admin_transfer();
        assert_eq!(client.get_pending_admin(), None);
    }

    /// `accept_admin_transfer` — the pending admin accepting the handover
    /// must succeed while paused (timelock at 0 so eta has elapsed).
    #[test]
    fn test_accept_admin_transfer_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        let next = Address::generate(&env);
        client.propose_admin_transfer(&next);
        client.pause();
        client.accept_admin_transfer(&next);
        assert_eq!(client.get_admin(), Some(next));
    }

    /// `force_admin_transfer` — the current admin forcing the handover
    /// must also succeed while paused (same governance-must-stay-open policy).
    #[test]
    fn test_force_admin_transfer_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        let next = Address::generate(&env);
        client.propose_admin_transfer(&next);
        client.pause();
        client.force_admin_transfer(&next);
        assert_eq!(client.get_admin(), Some(next));
    }

    /// `upgrade` — the upgrade entrypoint **deliberately** skips the pause
    /// check. An emergency stop should still allow the admin to deploy a
    /// patched WASM so the bug that caused the pause can be fixed without
    /// first unpausing. The admin can unpause anyway, so there is no
    /// escalation path through this exception.
    ///
    /// We cannot invoke `env.deployer().update_current_contract_wasm` with a
    /// zero-hash in tests (it will panic inside the WASM deployer, not with
    /// ContractPaused #9), so we assert the failure is _not_ #9 — i.e. the
    /// pause gate was skipped and the call reached the deployer logic.
    #[test]
    fn test_upgrade_not_blocked_by_pause() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        let dummy_hash = BytesN::from_array(&env, &[0u8; 32]);
        // The call must NOT fail with ContractPaused (#9).  It will fail
        // inside the deployer (unknown wasm hash), but that is beyond the
        // pause gate.
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            client.upgrade(&dummy_hash);
        }));
        if let Err(e) = result {
            let msg = e
                .downcast_ref::<String>()
                .cloned()
                .or_else(|| e.downcast_ref::<&str>().map(|s| s.to_string()))
                .unwrap_or_default();
            assert!(
                !msg.contains("Error(Contract, #9)"),
                "upgrade must NOT be blocked by ContractPaused; got: {msg}"
            );
        }
        // If the call succeeds (no panic) that is also fine — the pause gate
        // was not engaged.
    }

    // ── B2: Config setters (pause gate currently absent — acknowledged gap) ─

    /// `set_pair_min_amount` — per-pair lower-bound setter; no pause gate.
    /// Documented here so the absence is explicit and auditable.
    #[test]
    fn test_set_pair_min_amount_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.set_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC"), &5_i128);
        assert_eq!(
            client.get_pair_min_amount(&symbol_short!("USDC"), &symbol_short!("EURC")),
            5
        );
    }

    /// `set_pair_max_amount` — per-pair upper-bound setter; no pause gate.
    #[test]
    fn test_set_pair_max_amount_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.set_pair_max_amount(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &999_999_i128,
        );
        assert_eq!(
            client.get_pair_max_amount(&symbol_short!("USDC"), &symbol_short!("EURC")),
            999_999
        );
    }

    /// `set_pair_liquidity` (admin path) — liquidity oracle writes are not
    /// blocked by pause; the feed must stay fresh even during an emergency
    /// stop so the router is ready to resume accurately.
    #[test]
    fn test_set_pair_liquidity_admin_succeeds_while_paused() {
        let env = Env::default();
        let (client, admin, _oracle) = setup(&env);
        client.pause();
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &42_i128,
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            42
        );
    }

    /// `set_pair_liquidity` (oracle path) — the oracle caller path is
    /// equally unblocked while paused.
    #[test]
    fn test_set_pair_liquidity_oracle_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, oracle) = setup(&env);
        client.pause();
        client.set_pair_liquidity(
            &oracle,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &77_i128,
        );
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            77
        );
    }

    /// `top_up_pair_liquidity` (admin path) — liquidity oracle writes/top-ups are not
    /// blocked by pause.
    #[test]
    fn test_top_up_pair_liquidity_admin_succeeds_while_paused() {
        let env = Env::default();
        let (client, admin, _oracle) = setup(&env);
        client.pause();
        client.top_up_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
        // Initially liquidity is 1_000_000_000, top-up by 100 makes it 1_000_000_100
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            1_000_000_100
        );
    }

    /// `top_up_pair_liquidity` (oracle path) — the oracle caller path is
    /// equally unblocked while paused.
    #[test]
    fn test_top_up_pair_liquidity_oracle_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, oracle) = setup(&env);
        client.pause();
        client.top_up_pair_liquidity(
            &oracle,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &200_i128,
        );
        // Initially liquidity is 1_000_000_000, top-up by 200 makes it 1_000_000_200
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            1_000_000_200
        );
    }

    /// `set_pair_cooldown` — rate-limit config setter; no pause gate.
    #[test]
    fn test_set_pair_cooldown_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.set_pair_cooldown(&symbol_short!("USDC"), &symbol_short!("EURC"), &60_u64);
        assert_eq!(
            client.get_pair_cooldown(&symbol_short!("USDC"), &symbol_short!("EURC")),
            60
        );
    }

    /// `set_fee_recipient` — protocol fee destination setter; no pause gate.
    #[test]
    fn test_set_fee_recipient_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        let recipient = Address::generate(&env);
        client.pause();
        client.set_fee_recipient(&recipient);
        assert_eq!(client.get_fee_recipient(), Some(recipient));
    }

    /// `set_max_fee_absolute` — absolute fee ceiling setter; no pause gate.
    #[test]
    fn test_set_max_fee_absolute_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.set_max_fee_absolute(&5_000_i128);
        assert_eq!(client.get_max_fee_absolute(), Some(5_000));
    }

    /// `clear_max_fee_absolute` — cap removal; no pause gate. Governance
    /// cleanup must remain available during an emergency stop.
    #[test]
    fn test_clear_max_fee_absolute_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.set_max_fee_absolute(&5_000_i128);
        client.pause();
        client.clear_max_fee_absolute();
        assert_eq!(client.get_max_fee_absolute(), None);
    }

    /// `set_oracle` — oracle role grant/rotation; no pause gate.
    #[test]
    fn test_set_oracle_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        let new_oracle = Address::generate(&env);
        client.pause();
        client.set_oracle(&new_oracle);
        assert_eq!(client.get_oracle(), Some(new_oracle));
    }

    /// `remove_oracle` — oracle role revocation (compromise recovery);
    /// no pause gate. Removing the oracle while paused is a valid incident
    /// response step.
    #[test]
    fn test_remove_oracle_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.remove_oracle();
        assert_eq!(client.get_oracle(), None);
    }

    // ── B3: Pair lifecycle (pause gate currently absent — acknowledged gap) ─

    /// `unregister_pair` — pair removal must remain available while paused
    /// so the admin can delist a broken corridor during an incident.
    #[test]
    fn test_unregister_pair_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.unregister_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert!(!client.is_pair_registered(&symbol_short!("USDC"), &symbol_short!("EURC")));
    }

    /// `purge_pair_metrics` — operational-history reset must remain
    /// available while paused; metrics management is admin bookkeeping,
    /// not a route operation.
    #[test]
    fn test_purge_pair_metrics_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        // purge_pair_metrics requires admin auth; with mock_all_auths set up
        // in setup() this call succeeds regardless of pause state.
        client.purge_pair_metrics(&symbol_short!("USDC"), &symbol_short!("EURC"));
        assert_eq!(
            client.get_pair_route_count(&symbol_short!("USDC"), &symbol_short!("EURC")),
            0
        );
    }

    // ── B4: Migration (pause gate currently absent — acknowledged gap) ──────

    /// `migrate_v1_to_v2` — schema migration is an admin-only governance
    /// action that must not be blocked by an emergency pause.
    #[test]
    fn test_migrate_v1_to_v2_succeeds_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.pause();
        client.migrate_v1_to_v2();
        assert_eq!(client.get_schema_version(), 2);
    }

    // ═══════════════════════════════════════════════════════════════════════
    // GROUP C — Recovery invariants
    //
    // Assert end-to-end: every gated entrypoint resumes cleanly after
    // unpause, and state accumulated during the paused window is intact.
    // ═══════════════════════════════════════════════════════════════════════

    /// After unpausing, all five previously-gated entrypoints succeed.
    /// Also verifies that config changes made while paused (liquidity top-up,
    /// fee cap) take effect once routing resumes.
    #[test]
    fn test_all_gated_entrypoints_resume_after_unpause() {
        let env = Env::default();
        let (client, admin, _oracle) = setup(&env);

        // Pause and make config changes that should survive the pause window.
        client.pause();
        client.set_max_fee_absolute(&100_i128);
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500_i128,
        );

        // Verify gated ops are still blocked.
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &1_i128)
        }));
        assert!(result.is_err(), "compute_route_fee must stay blocked");

        // Unpause and verify all five gated ops now work.
        client.unpause();

        // 1. register_pair
        client.register_pair(&symbol_short!("XLM"), &symbol_short!("USDC"));
        assert!(client.is_pair_registered(&symbol_short!("XLM"), &symbol_short!("USDC")));

        // 2. register_pairs
        client.register_pairs(&vec![&env, (symbol_short!("ETH"), symbol_short!("BTC"))]);
        assert!(client.is_pair_registered(&symbol_short!("ETH"), &symbol_short!("BTC")));

        // 3. set_pair_fee_bps
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &50_u32);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC")),
            50
        );

        // 4. set_pair_fees_bps
        client.set_pair_fees_bps(&vec![
            &env,
            (symbol_short!("USDC"), symbol_short!("EURC"), 25_u32),
        ]);
        assert_eq!(
            client.get_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC")),
            25
        );

        // 5. compute_route_fee — uses the liquidity top-up from the paused window.
        let fee =
            client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &400_i128);
        // 400 * 25 bps / 10_000 = 1; capped by set_max_fee_absolute(100) → still 1.
        assert_eq!(fee, 1);
        assert_eq!(client.get_total_routes_all_time(), 1);
    }

    /// No route side-effects (counter, timestamp, liquidity debit, events)
    /// leak through while the router is paused: the counter stays at 0
    /// and no `route` event is emitted.
    #[test]
    fn test_no_route_side_effects_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);

        let counter_before = client.get_total_routes_all_time();
        let liq_before = client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC"));

        client.pause();

        let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            client.compute_route_fee(&symbol_short!("USDC"), &symbol_short!("EURC"), &100_i128)
        }));

        // Counter unchanged, liquidity unchanged, last_route_at still None.
        assert_eq!(client.get_total_routes_all_time(), counter_before);
        assert_eq!(
            client.get_pair_liquidity(&symbol_short!("USDC"), &symbol_short!("EURC")),
            liq_before
        );
        assert_eq!(
            client.get_pair_last_route_at(&symbol_short!("USDC"), &symbol_short!("EURC")),
            None
        );
    }

    /// `quote_route` (read-only) must remain available while paused.
    /// Planners should be able to preview fees even during an emergency stop.
    #[test]
    fn test_quote_route_available_while_paused() {
        let env = Env::default();
        let (client, _admin, _oracle) = setup(&env);
        client.set_pair_fee_bps(&symbol_short!("USDC"), &symbol_short!("EURC"), &100_u32);
        client.pause();
        let (fee, net) =
            client.quote_route(&symbol_short!("USDC"), &symbol_short!("EURC"), &10_000_i128);
        assert_eq!(fee, 100);
        assert_eq!(net, 9_900);
        // Counter still 0 — quote_route is read-only.
        assert_eq!(client.get_total_routes_all_time(), 0);
    }
}

/// Issue #225 — `remove_oracle` restores admin-only liquidity writes.
///
/// Proves the dual-auth degradation documented on [`StableRouteRouter::remove_oracle`]:
/// clearing `DataKey::Oracle` makes `Some(caller) != None` always true, so only
/// the admin may call [`StableRouteRouter::set_pair_liquidity`] again.
#[cfg(test)]
mod test_i225_remove_oracle {
    use super::*;
    use crate::test::event_payloads;
    use soroban_sdk::{symbol_short, testutils::Address as _, TryFromVal};

    /// Deploy an initialized router, register USDC→EURC, and grant `oracle`.
    fn setup_with_oracle(env: &Env) -> (StableRouteRouterClient<'_>, Address, Address) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let oracle = Address::generate(env);
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &contract_id);
        let (source, destination) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.register_pair(&source, &destination);
        client.set_oracle(&oracle);
        (client, admin, oracle)
    }

    /// While configured, the scoped oracle may drive the liquidity feed.
    #[test]
    fn test_oracle_writes_liquidity_before_removal() {
        let env = Env::default();
        let (client, _admin, oracle) = setup_with_oracle(&env);
        let (source, destination) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.set_pair_liquidity(&oracle, &source, &destination, &500_i128);
        assert_eq!(client.get_pair_liquidity(&source, &destination), 500);
    }

    /// After revocation the same oracle key is rejected with `NotAuthorized` (#16).
    #[test]
    #[should_panic(expected = "Error(Contract, #16)")]
    fn test_revoked_oracle_cannot_write_liquidity() {
        let env = Env::default();
        let (client, _admin, oracle) = setup_with_oracle(&env);
        let (source, destination) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.set_pair_liquidity(&oracle, &source, &destination, &500_i128);
        client.remove_oracle();
        assert_eq!(client.get_oracle(), None);
        client.set_pair_liquidity(&oracle, &source, &destination, &999_i128);
    }

    /// Admin-only degradation: governance retains the feed after revocation.
    #[test]
    fn test_admin_writes_liquidity_after_oracle_removal() {
        let env = Env::default();
        let (client, admin, _oracle) = setup_with_oracle(&env);
        let (source, destination) = (symbol_short!("USDC"), symbol_short!("EURC"));
        client.remove_oracle();
        client.set_pair_liquidity(&admin, &source, &destination, &42_i128);
        assert_eq!(client.get_pair_liquidity(&source, &destination), 42);
    }

    /// Removing when the slot was never set is a clean no-op that still audits
    /// via `orac_rm` carrying `None`.
    #[test]
    fn test_remove_oracle_noop_emits_orac_rm_with_none() {
        let env = Env::default();
        env.mock_all_auths();
        let admin = Address::generate(&env);
        let contract_id = env.register(StableRouteRouter, (admin,));
        let client = StableRouteRouterClient::new(&env, &contract_id);
        assert_eq!(client.get_oracle(), None);
        client.remove_oracle();
        let payloads = event_payloads(&env, symbol_short!("orac_rm"));
        assert_eq!(payloads.len(), 1);
        let removed: Option<Address> = TryFromVal::try_from_val(&env, &payloads[0])
            .expect("orac_rm decodes to Option<Address>");
        assert_eq!(removed, None);
        assert_eq!(client.get_oracle(), None);
    }
}

/// Inline unit tests for `compute_route_fee` key-construction optimisation.
///
/// These tests exercise the refactored paths where `DataKey` variants are
/// constructed once and reused, verifying that behaviour is unchanged and
/// that edge cases (bounded vs unbounded liquidity, cooldown gating,
/// fee cap/floor, consecutive calls, event payloads) are all covered.
#[cfg(test)]
mod test_compute_route_fee_keys {
    use super::*;
    use soroban_sdk::testutils::Address as _;
    use soroban_sdk::{symbol_short, Env};

    /// Helper: initialise a router, register USDC→EURC, set fee_bps.
    /// Returns `(client, admin)` so callers can use `admin` for
    /// `set_pair_liquidity` (which requires admin or oracle auth).
    fn setup(env: &Env, fee_bps: u32) -> (StableRouteRouterClient<'_>, Address) {
        env.mock_all_auths();
        let admin = Address::generate(env);
        let contract_id = env.register(StableRouteRouter, (admin.clone(),));
        let client = StableRouteRouterClient::new(env, &contract_id);
        client.register_pair(&symbol_short!("USDC"), &symbol_short!("EURC"));
        client.set_pair_fee_bps(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &fee_bps,
        );
        (client, admin)
    }

    // ── Happy-path: basic fee calculation ──────────────────────────

    #[test]
    fn fee_basic_with_50_bps() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 50);
        // 1_000_000 * 50 / 10_000 = 5_000
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(fee, 5_000);
    }

    #[test]
    fn fee_zero_when_fee_bps_is_zero() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(fee, 0);
    }

    // ── Guard: rejected paths ──────────────────────────────────────

    #[test]
    #[should_panic(expected = "Error(Contract, #5)")]
    fn rejects_unregistered_pair() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 50);
        // Never register the pair.
        client.compute_route_fee(
            &symbol_short!("AAAB"),
            &symbol_short!("CCCC"),
            &100_i128,
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn rejects_zero_amount() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 50);
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &0_i128,
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #6)")]
    fn rejects_negative_amount() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 50);
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &(-1_i128),
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #9)")]
    fn rejects_when_paused() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 50);
        client.pause();
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
    }

    // ── Bounds: min / max amount ───────────────────────────────────

    #[test]
    #[should_panic(expected = "Error(Contract, #10)")]
    fn rejects_below_minimum() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 50);
        client.set_pair_min_amount(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_i128,
        );
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &999_i128,
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #11)")]
    fn rejects_above_maximum() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 50);
        client.set_pair_max_amount(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500_i128,
        );
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &501_i128,
        );
    }

    #[test]
    fn succeeds_at_exact_minimum() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        client.set_pair_min_amount(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
        assert_eq!(fee, 0);
    }

    #[test]
    fn succeeds_at_exact_maximum() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        client.set_pair_max_amount(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500_i128,
        );
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500_i128,
        );
        assert_eq!(fee, 0);
    }

    // ── Liquidity: bounded and unbounded paths ─────────────────────

    #[test]
    #[should_panic(expected = "Error(Contract, #12)")]
    fn rejects_explicit_zero_liquidity() {
        let env = Env::default();
        let (client, admin) = setup(&env, 0);
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &0_i128,
        );
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_i128,
        );
    }

    #[test]
    #[should_panic(expected = "Error(Contract, #12)")]
    fn rejects_amount_exceeding_bounded_liquidity() {
        let env = Env::default();
        let (client, admin) = setup(&env, 0);
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500_i128,
        );
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &501_i128,
        );
    }

    #[test]
    fn succeeds_with_unbounded_liquidity_when_unset() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        // No liquidity set → treated as i128::MAX (unbounded).
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &i128::MAX,
        );
        assert_eq!(fee, 0);
    }

    #[test]
    fn bounded_liquidity_decremented_correctly() {
        let env = Env::default();
        let (client, admin) = setup(&env, 0);
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &10_000_i128,
        );
        let _fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &3_000_i128,
        );
        let remaining = client.get_pair_liquidity(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
        );
        assert_eq!(remaining, 7_000);
    }

    #[test]
    fn unbounded_liquidity_not_written() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        // No liquidity set → unbounded → no decrement.
        let _fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_i128,
        );
        // get_pair_liquidity returns 0 for absent slots.
        let liq = client.get_pair_liquidity(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
        );
        assert_eq!(liq, 0);
    }

    // ── Cooldown gating ────────────────────────────────────────────

    #[test]
    #[should_panic(expected = "Error(Contract, #17)")]
    fn rejects_within_cooldown_window() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        client.set_pair_cooldown(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &60_u64,
        );
        // First route succeeds.
        let _fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
        // Second route within 60s → rejected.
        client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
    }

    // ── Counter / timestamp / event side-effects ───────────────────

    #[test]
    fn counter_increments_on_each_route() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        let before = client.get_total_routes_all_time();
        let _f1 = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
        let after1 = client.get_total_routes_all_time();
        assert_eq!(after1, before + 1);
        let _f2 = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &200_i128,
        );
        let after2 = client.get_total_routes_all_time();
        assert_eq!(after2, before + 2);
    }

    #[test]
    fn pair_route_count_increments() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        let before = client.get_pair_route_count(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
        );
        let _f = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &500_i128,
        );
        let after = client.get_pair_route_count(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
        );
        assert_eq!(after, before + 1);
    }

    #[test]
    fn pair_volume_accumulates() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        let _f1 = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_i128,
        );
        let _f2 = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &2_500_i128,
        );
        let vol = client.get_pair_volume(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
        );
        assert_eq!(vol, 3_500);
    }

    #[test]
    fn last_route_at_is_stamped() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0);
        let before = env.ledger().timestamp();
        let _f = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &100_i128,
        );
        let ts = client.get_pair_last_route_at(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
        );
        assert_eq!(ts, Some(before));
    }

    // ── Consecutive calls: reentrancy lock released ────────────────

    #[test]
    fn consecutive_calls_succeed() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 10);
        for i in 1..=5 {
            let fee = client.compute_route_fee(
                &symbol_short!("USDC"),
                &symbol_short!("EURC"),
                &(i * 1_000_i128),
            );
            assert!(fee >= 0);
        }
        assert_eq!(client.get_total_routes_all_time(), 5);
    }

    // ── Fee cap / floor ────────────────────────────────────────────

    #[test]
    fn fee_capped_by_absolute_max() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 500); // 5% fee
        client.set_max_fee_absolute(&100_i128);
        // Without cap: 1_000_000 * 500 / 10_000 = 50_000 → capped to 100.
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_000_i128,
        );
        assert_eq!(fee, 100);
    }

    #[test]
    fn fee_raised_by_absolute_min() {
        let env = Env::default();
        let (client, _admin) = setup(&env, 0); // 0% fee
        client.set_min_fee_absolute(&500_i128);
        // Fee would be 0, but floor raises it to 500.
        let fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &10_000_i128,
        );
        assert_eq!(fee, 500);
    }

    // ── Edge: amount equals exact liquidity ─────────────────────────

    #[test]
    fn succeeds_when_amount_equals_liquidity() {
        let env = Env::default();
        let (client, admin) = setup(&env, 0);
        client.set_pair_liquidity(
            &admin,
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_i128,
        );
        let _fee = client.compute_route_fee(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
            &1_000_i128,
        );
        let remaining = client.get_pair_liquidity(
            &symbol_short!("USDC"),
            &symbol_short!("EURC"),
        );
        assert_eq!(remaining, 0);
    }
}