o2_deploy/

lib.rs

//! Contract deployment logic for the Fuel O2 exchange.
//!
//! This crate extracts the core deploy workflow from the `api` package,
//! making it reusable from both the API binary and the standalone `o2-deploy` CLI.

mod eval_minter;
mod eval_shop;
pub use eval_minter::{
    EvalAssetConfig,
    EvalMinterConfig,
    reconcile_eval_minter,
    reconcile_eval_minter_document,
};
mod sidecar;
pub use eval_shop::{
    EvalShopConfig,
    EvalShopPriceConfig,
};
#[cfg(test)]
mod tier_book_tests;
pub use sidecar::activate_sidecars;

use anyhow::Context;
use fuel_core_client::client::types::primitives::{
    ContractId,
    Salt,
};
use fuel_core_types::fuel_types::BlockHeight;
use fuels::{
    accounts::{
        Account,
        ViewOnlyAccount,
    },
    prelude::Execution,
    types::{
        Identity,
        SizedAsciiString,
    },
};
use o2_api_types::{
    domain::book::{
        AssetConfig,
        MarketIdAssets,
        OrderBookConfig,
        SidecarConfig,
    },
    parse::HexDisplayFromStr,
};
use o2_tools::{
    order_book::OrderBookManager,
    order_book_deploy::{
        OrderBookBlacklist,
        OrderBookConfigurables,
        OrderBookDeploy,
        OrderBookDeployConfig,
        OrderBookWhitelist,
    },
    order_book_registry::{
        OrderBookRegistryDeployConfig,
        OrderBookRegistryManager,
    },
    trade_account_deploy::{
        DeployConfig,
        TradeAccountDeploy,
        TradeAccountDeployConfig,
        TradingAccountOracle,
    },
    trade_account_registry::{
        TradeAccountRegistryConfigurables,
        TradeAccountRegistryDeployConfig,
        TradeAccountRegistryManager,
    },
    trial_trade_account_deploy::{
        DeployConfig as TrialDeployConfig,
        TrialTradeAccountDeploy,
        TrialTradeAccountDeployConfig,
        TrialTradingAccountOracle,
    },
};
use serde_with::serde_as;
use std::ops::{
    Deref,
    DerefMut,
};

pub use o2_tools::prop_deploy::{
    ExistingRegistry,
    PropDeployConfig,
    PropDeployment,
};

/// Access-control role that authorizes order-book maintenance actions
/// (`force_cancel_orders`, `cancel_blacklist_orders`, `eject_trigger_order`).
///
/// Must match `ORDERBOOK_MAINTAINER_ROLE` in `contracts/order-book/src/main.sw`.
const ORDERBOOK_MAINTAINER_ROLE: u64 = 1;

/// Access-control role on the prop margin pool that authorizes
/// `set_user_discount` - the ONLY caller that function accepts, the admin
/// included, so whoever prices user discounts must hold it.
///
/// Must match `DISCOUNT_MANAGER_ROLE` in
/// `contracts/prop-margin-pool/src/main.sw`.
const DISCOUNT_MANAGER_ROLE: u64 = 1;

/// Deploy the independent prop-account system.
///
/// This is additive to the existing exchange deployment: callers can choose
/// when to deploy the direct account oracle, mock price feed, proxied registry,
/// and proxied margin pool.
pub async fn deploy_prop_system<W>(
    wallet: &W,
    config: &PropDeployConfig,
) -> anyhow::Result<PropDeployment<W>>
where
    W: Account + Clone,
{
    // Generated ABI calls make this a large future. Keep it off callers'
    // stacks, including callers that perform several deployments in one task.
    Box::pin(PropDeployment::deploy(wallet, config)).await
}

fn to_registry_market_id(m: &MarketIdAssets) -> o2_tools::order_book_registry::MarketId {
    o2_tools::order_book_registry::MarketId {
        base_asset: m.base_asset,
        quote_asset: m.quote_asset,
    }
}

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

#[serde_as]
#[derive(Debug, serde::Serialize, Clone, Default)]
pub struct MarketsConfigOutput {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub eval_shop: Option<EvalShopConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub eval_minter: Option<EvalMinterConfig>,
    pub starting_height: u32,
    #[serde_as(as = "HexDisplayFromStr")]
    pub trade_account_registry_id: ContractId,
    #[serde_as(as = "HexDisplayFromStr")]
    pub trade_account_registry_blob_id: ContractId,
    #[serde_as(as = "HexDisplayFromStr")]
    pub trade_account_oracle_id: ContractId,
    #[serde_as(as = "HexDisplayFromStr")]
    pub trial_trade_account_oracle_id: ContractId,
    #[serde_as(as = "HexDisplayFromStr")]
    pub trade_account_root: ContractId,
    #[serde_as(as = "HexDisplayFromStr")]
    pub trade_account_proxy: ContractId,
    #[serde_as(as = "HexDisplayFromStr")]
    pub trade_account_blob_id: ContractId,
    #[serde_as(as = "Option<HexDisplayFromStr>")]
    pub order_book_whitelist_id: Option<ContractId>,
    #[serde_as(as = "Option<HexDisplayFromStr>")]
    pub order_book_blacklist_id: Option<ContractId>,
    #[serde_as(as = "HexDisplayFromStr")]
    pub order_book_registry_id: ContractId,
    #[serde_as(as = "HexDisplayFromStr")]
    pub order_book_registry_blob_id: ContractId,
    #[serde_as(as = "Option<HexDisplayFromStr>")]
    pub fast_bridge_asset_registry_proxy_id: Option<ContractId>,
    #[serde_as(as = "Option<HexDisplayFromStr>")]
    pub price_feed_id: Option<ContractId>,
    #[serde_as(as = "Option<HexDisplayFromStr>")]
    pub margin_pool_id: Option<ContractId>,
    #[serde_as(as = "Option<HexDisplayFromStr>")]
    pub margin_oracle_id: Option<ContractId>,
    /// The `margin` section, echoed back with the ids this run resolved
    /// folded in. CI writes the output OVER the deploy config, so anything
    /// the output drops is destroyed: without this the first margin deploy
    /// would erase the tier catalogue, the pool config, the publishers and
    /// the initial prices, and every later run would silently do no margin
    /// work at all.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub margin: Option<MarginConfig>,
    pub pairs: Vec<OrderBookConfig>,
}

/// Intermediate type for deserializing order book configs with string-encoded numbers.
#[serde_as]
#[derive(Debug, Clone, serde::Deserialize)]
struct OrderBookConfigDeHelper {
    #[serde_as(as = "Option<serde_with::DisplayFromStr>")]
    blob_id: Option<ContractId>,
    #[serde_as(as = "Option<serde_with::DisplayFromStr>")]
    contract_id: Option<ContractId>,
    #[serde_as(as = "serde_with::DisplayFromStr")]
    taker_fee: u64,
    #[serde_as(as = "serde_with::DisplayFromStr")]
    maker_fee: u64,
    #[serde_as(as = "serde_with::DisplayFromStr")]
    min_order: u64,
    #[serde_as(as = "serde_with::DisplayFromStr")]
    dust: u64,
    price_window: u8,
    #[serde(default)]
    allow_fractional_price: bool,
    base: AssetConfig,
    quote: AssetConfig,
    #[serde(default)]
    house_identities: Vec<String>,
    #[serde(default)]
    sidecar: Option<SidecarConfig>,
}

impl From<OrderBookConfigDeHelper> for OrderBookConfig {
    fn from(h: OrderBookConfigDeHelper) -> Self {
        let ids = MarketIdAssets {
            base_asset: h.base.asset,
            quote_asset: h.quote.asset,
        };
        let market_id = ids.market_id();
        OrderBookConfig {
            contract_id: h.contract_id,
            blob_id: h.blob_id,
            market_id,
            taker_fee: h.taker_fee,
            maker_fee: h.maker_fee,
            min_order: h.min_order,
            dust: h.dust,
            price_window: h.price_window,
            allow_fractional_price: h.allow_fractional_price,
            base: h.base,
            quote: h.quote,
            house_identities: h.house_identities,
            sidecar: h.sidecar,
        }
    }
}

#[derive(Debug, Clone, Default, serde::Serialize)]
pub struct MarketsConfigPartial {
    pub eval_shop: Option<EvalShopConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub eval_minter: Option<EvalMinterConfig>,
    pub starting_height: u32,
    pub trade_account_registry_id: Option<ContractId>,
    pub order_book_registry_id: Option<ContractId>,
    pub trade_account_oracle_id: Option<ContractId>,
    pub trial_trade_account_oracle_id: Option<ContractId>,
    /// Stable margin-account oracle proxy. Explicit IDs override the registry's
    /// live oracle; omission reuses it. Written back from the actual deployment.
    pub margin_oracle_id: Option<ContractId>,
    pub order_book_whitelist_id: Option<ContractId>,
    pub order_book_blacklist_id: Option<ContractId>,
    pub fast_bridge_asset_registry_proxy_id: Option<ContractId>,
    pub pairs: Vec<OrderBookConfig>,
    /// Optional `margin` section: the prop-account margin stack (price
    /// feed, pool, account oracle, in-place registry upgrade) plus the
    /// tier catalogue, deployed/upgraded idempotently after the books.
    pub margin: Option<MarginConfig>,
}

impl<'de> serde::Deserialize<'de> for MarketsConfigPartial {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[derive(serde::Deserialize, Default)]
        struct Helper {
            eval_shop: Option<EvalShopConfig>,
            eval_minter: Option<EvalMinterConfig>,
            #[serde(default)]
            starting_height: u32,
            trade_account_registry_id: Option<ContractId>,
            order_book_registry_id: Option<ContractId>,
            trade_account_oracle_id: Option<ContractId>,
            trial_trade_account_oracle_id: Option<ContractId>,
            margin_oracle_id: Option<ContractId>,
            order_book_whitelist_id: Option<ContractId>,
            order_book_blacklist_id: Option<ContractId>,
            fast_bridge_asset_registry_proxy_id: Option<ContractId>,
            #[serde(default)]
            pairs: Vec<OrderBookConfigDeHelper>,
            #[serde(default)]
            margin: Option<MarginConfig>,
        }
        let h = Helper::deserialize(deserializer)?;
        if let Some(margin) = &h.margin
            && margin.price_feed_id.is_some()
        {
            return Err(serde::de::Error::custom(
                "`margin.price_feed_id` moved into `margin.price_feed.id`. \
                 Refusing to load a config that uses the retired spelling: it \
                 would be ignored, a fresh feed would be derived, and the pool \
                 would be repointed at an oracle with no publisher. Move the id \
                 (and `publishers` / `supported_assets`) under \
                 `margin.price_feed`.",
            ));
        }
        Ok(MarketsConfigPartial {
            eval_shop: h.eval_shop,
            eval_minter: h.eval_minter,
            starting_height: h.starting_height,
            trade_account_registry_id: h.trade_account_registry_id,
            order_book_registry_id: h.order_book_registry_id,
            trade_account_oracle_id: h.trade_account_oracle_id,
            trial_trade_account_oracle_id: h.trial_trade_account_oracle_id,
            margin_oracle_id: h.margin_oracle_id,
            order_book_whitelist_id: h.order_book_whitelist_id,
            order_book_blacklist_id: h.order_book_blacklist_id,
            fast_bridge_asset_registry_proxy_id: h.fast_bridge_asset_registry_proxy_id,
            pairs: h.pairs.into_iter().map(Into::into).collect(),
            margin: h.margin,
        })
    }
}

/// One tier of the margin catalogue. Mirrors the on-chain `TierParams`
/// plus the tier id and the markets (order books) it covers. `line`
/// follows the config convention of u64 amounts as strings.
#[serde_as]
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MarginTierConfig {
    pub tier_id: u64,
    /// Credit line in collateral-asset base units, as a decimal string.
    #[serde_as(as = "serde_with::DisplayFromStr")]
    pub line: u64,
    pub leverage: u64,
    /// Initial session term in seconds. Prepaid tiers require a positive
    /// value; u64::MAX means no expiration.
    pub duration: u64,
    pub maintenance_bps: u64,
    pub open_buffer_bps: u64,
    pub liq_price_factor: u64,
    /// Historical paid-prolongation fees, in WHOLE collateral
    /// units as a decimal string - `"13.5"` at 9 decimals means
    /// `13_500_000_000` base units. Indexed six hours, day, week, month; a
    /// zero means the period is not offered. All four must be zero for an
    /// enabled prepaid tier; disabled catalogue entries may retain old fees.
    pub prolong_fee: [String; 4],
    pub max_credit_line_bps: u64,
    pub max_price_age: u64,
    /// Flat fee charged once at open, in WHOLE collateral units as a decimal
    /// string. Same form as `prolong_fee`.
    pub open_fee: String,
    /// Historical profit share; must be zero for an enabled prepaid tier.
    pub profit_share_bps: u64,
    pub price_band_bps: u64,
    /// Backend daily loss limit in basis points of `line` (0..=10_000).
    /// Omitted or null disables the policy; zero is a real zero-loss limit.
    /// Reconciliation treats changes like immutable tier economics and
    /// publishes a new version, preserving policies on historical versions.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub daily_loss_limit_bps: Option<u64>,
    /// Markets in this tier, referencing already-configured pairs by
    /// "BASE/QUOTE" symbol or by hex market id.
    pub markets: Vec<String>,
    /// Select each market's deployed sidecar instead of its canonical book.
    /// Defaults to canonical; independent of the prepaid account terms.
    #[serde(default)]
    pub sidecar: bool,
    /// The prepaid ("Turbo") sidecar. Its PRESENCE is what makes the tier
    /// prepaid: the version is published with `publish_tier_v3` and carries
    /// terms, and every reader keys the cohort off exactly that. Required
    /// for enabled tiers: entries without terms are rejected before any
    /// transactions, because the legacy publisher is disabled. Disabled
    /// entries only reconcile the sales gate and may retain legacy terms.
    ///
    /// Immutable once published - no setter exists on chain - so a change
    /// here is a NEW VERSION, exactly like a change to the economics.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub turbo: Option<MarginTurboConfig>,
    /// Whether the tier SELLS. Gates `open_session` only: a live session
    /// keeps every lifecycle call it was sold with, which is what lets an
    /// old catalogue be retired without stranding anybody on it.
    /// Disabled entries never publish versions or update books; unpublished
    /// disabled tiers are skipped. Their historical economics are not validated.
    ///
    /// Defaults to `true`, so an existing config keeps selling exactly what
    /// it sold before this field existed.
    #[serde(default = "tier_enabled_default")]
    pub enabled: bool,
}

/// Default for [`MarginTierConfig::enabled`] - a tier with no opinion sells.
fn tier_enabled_default() -> bool {
    true
}

/// The prepaid terms attached to a tier version, mirroring the pool's
/// `TurboTerms`. Published ATOMICALLY with the economics and the books, and
/// immutable afterwards.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MarginTurboConfig {
    /// The drawdown ESCALATOR in bps of `line`, indexed by rollovers used
    /// and clamped at the last entry. All zero leaves the tier's static
    /// floor alone; any non-zero entry opts the tier in.
    pub max_loss_bps: [u64; 4],
    /// Profit that EARNS one free rollover, in bps of `line`. Zero means
    /// the tier offers no rollover.
    pub rollover_profit_bps: u64,
    /// Consecutive free rollovers one session may earn.
    pub max_rollovers: u64,
}

impl From<&MarginTurboConfig> for o2_tools::prop::TurboTerms {
    fn from(turbo: &MarginTurboConfig) -> Self {
        Self {
            max_loss_bps: turbo.max_loss_bps,
            rollover_profit_bps: turbo.rollover_profit_bps,
            max_rollovers: turbo.max_rollovers,
        }
    }
}

/// One asset the price feed must know the decimals of. Registering the
/// decimals is what makes an asset SUPPORTED by the feed; publishing a
/// price for it is a separate, later act. Declaring assets here therefore
/// lets a freshly deployed feed be configured up front, before any
/// publisher has produced a single quote.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct MarginSupportedAsset {
    pub asset: fuels::types::AssetId,
    pub decimals: u8,
}

/// The `price_feed` sub-section: everything about the ORACLE the pool values
/// against, kept apart from the pool's own settings because it is a separate
/// contract with its own lifecycle, ownership and roles.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct MarginPriceFeedConfig {
    /// Reuse an existing feed. `None` deploys the production price feed
    /// behind its own SRC-14 proxy.
    pub id: Option<ContractId>,
    /// Submission-age bound in seconds, reconciled compare-first. `None`
    /// leaves whatever the feed enforces today.
    pub max_offchain_age_seconds: Option<u64>,
    /// Identities that must HOLD the submitter role, each prefixed with its
    /// kind (`address:0x..` for a wallet, `contract:0x..` for a publishing
    /// contract). Reconciled compare-first: an identity that already holds it
    /// costs no transaction. When empty, nothing is granted and only the
    /// feed's owner may publish.
    #[serde(default)]
    pub publishers: Vec<String>,
    /// Identities that must NOT hold the submitter role, same prefixed form,
    /// revoked only if currently held.
    ///
    /// An explicit list on purpose. The feed stores roles as a bitmap keyed
    /// BY ACCOUNT with no reverse index, so neither the contract nor this
    /// deploy can enumerate who holds the role - "revoke everyone not in
    /// `publishers`" is not a question that can be asked on chain, and
    /// inferring it from config absence would silently kick out a publisher
    /// granted out of band.
    ///
    /// Revoking stops FUTURE writes only. A price the publisher already
    /// pushed stays live until it ages out or is invalidated explicitly.
    #[serde(default)]
    pub remove_publishers: Vec<String>,
    /// Assets the feed supports, registered by their decimals before any price
    /// exists. Reconciled compare-first: an asset the feed already knows at the
    /// SAME decimals is skipped, an unknown one is registered, and a
    /// DISAGREEMENT is refused rather than overwritten. The pool pins an
    /// asset's decimals on first use and rejects a later change, so silently
    /// moving them here would strand it.
    #[serde(default)]
    pub supported_assets: Vec<MarginSupportedAsset>,
}

/// Optional `margin` section of the deploy config: the prop margin pool,
/// the prop account oracle, the price feed and the tier catalogue.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct MarginConfig {
    /// The price feed: its own contract, its own section.
    #[serde(default)]
    pub price_feed: MarginPriceFeedConfig,
    /// The RETIRED flat spelling of `price_feed.id`, present only so that a
    /// stale config is REJECTED rather than silently ignored.
    ///
    /// Silence here is catastrophic rather than untidy: an unread feed id
    /// means the run derives a FRESH feed, and the pool-feed reconcile then
    /// moves a live pool onto an oracle nobody publishes to. Every
    /// valuation, liquidation and session open fails afterwards.
    ///
    /// Never serialized, so the write-back drops it once migrated.
    #[serde(default, skip_serializing)]
    pub price_feed_id: Option<ContractId>,
    /// TIER-ONLY mode: run no system deploy, only reconcile the tier
    /// catalogue (and the feed's roster/assets when configured) against
    /// this already-deployed pool.
    pub margin_pool_id: Option<ContractId>,
    /// Identity receiving the platform profit share, prefixed with its
    /// kind (`address:0x..` / `contract:0x..`). Defaults to the deployer.
    pub platform_payout: Option<String>,
    /// The pool's OWN cosigner for `expire_or_rollover` and
    /// `force_close_session_signed`, including closure before expiry.
    /// A bare address (`0x..`, or unprefixed like every other id
    /// here) - an ADDRESS, never a key: this file is committed.
    ///
    /// While the pool has none, NO prepaid deadline can be settled at all -
    /// every call reverts with `ExpiryCosignerNotSet` - so a pool deployed
    /// without this has Turbo bricked. That is why it is carried in the
    /// config rather than left to a flag someone must remember: the value
    /// belongs to the DEPLOYMENT and has to survive run to run, the same
    /// reason `discount_managers` and `platform_payout` live here.
    ///
    /// `--margin-expiry-cosigner` overrides it for a single run; see the
    /// merge in `deploy_margin`.
    ///
    /// Distinct from the ORACLE's cosigner (a deploy flag, since that one
    /// names the operator's own signing key): separate contracts, separate
    /// addresses, which MAY be configured to the same key.
    pub expiry_cosigner: Option<fuels::types::Address>,
    /// Identities that must HOLD the pool's discount-manager role - the
    /// only role `set_user_discount` accepts, the admin included - each
    /// prefixed with its kind (`address:0x..` / `contract:0x..`).
    /// Reconciled compare-first: an identity that already holds it costs
    /// no transaction. When empty, nothing is granted and NOBODY can
    /// price user discounts.
    ///
    /// A ROSTER, so it lives in the config beside the feed's `publishers`
    /// rather than in a deploy flag: the cosigner and the liquidator are
    /// flags because they name the operator's own key and payee, while
    /// this is a list the deployment owns and carries forward run to run.
    #[serde(default)]
    pub discount_managers: Vec<String>,
    /// Identities that must NOT hold the discount-manager role, same
    /// prefixed form, revoked only if currently held.
    ///
    /// An explicit list for the same reason `remove_publishers` is one:
    /// roles are a bitmap keyed BY ACCOUNT with no reverse index, so
    /// "revoke everyone not in `discount_managers`" is not a question
    /// that can be asked on chain, and inferring it from config absence
    /// would silently kick out a manager granted out of band.
    ///
    /// Revoking stops FUTURE writes only: discounts the manager already
    /// granted stay in force until cleared.
    #[serde(default)]
    pub remove_discount_managers: Vec<String>,
    /// Collateral asset of the pool. Defaults to the quote asset of the
    /// first configured pair.
    pub collateral_asset: Option<fuels::types::AssetId>,
    /// Collateral asset decimals. REQUIRED: a wrong figure misprices every
    /// valuation the pool makes, so there is no default to fall back to.
    pub collateral_decimals: Option<u8>,
    /// Maximum order books one tier version may hold. Defaults to 80.
    pub max_tier_books: Option<u64>,
    /// Fee charged by `repay_base_from_collateral`, in PARTS PER MILLION of the
    /// quote value of the debt closed - the order book's `TAKER_FEE` scale, so
    /// `100` is one basis point. Defaults to 100.
    ///
    /// It is a pool CONFIGURABLE, so changing it here only takes effect on a
    /// deploy or an implementation upgrade (`--upgrade-bytecode`), never on a
    /// tier-only reconcile against an already-deployed pool.
    pub base_repay_fee_ppm: Option<u64>,
    /// The desired tier catalogue; reconciled idempotently (§ tier engine):
    /// enabled tiers publish new versions for changed economics and use
    /// `add_books` for grown book lists. Disabled entries only close sales.
    #[serde(default)]
    pub tiers: Vec<MarginTierConfig>,
}

#[derive(Debug, Clone, Default)]
pub struct OwnershipTransferOptions {
    pub new_proxy_owner: Option<fuels::types::Address>,
    pub new_contract_owner: Option<fuels::types::Address>,
    /// Accounts to revoke `ORDERBOOK_MAINTAINER_ROLE` from on each order book
    /// (via `owner_revoke_role`) before granting the new maintainers, so the role
    /// is rotated rather than accumulating holders across upgrades.
    pub revoke_orderbook_maintainers: Vec<fuels::types::Address>,
    /// Accounts to grant `ORDERBOOK_MAINTAINER_ROLE` to on each order book (via
    /// `owner_grant_role`) before ownership is transferred away.
    pub new_orderbook_maintainers: Vec<fuels::types::Address>,
}

/// Parameters for a deploy invocation.
#[derive(Debug, Clone)]
pub struct DeployParams {
    pub deploy_config: MarketsConfigPartial,
    pub output: Option<String>,
    pub deploy_whitelist: bool,
    pub deploy_blacklist: bool,
    pub upgrade_bytecode: bool,
    pub new_proxy_owner: Option<fuels::types::Address>,
    pub new_contract_owner: Option<fuels::types::Address>,
    /// Cosigner address for trial trade accounts. When set, the trial trade
    /// account implementation is (re)deployed on the trial oracle and this
    /// cosigner is configured on it; when absent, the configured cosigner is
    /// left untouched (the implementation still follows the regular
    /// seed/upgrade lifecycle).
    pub trial_cosigner: Option<fuels::types::Address>,
    /// Identity allowed to register (activate) trial trade accounts on the
    /// registry. When set, it is written via
    /// `set_trial_trade_account_creator` if it differs from the current one
    /// — registries upgraded in place start with the creator unset, which
    /// denies all trial registrations. When absent, the creator is left
    /// untouched.
    pub trial_creator: Option<Identity>,
    /// Reconcile margin CONFIGURATION only, leaving BYTECODE — the pool, the
    /// oracle, the price-feed implementation — and the registry's prop wiring
    /// untouched.
    ///
    /// It does still reconcile the things that are configuration rather than
    /// code: the tier catalogue, the feed's publisher roster, its supported
    /// assets, its submission-age bound, and the pool's feed pointer. That is
    /// the point of the mode — rotating a publisher must not need a redeploy.
    ///
    /// An explicit switch rather than an inference from the markets
    /// config: the mode decides WHETHER the system phase runs, which is
    /// unrelated to WHICH pool the config names. Conflating the two meant
    /// the ordinary steady state disabled the phase that owns the
    /// registry's prop configurables, so an upgrade that dropped them was
    /// never repaired.
    pub margin_tier_only: bool,
    /// Cosigner address for prop/margin accounts. When set, it is written to
    /// the prop account oracle if it differs from the live one; when absent,
    /// the configured cosigner is left untouched. Deliberately NOT sourced
    /// from the deploy config and NOT defaulted to the deployer: a cosigner
    /// the backend does not hold the key for makes margin silently inert.
    pub margin_cosigner: Option<fuels::types::Address>,
    /// Recipient of the residue from forced margin exits (liquidation and
    /// expiry). Same opt-in rule as `margin_cosigner`: set it and it is
    /// reconciled, omit it and the live value stands. Never defaulted to the
    /// deployer - the deploy key must not silently become the payee.
    pub margin_liquidator: Option<Identity>,
    /// One-run OVERRIDE of `margin.expiry_cosigner` from the deploy config,
    /// which is where this value normally lives. Set it and it wins for this
    /// run; omit it and the config file stands. Omitting BOTH leaves the live
    /// pool's cosigner untouched - it is never defaulted to the deployer on a
    /// pool that already has one.
    ///
    /// A pool that has none settles NO prepaid deadline at all - every
    /// `expire_or_rollover` reverts with `ExpiryCosignerNotSet` - so a pool
    /// deployed without this cannot settle prepaid deadlines or signed forced closes.
    ///
    /// Distinct from `margin_cosigner`, which has no config spelling at all:
    /// separate contracts, separate addresses, which MAY hold the same key.
    pub margin_expiry_cosigner: Option<fuels::types::Address>,
    pub revoke_orderbook_maintainers: Vec<fuels::types::Address>,
    pub new_orderbook_maintainers: Vec<fuels::types::Address>,
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Load a JSON config file, returning `T::default()` when the path is empty.
pub fn load_config_from_file<T>(config_path: &str) -> anyhow::Result<T>
where
    T: Default + serde::de::DeserializeOwned,
{
    if config_path.is_empty() {
        return Ok(T::default());
    }
    let current_dir = std::env::current_dir()?;
    let path = current_dir.join(config_path);
    tracing::info!("Loading config from {}", path.display());
    let file = std::fs::File::open(&path)?;
    let config: T = serde_json::from_reader(file)?;
    Ok(config)
}

// ---------------------------------------------------------------------------
// Core deploy logic
// ---------------------------------------------------------------------------

/// Deploy (or upgrade) the full set of O2 contracts.
///
/// The wallet type `W` must implement `Account + Clone + Signer` (e.g.
/// `fuels::prelude::WalletUnlocked` or the KMS-backed `O2Wallet` from the API).
pub async fn deploy<W>(
    wallet: W,
    mut params: DeployParams,
) -> anyhow::Result<MarketsConfigOutput>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    sidecar::validate_config(&params.deploy_config.pairs)?;
    if let Some(shop) = &params.deploy_config.eval_shop {
        eval_shop::validate_config(shop)?;
    }
    if let Some(minter) = &params.deploy_config.eval_minter {
        eval_minter::validate_config(minter)?;
    }
    // Validate the chosen oracle and its immutable pool binding before even
    // closing retired tiers or upgrading the ordinary registry. The explicit
    // config may intentionally restore an oracle different from the live one.
    if !params.margin_tier_only
        && let Some(margin) = &mut params.deploy_config.margin
        && let Some(existing) = o2_tools::prop_deploy::resolve_existing_oracle(
            &wallet,
            params.deploy_config.margin_oracle_id,
            params.deploy_config.trade_account_registry_id,
            margin.margin_pool_id,
        )
        .await?
    {
        params.deploy_config.margin_oracle_id = Some(existing.oracle_id);
        margin.margin_pool_id = margin.margin_pool_id.or(existing.pool_id);
    }
    if let Some(margin) = &params.deploy_config.margin {
        // Validate every enabled tier before any writes, including sales-gate
        // changes. Retired entries may keep their historical economics.
        validate_margin_tier_catalogue(margin)?;
        if let Some(pool_id) = margin.margin_pool_id
            && wallet.try_provider()?.contract_exists(&pool_id).await?
        {
            // Close retired tiers under the old implementation, before any
            // upgrade can change how their stored duration is interpreted.
            let pool =
                o2_tools::prop::PropMarginPoolContract::new(pool_id, wallet.clone());
            reconcile_disabled_margin_tiers(&pool, &margin.tiers).await?;
        }
    }
    tracing::info!("Starting Fuel o2 Registries and Markets");
    let mut markets_config_partial = params.deploy_config.clone();
    let starting_height: BlockHeight = markets_config_partial.starting_height.into();
    let trade_account_oracle_id = markets_config_partial.trade_account_oracle_id;
    let trial_trade_account_oracle_id =
        markets_config_partial.trial_trade_account_oracle_id;
    let order_book_registry_id = markets_config_partial.order_book_registry_id;
    let trade_account_registry_id = markets_config_partial.trade_account_registry_id;
    let fast_bridge_asset_registry_proxy_id =
        markets_config_partial.fast_bridge_asset_registry_proxy_id;

    let mut salt = Salt::zeroed();
    salt.deref_mut()[..4].copy_from_slice(&starting_height.deref().to_be_bytes());

    let (trade_account_oracle_deploy, trade_account_blob_id) =
        deploy_trade_account_oracle(
            wallet.clone(),
            params.upgrade_bytecode,
            trade_account_oracle_id,
            salt,
        )
        .await?;
    // The trial oracle is a dedicated contract (already-deployed trade
    // account oracles are immutable and cannot gain the trial functions), so
    // it deploys separately and the registry references both oracle ids.
    let trial_trade_account_oracle_id = deploy_trial_trade_account_oracle(
        wallet.clone(),
        params.upgrade_bytecode,
        trial_trade_account_oracle_id,
        params.trial_cosigner,
        salt,
    )
    .await?;
    let (trade_account_registry, _) = deploy_trade_account_registry(
        wallet.clone(),
        params.upgrade_bytecode,
        trade_account_oracle_deploy.clone(),
        trial_trade_account_oracle_id,
        trade_account_registry_id,
        salt,
    )
    .await?;
    let order_book_blacklist_id = deploy_order_book_blacklist(
        wallet.clone(),
        params.deploy_blacklist,
        markets_config_partial.order_book_blacklist_id,
        salt,
    )
    .await?;
    let order_book_whitelist_id = deploy_order_book_whitelist(
        wallet.clone(),
        params.deploy_whitelist,
        markets_config_partial.order_book_whitelist_id,
        salt,
    )
    .await?;
    let (order_book_registry, order_book_registry_blob_id) = deploy_order_book_registry(
        wallet.clone(),
        params.upgrade_bytecode,
        order_book_registry_id,
        salt,
    )
    .await?;
    let pairs = deploy_order_books(
        wallet.clone(),
        params.upgrade_bytecode,
        order_book_blacklist_id,
        order_book_whitelist_id,
        order_book_registry.clone(),
        &mut markets_config_partial.pairs,
        OwnershipTransferOptions {
            new_proxy_owner: params.new_proxy_owner,
            new_contract_owner: params.new_contract_owner,
            revoke_orderbook_maintainers: params.revoke_orderbook_maintainers.clone(),
            new_orderbook_maintainers: params.new_orderbook_maintainers.clone(),
        },
    )
    .await?;

    let order_book_registry_id = order_book_registry.contract_id;
    let trade_account_registry_id = trade_account_registry.contract_id;
    let trade_account_oracle_id = trade_account_oracle_deploy.oracle_id;

    // The margin phase runs BEFORE ownership transfer: the in-place
    // registry upgrade and the pool/tier governance calls need the deployer
    // to still hold the proxies and the pool admin role.
    let margin_ids = match &markets_config_partial.margin {
        Some(margin) => Some(
            deploy_margin(
                &wallet,
                margin,
                markets_config_partial.margin_oracle_id,
                salt,
                params.margin_tier_only,
                trade_account_registry_id,
                trade_account_oracle_id,
                trial_trade_account_oracle_id,
                &pairs,
                params.margin_cosigner,
                params.margin_liquidator,
                params.margin_expiry_cosigner,
                params.upgrade_bytecode,
            )
            .await?,
        ),
        None => None,
    };

    // Registries upgraded in place start with the trial creator unset (the
    // configurable seed only applies on the first initialize), so the deploy
    // writes it explicitly when provided. Must run before ownership transfer.
    if let Some(trial_creator) = params.trial_creator {
        let current_creator = trade_account_registry
            .get_trial_trade_account_creator()
            .await?;
        if current_creator != trial_creator {
            tracing::info!("Setting trial trade account creator to {trial_creator:?}");
            trade_account_registry
                .set_trial_trade_account_creator(trial_creator)
                .await?;
        }
    }

    let eval_shop = match &markets_config_partial.eval_shop {
        Some(config) => Some(
            eval_shop::deploy_and_reconcile(
                &wallet,
                config,
                trade_account_registry_id,
                salt,
                &params,
            )
            .await?,
        ),
        None => None,
    };

    let eval_minter = match &markets_config_partial.eval_minter {
        Some(config) => {
            Some(eval_minter::deploy_and_reconcile(&wallet, config, salt, &params).await?)
        }
        None => None,
    };

    transfer_ownership(
        &wallet,
        &params,
        &order_book_registry,
        &trade_account_registry,
        &trade_account_oracle_deploy,
        trial_trade_account_oracle_id,
        order_book_blacklist_id,
        order_book_whitelist_id,
    )
    .await?;

    // The margin phase can retarget the registry again. Report the final
    // on-chain target and templates, not the earlier ordinary-registry result.
    let trade_account_registry_blob_id = trade_account_registry
        .registry_proxy
        .methods()
        .proxy_target()
        .simulate(Execution::state_read_only())
        .await?
        .value
        .context("trade account registry has no target after deployment")?;
    let trade_account_proxy = trade_account_registry
        .registry
        .methods()
        .default_bytecode()
        .simulate(Execution::state_read_only())
        .await?
        .value
        .context(
            "Trade account registry default bytecode should exist after initialization",
        )?;
    let trade_account_root = trade_account_registry
        .registry
        .methods()
        .factory_bytecode_root()
        .simulate(Execution::state_read_only())
        .await?
        .value
        .context("Trade account registry factory bytecode root should exist after initialization")?;

    let deploy_result = MarketsConfigOutput {
        eval_shop,
        eval_minter,
        starting_height: starting_height.into(),
        trade_account_registry_id,
        trade_account_registry_blob_id,
        trade_account_proxy,
        trade_account_blob_id,
        trade_account_root: ContractId::from(trade_account_root.0),
        trade_account_oracle_id,
        trial_trade_account_oracle_id,
        order_book_whitelist_id,
        order_book_blacklist_id,
        order_book_registry_id,
        order_book_registry_blob_id,
        pairs,
        fast_bridge_asset_registry_proxy_id,
        price_feed_id: margin_ids.map(|ids| ids.price_feed_id),
        margin_pool_id: margin_ids.map(|ids| ids.margin_pool_id),
        margin_oracle_id: margin_ids.and_then(|ids| ids.margin_oracle_id),
        // Persist resolved IDs so a subsequent deployment reuses the same
        // contracts, even when implementation bytecode or derivation changes.
        margin: markets_config_partial.margin.clone().map(|mut margin| {
            if let Some(ids) = margin_ids {
                margin.price_feed.id = Some(ids.price_feed_id);
                margin.margin_pool_id = Some(ids.margin_pool_id);
            }
            margin
        }),
    };

    if let Some(output_path) = params.output {
        let json = serde_json::to_string_pretty(&deploy_result)?;
        tracing::info!("Deploy result saved to {}", output_path);
        std::fs::write(output_path, json)?;
    }

    Ok(deploy_result)
}

// ---------------------------------------------------------------------------
// Margin (prop) deployment
// ---------------------------------------------------------------------------

/// The margin stack's resolved ids, echoed on the deploy output.
#[derive(Debug, Clone, Copy)]
pub struct MarginIds {
    pub price_feed_id: ContractId,
    pub margin_pool_id: ContractId,
    pub margin_oracle_id: Option<ContractId>,
}

/// The margin phase of [`deploy`]: the prop system deployed/resumed
/// deterministically (salted ids, exists-checked steps), the SHARED
/// trade-account registry upgraded IN PLACE to carry the prop
/// configurables, and the tier catalogue reconciled. With `tier_only` the
/// system deploy is skipped and only the feed and tier reconciliation runs
/// against the pool the config names.
///
/// Every step is compare-first: it reads the live value and sends nothing
/// when the chain already agrees. A settled system therefore costs a run of
/// reads and no transactions, which is what a rehearsal used to be for.
#[allow(clippy::too_many_arguments)]
async fn deploy_margin<W>(
    wallet: &W,
    margin: &MarginConfig,
    existing_margin_oracle: Option<ContractId>,
    salt: fuels::types::Salt,
    tier_only: bool,
    trade_account_registry_id: ContractId,
    trade_account_oracle_id: ContractId,
    trial_trade_account_oracle_id: ContractId,
    pairs: &[OrderBookConfig],
    margin_cosigner: Option<fuels::types::Address>,
    margin_liquidator: Option<Identity>,
    margin_expiry_cosigner: Option<fuels::types::Address>,
    upgrade_bytecode: bool,
) -> anyhow::Result<MarginIds>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    use o2_tools::prop::{
        PriceFeedContract,
        PropAccountOracleContract,
        PropMarginPoolContract,
    };

    let collateral_asset = match margin.collateral_asset {
        Some(collateral_asset) => collateral_asset,
        None => {
            pairs
                .first()
                .context(
                    "margin.collateral_asset is not set and there are no pairs to \
                     default it from",
                )?
                .quote
                .asset
        }
    };
    // The cosigner and the liquidator arrive as DEPLOY PARAMETERS, not from
    // the config file: both name a key or a payee that belongs to the
    // operator running the deploy, and both are opt-in - provide one and it
    // is reconciled, omit it and whatever is live stands.
    let cosigner = margin_cosigner;
    let platform_payout = margin
        .platform_payout
        .as_deref()
        .map(parse_margin_identity)
        .transpose()?;
    let liquidator = margin_liquidator;
    // The expiry cosigner is the exception to the paragraph above: it is
    // deployment state, not an operator key, so the config file carries it
    // and the deploy does not depend on anyone remembering a flag.
    //
    // PRECEDENCE: the flag WINS when both are given, so a rotation can be
    // driven from a single workflow run before the config PR lands; the
    // config stands whenever the flag is absent. Supplying NEITHER leaves
    // this `None`, and the pool is left exactly as it was found.
    let expiry_cosigner = margin_expiry_cosigner.or(margin.expiry_cosigner);

    let mut prop_config = PropDeployConfig::new(collateral_asset);
    // No default: a wrong decimals figure misprices every valuation the pool
    // makes, and it is invisible until money moves.
    prop_config.collateral_decimals = margin.collateral_decimals.context(
        "margin.collateral_decimals is required - set it to the collateral \
         asset's decimals in the deploy config",
    )?;
    prop_config.max_tier_books = margin.max_tier_books.unwrap_or(80);
    prop_config.base_repay_fee_ppm = margin.base_repay_fee_ppm.unwrap_or(100);
    prop_config.cosigner = cosigner;
    prop_config.platform_payout = platform_payout;
    prop_config.liquidator = liquidator;
    prop_config.salt = salt;
    prop_config.existing_oracle = existing_margin_oracle;
    prop_config.existing_price_feed = margin.price_feed.id;
    prop_config.max_offchain_age_seconds = margin.price_feed.max_offchain_age_seconds;
    // The config names WHICH pool; it no longer decides whether the system
    // phase runs. Pinning it also keeps an upgrade from forking the pool
    // when a release changes the pool bytecode.
    prop_config.existing_pool = margin.margin_pool_id;
    prop_config.existing_registry = Some(ExistingRegistry {
        registry_id: trade_account_registry_id,
        trade_account_oracle_id,
        trial_trade_account_oracle_id,
    });

    anyhow::ensure!(
        !(tier_only && margin.margin_pool_id.is_none()),
        "--margin-tier-only was requested but the markets config names no \
         `margin.margin_pool_id`: there is no pool to reconcile tiers against"
    );

    // Resolve the system: tier-only mode, or a real deploy-or-resume.
    let (price_feed_id, margin_pool_id, margin_oracle_id) = if let (
        true,
        Some(margin_pool_id),
    ) =
        (tier_only, margin.margin_pool_id)
    {
        tracing::info!("Margin: tier-only mode against pool {margin_pool_id}");
        let price_feed_id = match margin.price_feed.id {
            Some(price_feed_id) => price_feed_id,
            None => {
                PropMarginPoolContract::new(margin_pool_id, wallet.clone())
                    .methods()
                    .price_feed()
                    .simulate(Execution::state_read_only())
                    .await
                    .context("read the pool's price feed")?
                    .value
            }
        };
        // Read the oracle back off the registry rather than reporting
        // `None`. The caller writes what it gets straight into
        // markets.json, so a `None` here NULLS a live, known-good id —
        // the same class of mistake as writing ids a rehearsal never
        // deployed.
        let margin_oracle_id =
            TradeAccountRegistryManager::new(wallet.clone(), trade_account_registry_id)
                .registry
                .methods()
                .get_prop_oracle_id()
                .simulate(Execution::state_read_only())
                .await
                .map(|result| result.value)
                .ok()
                .filter(|oracle_id| *oracle_id != ContractId::zeroed());
        (price_feed_id, margin_pool_id, margin_oracle_id)
    } else {
        let deployment = deploy_prop_system(wallet, &prop_config).await?;
        tracing::info!(
            "Margin: oracle {}, pool {}, feed {} (shared registry {} upgraded in place)",
            deployment.oracle_id,
            deployment.pool_id,
            deployment.price_feed_id,
            deployment.registry_id,
        );
        (
            deployment.price_feed_id,
            deployment.pool_id,
            Some(deployment.oracle_id),
        )
    };

    // -- the payout parties ----------------------------------------------
    // Reconciled compare-first against the LIVE pool, so a re-run is a
    // no-op and an absent config key never overwrites what the pool has.
    // A pool not deployed yet gets both values through its INITIAL_*
    // configurables on the real run.
    let pool_deployed = wallet
        .try_provider()?
        .contract_exists(&margin_pool_id)
        .await?;
    if pool_deployed {
        let pool = PropMarginPoolContract::new(margin_pool_id, wallet.clone());
        if let Some(platform_payout) = platform_payout {
            let current = pool
                .methods()
                .platform_payout()
                .simulate(Execution::state_read_only())
                .await
                .context("read the pool's platform payout")?
                .value;
            if current != platform_payout {
                tracing::info!(
                    "Margin: platform payout {current:?} -> {platform_payout:?}"
                );
                pool.methods()
                    .set_platform_payout(platform_payout)
                    .call()
                    .await?;
            }
        }
        if let Some(liquidator) = liquidator {
            let current = pool
                .methods()
                .liquidator()
                .simulate(Execution::state_read_only())
                .await
                .context("read the pool's liquidator")?
                .value;
            if current != liquidator {
                tracing::info!("Margin: liquidator {current:?} -> {liquidator:?}");
                pool.methods().set_liquidator(liquidator).call().await?;
            }
        }

        // -- who may settle a prepaid deadline -----------------------------
        // Reconciled here as well as through the system deploy, so TIER-ONLY
        // mode honours it: the pool's expiry cosigner is configuration, not
        // bytecode, and a pool that has none settles nothing at all.
        //
        // `Option`-aware, like the oracle's cosigner below: the pool answers
        // `None` until someone writes one, so the read is matched against
        // `Some(expiry_cosigner)` rather than unwrapped. Compare-first, so the
        // settled case sends nothing and the double-apply on a full deploy is
        // free.
        if let Some(expiry_cosigner) = expiry_cosigner {
            let current = pool
                .methods()
                .expiry_cosigner()
                .simulate(Execution::state_read_only())
                .await
                .context("read the pool's expiry cosigner")?
                .value;
            if current != Some(expiry_cosigner) {
                tracing::info!(
                    "Margin: expiry cosigner {current:?} -> {expiry_cosigner:?}"
                );
                pool.methods()
                    .set_expiry_cosigner(expiry_cosigner)
                    .call()
                    .await?;
            }
        } else {
            // Nothing configured. Say so if the pool has none either: while it
            // is unset NO prepaid (Turbo) deadline can be settled at all, and
            // nothing else in the system notices.
            let current = pool
                .methods()
                .expiry_cosigner()
                .simulate(Execution::state_read_only())
                .await
                .context("read the pool's expiry cosigner")?
                .value;
            if current.is_none() {
                tracing::warn!(
                    "Margin: no expiry cosigner configured and this pool has \
                     none - PREPAID (Turbo) deadlines cannot be settled until \
                     `margin.expiry_cosigner` names the address of the \
                     backend's margin cosigner key."
                );
            }
        }

        // -- the discount managers -----------------------------------------
        // The feed's publisher roster, part for part: granted and revoked
        // only where the pool disagrees with the config, so a settled
        // roster sends nothing at all.
        //
        // An identity in BOTH lists would be granted and then revoked in
        // the same run, silently, decided by iteration order. Refuse the
        // ambiguity.
        for entry in &margin.discount_managers {
            anyhow::ensure!(
                !margin.remove_discount_managers.contains(entry),
                "discount manager {entry} is listed in both \
                 `discount_managers` and `remove_discount_managers`"
            );
        }
        for (entry, should_hold) in margin
            .discount_managers
            .iter()
            .map(|entry| (entry, true))
            .chain(
                margin
                    .remove_discount_managers
                    .iter()
                    .map(|entry| (entry, false)),
            )
        {
            let manager = parse_margin_identity(entry)?;
            let holds = pool
                .methods()
                .has_role(DISCOUNT_MANAGER_ROLE, manager)
                .simulate(Execution::state_read_only())
                .await
                .context("read a discount manager's role")?
                .value;
            if holds == should_hold {
                continue;
            }
            if should_hold {
                tracing::info!("Margin: adding discount manager {manager:?}");
                pool.methods()
                    .grant_role(DISCOUNT_MANAGER_ROLE, manager)
                    .call()
                    .await
                    .context("grant a discount manager its role")?;
            } else {
                tracing::info!("Margin: removing discount manager {manager:?}");
                pool.methods()
                    .revoke_role(DISCOUNT_MANAGER_ROLE, manager)
                    .call()
                    .await
                    .context("revoke a discount manager's role")?;
            }
        }
    }

    // Tier-only mode resolves no oracle of its own - ask the live registry,
    // which is the same lookup the backend performs at boot.
    let margin_oracle_id = match margin_oracle_id {
        Some(oracle_id) => Some(oracle_id),
        None if cosigner.is_some() => {
            let registry = o2_tools::trade_account_registry::TradeAccountRegistry::new(
                trade_account_registry_id,
                wallet.clone(),
            );
            let oracle_id = registry
                .methods()
                .get_prop_oracle_id()
                .simulate(Execution::state_read_only())
                .await
                .context("read the registry's prop account oracle")?
                .value;
            (oracle_id != ContractId::zeroed()).then_some(oracle_id)
        }
        None => None,
    };

    // The cosigner lives on the ORACLE, not the pool, and only reaches
    // storage through INITIAL_COSIGNER on the very first initialize - so an
    // already-initialized oracle needs this explicit reconciliation, or
    // "set it if provided" would silently mean "only on a fresh deploy".
    if let (Some(cosigner), Some(oracle_id)) = (cosigner, margin_oracle_id)
        && wallet.try_provider()?.contract_exists(&oracle_id).await?
    {
        let oracle = PropAccountOracleContract::new(oracle_id, wallet.clone());
        let current = oracle
            .methods()
            .get_cosigner()
            .simulate(Execution::state_read_only())
            .await
            .context("read the prop account oracle's cosigner")?
            .value;
        if current != Some(cosigner) {
            tracing::info!("Margin: cosigner {current:?} -> {cosigner:?}");
            oracle.methods().set_cosigner(cosigner).call().await?;
        }
    }

    // -- who may publish --------------------------------------------------
    // Compare-first, like every other reconcile here: the role is granted or
    // revoked only when the feed disagrees with the config, so a settled
    // roster sends nothing at all.
    //
    // An identity in BOTH lists would be granted and then revoked in the same
    // run, silently, decided by iteration order. Refuse the ambiguity.
    for entry in &margin.price_feed.publishers {
        anyhow::ensure!(
            !margin.price_feed.remove_publishers.contains(entry),
            "price feed publisher {entry} is listed in both `publishers` and \
             `remove_publishers`"
        );
    }
    let price_feed = PriceFeedContract::new(price_feed_id, wallet.clone());
    for (entry, should_hold) in margin
        .price_feed
        .publishers
        .iter()
        .map(|entry| (entry, true))
        .chain(
            margin
                .price_feed
                .remove_publishers
                .iter()
                .map(|entry| (entry, false)),
        )
    {
        let publisher = parse_margin_identity(entry)?;
        let holds = price_feed
            .methods()
            .has_role(o2_tools::prop_deploy::PRICE_SUBMITTER_ROLE, publisher)
            .simulate(Execution::state_read_only())
            .await
            .context("read a price feed publisher's submitter role")?
            .value;
        if holds == should_hold {
            continue;
        }
        if should_hold {
            tracing::info!("Margin: adding price feed publisher {publisher:?}");
            price_feed
                .methods()
                .add_publisher(publisher)
                .call()
                .await
                .context("grant a price feed publisher the submitter role")?;
        } else {
            tracing::info!("Margin: removing price feed publisher {publisher:?}");
            price_feed
                .methods()
                .remove_publisher(publisher)
                .call()
                .await
                .context("revoke a price feed publisher's submitter role")?;
        }
    }
    // -- the feed's implementation ---------------------------------------
    // Same contract as the order books: under `--upgrade-bytecode`, rebuild
    // the configured blob and retarget the proxy only when it differs, so a
    // feed already on this bytecode costs no transaction.
    //
    // Never in tier-only mode: that mode reconciles configuration, never
    // bytecode. Rotating a publisher must not also swap the implementation
    // every margin valuation reads.
    if upgrade_bytecode && !tier_only {
        o2_tools::prop_deploy::upgrade_price_feed_implementation(
            wallet,
            price_feed_id,
            // The blob's owner configurable must match what the fresh deploy
            // derived, or the retarget would chase a different blob id.
            prop_config
                .owner
                .unwrap_or(Identity::Address(wallet.address())),
            &prop_config,
        )
        .await
        .context("upgrade the price feed implementation")?;
    }

    // -- the feed's submission-age bound ----------------------------------
    // Also reconciled here, not just through the system deploy, so tier-only
    // mode honours it. Compare-first, so the settled case sends nothing and
    // the double-apply on a full deploy is free.
    if let Some(seconds) = margin.price_feed.max_offchain_age_seconds {
        let current = price_feed
            .methods()
            .get_max_offchain_age()
            .simulate(Execution::state_read_only())
            .await
            .context("read the price feed's submission-age bound")?
            .value;
        if current != seconds {
            tracing::info!("Margin: submission-age bound {current} -> {seconds}");
            price_feed
                .methods()
                .set_max_offchain_age(seconds)
                .call()
                .await
                .context("set the price feed's submission-age bound")?;
        }
    }

    // -- the feed's supported assets -------------------------------------
    // Registering decimals is what makes an asset known to the feed, and it
    // is independent of ever having a price: a tier catalogue publishes
    // against a feed configured this way even when no quote has ever been
    // seeded.
    for supported in &margin.price_feed.supported_assets {
        let current = price_feed
            .methods()
            .get_asset_decimals(supported.asset)
            .simulate(Execution::state_read_only())
            .await
            .context("read the price feed's asset decimals")?
            .value;
        match current {
            Some(decimals) if decimals == supported.decimals => continue,
            // Refused, not overwritten: the pool pins an asset's oracle
            // decimals on first use and reverts on a later change, so an
            // asset already live at other decimals would be stranded.
            Some(decimals) => anyhow::bail!(
                "price feed already knows {} at {decimals} decimals, config says \
                 {} - refusing to move it, since the pool pins decimals on first \
                 use and rejects a change",
                supported.asset,
                supported.decimals,
            ),
            None => {
                tracing::info!(
                    "Margin: registering {} at {} decimals on the feed",
                    supported.asset,
                    supported.decimals,
                );
                price_feed
                    .methods()
                    .set_asset_decimals(supported.asset, supported.decimals)
                    .call()
                    .await
                    .context("register a supported asset on the price feed")?;
            }
        }
    }

    let pool = PropMarginPoolContract::new(margin_pool_id, wallet.clone());
    let pool_reachable = wallet
        .try_provider()?
        .contract_exists(&margin_pool_id)
        .await?;

    // -- the feed the POOL values against ---------------------------------
    // `INITIAL_PRICE_FEED` only reaches storage through the pool's one-time
    // `initialize`, so a pool that is already live keeps its old feed no
    // matter what the config says. Reconcile it explicitly, or "point the
    // pool at this feed" would silently mean "only on a fresh deploy".
    //
    // Runs AFTER the supported-assets step on purpose: `set_price_feed`
    // validates that the replacement already knows every admitted asset at
    // the pinned decimals, which is exactly what that step registers.
    if pool_reachable {
        let live_feed = pool
            .methods()
            .price_feed()
            .simulate(Execution::state_read_only())
            .await
            .context("read the pool's price feed")?
            .value;
        if live_feed != price_feed_id {
            tracing::info!("Margin: pool price feed {live_feed} -> {price_feed_id}");
            pool.methods()
                .set_price_feed(price_feed_id)
                // `validate_replacement_feed` calls INTO the new feed once per
                // admitted asset, so it must ride as an input.
                .with_contract_ids(&[price_feed_id])
                .call()
                .await
                .context(
                    "point the pool at the configured price feed - the \
                     replacement must already know every admitted asset at the \
                     decimals the pool pinned",
                )?;
        }
    }

    // -- the tier catalogue ---------------------------------------------
    // The pool is unreachable only when the system deploy did not run, which
    // means tier-only mode against a pool the config NAMES but the chain does
    // not have. The guard above only checks that a pool is named, so refuse
    // here rather than skip: a run that publishes no tiers and reports
    // success is the failure an operator cannot see.
    anyhow::ensure!(
        pool_reachable || margin.tiers.is_empty(),
        "margin pool {margin_pool_id} is not on chain, so its {} configured \
         tier(s) cannot be reconciled",
        margin.tiers.len()
    );
    if pool_reachable {
        reconcile_margin_tiers(
            &pool,
            price_feed_id,
            pairs,
            &margin.tiers,
            prop_config.collateral_decimals,
        )
        .await?;
    }

    Ok(MarginIds {
        price_feed_id,
        margin_pool_id,
        margin_oracle_id,
    })
}

/// The tier engine: reconcile the DECLARED catalogue against the LIVE
/// pool, idempotently.
///
/// - disabled                    -> close sales only; never publish or add books;
/// - no live version              -> publish version 1;
/// - params, terms, daily loss policy or book venue differ -> publish a NEW version;
/// - publication settings equal, books grew -> `add_books` with the missing books;
/// - publication settings equal, books covered -> untouched (books are append-only:
///   a SHRUNK declared list cannot be enacted and is reported).
async fn reconcile_margin_tiers<W>(
    pool: &o2_tools::prop::PropMarginPoolContract<W>,
    price_feed_id: ContractId,
    pairs: &[OrderBookConfig],
    tiers: &[MarginTierConfig],
    collateral_decimals: u8,
) -> anyhow::Result<()>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    // Also covers a fresh pool: absent retired versions are simply skipped.
    reconcile_disabled_margin_tiers(pool, tiers).await?;
    for tier in tiers.iter().filter(|tier| tier.enabled) {
        let books = tier
            .markets
            .iter()
            .map(|market| resolve_tier_market(market, pairs, tier.sidecar))
            .collect::<anyhow::Result<Vec<_>>>()?;
        let params = tier_params(tier, collateral_decimals)?;
        let terms = required_turbo_terms(tier)?;
        // Refused HERE rather than on chain: `publish_tier_v3` validates the
        // same invariants and reverts, which costs a transaction and reports
        // one undifferentiated error for nine distinct mistakes.
        validate_turbo_tier_config(tier, &params, &terms)?;
        let current_version = pool
            .methods()
            .current_tier_version(tier.tier_id)
            .simulate(Execution::state_read_only())
            .await?
            .value;

        let mut contract_ids = vec![price_feed_id];
        contract_ids.extend(books.iter().copied());

        let Some(version) = current_version else {
            let version = publish_margin_tier(
                pool,
                tier.tier_id,
                params,
                terms.clone(),
                books,
                tier.daily_loss_limit_bps,
                &contract_ids,
            )
            .await?;
            tracing::info!(
                "Margin: tier {} published version {version} (prepaid)",
                tier.tier_id
            );
            reconcile_margin_tier_enabled(pool, tier).await?;
            continue;
        };

        let live = pool
            .methods()
            .get_tier(tier.tier_id, version)
            .simulate(Execution::state_read_only())
            .await?
            .value
            .with_context(|| {
                format!("tier {} version {version} vanished mid-read", tier.tier_id)
            })?;
        // The terms are HALF the published version and are immutable once
        // written, so a change to them is a new version exactly as a change
        // to the economics is. Comparing only `params` would drop a re-tuned
        // escalator on the floor and report the tier as unchanged. Explicitly
        // adding prepaid terms to a legacy tier also publishes a new version.
        let live_terms = pool
            .methods()
            .get_turbo_terms(tier.tier_id, version)
            .simulate(Execution::state_read_only())
            .await?
            .value;
        // Daily loss follows the same versioning rules as the tier economics.
        // The setter is an emergency admin override, never a reconciliation
        // operation: existing sessions retain their version's policy.
        let live_daily_loss_limit = pool
            .methods()
            .get_daily_loss_limit(tier.tier_id, version)
            .simulate(Execution::state_read_only())
            .await?
            .value;
        let live_books = pool
            .methods()
            .tier_books(tier.tier_id, version)
            .simulate(Execution::state_read_only())
            .await?
            .value;
        // Switching venues replaces the allowlist. Appending would leave
        // canonical trading available to a sidecar-only tier (or vice versa).
        let venue_changed = tier_book_route_changed(tier.sidecar, pairs, &live_books);
        if live != params
            || live_terms.as_ref() != Some(&terms)
            || live_daily_loss_limit != tier.daily_loss_limit_bps
            || venue_changed
        {
            let new_version = publish_margin_tier(
                pool,
                tier.tier_id,
                params,
                terms.clone(),
                books,
                tier.daily_loss_limit_bps,
                &contract_ids,
            )
            .await?;
            tracing::info!(
                "Margin: tier {} republished as version {new_version} ({})",
                tier.tier_id,
                if venue_changed {
                    "book venue changed"
                } else if live_terms.as_ref() != Some(&terms) {
                    "terms changed"
                } else if live_daily_loss_limit != tier.daily_loss_limit_bps {
                    "daily loss policy changed"
                } else {
                    "economics changed"
                }
            );
            reconcile_margin_tier_enabled(pool, tier).await?;
            continue;
        }
        reconcile_margin_tier_enabled(pool, tier).await?;

        let missing: Vec<ContractId> = books
            .iter()
            .copied()
            .filter(|book| !live_books.contains(book))
            .collect();
        let shrunk = live_books
            .iter()
            .filter(|book| !books.contains(book))
            .count();
        if shrunk > 0 {
            tracing::warn!(
                "Margin: tier {} declares {shrunk} fewer book(s) than live version \
                 {version}; books are append-only — publish a new version to drop \
                 markets",
                tier.tier_id
            );
        }
        if missing.is_empty() {
            tracing::info!(
                "Margin: tier {} version {version} matches the declared catalogue — \
                 unchanged",
                tier.tier_id
            );
            continue;
        }
        let mut add_contract_ids = vec![price_feed_id];
        add_contract_ids.extend(missing.iter().copied());
        pool.methods()
            .add_books(tier.tier_id, missing.clone())
            .with_contract_ids(&add_contract_ids)
            .call()
            .await?;
        tracing::info!(
            "Margin: tier {} version {version} gained {} book(s)",
            tier.tier_id,
            missing.len()
        );
    }
    Ok(())
}

/// Requires explicit prepaid terms; legacy publication is no longer supported.
fn required_turbo_terms(
    tier: &MarginTierConfig,
) -> anyhow::Result<o2_tools::prop::TurboTerms> {
    tier.turbo
        .as_ref()
        .map(o2_tools::prop::TurboTerms::from)
        .with_context(|| {
            format!(
                "tier {} has no `turbo` terms: legacy tier publishing is disabled; \
                 set `enabled` to false to retire it or configure valid prepaid \
                 terms",
                tier.tier_id
            )
        })
}

/// Validate all enabled economics before any deployment transaction is sent.
fn validate_margin_tier_catalogue(margin: &MarginConfig) -> anyhow::Result<()> {
    let decimals = margin.collateral_decimals.context(
        "margin.collateral_decimals is required - set it to the collateral \
         asset's decimals in the deploy config",
    )?;
    let mut ids = std::collections::BTreeSet::new();
    for tier in &margin.tiers {
        anyhow::ensure!(
            ids.insert(tier.tier_id),
            "tier {} appears more than once in the margin catalogue",
            tier.tier_id
        );
        if !tier.enabled {
            continue;
        }
        let terms = required_turbo_terms(tier)?;
        let params = tier_params(tier, decimals)?;
        validate_turbo_tier_config(tier, &params, &terms)?;
    }
    Ok(())
}

/// Retire existing tiers without interpreting or republishing their economics.
async fn reconcile_disabled_margin_tiers<W>(
    pool: &o2_tools::prop::PropMarginPoolContract<W>,
    tiers: &[MarginTierConfig],
) -> anyhow::Result<()>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    for tier in tiers.iter().filter(|tier| !tier.enabled) {
        let version = pool
            .methods()
            .current_tier_version(tier.tier_id)
            .simulate(Execution::state_read_only())
            .await?
            .value;
        // set_tier_enabled rejects unknown ids. Never create an obsolete
        // version just to disable it: no version already means no sales.
        if version.is_some() {
            reconcile_margin_tier_enabled(pool, tier).await?;
        }
    }
    Ok(())
}

/// Publishes prepaid terms and daily loss policy atomically through V3.
async fn publish_margin_tier<W>(
    pool: &o2_tools::prop::PropMarginPoolContract<W>,
    tier_id: u64,
    params: o2_tools::prop::TierParams,
    terms: o2_tools::prop::TurboTerms,
    books: Vec<ContractId>,
    daily_loss_limit_bps: Option<u64>,
    contract_ids: &[ContractId],
) -> anyhow::Result<u32>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let version = pool
        .methods()
        .publish_tier_v3(tier_id, params, terms, books, daily_loss_limit_bps)
        .with_contract_ids(contract_ids)
        .call()
        .await?
        .value;
    Ok(version)
}

/// Brings the tier's SALES switch to what the config declares.
///
/// Compare-first, like the discount-manager roster: a tier already in the
/// declared state costs no transaction, so a routine reconcile of an
/// unchanged catalogue sends nothing. Gates `open_session` only - a live
/// session on a switched-off tier keeps every call it was sold with, which
/// is what lets an old catalogue be retired without stranding anybody.
async fn reconcile_margin_tier_enabled<W>(
    pool: &o2_tools::prop::PropMarginPoolContract<W>,
    tier: &MarginTierConfig,
) -> anyhow::Result<()>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let live = pool
        .methods()
        .is_tier_enabled(tier.tier_id)
        .simulate(Execution::state_read_only())
        .await?
        .value;
    if live == tier.enabled {
        return Ok(());
    }
    pool.methods()
        .set_tier_enabled(tier.tier_id, tier.enabled)
        .call()
        .await?;
    tracing::info!(
        "Margin: tier {} now {} for new sessions",
        tier.tier_id,
        if tier.enabled { "OPEN" } else { "CLOSED" }
    );
    Ok(())
}

/// The pool's shared tier and Turbo economics, checked before deployment.
///
/// Every rule here is enforced on chain too - this is not the authority, it
/// is the early and NAMED report of a config the chain would refuse with a
/// single undifferentiated error.
fn validate_turbo_tier_config(
    tier: &MarginTierConfig,
    params: &o2_tools::prop::TierParams,
    terms: &o2_tools::prop::TurboTerms,
) -> anyhow::Result<()> {
    let id = tier.tier_id;
    if let Some(limit) = tier.daily_loss_limit_bps {
        anyhow::ensure!(
            limit <= 10_000,
            "tier {id} `daily_loss_limit_bps` must be <= 10000"
        );
    }
    anyhow::ensure!(params.line > 0, "tier {id} `line` must be greater than 0");
    anyhow::ensure!(
        params.leverage > 0 && params.leverage <= params.line,
        "tier {id} `leverage` must be positive and leave nonzero required collateral"
    );
    for (field, value) in [
        ("maintenance_bps", params.maintenance_bps),
        ("open_buffer_bps", params.open_buffer_bps),
        ("price_band_bps", params.price_band_bps),
    ] {
        anyhow::ensure!(value <= 10_000, "tier {id} `{field}` must be <= 10000");
    }
    anyhow::ensure!(
        (1..=10_000).contains(&params.liq_price_factor),
        "tier {id} `liq_price_factor` must be between 1 and 10000"
    );
    anyhow::ensure!(
        params.duration > 0,
        "tier {id} is prepaid, so `duration` must be greater than 0 seconds; \
         use u64::MAX for a perpetual term"
    );
    anyhow::ensure!(
        params.prolong_fee.iter().all(|fee| *fee == 0),
        "tier {id} is prepaid, so every `prolong_fee` must be \"0\" - a \
         prepaid term is extended by the FREE rollover and by nothing else"
    );
    anyhow::ensure!(
        params.profit_share_bps == 0,
        "tier {id} is prepaid, so `profit_share_bps` must be 0 - the user \
         keeps 100% of profits and the platform's take is the forfeited entry"
    );
    // Turbo publication also runs the shared tier guard, which is stricter
    // than the Turbo-only >= 10000 check.
    anyhow::ensure!(
        params.max_credit_line_bps > 10_000,
        "tier {id} is prepaid, so `max_credit_line_bps` must be > 10000 - \
         the cap must not truncate the line the session opens with"
    );
    anyhow::ensure!(
        terms.rollover_profit_bps <= 10_000,
        "tier {id} `rollover_profit_bps` must be <= 10000"
    );
    anyhow::ensure!(
        terms.max_loss_bps.iter().all(|bps| *bps <= 10_000),
        "tier {id} every `max_loss_bps` entry must be <= 10000 - a rate past \
         BPS would put the floor below zero for any line"
    );
    if terms.rollover_profit_bps != 0 {
        anyhow::ensure!(
            terms.max_rollovers != 0,
            "tier {id} offers a rollover, so `max_rollovers` must not be 0 - \
             an enabled feature must be a real one"
        );
    }
    // Every prepaid session needs a drawdown allowance, even without
    // rollovers: its floor is measured from the LINE, not a rollover anchor.
    // Match the pool's validation of every step allowed by the configured cap.
    let last_step = terms.max_rollovers.min(3) as usize;
    for step in 0..=last_step {
        anyhow::ensure!(
            terms.max_loss_bps[step] != 0,
            "tier {id} sells a drawdown escalator whose step {step} is 0, \
             which floors that term at the session's line - a \
             session reaching it is liquidatable immediately"
        );
        anyhow::ensure!(
            step == 0 || terms.max_loss_bps[step] >= terms.max_loss_bps[step - 1],
            "tier {id} drawdown step {step} is NARROWER than the step \
             before it - the schedule is sold as an escalator and must \
             never take back room a previous term already granted"
        );
    }
    // The first allowance must cover the buffer gap, or the session opens
    // frozen despite having paid its non-refundable entry.
    let line = u128::from(params.line);
    let bps_up = |bps: u64| (line * u128::from(bps)).div_ceil(10_000);
    let maintenance = bps_up(params.maintenance_bps);
    let open_buffer = bps_up(params.open_buffer_bps);
    let cap = line * u128::from(params.max_credit_line_bps) / 10_000;
    anyhow::ensure!(
        cap <= u128::from(u64::MAX),
        "tier {id} credit-line cap does not fit a u64"
    );
    anyhow::ensure!(
        open_buffer > maintenance,
        "tier {id} `open_buffer_bps` must produce a buffer above maintenance"
    );
    let k = line - line / u128::from(params.leverage);
    anyhow::ensure!(
        k + open_buffer < cap,
        "tier {id} open buffer puts the freeze threshold at or above the credit-line cap"
    );
    let allowance = line * u128::from(terms.max_loss_bps[0]) / 10_000;
    let gap = open_buffer - maintenance;
    anyhow::ensure!(
        gap <= allowance,
        "tier {id} first drawdown step ({} bps) is narrower than the \
         tier's own `open_buffer_bps - maintenance_bps` gap, so every \
         session it sells opens already FROZEN and can never trade",
        terms.max_loss_bps[0]
    );
    Ok(())
}

/// Whole collateral units (`"7.5"`) into base units, EXACTLY.
///
/// Never through `f64`: a binary float cannot hold most decimal fractions, so
/// `"7.1"` at 9 decimals would land on 7_099_999_999 - and this is money. The
/// integer is built from the digits instead.
///
/// More fractional digits than the asset has is an ERROR, not a rounding: a
/// figure the chain cannot represent is a figure the operator did not mean.
fn collateral_amount(value: &str, decimals: u8, field: &str) -> anyhow::Result<u64> {
    let raw = value.trim();
    anyhow::ensure!(!raw.is_empty(), "{field}: empty amount");
    anyhow::ensure!(
        !raw.starts_with('-'),
        "{field}: `{raw}` is negative; fees are unsigned"
    );
    let (whole, fraction) = match raw.split_once('.') {
        Some((whole, fraction)) => (whole, fraction),
        None => (raw, ""),
    };
    anyhow::ensure!(
        !fraction.contains('.'),
        "{field}: `{raw}` has more than one decimal point"
    );
    anyhow::ensure!(
        !whole.is_empty() && whole.bytes().all(|b| b.is_ascii_digit()),
        "{field}: `{raw}` is not a decimal amount"
    );
    anyhow::ensure!(
        fraction.bytes().all(|b| b.is_ascii_digit()),
        "{field}: `{raw}` is not a decimal amount"
    );
    let decimals = usize::from(decimals);
    anyhow::ensure!(
        fraction.len() <= decimals,
        "{field}: `{raw}` has {} decimal places, but the collateral asset has \
         only {decimals}; the chain cannot represent it",
        fraction.len()
    );
    let digits = format!("{whole}{fraction}{}", "0".repeat(decimals - fraction.len()));
    digits
        .parse::<u64>()
        .map_err(|e| anyhow::anyhow!("{field}: `{raw}` does not fit a u64: {e}"))
}

fn tier_params(
    tier: &MarginTierConfig,
    collateral_decimals: u8,
) -> anyhow::Result<o2_tools::prop::TierParams> {
    let fee = |value: &str, what: &str| {
        collateral_amount(
            value,
            collateral_decimals,
            &format!("tier {} {what}", tier.tier_id),
        )
    };
    Ok(o2_tools::prop::TierParams {
        line: tier.line,
        leverage: tier.leverage,
        duration: tier.duration,
        maintenance_bps: tier.maintenance_bps,
        open_buffer_bps: tier.open_buffer_bps,
        liq_price_factor: tier.liq_price_factor,
        prolong_fee: [
            fee(&tier.prolong_fee[0], "prolong_fee[0]")?,
            fee(&tier.prolong_fee[1], "prolong_fee[1]")?,
            fee(&tier.prolong_fee[2], "prolong_fee[2]")?,
            fee(&tier.prolong_fee[3], "prolong_fee[3]")?,
        ],
        max_credit_line_bps: tier.max_credit_line_bps,
        max_price_age: tier.max_price_age,
        open_fee: fee(&tier.open_fee, "open_fee")?,
        profit_share_bps: tier.profit_share_bps,
        price_band_bps: tier.price_band_bps,
    })
}

/// Whether the live allowlist still contains books from the other venue.
fn tier_book_route_changed(
    sidecar: bool,
    pairs: &[OrderBookConfig],
    live_books: &[ContractId],
) -> bool {
    pairs.iter().any(|pair| {
        let previous_book = if sidecar {
            pair.contract_id
        } else {
            pair.sidecar
                .as_ref()
                .and_then(|settings| settings.contract_id)
        };
        previous_book.is_some_and(|book| live_books.contains(&book))
    })
}

/// Resolve a tier market symbol or market id to its selected book's contract id.
fn resolve_tier_market(
    market: &str,
    pairs: &[OrderBookConfig],
    sidecar: bool,
) -> anyhow::Result<ContractId> {
    let wanted = market.trim();
    let wanted_id = wanted
        .strip_prefix("0x")
        .unwrap_or(wanted)
        .to_ascii_lowercase();
    let pair = pairs
        .iter()
        .find(|pair| {
            let symbol = format!("{}/{}", pair.base.symbol, pair.quote.symbol);
            symbol.eq_ignore_ascii_case(wanted)
                || hex::encode(*pair.market_id) == wanted_id
        })
        .with_context(|| format!("margin tier references unknown market `{market}`"))?;
    if sidecar {
        pair.sidecar
            .as_ref()
            .and_then(|settings| settings.contract_id)
            .with_context(|| {
                format!("margin tier market `{market}` has no deployed sidecar")
            })
    } else {
        pair.contract_id.with_context(|| {
            format!("margin tier market `{market}` has no deployed order book")
        })
    }
}

/// `address:0x..` or `contract:0x..` into an `Identity`.
fn parse_margin_identity(s: &str) -> anyhow::Result<Identity> {
    if let Some(hex_part) = s.strip_prefix("address:") {
        Ok(Identity::Address(fuels::types::Address::new(
            parse_margin_bytes32(hex_part)?,
        )))
    } else if let Some(hex_part) = s.strip_prefix("contract:") {
        Ok(Identity::ContractId(ContractId::new(parse_margin_bytes32(
            hex_part,
        )?)))
    } else {
        anyhow::bail!("expected `address:0x..` or `contract:0x..`, got `{s}`")
    }
}

fn parse_margin_bytes32(s: &str) -> anyhow::Result<[u8; 32]> {
    let raw = s.trim().strip_prefix("0x").unwrap_or(s.trim());
    let bytes = hex::decode(raw)
        .map_err(|e| anyhow::anyhow!("expected 32 hex bytes, got `{s}`: {e}"))?;
    bytes
        .try_into()
        .map_err(|_| anyhow::anyhow!("expected 32 hex bytes, got `{s}`"))
}

// ---------------------------------------------------------------------------
// Ownership transfer
// ---------------------------------------------------------------------------

#[allow(clippy::too_many_arguments)]
async fn transfer_ownership<W>(
    wallet: &W,
    params: &DeployParams,
    order_book_registry: &OrderBookRegistryManager<W>,
    trade_account_registry: &TradeAccountRegistryManager<W>,
    trade_account_oracle_deploy: &TradeAccountDeploy<W>,
    trial_trade_account_oracle_id: ContractId,
    order_book_blacklist_id: Option<ContractId>,
    order_book_whitelist_id: Option<ContractId>,
) -> anyhow::Result<()>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    if let Some(new_proxy_owner) = params.new_proxy_owner {
        let new_identity = Identity::Address(new_proxy_owner);
        tracing::info!(
            "Transferring OrderBookRegistry proxy ownership to {}",
            new_proxy_owner
        );
        order_book_registry
            .registry_proxy
            .methods()
            .set_owner(new_identity)
            .call()
            .await?;
        tracing::info!(
            "Transferring TradeAccountRegistry proxy ownership to {}",
            new_proxy_owner
        );
        trade_account_registry
            .registry_proxy
            .methods()
            .set_owner(new_identity)
            .call()
            .await?;
    }

    if let Some(new_contract_owner) = params.new_contract_owner {
        let new_identity = Identity::Address(new_contract_owner);
        tracing::info!(
            "Transferring TradeAccountOracle ownership to {}",
            new_contract_owner
        );
        trade_account_oracle_deploy
            .oracle
            .methods()
            .transfer_ownership(new_identity)
            .call()
            .await?;
        tracing::info!(
            "Transferring TrialTradeAccountOracle ownership to {}",
            new_contract_owner
        );
        TrialTradingAccountOracle::new(trial_trade_account_oracle_id, wallet.clone())
            .methods()
            .transfer_ownership(new_identity)
            .call()
            .await?;
        tracing::info!(
            "Transferring TradeAccountRegistry ownership to {}",
            new_contract_owner
        );
        trade_account_registry
            .registry
            .methods()
            .transfer_ownership(new_identity)
            .call()
            .await?;
        tracing::info!(
            "Transferring OrderBookRegistry ownership to {}",
            new_contract_owner
        );
        order_book_registry
            .registry
            .methods()
            .transfer_ownership(new_identity)
            .call()
            .await?;
        if let Some(blacklist_id) = order_book_blacklist_id {
            tracing::info!(
                "Transferring OrderBookBlacklist ownership to {}",
                new_contract_owner
            );
            OrderBookBlacklist::new(blacklist_id, wallet.clone())
                .methods()
                .transfer_ownership(new_identity)
                .call()
                .await?;
        }
        if let Some(whitelist_id) = order_book_whitelist_id {
            tracing::info!(
                "Transferring OrderBookWhitelist ownership to {}",
                new_contract_owner
            );
            OrderBookWhitelist::new(whitelist_id, wallet.clone())
                .methods()
                .transfer_ownership(new_identity)
                .call()
                .await?;
        }
    }

    Ok(())
}

// ---------------------------------------------------------------------------
// Internal deploy helpers
// ---------------------------------------------------------------------------

async fn deploy_order_book_blacklist<W>(
    deployer_wallet: W,
    deploy_blacklist: bool,
    order_book_blacklist_id: Option<ContractId>,
    salt: Salt,
) -> anyhow::Result<Option<ContractId>>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    match order_book_blacklist_id {
        Some(order_book_blacklist_id) => {
            tracing::info!(
                "Using existing OrderBookBlacklist: {}",
                order_book_blacklist_id
            );
            Ok(Some(order_book_blacklist_id))
        }
        None => {
            if !deploy_blacklist {
                return Ok(None);
            }
            tracing::info!("Deploying OrderBookBlacklist");
            let order_book_blacklist = OrderBookDeploy::deploy_order_book_blacklist(
                &deployer_wallet,
                &Identity::Address(ViewOnlyAccount::address(&deployer_wallet)),
                &OrderBookDeployConfig {
                    salt,
                    ..Default::default()
                },
            )
            .await?;
            tracing::info!("OrderBookBlacklist: {}", order_book_blacklist.contract_id());
            Ok(Some(order_book_blacklist.contract_id()))
        }
    }
}

async fn deploy_order_book_whitelist<W>(
    deployer_wallet: W,
    deploy_whitelist: bool,
    order_book_whitelist_id: Option<ContractId>,
    salt: Salt,
) -> anyhow::Result<Option<ContractId>>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    match (order_book_whitelist_id, deploy_whitelist) {
        (Some(order_book_whitelist_id), false)
        | (Some(order_book_whitelist_id), true) => {
            tracing::info!(
                "Using existing OrderBookWhitelist: {}",
                order_book_whitelist_id
            );
            Ok(Some(order_book_whitelist_id))
        }
        (None, false) => Ok(None),
        (None, true) => {
            tracing::info!("Deploying OrderBookWhitelist");
            let trade_account_whitelist = OrderBookDeploy::deploy_order_book_whitelist(
                &deployer_wallet,
                &Identity::Address(ViewOnlyAccount::address(&deployer_wallet)),
                &OrderBookDeployConfig {
                    salt,
                    ..Default::default()
                },
            )
            .await?;
            tracing::info!(
                "OrderBookWhitelist: {}",
                trade_account_whitelist.contract_id()
            );
            Ok(Some(trade_account_whitelist.contract_id()))
        }
    }
}

/// Load an existing oracle and recover from partial deployment if needed.
/// Unlike `TradeAccountDeploy::from_oracle_id`, this does not error when
/// the trade account implementation is missing — it deploys and sets it.
async fn load_or_recover_trade_account_oracle<W>(
    deployer_wallet: &W,
    oracle_id: ContractId,
) -> anyhow::Result<(TradeAccountDeploy<W>, ContractId)>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let oracle = TradingAccountOracle::new(oracle_id, deployer_wallet.clone());
    let impl_id = oracle
        .methods()
        .get_trade_account_impl()
        .simulate(Execution::state_read_only())
        .await?
        .value;

    let blob_id = match impl_id {
        Some(id) => id,
        None => {
            tracing::info!(
                "Trade account implementation not set on oracle {}, deploying...",
                oracle_id
            );
            let blob = TradeAccountDeploy::trade_account_blob(
                deployer_wallet,
                &Default::default(),
            )
            .await?;
            TradeAccountDeploy::deploy_trade_account_blob(
                deployer_wallet,
                &DeployConfig::Latest(Default::default()),
            )
            .await?;
            oracle
                .methods()
                .set_trade_account_impl(ContractId::from(blob.id))
                .call()
                .await?;
            ContractId::from(blob.id)
        }
    };

    let deploy = TradeAccountDeploy {
        oracle,
        oracle_id,
        trade_account_blob_id: blob_id.into(),
        deployer_wallet: deployer_wallet.clone(),
        proxy: None,
        proxy_id: None,
    };
    Ok((deploy, blob_id))
}

async fn deploy_trade_account_oracle<W>(
    deployer_wallet: W,
    should_upgrade_bytecode: bool,
    trade_account_oracle_id: Option<ContractId>,
    salt: Salt,
) -> anyhow::Result<(TradeAccountDeploy<W>, ContractId)>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let (trade_account_oracle_deploy, mut trade_account_blob_id) =
        match trade_account_oracle_id {
            Some(oracle_id) => {
                load_or_recover_trade_account_oracle(&deployer_wallet, oracle_id).await?
            }
            None => {
                let deploy = TradeAccountDeploy::deploy(
                    &deployer_wallet,
                    &DeployConfig::Latest(TradeAccountDeployConfig {
                        salt,
                        ..Default::default()
                    }),
                )
                .await?;
                let blob_id = deploy
                    .oracle
                    .methods()
                    .get_trade_account_impl()
                    .simulate(Execution::state_read_only())
                    .await?
                    .value
                    .context("Trade account impl should exist after fresh deploy")?;
                (deploy, blob_id)
            }
        };
    tracing::info!(
        "TradeAccountOracle: {}",
        trade_account_oracle_deploy.oracle_id
    );

    if should_upgrade_bytecode {
        let trade_account_blob =
            TradeAccountDeploy::trade_account_blob(&deployer_wallet, &Default::default())
                .await?;
        if ContractId::from(trade_account_blob.id) != trade_account_blob_id {
            tracing::info!(
                "Update TradeAccountImpl on Oracle from {:?} to new blob {:?}",
                trade_account_blob_id,
                ContractId::from(trade_account_blob.id)
            );
            TradeAccountDeploy::deploy_trade_account_blob(
                &deployer_wallet,
                &DeployConfig::Latest(Default::default()),
            )
            .await?;
            trade_account_oracle_deploy
                .oracle
                .methods()
                .set_trade_account_impl(ContractId::from(trade_account_blob.id))
                .call()
                .await?;
            trade_account_blob_id = ContractId::from(trade_account_blob.id);
        }
    }

    Ok((trade_account_oracle_deploy, trade_account_blob_id))
}

/// Deploy (or load) the dedicated trial trade account oracle and keep its
/// implementation current. The implementation follows the trade-account
/// implementation's lifecycle: seeded when the oracle has none, upgraded
/// under `should_upgrade_bytecode`. The cosigner is opt-in: providing one
/// also (re)deploys the implementation and configures the cosigner; without
/// one, the configured cosigner is left untouched. This runs before
/// ownership transfer since it writes to the oracle.
async fn deploy_trial_trade_account_oracle<W>(
    deployer_wallet: W,
    should_upgrade_bytecode: bool,
    trial_trade_account_oracle_id: Option<ContractId>,
    trial_cosigner: Option<fuels::types::Address>,
    salt: Salt,
) -> anyhow::Result<ContractId>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let mut trial_deploy_config = TrialTradeAccountDeployConfig {
        salt,
        ..Default::default()
    };
    if let Some(cosigner) = trial_cosigner {
        trial_deploy_config = trial_deploy_config.with_cosigner(cosigner);
    }
    let deploy_config = TrialDeployConfig::Latest(trial_deploy_config);

    let oracle_id = match trial_trade_account_oracle_id {
        None => {
            let trial_deploy =
                TrialTradeAccountDeploy::deploy(&deployer_wallet, &deploy_config).await?;
            tracing::info!(
                "TrialTradeAccountOracle: {} (implementation {:?}, cosigner {:?})",
                trial_deploy.oracle_id,
                trial_deploy.trial_trade_account_blob_id,
                trial_cosigner,
            );
            trial_deploy.oracle_id
        }
        Some(oracle_id) => {
            let current_trial_impl =
                TrialTradingAccountOracle::new(oracle_id, deployer_wallet.clone())
                    .methods()
                    .get_trial_account_impl()
                    .simulate(Execution::state_read_only())
                    .await?
                    .value;
            if current_trial_impl.is_none()
                || should_upgrade_bytecode
                || trial_cosigner.is_some()
            {
                let trial_deploy = TrialTradeAccountDeploy::deploy_to_oracle(
                    &deployer_wallet,
                    oracle_id,
                    &deploy_config,
                )
                .await?;
                tracing::info!(
                    "Trial implementation {:?} deployed to oracle {} (cosigner {:?})",
                    trial_deploy.trial_trade_account_blob_id,
                    oracle_id,
                    trial_cosigner,
                );
            }
            oracle_id
        }
    };

    Ok(oracle_id)
}

async fn deploy_trade_account_registry<W>(
    deployer_wallet: W,
    should_upgrade_bytecode: bool,
    trade_account_deploy: TradeAccountDeploy<W>,
    trial_trade_account_oracle_id: ContractId,
    trade_account_registry_id: Option<ContractId>,
    salt: Salt,
) -> anyhow::Result<(TradeAccountRegistryManager<W>, ContractId)>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let trade_account_oracle_id = trade_account_deploy.oracle_id;
    let trade_account_registry = match trade_account_registry_id {
        Some(trade_account_registry_contract_id) => TradeAccountRegistryManager::new(
            deployer_wallet.clone(),
            trade_account_registry_contract_id,
        ),
        None => {
            let trade_account_registry_deploy_config = TradeAccountRegistryDeployConfig {
                salt,
                ..Default::default()
            };
            TradeAccountRegistryManager::deploy(
                &deployer_wallet,
                trade_account_oracle_id,
                trial_trade_account_oracle_id,
                &trade_account_registry_deploy_config,
            )
            .await?
        }
    };
    tracing::info!(
        "TradeAccountRegistry: {}",
        trade_account_registry.contract_id
    );
    let mut trade_account_registry_blob_id = match trade_account_registry
        .registry_proxy
        .methods()
        .proxy_target()
        .simulate(Execution::state_read_only())
        .await?
        .value
    {
        Some(blob_id) => blob_id,
        None => {
            tracing::info!("TradeAccountRegistry proxy target not set, initializing...");
            // Call initialize_proxy() to write INITIAL_OWNER and INITIAL_TARGET
            // from configurables to storage (upgrade/set_proxy_target would fail
            // because the owner is not yet in storage)
            trade_account_registry
                .registry_proxy
                .methods()
                .initialize_proxy()
                .call()
                .await?;
            trade_account_registry
                .registry
                .methods()
                .initialize()
                .call()
                .await?;
            trade_account_registry
                .registry_proxy
                .methods()
                .proxy_target()
                .simulate(Execution::state_read_only())
                .await?
                .value
                .context("TradeAccountRegistry proxy target should be set after initialization")?
        }
    };

    if should_upgrade_bytecode {
        // The rebuilt blob carries whatever this config says and DEFAULTS
        // everything else — so the prop wiring has to be repeated here or
        // the upgrade silently zeroes it. See `live_prop_registry_config`.
        let trade_account_registry_deploy_config = TradeAccountRegistryDeployConfig {
            registry_config: trade_account_registry
                .live_prop_config(TradeAccountRegistryConfigurables::default())
                .await?,
            ..Default::default()
        };
        let trade_account_proxy_blob = TradeAccountRegistryManager::register_proxy_blob(
            &deployer_wallet,
            &trade_account_registry_deploy_config,
        )
        .await?;
        let trial_trade_account_proxy_blob =
            TradeAccountRegistryManager::register_trial_proxy_blob(
                &deployer_wallet,
                &trade_account_registry_deploy_config,
            )
            .await?;

        let trade_account_register_blob = TradeAccountRegistryManager::register_blob(
            &deployer_wallet,
            trade_account_oracle_id,
            trial_trade_account_oracle_id,
            trade_account_proxy_blob.id,
            trial_trade_account_proxy_blob.id,
            &trade_account_registry_deploy_config,
        )
        .await?;

        if trade_account_registry_blob_id
            != ContractId::from(trade_account_register_blob.id)
        {
            tracing::info!(
                "Upgrade TradeAccountRegistry blob from {:?} to {:?}",
                trade_account_registry.contract_id,
                ContractId::from(trade_account_register_blob.id)
            );
            // The SAME config the blob above was computed from: `upgrade`
            // rebuilds the blob internally, so passing a different one
            // would retarget the proxy at something we never compared.
            trade_account_registry
                .upgrade(
                    trade_account_oracle_id,
                    trial_trade_account_oracle_id,
                    &trade_account_registry_deploy_config,
                )
                .await?;
            trade_account_registry_blob_id = trade_account_register_blob.id.into();
        }
    }
    Ok((trade_account_registry, trade_account_registry_blob_id))
}

async fn deploy_order_book_registry<W>(
    deployer_wallet: W,
    should_upgrade_bytecode: bool,
    order_book_registry_id: Option<ContractId>,
    salt: Salt,
) -> anyhow::Result<(OrderBookRegistryManager<W>, ContractId)>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let order_book_registry = match order_book_registry_id {
        Some(registry_contract_id) => {
            OrderBookRegistryManager::new(deployer_wallet.clone(), registry_contract_id)
        }
        None => {
            OrderBookRegistryManager::deploy(
                &deployer_wallet,
                &OrderBookRegistryDeployConfig {
                    salt,
                    ..Default::default()
                },
            )
            .await?
        }
    };
    tracing::info!("OrderBookRegistry: {}", order_book_registry.contract_id);
    let mut order_book_registry_blob_id = match order_book_registry
        .registry_proxy
        .methods()
        .proxy_target()
        .simulate(Execution::state_read_only())
        .await?
        .value
    {
        Some(blob_id) => blob_id,
        None => {
            tracing::info!("OrderBookRegistry proxy target not set, initializing...");
            // Call initialize_proxy() to write INITIAL_OWNER and INITIAL_TARGET
            // from configurables to storage (upgrade/set_proxy_target would fail
            // because the owner is not yet in storage)
            order_book_registry
                .registry_proxy
                .methods()
                .initialize_proxy()
                .call()
                .await?;
            order_book_registry
                .registry
                .methods()
                .initialize()
                .call()
                .await?;
            order_book_registry
                .registry_proxy
                .methods()
                .proxy_target()
                .simulate(Execution::state_read_only())
                .await?
                .value
                .context(
                    "OrderBookRegistry proxy target should be set after initialization",
                )?
        }
    };

    if should_upgrade_bytecode {
        let order_book_register_deploy_config = OrderBookRegistryDeployConfig::default();
        let order_book_register_blob = OrderBookRegistryManager::register_blob(
            &deployer_wallet,
            &order_book_register_deploy_config,
        )
        .await?;
        if order_book_registry_blob_id != order_book_register_blob.id.into() {
            tracing::info!(
                "Upgrade OrderBookRegistry blob from {:?} to {:?}",
                order_book_registry.contract_id,
                ContractId::from(order_book_register_blob.id)
            );
            order_book_registry
                .upgrade(&order_book_register_deploy_config)
                .await?;
            order_book_registry_blob_id = order_book_register_blob.id.into();
        }
    }

    Ok((order_book_registry, order_book_registry_blob_id))
}

async fn deploy_order_books<W>(
    deployer_wallet: W,
    should_upgrade_bytecode: bool,
    order_book_blacklist_id: Option<ContractId>,
    order_book_whitelist_id: Option<ContractId>,
    order_book_registry: OrderBookRegistryManager<W>,
    order_book_configs: &mut [OrderBookConfig],
    ownership_options: OwnershipTransferOptions,
) -> anyhow::Result<Vec<OrderBookConfig>>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    // Pre-flight every pair before deploying any of them. A precision budget
    // breach is a config mistake, and the loop below deploys and registers as it
    // goes — failing on pair N would otherwise leave 1..N-1 live on chain, with
    // an append-only registry that cannot take them back.
    audit_order_book_precision(order_book_configs)?;

    let mut pairs: Vec<OrderBookConfig> = Vec::with_capacity(order_book_configs.len());

    for order_book_config in order_book_configs.iter_mut() {
        let pair = deploy_single_order_book(
            &deployer_wallet,
            should_upgrade_bytecode,
            order_book_blacklist_id,
            order_book_whitelist_id,
            &order_book_registry,
            order_book_config,
            &ownership_options,
        )
        .await?;
        pairs.push(pair);
    }

    Ok(pairs)
}

async fn deploy_single_order_book<W>(
    deployer_wallet: &W,
    should_upgrade_bytecode: bool,
    order_book_blacklist_id: Option<ContractId>,
    order_book_whitelist_id: Option<ContractId>,
    order_book_registry: &OrderBookRegistryManager<W>,
    order_book_config: &mut OrderBookConfig,
    ownership_options: &OwnershipTransferOptions,
) -> anyhow::Result<OrderBookConfig>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let market_symbol = format!(
        "{}/{}",
        order_book_config.base.symbol, order_book_config.quote.symbol
    );
    let market_id = MarketIdAssets {
        base_asset: order_book_config.base.asset,
        quote_asset: order_book_config.quote.asset,
    };
    let order_book_configurables = build_order_book_configurables(
        order_book_config,
        order_book_blacklist_id,
        order_book_whitelist_id,
        deployer_wallet,
    )?;

    let order_book = load_or_deploy_order_book(
        deployer_wallet,
        order_book_registry,
        &market_id,
        &market_symbol,
        &order_book_configurables,
        order_book_config,
    )
    .await?;

    tracing::info!(
        "[{}] OrderBook: {}",
        market_symbol,
        order_book.contract.contract_id()
    );

    let order_book_blob_id = maybe_upgrade_order_book(
        deployer_wallet,
        should_upgrade_bytecode,
        &order_book,
        order_book_config,
        order_book_configurables,
        &market_symbol,
    )
    .await?;

    // Set the maintainer while the deployer is still the owner, i.e. before any
    // ownership transfer below (`owner_grant_role`/`owner_revoke_role` are
    // `only_owner`).
    set_order_book_maintainer(&order_book, ownership_options, &market_symbol).await?;

    sidecar::deploy_sidecar(
        deployer_wallet,
        &order_book,
        order_book_config,
        should_upgrade_bytecode,
        ownership_options,
    )
    .await?;
    sidecar::grant_house_roles(&order_book, &order_book_config.house_identities).await?;

    transfer_order_book_ownership(&order_book, ownership_options, &market_symbol).await?;

    order_book_config.contract_id = Some(order_book.contract.contract_id());
    order_book_config.blob_id = order_book_blob_id.into();

    Ok(order_book_config.clone())
}

/// Checks every pair against its precision budget, naming the first offender.
///
/// The deploy path calls this before it touches the chain; it is public so a
/// config can be audited without one — CI, a linter, or `o2-api`'s
/// `validate_markets_config` example — against the same rule the deploy
/// enforces rather than a re-derived copy of it. See
/// [`order_book_precision_exponents`] for what the budget is and why.
pub fn audit_order_book_precision(configs: &[OrderBookConfig]) -> anyhow::Result<()> {
    for config in configs {
        order_book_precision_exponents(config)?;
    }
    Ok(())
}

/// The exponents behind `PRICE_PRECISION` and `QUANTITY_PRECISION`, after
/// checking the pair fits its precision budget.
///
/// The book settles a fill as `quantity * price / BASE_DECIMALS`
/// (`quote_coins_from_quantity`). A price on a
/// `10^(quote.decimals - quote.max_precision)` grid and a quantity on a
/// `10^(base.decimals - base.max_precision)` grid therefore put the notional on
/// a grid of `10^(quote.decimals - quote.max_precision - base.max_precision)`
/// quote atoms — so the two `max_precision` values are spending one shared
/// budget of `quote.decimals` digits.
///
/// Overspend it and the notional is a fraction of an atom the quote asset
/// cannot hold. Under `ALLOW_FRACTIONAL_PRICE = false` `quote_would_truncate`
/// turns that into a `FractionalPrice` revert on *every* order the book ever
/// receives; with fractional prices allowed it silently truncates instead.
///
/// Nothing downstream catches this: an over-budget book deploys, registers and
/// serves from `/v1/markets` looking healthy, and only fails when someone tries
/// to trade it.
fn order_book_precision_exponents(config: &OrderBookConfig) -> anyhow::Result<(u8, u8)> {
    let price_precision = config
        .quote
        .decimals
        .checked_sub(config.quote.max_precision)
        .ok_or_else(|| {
            anyhow::anyhow!(
                "quote max_precision ({}) exceeds decimals ({})",
                config.quote.max_precision,
                config.quote.decimals
            )
        })?;
    let quantity_precision = config
        .base
        .decimals
        .checked_sub(config.base.max_precision)
        .ok_or_else(|| {
            anyhow::anyhow!(
                "base max_precision ({}) exceeds decimals ({})",
                config.base.max_precision,
                config.base.decimals
            )
        })?;

    // Widen before summing: the checks above bound each side by its own
    // decimals, which still leaves room to wrap a u8.
    let spent = config.base.max_precision as u16 + config.quote.max_precision as u16;
    let budget = config.quote.decimals as u16;

    if config.allow_fractional_price {
        if spent > budget {
            tracing::warn!(
                "{}/{}: base max_precision ({}) + quote max_precision ({}) = {spent} \
                 exceeds the quote's {budget} decimals; ALLOW_FRACTIONAL_PRICE is set, \
                 so notionals will silently truncate rather than revert",
                config.base.symbol,
                config.quote.symbol,
                config.base.max_precision,
                config.quote.max_precision,
            );
        }
    } else {
        anyhow::ensure!(
            spent <= budget,
            "{}/{}: base max_precision ({}) + quote max_precision ({}) = {spent} \
             exceeds the quote's {budget} decimals, so every order would revert \
             with FractionalPrice. Lower one of the two until they sum to {budget} \
             or less.",
            config.base.symbol,
            config.quote.symbol,
            config.base.max_precision,
            config.quote.max_precision,
        );
    }

    Ok((price_precision, quantity_precision))
}

fn build_order_book_configurables<W: ViewOnlyAccount>(
    config: &OrderBookConfig,
    order_book_blacklist_id: Option<ContractId>,
    order_book_whitelist_id: Option<ContractId>,
    deployer_wallet: &W,
) -> anyhow::Result<OrderBookConfigurables> {
    let (price_precision, quantity_precision) = order_book_precision_exponents(config)?;

    Ok(OrderBookConfigurables::default()
        .with_MIN_ORDER(config.min_order)?
        .with_ALLOW_FRACTIONAL_PRICE(config.allow_fractional_price)?
        .with_TAKER_FEE(config.taker_fee.into())?
        .with_MAKER_FEE(config.maker_fee.into())?
        .with_DUST(config.dust)?
        .with_PRICE_WINDOW(config.price_window as u64)?
        .with_BASE_DECIMALS(10u64.pow(config.base.decimals as u32))?
        .with_QUOTE_DECIMALS(10u64.pow(config.quote.decimals as u32))?
        .with_BASE_SYMBOL(SizedAsciiString::new_with_right_whitespace_padding(
            config.base.symbol.clone(),
        )?)?
        .with_QUOTE_SYMBOL(SizedAsciiString::new_with_right_whitespace_padding(
            config.quote.symbol.clone(),
        )?)?
        .with_PRICE_PRECISION(10u64.pow(price_precision as u32))?
        .with_QUANTITY_PRECISION(10u64.pow(quantity_precision as u32))?
        .with_INITIAL_OWNER(o2_tools::order_book_deploy::State::Initialized(
            Identity::Address(ViewOnlyAccount::address(deployer_wallet)),
        ))?
        .with_WHITE_LIST_CONTRACT(order_book_whitelist_id)?
        .with_BLACK_LIST_CONTRACT(order_book_blacklist_id)?)
}

async fn load_or_deploy_order_book<W>(
    deployer_wallet: &W,
    order_book_registry: &OrderBookRegistryManager<W>,
    market_id: &MarketIdAssets,
    market_symbol: &str,
    order_book_configurables: &OrderBookConfigurables,
    order_book_config: &OrderBookConfig,
) -> anyhow::Result<OrderBookManager<W>>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let register_contract_id = order_book_registry
        .registry
        .methods()
        .get_order_book(to_registry_market_id(market_id))
        .simulate(Execution::state_read_only())
        .await?
        .value;

    match register_contract_id {
        Some(contract_id) => {
            let order_book_deploy = OrderBookDeploy::new(
                deployer_wallet.clone(),
                contract_id,
                market_id.base_asset,
                market_id.quote_asset,
            );
            // Handle partially deployed contracts (e.g. previous deploy failed
            // after registering but before initializing the proxy)
            let proxy_target = order_book_deploy
                .order_book_proxy
                .methods()
                .proxy_target()
                .simulate(Execution::state_read_only())
                .await?
                .value;
            if proxy_target.is_none() {
                tracing::info!(
                    "[{}] Proxy target not set, initializing...",
                    market_symbol
                );
                order_book_deploy.initialize().await?;
            }
            Ok(OrderBookManager::new(
                deployer_wallet,
                10u64.pow(order_book_config.base.decimals as u32),
                10u64.pow(order_book_config.quote.decimals as u32),
                &order_book_deploy,
            ))
        }
        None => {
            let (order_book_deployment, initialization_required) =
                OrderBookDeploy::deploy_without_initialization(
                    deployer_wallet,
                    market_id.base_asset,
                    market_id.quote_asset,
                    &OrderBookDeployConfig {
                        order_book_configurables: order_book_configurables.clone(),
                        salt: Salt::from(*order_book_registry.contract_id),
                        ..Default::default()
                    },
                )
                .await?;

            order_book_registry
                .register_order_book(
                    to_registry_market_id(market_id),
                    order_book_deployment.contract_id,
                )
                .await?;

            if initialization_required {
                order_book_deployment.initialize().await?;
            }
            Ok(OrderBookManager::new(
                deployer_wallet,
                10u64.pow(order_book_config.base.decimals as u32),
                10u64.pow(order_book_config.quote.decimals as u32),
                &order_book_deployment,
            ))
        }
    }
}

async fn maybe_upgrade_order_book<W>(
    deployer_wallet: &W,
    should_upgrade_bytecode: bool,
    order_book: &OrderBookManager<W>,
    order_book_config: &OrderBookConfig,
    order_book_configurables: OrderBookConfigurables,
    market_symbol: &str,
) -> anyhow::Result<ContractId>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    let mut order_book_blob_id = order_book
        .proxy
        .methods()
        .proxy_target()
        .simulate(Execution::state_read_only())
        .await?
        .value
        .context("Order book proxy target should be set after initialization")?;

    if should_upgrade_bytecode {
        let order_book_deploy_config = OrderBookDeployConfig {
            order_book_configurables,
            ..Default::default()
        };
        let order_book_deploy = OrderBookDeploy::new(
            deployer_wallet.clone(),
            order_book.contract.contract_id(),
            order_book_config.base.asset,
            order_book_config.quote.asset,
        );
        let order_book_manager = OrderBookManager::new(
            deployer_wallet,
            10u64.pow(order_book_config.base.decimals as u32),
            10u64.pow(order_book_config.quote.decimals as u32),
            &order_book_deploy,
        );
        let order_book_blob = OrderBookDeploy::order_book_blob(
            deployer_wallet,
            order_book_config.base.asset,
            order_book_config.quote.asset,
            &order_book_deploy_config,
        )
        .await?;

        if order_book_blob_id != order_book_blob.id.into() {
            tracing::info!(
                "[{}] Upgrade OrderBook blob from {:?} to {:?}",
                market_symbol,
                order_book_blob_id,
                ContractId::from(order_book_blob.id)
            );
            order_book_manager
                .upgrade(&order_book_deploy_config)
                .await?;
            tracing::info!(
                "[{}] Emit new configuration event for {}",
                market_symbol,
                order_book.contract.contract_id()
            );
            order_book_manager.emit_config().await?;
            order_book_blob_id = order_book_blob.id.into();
        }
    }

    Ok(order_book_blob_id)
}

async fn set_order_book_maintainer<W>(
    order_book: &OrderBookManager<W>,
    ownership_options: &OwnershipTransferOptions,
    market_symbol: &str,
) -> anyhow::Result<()>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    // Revoke the maintainer role from the previous holders first, so the role is
    // rotated rather than accumulating holders across upgrades. Revoking an
    // account that does not hold the role is a no-op on-chain.
    for account in &ownership_options.revoke_orderbook_maintainers {
        tracing::info!(
            "[{}] Revoking ORDERBOOK_MAINTAINER_ROLE from {}",
            market_symbol,
            account
        );
        order_book
            .contract
            .methods()
            .owner_revoke_role(ORDERBOOK_MAINTAINER_ROLE, Identity::Address(*account))
            .call()
            .await?;
    }

    for account in &ownership_options.new_orderbook_maintainers {
        tracing::info!(
            "[{}] Granting ORDERBOOK_MAINTAINER_ROLE to {}",
            market_symbol,
            account
        );
        order_book
            .contract
            .methods()
            .owner_grant_role(ORDERBOOK_MAINTAINER_ROLE, Identity::Address(*account))
            .call()
            .await?;
    }

    Ok(())
}

async fn transfer_order_book_ownership<W>(
    order_book: &OrderBookManager<W>,
    ownership_options: &OwnershipTransferOptions,
    market_symbol: &str,
) -> anyhow::Result<()>
where
    W: Account + ViewOnlyAccount + Clone + 'static,
{
    if let Some(new_owner) = ownership_options.new_proxy_owner {
        let new_identity = Identity::Address(new_owner);
        tracing::info!(
            "[{}] Transferring OrderBook proxy ownership to {}",
            market_symbol,
            new_owner
        );
        order_book
            .proxy
            .methods()
            .set_owner(new_identity)
            .call()
            .await?;
    }

    if let Some(new_owner) = ownership_options.new_contract_owner {
        let new_identity = Identity::Address(new_owner);
        tracing::info!(
            "[{}] Transferring OrderBook contract ownership to {}",
            market_symbol,
            new_owner
        );
        order_book
            .contract
            .methods()
            .transfer_ownership(new_identity)
            .call()
            .await?;
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn load_config_empty_path_returns_default() {
        let result: MarketsConfigPartial = load_config_from_file("").unwrap();
        assert!(result.pairs.is_empty());
    }

    #[test]
    fn load_config_missing_file_errors() {
        let result: Result<MarketsConfigPartial, _> =
            load_config_from_file("nonexistent_file_12345.json");
        assert!(result.is_err());
    }

    #[test]
    fn checked_sub_catches_overflow() {
        // Validates that our checked_sub pattern works correctly
        let decimals: u32 = 6;
        let max_precision: u32 = 8; // greater than decimals

        let result = decimals.checked_sub(max_precision);
        assert!(
            result.is_none(),
            "should return None when max_precision > decimals"
        );

        // Normal case
        let result = 9u32.checked_sub(6);
        assert_eq!(result, Some(3));
    }

    #[test]
    fn markets_config_partial_default_has_empty_pairs() {
        let config = MarketsConfigPartial::default();
        assert!(config.pairs.is_empty());
    }

    /// A tier verbatim from `networks/testnet/markets.json`, to prove
    /// `deny_unknown_fields` did not just invalidate every shipped config.
    pub(super) const LIVE_LEGACY_TIER: &str = r#"{
        "tier_id": 11,
        "line": "2500000000000",
        "leverage": 40,
        "duration": 0,
        "maintenance_bps": 150,
        "open_buffer_bps": 151,
        "liq_price_factor": 9900,
        "prolong_fee": ["10", "18", "60", "200"],
        "max_credit_line_bps": 20000,
        "max_price_age": 300,
        "open_fee": "0",
        "profit_share_bps": 0,
        "price_band_bps": 85,
        "markets": ["fwBTC/fUSDC", "fETH/fUSDC", "fXAUT/fUSDC"]
    }"#;

    fn turbo_tier(turbo: &str) -> String {
        format!(
            r#"{{
                "tier_id": 33,
                "line": "10000000000000",
                "leverage": 40,
                "duration": 604800,
                "maintenance_bps": 100,
                "open_buffer_bps": 101,
                "liq_price_factor": 9900,
                "prolong_fee": ["0", "0", "0", "0"],
                "max_credit_line_bps": 20000,
                "max_price_age": 300,
                "open_fee": "0",
                "profit_share_bps": 0,
                "price_band_bps": 100,
                "markets": ["fwBTC/fUSDC"],
                "turbo": {turbo}
            }}"#
        )
    }

    const SHIPPED_TERMS: &str = r#"{
        "max_loss_bps": [150, 200, 250, 300],
        "rollover_profit_bps": 900,
        "max_rollovers": 3
    }"#;

    /// Parsing preserves the historical defaults. Deployment validation rejects
    /// this enabled legacy shape; it must be explicitly retired or migrated to V2.
    #[test]
    fn a_legacy_tier_parses_with_enabled_default_but_is_not_publishable() {
        let tier: MarginTierConfig = serde_json::from_str(LIVE_LEGACY_TIER).unwrap();
        assert_eq!(tier.tier_id, 11);
        assert!(tier.turbo.is_none(), "no terms means the legacy cohort");
        assert!(tier.enabled, "the historical parsing default stays enabled");
        assert!(!tier.sidecar, "omitted selection keeps canonical books");
        assert!(
            required_turbo_terms(&tier)
                .unwrap_err()
                .to_string()
                .contains("legacy tier publishing is disabled")
        );
    }

    /// The whole point of the flag: a typo is a REFUSAL, not a silently
    /// dropped field. Before this, `max_los_bps` would have published a tier
    /// with no escalator at all.
    #[test]
    fn a_misspelled_tier_key_is_refused_rather_than_ignored() {
        let typo = LIVE_LEGACY_TIER.replace("\"leverage\"", "\"leverag\"");
        let err = serde_json::from_str::<MarginTierConfig>(&typo).unwrap_err();
        assert!(err.to_string().contains("leverag"), "{err}");

        let typo = turbo_tier(&SHIPPED_TERMS.replace("max_loss_bps", "max_los_bps"));
        let err = serde_json::from_str::<MarginTierConfig>(&typo).unwrap_err();
        assert!(err.to_string().contains("max_los_bps"), "{err}");
    }

    #[test]
    fn a_prepaid_tier_carries_its_terms_through_to_the_pools_shape() {
        let tier: MarginTierConfig =
            serde_json::from_str(&turbo_tier(SHIPPED_TERMS)).unwrap();
        assert!(!tier.sidecar, "prepaid terms do not select the sidecar");
        let turbo = tier.turbo.as_ref().expect("the tier declares terms");
        let terms = o2_tools::prop::TurboTerms::from(turbo);
        assert_eq!(terms.max_loss_bps, [150, 200, 250, 300]);
        assert_eq!(terms.rollover_profit_bps, 900);
        assert_eq!(terms.max_rollovers, 3);

        let params = tier_params(&tier, 9).unwrap();
        validate_turbo_tier_config(&tier, &params, &terms)
            .expect("the shipped shape is publishable");
    }

    #[test]
    fn prepaid_durations_parse_exactly_and_allow_valid_rollover_terms() {
        for (duration, json_duration) in [
            (1, "1"),
            (21_600, "21600"),
            (86_400, "86400"),
            (604_800, "604800"),
            (1_209_600, "1209600"),
            (u64::MAX - 1, "18446744073709551614"),
            (u64::MAX, "18446744073709551615"),
        ] {
            let json = turbo_tier(SHIPPED_TERMS).replace(
                "\"duration\": 604800",
                &format!("\"duration\": {json_duration}"),
            );
            let tier: MarginTierConfig = serde_json::from_str(&json).unwrap();
            assert_eq!(tier.duration, duration);
            let params = tier_params(&tier, 9).unwrap();
            assert_eq!(params.duration, duration);
            let terms = o2_tools::prop::TurboTerms::from(tier.turbo.as_ref().unwrap());
            validate_turbo_tier_config(&tier, &params, &terms)
                .expect("positive durations allow valid rollover terms, including perpetual tiers");
        }
    }

    #[test]
    fn a_three_percent_drawdown_needs_no_rollover() {
        let json = turbo_tier(
            r#"{
                "max_loss_bps": [300, 0, 0, 0],
                "rollover_profit_bps": 0,
                "max_rollovers": 0
            }"#,
        );
        for duration in [21_600, 604_800, u64::MAX] {
            let mut tier: MarginTierConfig = serde_json::from_str(&json).unwrap();
            tier.duration = duration;
            let params = tier_params(&tier, 9).unwrap();
            let terms = o2_tools::prop::TurboTerms::from(tier.turbo.as_ref().unwrap());
            validate_turbo_tier_config(&tier, &params, &terms)
                .expect("the line-based floor needs no rollover state");
        }
    }

    #[test]
    fn daily_loss_policy_accepts_disabled_zero_and_the_full_basis_point_range() {
        let mut tier: MarginTierConfig =
            serde_json::from_str(&turbo_tier(SHIPPED_TERMS)).unwrap();
        let params = tier_params(&tier, 9).unwrap();
        let terms = required_turbo_terms(&tier).unwrap();
        for limit in [None, Some(0), Some(1), Some(10_000)] {
            tier.daily_loss_limit_bps = limit;
            validate_turbo_tier_config(&tier, &params, &terms).unwrap();
        }
    }

    /// Each refusal the pool would make, made here instead - with a sentence
    /// naming which rule was broken rather than one revert code for all of
    /// them.
    #[test]
    fn a_config_the_pool_would_refuse_is_refused_before_it_costs_a_transaction() {
        let check = |mutate: &dyn Fn(&mut MarginTierConfig), expect: &str| {
            let mut tier: MarginTierConfig =
                serde_json::from_str(&turbo_tier(SHIPPED_TERMS)).unwrap();
            mutate(&mut tier);
            let params = tier_params(&tier, 9).unwrap();
            let terms = required_turbo_terms(&tier).unwrap();
            let err = validate_turbo_tier_config(&tier, &params, &terms)
                .expect_err("must be refused");
            assert!(
                err.to_string().contains(expect),
                "expected {expect:?} in: {err}"
            );
        };

        check(
            &|t| t.duration = 0,
            "duration` must be greater than 0 seconds",
        );
        check(&|t| t.line = 0, "line");
        check(&|t| t.leverage = 0, "leverage");
        check(&|t| t.leverage = t.line + 1, "leverage");
        check(&|t| t.maintenance_bps = 10_001, "maintenance_bps");
        check(&|t| t.open_buffer_bps = 10_001, "open_buffer_bps");
        check(
            &|t| t.open_buffer_bps = t.maintenance_bps,
            "above maintenance",
        );
        check(&|t| t.price_band_bps = 10_001, "price_band_bps");
        check(
            &|t| t.daily_loss_limit_bps = Some(10_001),
            "daily_loss_limit_bps",
        );
        check(
            &|t| t.daily_loss_limit_bps = Some(u64::MAX),
            "daily_loss_limit_bps",
        );
        check(&|t| t.liq_price_factor = 0, "liq_price_factor");
        check(&|t| t.liq_price_factor = 10_001, "liq_price_factor");
        check(&|t| t.max_credit_line_bps = u64::MAX, "cap does not fit");
        check(
            &|t| {
                t.open_buffer_bps = 9_999;
                t.max_credit_line_bps = 10_001;
            },
            "at or above the credit-line cap",
        );
        check(&|t| t.prolong_fee[2] = "60".to_owned(), "prolong_fee");
        check(&|t| t.profit_share_bps = 500, "profit_share_bps");
        for cap in [9_999, 10_000] {
            check(&|t| t.max_credit_line_bps = cap, "max_credit_line_bps");
        }
        check(&|t| t.open_buffer_bps = 251, "FROZEN");
        // A drawdown whose first step is zero opens every session already on
        // its liquidation line.
        check(
            &|t| t.turbo.as_mut().unwrap().max_loss_bps = [0, 200, 250, 300],
            "step 0 is 0",
        );
        check(
            &|t| t.turbo.as_mut().unwrap().max_loss_bps = [0; 4],
            "step 0 is 0",
        );
        // The gap the first cut of this guard left open: a zero in a LATER
        // reachable step seizes the user on the block after he earns that
        // week.
        check(
            &|t| t.turbo.as_mut().unwrap().max_loss_bps = [150, 0, 250, 300],
            "step 1 is 0",
        );
        check(
            &|t| t.turbo.as_mut().unwrap().max_loss_bps = [150, 200, 250, 0],
            "step 3 is 0",
        );
        // An escalator must never narrow.
        check(
            &|t| t.turbo.as_mut().unwrap().max_loss_bps = [150, 100, 250, 300],
            "NARROWER",
        );
        // ...but a step it can never reach is nobody's business.
        {
            let mut tier: MarginTierConfig =
                serde_json::from_str(&turbo_tier(SHIPPED_TERMS)).unwrap();
            let turbo = tier.turbo.as_mut().unwrap();
            turbo.max_rollovers = 1;
            turbo.max_loss_bps = [150, 200, 0, 0];
            let params = tier_params(&tier, 9).unwrap();
            let terms = required_turbo_terms(&tier).unwrap();
            validate_turbo_tier_config(&tier, &params, &terms)
                .expect("only reachable steps are policed");
        }
        // A rollover nobody can ever consume.
        check(
            &|t| {
                let turbo = t.turbo.as_mut().unwrap();
                turbo.max_rollovers = 0;
            },
            "max_rollovers",
        );
        check(
            &|t| t.turbo.as_mut().unwrap().max_loss_bps = [150, 200, 250, 10_001],
            "<= 10000",
        );
        check(
            &|t| t.turbo.as_mut().unwrap().rollover_profit_bps = 10_001,
            "rollover_profit_bps",
        );
    }

    #[test]
    fn legacy_tiers_may_be_retired_but_not_enabled() {
        for json in [LIVE_LEGACY_TIER.to_owned(), turbo_tier("null")] {
            let tier: MarginTierConfig = serde_json::from_str(&json).unwrap();
            let mut margin = MarginConfig {
                collateral_decimals: Some(9),
                tiers: vec![tier],
                ..Default::default()
            };
            let err = validate_margin_tier_catalogue(&margin)
                .unwrap_err()
                .to_string();
            assert!(
                err.contains(&format!("tier {}", margin.tiers[0].tier_id)),
                "{err}"
            );
            assert!(err.contains("legacy tier publishing is disabled"), "{err}");
            margin.tiers[0].enabled = false;
            validate_margin_tier_catalogue(&margin).unwrap();
        }
    }

    #[test]
    fn the_retired_catalogue_accepts_historical_terms_and_perpetual_active_tiers() {
        // The user's tier catalogue, with its original values and market lists.
        let margin: MarginConfig = serde_json::from_str(include_str!(
            "../tests/fixtures/retired-margin-catalogue.json"
        ))
        .unwrap();
        validate_margin_tier_catalogue(&margin).unwrap();
        assert_eq!(margin.tiers.iter().filter(|tier| !tier.enabled).count(), 9);
        for tier in margin.tiers.iter().filter(|tier| tier.enabled) {
            assert!([14, 24, 34].contains(&tier.tier_id));
            assert_eq!(tier.duration, u64::MAX);
        }
        for index in 0..9 {
            let mut reenabled = margin.clone();
            reenabled.tiers[index].enabled = true;
            let error = validate_margin_tier_catalogue(&reenabled).unwrap_err();
            assert!(
                error
                    .to_string()
                    .contains(&format!("tier {}", margin.tiers[index].tier_id))
            );
        }
    }

    #[test]
    fn a_catalogue_cannot_both_retire_and_enable_the_same_tier() {
        let mut tier: MarginTierConfig =
            serde_json::from_str(&turbo_tier(SHIPPED_TERMS)).unwrap();
        let mut margin = MarginConfig {
            collateral_decimals: Some(9),
            tiers: vec![tier.clone()],
            ..Default::default()
        };
        tier.enabled = false;
        margin.tiers.push(tier);
        let error = validate_margin_tier_catalogue(&margin).unwrap_err();
        assert!(error.to_string().contains("tier 33 appears more than once"));
    }
}

#[cfg(test)]
mod precision_budget_tests {
    use super::*;

    /// A pair shaped like every listed o2 market: `decimals: 9` on both sides,
    /// fractional prices off.
    fn pair(base_max: u8, quote_max: u8) -> OrderBookConfig {
        let asset = |symbol: &str, max_precision: u8| AssetConfig {
            symbol: symbol.to_string(),
            asset: Default::default(),
            decimals: 9,
            min_precision: 0,
            max_precision,
        };
        OrderBookConfig {
            contract_id: None,
            blob_id: None,
            house_identities: vec![],
            sidecar: None,
            market_id: Default::default(),
            taker_fee: 100,
            maker_fee: 0,
            min_order: 1_000_000_000,
            dust: 1_000,
            price_window: 0,
            allow_fractional_price: false,
            base: asset("TKN", base_max),
            quote: asset("USDC", quote_max),
        }
    }

    #[test]
    fn a_pair_that_spends_its_whole_budget_yields_the_contract_exponents() {
        // ENA/USDC: base 2 + quote 7 == 9, right on the limit.
        let (price, quantity) = order_book_precision_exponents(&pair(2, 7)).unwrap();
        assert_eq!(price, 2, "PRICE_PRECISION = 10^(9-7)");
        assert_eq!(quantity, 7, "QUANTITY_PRECISION = 10^(9-2)");
    }

    #[test]
    fn one_digit_over_budget_is_refused() {
        // The USDT/USDC trap: base 4 leaves room for 5 price digits, not 6.
        let err = order_book_precision_exponents(&pair(4, 6))
            .unwrap_err()
            .to_string();
        assert!(err.contains("FractionalPrice"), "{err}");
        assert!(err.contains("TKN/USDC"), "{err}");
        assert!(err.contains("= 10"), "{err}");
    }

    #[test]
    fn fractional_prices_downgrade_the_breach_to_a_warning() {
        // ALLOW_FRACTIONAL_PRICE truncates the notional rather than reverting,
        // so overspending is a smell there, not a hard failure.
        let mut config = pair(4, 6);
        config.allow_fractional_price = true;
        assert!(order_book_precision_exponents(&config).is_ok());
    }

    #[test]
    fn max_precision_beyond_the_asset_decimals_is_still_refused() {
        let err = order_book_precision_exponents(&pair(0, 10))
            .unwrap_err()
            .to_string();
        assert!(err.contains("exceeds decimals"), "{err}");
    }

    #[test]
    fn the_budget_tracks_the_quote_decimals_not_a_hardcoded_nine() {
        let mut config = pair(4, 2);
        config.quote.decimals = 6;
        assert!(
            order_book_precision_exponents(&config).is_ok(),
            "4 + 2 fits a 6-decimal quote"
        );

        config.quote.max_precision = 3;
        assert!(
            order_book_precision_exponents(&config).is_err(),
            "4 + 3 does not"
        );
    }
}

#[cfg(test)]
mod fee_amount_tests {
    use super::collateral_amount;

    fn at9(value: &str) -> anyhow::Result<u64> {
        collateral_amount(value, 9, "tier 1 open_fee")
    }

    #[test]
    fn whole_and_fractional_units_scale_by_the_asset_decimals() {
        assert_eq!(at9("7.5").unwrap(), 7_500_000_000);
        assert_eq!(at9("7").unwrap(), 7_000_000_000);
        assert_eq!(at9("0").unwrap(), 0);
        assert_eq!(at9("0.000000001").unwrap(), 1);
        assert_eq!(at9("13.5").unwrap(), 13_500_000_000);
        // The case a binary float gets wrong: `7.1 * 1e9` is 7099999999.99…
        assert_eq!(at9("7.1").unwrap(), 7_100_000_000);
    }

    #[test]
    fn a_figure_the_asset_cannot_represent_is_refused_not_rounded() {
        let err = at9("7.0000000001").unwrap_err().to_string();
        assert!(err.contains("10 decimal places"), "{err}");
        assert!(err.contains("tier 1 open_fee"), "{err}");
    }

    #[test]
    fn junk_is_refused() {
        for bad in ["", "   ", "-1", "1.2.3", "abc", "1e9", ".5", "1_000"] {
            assert!(at9(bad).is_err(), "`{bad}` should not parse");
        }
    }

    #[test]
    fn an_amount_past_u64_is_refused_rather_than_wrapping() {
        assert!(at9("18446744074").is_err());
        assert_eq!(at9("18446744073.709551615").unwrap(), u64::MAX);
    }

    #[test]
    fn other_decimal_scales_are_honoured() {
        assert_eq!(collateral_amount("7.5", 6, "f").unwrap(), 7_500_000);
        assert_eq!(collateral_amount("7.5", 1, "f").unwrap(), 75);
        assert!(collateral_amount("7.5", 0, "f").is_err());
        assert_eq!(collateral_amount("7", 0, "f").unwrap(), 7);
    }
}