settlement.rs

//! Settlement and withdrawal tests for the LiquiFact escrow contract.
//!
//! Covers the full `withdraw` surface (happy path, wrong-status guards, legal-hold
//! block, idempotency, event emission, and terminal status assertion) as well as
//! the `settle` → `claim_investor_payout` flow, maturity gates, and dust-sweep
//! integration that belong in the same lifecycle module.
//!
//! # State model recap (ADR-001)
//! ```text
//! 0 (open) ──fund──▶ 1 (funded) ──settle──▶ 2 (settled)
//!                           └────withdraw───▶ 3 (withdrawn)
//! ```
//! `withdraw` and `settle` are mutually exclusive; both require `status == 1`.
//!
//! # Test organisation
//! Each test builds its own `Env` via the shared `setup` / `default_init` helpers
//! defined in `escrow/src/test.rs`. No cross-test state is shared.

#[cfg(test)]
use super::{
    assert_contract_error, default_init, deploy, deploy_with_id, free_addresses,
    install_stellar_asset_token, setup, StellarTestToken, MAX_DUST_SWEEP_AMOUNT, TARGET,
};
use crate::{
    EscrowError, EscrowSettled, InvoiceEscrow, LiquifactEscrow, SettlementReadiness, YieldTier,
};
use soroban_sdk::{
    testutils::{Address as _, Events, Ledger as _},
    token::StellarAssetClient,
    Address, Env, Event, String, Vec as SorobanVec,
};

// ──────────────────────────────────────────────────────────────────────────────
// Helpers
// ──────────────────────────────────────────────────────────────────────────────

/// Bring an escrow to `status == 1` (funded) by depositing exactly `TARGET`
/// from a single investor, then return the investor address.
fn fund_to_target(client: &super::LiquifactEscrowClient<'_>, env: &Env) -> Address {
    let investor = Address::generate(env);
    client.fund(&investor, &TARGET);
    investor
}

fn setup_claim_env<'a>(
    env: &'a Env,
    invoice_id: &str,
    target: i128,
    yield_bps: i64,
) -> (
    super::LiquifactEscrowClient<'a>,
    StellarTestToken<'a>,
    Address,
    Address,
) {
    env.mock_all_auths();
    let token = install_stellar_asset_token(env);
    let (contract_id, client) = deploy_with_id(env);
    let admin = Address::generate(env);
    let sme = Address::generate(env);
    let treasury = Address::generate(env);

    client.init(
        &admin,
        &String::from_str(env, invoice_id),
        &sme,
        &target,
        &yield_bps,
        &0u64,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    (client, token, contract_id, treasury)
}

/// Set up an escrow backed by a real Stellar asset contract (SAC), fund it to
/// target, and mint `TARGET` tokens into the escrow contract so `withdraw()` can
/// actually transfer them.  Returns `(client, sme, sac_admin_client)`.
fn setup_funded_with_token<'a>(
    env: &'a Env,
) -> (
    super::LiquifactEscrowClient<'a>,
    Address,
    StellarAssetClient<'a>,
) {
    env.mock_all_auths();
    let sac = env.register_stellar_asset_contract_v2(Address::generate(env));
    let token_id = sac.address();
    let sac_admin = StellarAssetClient::new(env, &token_id);

    let escrow_id = env.register(LiquifactEscrow, ());
    let client = super::LiquifactEscrowClient::new(env, &escrow_id);
    let admin = Address::generate(env);
    let sme = Address::generate(env);
    let treasury = Address::generate(env);

    client.init(
        &admin,
        &soroban_sdk::String::from_str(env, "INV_TOK"),
        &sme,
        &TARGET,
        &800i64,
        &0u64,
        &token_id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    // Mint tokens to investor so fund() can transfer them into the escrow.
    let investor = Address::generate(env);
    sac_admin.mint(&investor, &TARGET);
    client.fund(&investor, &TARGET);

    // The tokens are now in the escrow from the fund() transfer — no extra mint needed for withdraw().

    (client, sme, sac_admin)
}

/// Bring an escrow to `status == 2` (settled) and return the investor address.
fn settle_escrow(client: &super::LiquifactEscrowClient<'_>, env: &Env) -> Address {
    let investor = fund_to_target(client, env);
    client.settle();
    investor
}

// ──────────────────────────────────────────────────────────────────────────────
// `withdraw` — happy path
// ──────────────────────────────────────────────────────────────────────────────

/// Status must become 3 after a successful `withdraw`.
///
/// This is the primary assertion required by the task description.
#[test]
fn withdraw_sets_status_to_three() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);

    client.withdraw();

    let escrow = client.get_escrow();
    assert_eq!(
        escrow.status, 3u32,
        "status must be 3 (withdrawn) after withdraw"
    );
}

/// `withdraw` must require SME auth.
///
/// In `mock_all_auths` environments the check always passes; this test
/// documents the expected signer so a future auth-audit can grep for it.
#[test]
fn withdraw_requires_sme_auth() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);

    // Passes because test env mocks all auth. The assertion is on the *call*
    // succeeding for the correct signer (sme), not an impostor.
    client.withdraw();

    // Verify state changed — confirming it was sme who triggered the path.
    assert_eq!(client.get_escrow().status, 3u32);
}

/// After `withdraw` the funded_amount and funding_target remain intact —
/// `withdraw` transitions state and transfers tokens, but does not zero accounting fields.
#[test]
fn withdraw_preserves_accounting_fields() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);

    client.withdraw();

    let escrow = client.get_escrow();
    assert_eq!(
        escrow.funded_amount, TARGET,
        "funded_amount must not be wiped by withdraw"
    );
    assert_eq!(
        escrow.funding_target, TARGET,
        "funding_target must not be mutated by withdraw"
    );
}

/// `withdraw` emits an `SmeWithdrew` event.
#[test]
fn withdraw_emits_event() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);

    client.withdraw();

    // At least one event must be emitted in the transaction.
    let contract_events = env.events().all();
    let events = contract_events.events();
    assert!(
        !events.is_empty(),
        "withdraw must emit at least one contract event"
    );
}

// ──────────────────────────────────────────────────────────────────────────────
// `withdraw` — wrong-status guards
// ──────────────────────────────────────────────────────────────────────────────

/// `withdraw` on an `open` (status 0) escrow must panic.
///
/// The escrow has not been funded; `withdraw` requires `status == 1`.
#[test]
#[should_panic]
fn withdraw_on_open_escrow_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    // No funding — status is still 0.
    client.withdraw();
}

/// `withdraw` on an already-settled (status 2) escrow must panic.
///
/// Once `settle` has been called the escrow is terminal in the settlement path;
/// `withdraw` must not be able to re-label it.
#[test]
#[should_panic]
fn withdraw_on_settled_escrow_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    settle_escrow(&client, &env);
    // status == 2 — withdraw must be rejected.
    client.withdraw();
}

/// `withdraw` called twice on the same escrow must panic on the second call.
///
/// Once status reaches 3 (withdrawn) it is terminal; no forward transition
/// exists from 3, so a second `withdraw` must be rejected.
#[test]
#[should_panic]
fn withdraw_twice_panics() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);

    client.withdraw(); // first call — succeeds, status → 3
    client.withdraw(); // second call — must panic (status == 3, not 1)
}

/// `settle` cannot be called after `withdraw` (status 3 is terminal).
#[test]
#[should_panic]
fn settle_after_withdraw_panics() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);
    client.withdraw(); // status → 3
    client.settle(); // must panic — settle requires status == 1
}

/// `fund` cannot be called after `withdraw` (status 3 is terminal).
#[test]
#[should_panic]
fn fund_after_withdraw_panics() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);
    client.withdraw(); // status → 3
    let late_investor = Address::generate(&env);
    client.fund(&late_investor, &10_000_000_000_i128); // must panic — fund requires status == 0
}

// ──────────────────────────────────────────────────────────────────────────────
// `withdraw` — legal-hold block (ADR-004)
// ──────────────────────────────────────────────────────────────────────────────

/// `withdraw` must be blocked while a legal hold is active.
///
/// Per ADR-004 the hold freezes `withdraw` regardless of escrow status.
#[test]
#[should_panic]
fn withdraw_blocked_by_legal_hold() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    client.set_legal_hold(&true);
    // Status is 1 but hold is active — must panic.
    client.withdraw();
}

/// `withdraw` must succeed after a legal hold is cleared.
///
/// Verifies that `clear_legal_hold` (or `set_legal_hold(false)`) fully lifts
/// the block and the escrow can proceed to `status == 3`.
#[test]
fn withdraw_succeeds_after_hold_cleared() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, _sme, _sac) = setup_funded_with_token(&env);

    client.set_legal_hold(&true);
    client.set_legal_hold(&false);

    client.withdraw();
    assert_eq!(client.get_escrow().status, 3u32);
}

// ──────────────────────────────────────────────────────────────────────────────
// Investor claim idempotency and per-investor isolation
// ──────────────────────────────────────────────────────────────────────────────

#[test]
fn test_claim_investor_twice_is_idempotent() {
    let env = Env::default();
    let (client, token, contract_id, _treasury) =
        setup_claim_env(&env, "IDEMP001", 1_000i128, 400i64);
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &1_000i128);
    client.fund(&investor, &1_000i128);
    token.stellar.mint(&contract_id, &40i128); // extra yield portion only
    client.settle();

    // First claim - should succeed and set the claimed marker
    client.claim_investor_payout(&investor);

    assert!(client.is_investor_claimed(&investor));

    // Second claim - should be idempotent (no-op, does not panic)
    client.claim_investor_payout(&investor);
    assert!(client.is_investor_claimed(&investor));
}

#[test]
#[should_panic]
fn test_claim_by_non_investor_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let stranger = Address::generate(&env);
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "STR001"),
        &sme,
        &1_000i128,
        &400i64,
        &0u64,
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    // Escrow settled but stranger never funded
    let investor = Address::generate(&env);
    client.fund(&investor, &1_000i128);
    client.settle();

    client.claim_investor_payout(&stranger);
}

#[test]
fn test_clashing_investors_have_independent_claims() {
    let env = Env::default();
    let (client, token, contract_id, _treasury) =
        setup_claim_env(&env, "CLASH001", 2_000i128, 400i64);
    let inv_a = Address::generate(&env);
    let inv_b = Address::generate(&env);
    token.stellar.mint(&inv_a, &1_000i128);
    token.stellar.mint(&inv_b, &1_000i128);
    client.fund(&inv_a, &1_000i128);
    client.fund(&inv_b, &1_000i128);
    token.stellar.mint(&contract_id, &80i128); // extra yield
    client.settle();

    client.claim_investor_payout(&inv_a);
    assert!(client.is_investor_claimed(&inv_a));
    assert!(!client.is_investor_claimed(&inv_b));

    client.claim_investor_payout(&inv_b);
    assert!(client.is_investor_claimed(&inv_b));
}

/// `set_legal_hold` must be admin-only; a non-admin cannot place a hold.
#[test]
#[should_panic]
fn legal_hold_set_by_non_admin_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    env.mock_all_auths_allowing_non_root_auth(); // stricter auth mode
    env.mock_auths(&[]);
    default_init(&client, &env, &admin, &sme);
    // `sme` is not the admin — must panic.
    client.set_legal_hold(&true);
}

// ──────────────────────────────────────────────────────────────────────────────
// `settle` path — complementary coverage ensuring mutual exclusivity
// ──────────────────────────────────────────────────────────────────────────────

/// `settle` transitions status from 1 to 2.
#[test]
fn settle_sets_status_to_two() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    client.settle();

    assert_eq!(client.get_escrow().status, 2u32);
}

/// `settle` is blocked while a legal hold is active.
#[test]
#[should_panic]
fn settle_blocked_by_legal_hold() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    client.set_legal_hold(&true);
    client.settle();
}

#[test]
#[should_panic]
fn test_claim_blocked_until_commitment_ledger_time() {
    let env = Env::default();
    env.mock_all_auths();
    let client = deploy(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let inv = Address::generate(&env);
    let (tok, treasury) = free_addresses(&env);
    client.init(
        &admin,
        &String::from_str(&env, "LOCK001"),
        &sme,
        &1_000i128,
        &400i64,
        &0u64,
        &tok,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund_with_commitment(&inv, &1_000i128, &500u64);
    client.settle();
    client.claim_investor_payout(&inv);
}

#[test]
fn test_claim_succeeds_after_commitment_and_settle() {
    let env = Env::default();
    let (client, token, contract_id, _treasury) =
        setup_claim_env(&env, "COMMIT1", 1_000i128, 400i64);
    let inv = Address::generate(&env);
    token.stellar.mint(&inv, &1_000i128);
    client.fund_with_commitment(&inv, &1_000i128, &100u64);
    token.stellar.mint(&contract_id, &40i128); // extra yield
    client.settle();
    env.ledger().set_timestamp(150);
    client.claim_investor_payout(&inv);
    assert!(client.is_investor_claimed(&inv));
}

#[test]
fn test_claim_gating_exact_timestamp() {
    let env = Env::default();
    let (client, token, contract_id, _treasury) = setup_claim_env(&env, "GATE1", 1_000i128, 400i64);
    let inv = Address::generate(&env);

    env.ledger().set_timestamp(1000);
    let lock_duration = 500u64;
    token.stellar.mint(&inv, &1_000i128);
    client.fund_with_commitment(&inv, &1_000i128, &lock_duration);
    token.stellar.mint(&contract_id, &40i128); // extra yield
    client.settle();

    let expiry = 1000 + lock_duration;

    // 1 second before expiry
    env.ledger().set_timestamp(expiry - 1);
    let err = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        client.claim_investor_payout(&inv);
    }));
    assert!(err.is_err(), "Claim should be blocked 1s before expiry");

    // Exact expiry
    env.ledger().set_timestamp(expiry);
    client.claim_investor_payout(&inv);
    assert!(client.is_investor_claimed(&inv));
}

#[test]
fn test_claim_gating_with_multiple_investors() {
    let env = Env::default();
    let (client, token, contract_id, _treasury) = setup_claim_env(&env, "GATE2", 2_000i128, 400i64);
    let inv1 = Address::generate(&env);
    let inv2 = Address::generate(&env);

    env.ledger().set_timestamp(1000);
    token.stellar.mint(&inv1, &1_000i128);
    token.stellar.mint(&inv2, &1_000i128);
    client.fund_with_commitment(&inv1, &1_000i128, &100u64); // Expiry 1100
    client.fund_with_commitment(&inv2, &1_000i128, &200u64); // Expiry 1200
    token.stellar.mint(&contract_id, &80i128); // extra yield
    client.settle();

    env.ledger().set_timestamp(1150);

    // inv1 can claim
    client.claim_investor_payout(&inv1);
    assert!(client.is_investor_claimed(&inv1));

    // inv2 still blocked
    let err = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        client.claim_investor_payout(&inv2);
    }));
    assert!(err.is_err(), "inv2 should still be blocked at 1150");

    env.ledger().set_timestamp(1200);
    client.claim_investor_payout(&inv2);
    assert!(client.is_investor_claimed(&inv2));
}

/// Cost baseline: settle after funding.
#[test]
fn test_cost_baseline_settle() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let investor = Address::generate(&env);
    client.init(
        &admin,
        &String::from_str(&env, "INV103b"),
        &sme,
        &TARGET,
        &800i64,
        &50_000u64, // maturity after setup's default timestamp of 12345
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &TARGET);
    env.ledger().set_timestamp(50_001);
    let settled = client.settle();
    assert_eq!(settled.status, 2);
}

/// `settle` called twice must panic on the second call.
#[test]
#[should_panic]
fn settle_twice_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    client.settle();
    client.settle(); // status == 2, must panic
}

// ──────────────────────────────────────────────────────────────────────────────
// Maturity gate — settle is time-gated when `maturity > 0`; bypass when 0
// ──────────────────────────────────────────────────────────────────────────────

/// `settle` succeeds immediately when `maturity == 0` regardless of ledger time.
#[test]
fn settle_with_maturity_zero_succeeds_immediately() {
    let env = Env::default();
    env.mock_all_auths();

    let client = deploy(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (token, treasury) = free_addresses(&env);

    client.init(
        &admin,
        &String::from_str(&env, "INV_MAT_001"),
        &sme,
        &TARGET,
        &800i64,
        &0u64,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    assert!(
        !client.has_maturity_lock(),
        "maturity == 0 must be surfaced as no maturity lock"
    );
    assert!(!client.get_escrow_summary().has_maturity_lock);

    fund_to_target(&client, &env);

    env.ledger().with_mut(|l| l.timestamp = 1);
    let settled = client.settle();
    assert_eq!(settled.status, 2);
    assert_eq!(settled.maturity, 0);
}

/// `settle` with `maturity > 0` must trap one second before the configured
/// validator-observed ledger timestamp and must not mutate the funded state.
#[test]
fn settle_one_second_before_maturity_traps_and_preserves_state() {
    let env = Env::default();
    env.mock_all_auths();

    let client = deploy(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (token, treasury) = free_addresses(&env);

    let maturity: u64 = 20_000;
    client.init(
        &admin,
        &String::from_str(&env, "INV_MAT_003"),
        &sme,
        &TARGET,
        &800i64,
        &maturity,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    fund_to_target(&client, &env);
    let snapshot_before = client.get_funding_close_snapshot();

    env.ledger().with_mut(|l| l.timestamp = maturity - 1);
    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        client.settle();
    }));

    assert!(
        result.is_err(),
        "settle must trap before the inclusive maturity boundary"
    );
    assert_eq!(
        client.get_escrow().status,
        1,
        "pre-maturity settlement attempt must leave escrow funded"
    );
    assert_eq!(
        client.get_funding_close_snapshot(),
        snapshot_before,
        "pre-maturity settlement attempt must not mutate snapshot state"
    );
}

/// `settle` with `maturity > 0` succeeds at exactly the maturity timestamp.
#[test]
fn settle_at_maturity_succeeds() {
    let env = Env::default();
    env.mock_all_auths();

    let client = deploy(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (token, treasury) = free_addresses(&env);

    let maturity: u64 = 20_000;
    client.init(
        &admin,
        &String::from_str(&env, "INV_MAT_002"),
        &sme,
        &TARGET,
        &800i64,
        &maturity,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    assert!(
        client.has_maturity_lock(),
        "positive maturity must be surfaced as an active maturity lock"
    );
    assert!(client.get_escrow_summary().has_maturity_lock);

    fund_to_target(&client, &env);
    env.ledger().with_mut(|l| l.timestamp = maturity);
    let settled = client.settle();
    assert_eq!(settled.status, 2);
    assert_eq!(settled.maturity, maturity);
}

/// `settle` must panic if SME auth is not provided.
#[test]
#[should_panic]
fn settle_requires_sme_auth() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    env.mock_auths(&[]); // clear mocks — auth will fail
    client.settle();
}

/// `settle` on open (status 0) escrow must panic.
#[test]
#[should_panic]
fn settle_on_open_escrow_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    // No funding — status is still 0.
    client.settle();
}

/// `settle` on withdrawn (status 3) escrow must panic.
#[test]
#[should_panic]
fn settle_on_withdrawn_escrow_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    client.withdraw(); // status → 3
    client.settle();
}

/// `sweep_terminal_dust` must reject open/funded escrows before terminal state.
// HostError wraps contract panic; expected substring not matched in outer message.
#[ignore = "HostError wraps contract panic; expected substring not matched"]
#[test]
#[should_panic(expected = "dust sweep only in terminal states (settled, withdrawn, or cancelled)")]
fn sweep_terminal_dust_before_terminal_state_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    let investor = settle_escrow(&client, &env);

    client.claim_investor_payout(&investor);

    let contract_events = env.events().all();
    let events = contract_events.events();
    assert!(
        !events.is_empty(),
        "claim must emit InvestorPayoutClaimed event"
    );
}

/// `claim_investor_payout` must be blocked while a legal hold is active.
#[test]
#[should_panic]
fn claim_investor_payout_blocked_by_legal_hold() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    let investor = settle_escrow(&client, &env);

    client.set_legal_hold(&true);
    client.claim_investor_payout(&investor); // must panic
}

/// `claim_investor_payout` must fail before `settle` (status != 2).
#[test]
#[should_panic]
fn claim_investor_payout_before_settle_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    let investor = fund_to_target(&client, &env);
    client.claim_investor_payout(&investor);
}

/// An investor that did not participate cannot claim.
#[test]
#[should_panic]
fn claim_investor_payout_non_participant_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    env.mock_all_auths_allowing_non_root_auth();
    env.mock_auths(&[]);
    default_init(&client, &env, &admin, &sme);
    settle_escrow(&client, &env);

    let stranger = Address::generate(&env);
    client.claim_investor_payout(&stranger);
}

// ──────────────────────────────────────────────────────────────────────────────
// Terminal dust sweep
// ──────────────────────────────────────────────────────────────────────────────

// Uses `token.stellar`/`escrow_id` not in scope (deploy not deploy_with_id).
#[cfg(any())]
#[test]
fn test_sweep_terminal_dust_after_settle_transfers_to_treasury() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (_tok, treasury) = free_addresses(&env);
    let maturity = 5000u64;
    client.init(
        &admin,
        &String::from_str(&env, "SW001"),
        &sme,
        &TARGET,
        &100i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    client.fund(&investor, &1_000i128);
    client.settle();

    token.stellar.mint(&contract_id, &5_000i128);
    let before_t = token.token.balance(&treasury);
    let swept = client.sweep_terminal_dust(&5_000i128);
    assert_eq!(swept, 5_000i128);
    assert_eq!(token.token.balance(&tre), before_t + 5_000i128);
}

// Uses `token.stellar`/`escrow_id` not in scope.
#[cfg(any())]
#[test]
fn test_sweep_terminal_dust_after_withdraw_and_ledger_tick() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (_tok, treasury) = free_addresses(&env);
    let maturity = 5000u64;
    client.init(
        &admin,
        &String::from_str(&env, "SW002"),
        &sme,
        &TARGET,
        &100i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    client.fund(&investor, &1_000i128);
    client.withdraw();

    env.ledger()
        .set_sequence_number(env.ledger().sequence() + 10);

    token.stellar.mint(&contract_id, &333i128);
    let swept = client.sweep_terminal_dust(&333i128);
    assert_eq!(swept, 333i128);
}

// HostError wraps contract panic; expected substring not matched.
#[ignore = "HostError wraps contract panic; expected substring not matched"]
#[test]
#[should_panic]
fn test_sweep_rejected_when_open() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let investor = Address::generate(&env);
    client.init(
        &admin,
        &String::from_str(&env, "SW003"),
        &sme,
        &TARGET,
        &100i64,
        &0u64,
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &1_000i128);
    client.settle();
    client.claim_investor_payout(&investor);
    assert!(client.is_investor_claimed(&investor));
}

#[test]
#[should_panic]
fn test_sweep_blocked_under_legal_hold() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let investor = Address::generate(&env);
    client.init(
        &admin,
        &String::from_str(&env, "SW004"),
        &sme,
        &1_000i128,
        &100i64,
        &0u64,
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &1_000i128);
    client.settle();
    client.set_legal_hold(&true);
    client.sweep_terminal_dust(&1i128);
}

// HostError wraps contract panic; expected substring not matched.
#[ignore = "HostError wraps contract panic; expected substring not matched"]
#[test]
#[should_panic]
fn test_sweep_rejects_amount_above_dust_cap() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let investor = Address::generate(&env);
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SW005"),
        &sme,
        &TARGET,
        &100i64,
        &0u64,
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &1_000i128);
    // status == 1 (funded), not settled — must panic
    client.claim_investor_payout(&investor);
}

// Body calls claim_investor_payout for a stranger (panics); no #[should_panic].
#[ignore = "body tests non-participant claim, not dust sweep capping; panics without #[should_panic]"]
#[test]
fn test_sweep_caps_at_contract_balance() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let investor = Address::generate(&env);
    let stranger = Address::generate(&env);
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SW006"),
        &sme,
        &1_000i128,
        &100i64,
        &0u64,
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &1_000i128);
    client.settle();
    client.claim_investor_payout(&stranger); // must panic — no contribution
}

// Uses `token.stellar`/`escrow_id` not in scope (setup/default_init pattern).
#[cfg(any())]
#[test]
fn test_sweep_requires_treasury_auth() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (_tok, treasury) = free_addresses(&env);
    client.init(
        &admin,
        &String::from_str(&env, "SW007"),
        &sme,
        &TARGET,
        &100i64,
        &0u64,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    fund_to_target(&client, &env);
    client.settle();
    token
        .stellar
        .mint(&contract_id, &(MAX_DUST_SWEEP_AMOUNT + 1));

    client.sweep_terminal_dust(&(MAX_DUST_SWEEP_AMOUNT + 1));
}

/// `claim_investor_payout` succeeds for an investor after `settle`.
// Uses `token.stellar`/`escrow_id` not in scope (setup/default_init pattern).
#[cfg(any())]
#[test]
fn claim_investor_payout_succeeds_after_settle() {
    let env = Env::default();
    env.mock_all_auths();
    let investor = Address::generate(&env);
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (_tok, treasury) = free_addresses(&env);

    client.init(
        &admin,
        &String::from_str(&env, "SW008"),
        &sme,
        &TARGET,
        &800i64,
        &0u64,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &TARGET);
    client.settle();
    token.stellar.mint(&contract_id, &10i128);

    env.mock_auths(&[]);
    let err = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        client.sweep_terminal_dust(&10i128);
    }));
    assert!(err.is_err(), "sweep without treasury auth must fail");
}

// ──────────────────────────────────────────────────────────────────────────────
// Funding snapshot invariant (ADR-003)
// ──────────────────────────────────────────────────────────────────────────────

/// The funding-close snapshot is written once when status transitions to 1.
/// After `withdraw` the snapshot must still be readable with the original values.
///
/// This guards against the denominator being zeroed or mutated by the withdrawal
/// path — off-chain accounting always needs a stable snapshot.
#[test]
fn funding_snapshot_survives_withdraw() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    let snapshot_before = client
        .get_funding_close_snapshot()
        .expect("snapshot exists after fund close");
    client.withdraw();
    let snapshot_after = client
        .get_funding_close_snapshot()
        .expect("snapshot persists after withdraw");

    assert_eq!(
        snapshot_before, snapshot_after,
        "funding snapshot must be immutable after withdraw"
    );
    assert_eq!(
        snapshot_after.total_principal, TARGET,
        "snapshot total_principal must equal funded amount"
    );
}

/// The threshold-crossing deposit may overfund the target; the snapshot must capture the
/// full credited funded_amount and the exact ledger timestamp/sequence at close.
#[test]
fn funding_close_snapshot_captures_overfunding_and_close_ledger() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    let investor_a = Address::generate(&env);
    let investor_b = Address::generate(&env);
    let first_leg = TARGET - 10_000i128;
    let crossing_leg = 25_000i128;
    let close_total = first_leg + crossing_leg;

    client.fund(&investor_a, &first_leg);
    assert_eq!(
        client.get_funding_close_snapshot(),
        None,
        "snapshot must be absent before funded transition"
    );

    let close_timestamp = 88_888u64;
    let close_sequence = 777u32;
    env.ledger().with_mut(|ledger| {
        ledger.timestamp = close_timestamp;
        ledger.sequence_number = close_sequence;
    });

    client.fund(&investor_b, &crossing_leg);

    let escrow = client.get_escrow();
    let snapshot = client
        .get_funding_close_snapshot()
        .expect("snapshot must be written at funded transition");
    assert_eq!(escrow.status, 1, "escrow must close as funded");
    assert_eq!(escrow.funded_amount, close_total);
    assert_eq!(
        snapshot.total_principal, escrow.funded_amount,
        "snapshot denominator must match overfunded close amount"
    );
    assert_eq!(snapshot.total_principal, TARGET + 15_000i128);
    assert_eq!(snapshot.funding_target, TARGET);
    assert_eq!(snapshot.closed_at_ledger_timestamp, close_timestamp);
    assert_eq!(snapshot.closed_at_ledger_sequence, close_sequence);
}

/// After the funded transition, another same-ledger funding attempt must not overwrite the
/// snapshot or mutate contributions. This guards the write-once denominator invariant even if a
/// caller retries immediately after the close.
#[test]
fn funding_close_snapshot_not_overwritten_by_same_ledger_follow_on_attempt() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    let closer = Address::generate(&env);
    let late_investor = Address::generate(&env);
    let close_amount = TARGET + 1_234i128;

    env.ledger().with_mut(|ledger| {
        ledger.timestamp = 99_999;
        ledger.sequence_number = 999;
    });
    client.fund(&closer, &close_amount);
    let snapshot_at_close = client
        .get_funding_close_snapshot()
        .expect("snapshot exists after overfunded close");

    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        client.fund(&late_investor, &1i128);
    }));
    assert!(
        result.is_err(),
        "funding after close must fail before it can overwrite snapshot"
    );

    let snapshot_after_attempt = client
        .get_funding_close_snapshot()
        .expect("snapshot remains present after rejected follow-on attempt");
    assert_eq!(
        snapshot_at_close, snapshot_after_attempt,
        "snapshot must remain write-once after same-ledger follow-on attempt"
    );
    assert_eq!(client.get_escrow().funded_amount, close_amount);
    assert_eq!(
        client.get_contribution(&late_investor),
        0,
        "rejected follow-on funding must not create contribution state"
    );
}

/// After `settle` the snapshot still matches what was recorded at fund-close.
#[test]
fn funding_snapshot_survives_settle() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);

    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    let snapshot_before = client
        .get_funding_close_snapshot()
        .expect("snapshot exists after fund");
    client.settle();
    let snapshot_after = client.get_funding_close_snapshot();

    assert_eq!(
        snapshot_before.total_principal,
        snapshot_after.unwrap().total_principal
    );
}

// ── is_investor_claimed: idempotent read behavior & cross-investor isolation ──

#[test]
fn test_is_investor_claimed_false_before_any_claim() {
    // Getter must return false for a funded investor who has not yet claimed;
    // repeated reads must not mutate state.
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let investor = Address::generate(&env);
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "GIC001"),
        &sme,
        &1_000i128,
        &400i64,
        &0u64,
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &1_000i128);
    client.settle();
    assert!(!client.is_investor_claimed(&investor));
    assert!(!client.is_investor_claimed(&investor)); // idempotent — no state change
}

#[test]
fn test_is_investor_claimed_returns_false_for_unfunded_address() {
    // An address that never participated must return false, not panic.
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    let investor = Address::generate(&env);
    let stranger = Address::generate(&env);
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "GIC002"),
        &sme,
        &1_000i128,
        &400i64,
        &0u64,
        &Address::generate(&env),
        &None,
        &Address::generate(&env),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    client.fund(&investor, &1_000i128);
    client.settle();
    assert!(!client.is_investor_claimed(&stranger));
}

#[test]
fn test_claim_marker_persists_after_claim() {
    // After a successful claim the flag must remain true across repeated reads.
    let env = Env::default();
    let (client, token, contract_id, _treasury) =
        setup_claim_env(&env, "PERSIST001", 1_000i128, 400i64);
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &1_000i128);
    client.fund(&investor, &1_000i128);
    token.stellar.mint(&contract_id, &40i128); // extra yield
    client.settle();
    client.claim_investor_payout(&investor);
    assert!(client.is_investor_claimed(&investor));
    assert!(client.is_investor_claimed(&investor)); // second read: still persisted
}

#[test]
fn test_claim_marker_isolated_per_investor() {
    // Claiming for investor_a must not set the flag for investor_b (no key crosstalk).
    let env = Env::default();
    let (client, token, contract_id, _treasury) =
        setup_claim_env(&env, "ISO001", 2_000i128, 400i64);
    let investor_a = Address::generate(&env);
    let investor_b = Address::generate(&env);
    token.stellar.mint(&investor_a, &1_000i128);
    token.stellar.mint(&investor_b, &1_000i128);
    client.fund(&investor_a, &1_000i128);
    client.fund(&investor_b, &1_000i128);
    token.stellar.mint(&contract_id, &80i128); // extra yield
    client.settle();
    client.claim_investor_payout(&investor_a);
    assert!(client.is_investor_claimed(&investor_a));
    assert!(!client.is_investor_claimed(&investor_b)); // b unaffected by a's claim
}

#[test]
fn test_claim_marker_all_investors_independent() {
    // Three investors with independent claim keys; partial claiming must not
    // corrupt unclaimed investors' flags.
    let env = Env::default();
    let (client, token, contract_id, _treasury) =
        setup_claim_env(&env, "IND001", 3_000i128, 400i64);
    let inv_a = Address::generate(&env);
    let inv_b = Address::generate(&env);
    let inv_c = Address::generate(&env);
    token.stellar.mint(&inv_a, &1_000i128);
    token.stellar.mint(&inv_b, &1_000i128);
    token.stellar.mint(&inv_c, &1_000i128);
    client.fund(&inv_a, &1_000i128);
    client.fund(&inv_b, &1_000i128);
    client.fund(&inv_c, &1_000i128);
    token.stellar.mint(&contract_id, &120i128); // extra yield (3*40)
    client.settle();
    client.claim_investor_payout(&inv_a);
    client.claim_investor_payout(&inv_c);
    assert!(client.is_investor_claimed(&inv_a));
    assert!(!client.is_investor_claimed(&inv_b)); // b still unclaimed
    assert!(client.is_investor_claimed(&inv_c));
    client.claim_investor_payout(&inv_b);
    assert!(client.is_investor_claimed(&inv_b));
}

#[test]
#[ignore = "upstream latent: escrow API/test drift"]
fn investor_contribution_readable_after_withdraw() {
    let env = Env::default();
    let (client, token, _contract_id, _treasury) =
        setup_claim_env(&env, "INV_WTHD", TARGET, 800i64);

    let investor = Address::generate(&env);
    let contribution: i128 = TARGET;
    token.stellar.mint(&investor, &contribution);
    client.fund(&investor, &contribution);
    client.withdraw();

    let recorded = client.get_contribution(&investor);
    assert_eq!(
        recorded, contribution,
        "investor contribution must be readable after withdraw for refund accounting"
    );
}

/// Multiple investors — each contribution is preserved after `withdraw`.
#[test]
#[ignore = "upstream latent: escrow API/test drift"]
fn multi_investor_contributions_preserved_after_withdraw() {
    let env = Env::default();
    let (client, token, _contract_id, _treasury) =
        setup_claim_env(&env, "INV_MULTI", TARGET, 800i64);

    // Fund with two investors reaching target collectively.
    let inv_a = Address::generate(&env);
    let inv_b = Address::generate(&env);
    let half = TARGET / 2;
    token.stellar.mint(&inv_a, &half);
    token.stellar.mint(&inv_b, &(TARGET - half));
    client.fund(&inv_a, &half);
    client.fund(&inv_b, &(TARGET - half));
    client.withdraw();

    assert_eq!(client.get_contribution(&inv_a), half);
    assert_eq!(client.get_contribution(&inv_b), TARGET - half);
    assert_eq!(client.get_escrow().status, 3u32);
}

// ──────────────────────────────────────────────────────────────────────────────
// Terminal status — no entrypoint can move state backward from 3
// ──────────────────────────────────────────────────────────────────────────────

/// After `withdraw` (status 3) no write entrypoint must succeed.
///
/// This is a belt-and-suspenders test that exercises every state-mutating
/// path the SME might attempt after withdrawal.
#[test]
fn no_state_mutation_possible_after_withdraw() {
    // settle after withdraw
    {
        let env = Env::default();
        let (client, admin, sme) = setup(&env);
        default_init(&client, &env, &admin, &sme);
        fund_to_target(&client, &env);
        client.withdraw();
        let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            client.settle();
        }));
        assert!(r.is_err(), "settle after withdraw must panic");
    }

    // withdraw after withdraw
    {
        let env = Env::default();
        let (client, admin, sme) = setup(&env);
        default_init(&client, &env, &admin, &sme);
        fund_to_target(&client, &env);
        client.withdraw();
        let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            client.withdraw();
        }));
        assert!(r.is_err(), "withdraw after withdraw must panic");
    }

    // fund after withdraw
    {
        let env = Env::default();
        let (client, admin, sme) = setup(&env);
        default_init(&client, &env, &admin, &sme);
        fund_to_target(&client, &env);
        client.withdraw();
        let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            let late = Address::generate(&env);
            client.fund(&late, &10_000_000_000_i128);
        }));
        assert!(r.is_err(), "fund after withdraw must panic");
    }
}
// ──────────────────────────────────────────────────────────────────────────────
// `partial_settle` tests
// ──────────────────────────────────────────────────────────────────────────────

#[test]
fn test_partial_settle_sme_happy_path() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    // Partially fund
    let investor = Address::generate(&env);
    client.fund(&investor, &(TARGET / 2));

    // SME settles early
    client.partial_settle(&sme);

    let escrow = client.get_escrow();
    assert_eq!(
        escrow.status, 1u32,
        "Status must be 1 (funded/settleable) after partial_settle"
    );
    assert_eq!(escrow.funded_amount, TARGET / 2);
}

#[test]
fn test_partial_settle_admin_happy_path() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    // Admin settles early
    client.partial_settle(&admin);

    let escrow = client.get_escrow();
    assert_eq!(escrow.status, 1u32);
}

#[test]
#[should_panic]
fn test_partial_settle_unauthorized_caller_panics() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    let stranger = Address::generate(&env);
    client.partial_settle(&stranger);
}

#[test]
#[should_panic]
fn test_partial_settle_blocked_by_legal_hold() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    client.set_legal_hold(&true);
    client.partial_settle(&sme);
}

#[test]
#[should_panic]
fn test_partial_settle_rejected_if_not_open() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    // Fully fund — status becomes 1; partial_settle requires status == 0.
    fund_to_target(&client, &env);
    client.partial_settle(&sme);
}

#[test]
fn test_partial_settle_writes_correct_snapshot() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    let amount = 123_456_789i128;
    let investor = Address::generate(&env);
    client.fund(&investor, &amount);

    client.partial_settle(&sme);

    let snapshot = client
        .get_funding_close_snapshot()
        .expect("Snapshot must exist");
    assert_eq!(snapshot.total_principal, amount);
    assert_eq!(snapshot.funding_target, TARGET);
}

#[test]
#[should_panic]
fn test_funding_blocked_after_partial_settle() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    client.partial_settle(&sme);

    let late_investor = Address::generate(&env);
    client.fund(&late_investor, &1_000i128);
}

// ── get_settled_at tests ──────────────────────────────────────────────────────

/// `get_settled_at` returns `None` before the escrow is settled (pre-settle state).
#[test]
fn settled_at_is_none_before_settle() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    // Not yet funded — should be None.
    assert!(
        client.get_settled_at().is_none(),
        "settled_at must be None before settle"
    );

    // Fund to target (status 1) — still None.
    fund_to_target(&client, &env);
    assert!(
        client.get_settled_at().is_none(),
        "settled_at must be None after funding, before settle"
    );
}

/// `get_settled_at` returns `Some(timestamp)` equal to the ledger time at `settle()`.
#[test]
fn settled_at_recorded_at_settle() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    let settle_ts: u64 = 9_999;
    env.ledger().with_mut(|l| l.timestamp = settle_ts);
    client.settle();

    let stored = client
        .get_settled_at()
        .expect("settled_at must be Some after settle");
    assert_eq!(
        stored, settle_ts,
        "settled_at must equal the ledger timestamp at settle()"
    );
}

/// `get_settled_at` value is stable — subsequent reads return the same timestamp.
#[test]
fn settled_at_is_stable_after_settle() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    let settle_ts: u64 = 42_000;
    env.ledger().with_mut(|l| l.timestamp = settle_ts);
    client.settle();

    // Advance ledger — stored value must not change.
    env.ledger().with_mut(|l| l.timestamp = settle_ts + 10_000);
    let stored = client
        .get_settled_at()
        .expect("settled_at must remain Some");
    assert_eq!(
        stored, settle_ts,
        "settled_at must not change after additional ledger advancement"
    );
}

/// `settle()` with maturity = 0 (no time-lock) still records the correct timestamp.
#[test]
fn settled_at_recorded_no_maturity_escrow() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    // default_init uses maturity=0 (no lock).
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    let ts: u64 = 1_234_567;
    env.ledger().with_mut(|l| l.timestamp = ts);
    client.settle();

    assert_eq!(
        client.get_settled_at(),
        Some(ts),
        "settled_at must be recorded even when maturity == 0"
    );
}

/// `settle()` with a positive maturity records the timestamp at the moment the call succeeds.
#[test]
fn settled_at_recorded_with_maturity() {
    let env = Env::default();
    env.mock_all_auths();

    let maturity: u64 = 5_000;
    let sac = env.register_stellar_asset_contract_v2(Address::generate(&env));
    let token_id = sac.address();
    let sac_admin = StellarAssetClient::new(&env, &token_id);
    let (escrow_id, client2) = super::deploy_with_id(&env);
    let (admin2, sme2, treasury2) = (
        Address::generate(&env),
        Address::generate(&env),
        Address::generate(&env),
    );
    client2.init(
        &admin2,
        &soroban_sdk::String::from_str(&env, "MAT001"),
        &sme2,
        &TARGET,
        &500i64,
        &maturity,
        &token_id,
        &None,
        &treasury2,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    sac_admin.mint(&investor, &TARGET);
    client2.fund(&investor, &TARGET);

    // Advance ledger past maturity.
    let settle_ts = maturity + 100;
    env.ledger().with_mut(|l| l.timestamp = settle_ts);
    client2.settle();

    assert_eq!(
        client2.get_settled_at(),
        Some(settle_ts),
        "settled_at must equal the ledger timestamp when settle() succeeds with maturity gate"
    );
}

// ──────────────────────────────────────────────────────────────────────────────
// fund_with_commitment claim-lock interaction with maturity and settlement
// ──────────────────────────────────────────────────────────────────────────────

/// A committed investor's `claim_investor_payout` is blocked with
/// `InvestorCommitmentLockNotExpired` until `now >= InvestorClaimNotBefore`,
/// even after the escrow has settled.
#[test]
fn test_commitment_claim_blocked_after_settle_before_lock() {
    let env = Env::default();
    let (client, token, contract_id, _treasury) =
        setup_claim_env(&env, "CLT001", 1_000i128, 400i64);
    let inv = Address::generate(&env);

    env.ledger().set_timestamp(1000);

    token.stellar.mint(&inv, &1_000i128);
    client.fund_with_commitment(&inv, &1_000i128, &500u64);
    token.stellar.mint(&contract_id, &1_040i128);
    client.settle();

    // Lock expires at 1500; try claim at 1200 — must be blocked.
    env.ledger().set_timestamp(1200);
    assert_contract_error(
        client.try_claim_investor_payout(&inv),
        EscrowError::InvestorCommitmentLockNotExpired,
    );

    // Advance past lock expiry — claim succeeds.
    env.ledger().set_timestamp(1500);
    let balance_before = token.token.balance(&inv);
    client.claim_investor_payout(&inv);
    assert!(client.is_investor_claimed(&inv));
    assert_eq!(token.token.balance(&inv) - balance_before, 1_040i128);
}

/// `fund_with_commitment` rejects a second commitment deposit from the same
/// investor with `TieredSecondDeposit`.
#[test]
fn test_commitment_second_deposit_rejected() {
    let env = Env::default();
    let (client, token, _contract_id, _treasury) =
        setup_claim_env(&env, "CLT002", 2_000i128, 400i64);
    let inv = Address::generate(&env);

    token.stellar.mint(&inv, &2_000i128);
    client.fund_with_commitment(&inv, &1_000i128, &100u64);
    assert_contract_error(
        client.try_fund_with_commitment(&inv, &1_000i128, &100u64),
        EscrowError::TieredSecondDeposit,
    );
}

/// `fund_with_commitment` rejects a commitment lock that extends past the
/// escrow maturity with `CommitmentLockExceedsMaturity`.
#[test]
fn test_commitment_lock_past_maturity_rejected() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (_contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);

    env.ledger().set_timestamp(1000);

    client.init(
        &admin,
        &String::from_str(&env, "CLT003"),
        &sme,
        &10_000i128,
        &800i64,
        &2000u64,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    let inv = Address::generate(&env);
    assert_contract_error(
        client.try_fund_with_commitment(&inv, &1_000i128, &1001u64),
        EscrowError::CommitmentLockExceedsMaturity,
    );
}

/// `get_effective_yield_bps` returns the tier yield for an investor who
/// committed with a lock matching a configured yield tier.
#[test]
fn test_commitment_effective_yield_reflects_tier() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (_contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);
    let inv = Address::generate(&env);

    let mut tiers: SorobanVec<YieldTier> = SorobanVec::new(&env);
    tiers.push_back(YieldTier {
        min_lock_secs: 100,
        yield_bps: 1000,
    });

    client.init(
        &admin,
        &String::from_str(&env, "CLT004"),
        &sme,
        &10_000i128,
        &800i64,
        &0u64,
        &token.id,
        &None,
        &treasury,
        &Some(tiers),
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    token.stellar.mint(&inv, &5_000i128);
    client.fund_with_commitment(&inv, &5_000i128, &100u64);
    assert_eq!(client.get_investor_yield_bps(&inv), 1000);
}

// ──────────────────────────────────────────────────────────────────────────────
// is_settleable coverage
// ──────────────────────────────────────────────────────────────────────────────

#[test]
fn test_is_settleable_created_never_funded() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    assert!(!client.is_settleable(), "open escrow is not settleable");
}

#[test]
fn test_is_settleable_funded_before_maturity() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);
    let maturity: u64 = 5_000;
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "MAT001"),
        &sme,
        &TARGET,
        &500i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &TARGET);
    client.fund(&investor, &TARGET);
    env.ledger().with_mut(|l| l.timestamp = maturity - 1);
    assert!(
        !client.is_settleable(),
        "funded but before maturity is not settleable"
    );
}

#[test]
fn test_is_settleable_funded_exact_maturity() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);
    let maturity: u64 = 5_000;
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "MAT002"),
        &sme,
        &TARGET,
        &500i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &TARGET);
    client.fund(&investor, &TARGET);
    env.ledger().with_mut(|l| l.timestamp = maturity);
    assert!(
        client.is_settleable(),
        "funded at exact maturity is settleable"
    );
}

#[test]
fn test_is_settleable_funded_after_maturity() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);
    let maturity: u64 = 5_000;
    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "MAT003"),
        &sme,
        &TARGET,
        &500i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &TARGET);
    client.fund(&investor, &TARGET);
    env.ledger().with_mut(|l| l.timestamp = maturity + 100);
    assert!(
        client.is_settleable(),
        "funded after maturity is settleable"
    );
}

#[test]
fn test_is_settleable_legal_hold_active() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    client.set_legal_hold(&true);
    assert!(
        !client.is_settleable(),
        "legal hold active is not settleable"
    );
}

#[test]
fn test_is_settleable_already_settled() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    client.settle();
    assert!(!client.is_settleable(), "already settled is not settleable");
}

#[test]
fn test_is_settleable_normal_successful() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    assert!(client.is_settleable(), "normal successful is settleable");
}

// ── get_settlement_readiness bundled view coverage (issue #558) ───────────────

/// Open (not yet funded) escrow with no maturity lock: not settleable, no hold,
/// maturity vacuously reached, and not ready.
#[test]
fn test_settlement_readiness_open_not_ready() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);

    let r = client.get_settlement_readiness();
    assert_eq!(
        r,
        SettlementReadiness {
            is_settleable: false,
            legal_hold_active: false,
            maturity_reached: true, // maturity == 0 ⇒ vacuously reached
            ready_now: false,
        }
    );
    assert!(!r.ready_now);
}

/// Funded, no maturity lock, no hold: fully ready, and `ready_now == true` must
/// predict a successful `settle`.
#[test]
fn test_settlement_readiness_funded_ready_predicts_settle() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    let r = client.get_settlement_readiness();
    assert!(r.is_settleable);
    assert!(!r.legal_hold_active);
    assert!(r.maturity_reached);
    assert!(r.ready_now);

    // Parity: ready_now == true ⇒ settle succeeds on the current ledger.
    let settled = client.settle();
    assert_eq!(settled.status, 2);
}

/// Funded but on legal hold: `legal_hold_active` true and `ready_now` false even
/// though maturity is reached. A `settle` would fail.
#[test]
fn test_settlement_readiness_funded_but_held_blocks_ready() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);

    client.set_legal_hold(&true);

    let r = client.get_settlement_readiness();
    assert!(r.legal_hold_active);
    assert!(r.maturity_reached);
    assert!(
        !r.is_settleable,
        "a legal hold makes the escrow not settleable"
    );
    assert!(!r.ready_now, "ready_now must be false under an active hold");

    // Parity: ready_now == false ⇒ settle fails.
    let res = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        client.settle();
    }));
    assert!(
        res.is_err(),
        "settle must fail while a legal hold is active"
    );
}

/// Funded with a future maturity: pre-maturity `maturity_reached` is false and
/// `ready_now` is false; after the maturity timestamp both flip true and `settle`
/// succeeds — exercising the maturity precedence branch.
#[test]
fn test_settlement_readiness_maturity_gate_parity() {
    let env = Env::default();
    env.mock_all_auths();

    let client = deploy(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let (token, treasury) = free_addresses(&env);

    let maturity: u64 = 20_000;
    client.init(
        &admin,
        &String::from_str(&env, "INV_RDY_MAT"),
        &sme,
        &TARGET,
        &800i64,
        &maturity,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    fund_to_target(&client, &env);

    // Pre-maturity: not reached, not ready.
    env.ledger().with_mut(|l| l.timestamp = maturity - 1);
    let pre = client.get_settlement_readiness();
    assert!(!pre.maturity_reached);
    assert!(!pre.is_settleable);
    assert!(!pre.ready_now);
    let res = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        client.settle();
    }));
    assert!(res.is_err(), "settle must fail before maturity");

    // At maturity (inclusive): reached and ready; settle succeeds.
    env.ledger().with_mut(|l| l.timestamp = maturity);
    let at = client.get_settlement_readiness();
    assert!(at.maturity_reached);
    assert!(at.is_settleable);
    assert!(at.ready_now);
    let settled = client.settle();
    assert_eq!(settled.status, 2);
}

// ── get_settlement_readiness field-by-field parity with source predicates ──

/// Assert that every field of [`SettlementReadiness`] matches the corresponding
/// standalone predicate and that the invariant `ready_now == is_settleable`
/// holds. Also verifies the struct never reports settleable/ready while a legal
/// hold is active.
fn assert_readiness_matches_predicates(env: &Env, client: &super::LiquifactEscrowClient<'_>) {
    let r = client.get_settlement_readiness();
    assert_eq!(
        r.is_settleable,
        client.is_settleable(),
        "is_settleable must match standalone is_settleable()"
    );
    assert_eq!(
        r.legal_hold_active,
        client.get_legal_hold(),
        "legal_hold_active must match standalone get_legal_hold()"
    );
    let maturity_reached_expected =
        !client.has_maturity_lock() || env.ledger().timestamp() >= client.get_escrow().maturity;
    assert_eq!(
        r.maturity_reached, maturity_reached_expected,
        "maturity_reached must match derived predicate from has_maturity_lock() + ledger timestamp"
    );
    assert_eq!(
        r.ready_now, r.is_settleable,
        "ready_now must equal is_settleable by construction"
    );
    assert!(
        !(r.is_settleable && r.legal_hold_active),
        "never settleable while legal hold is active"
    );
    assert!(
        !(r.ready_now && r.legal_hold_active),
        "never ready while legal hold is active"
    );
}

/// Open (status=0, not-funded) escrow with maturity=0 (no maturity lock).
#[test]
fn test_readiness_fields_open_not_funded() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    assert_readiness_matches_predicates(&env, &client);
}

/// Funded escrow with maturity=0 and no legal hold: fully settleable.
#[test]
fn test_readiness_fields_funded_no_lock_no_hold() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    assert_readiness_matches_predicates(&env, &client);
}

/// Funded, maturity=0, legal hold active: the hold must block
/// settleability even though maturity is vacuously reached.
#[test]
fn test_readiness_fields_funded_no_lock_with_hold() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    client.set_legal_hold(&true);
    assert_readiness_matches_predicates(&env, &client);
}

/// Funded with a future maturity (no hold), ledger before maturity:
/// `maturity_reached` and `is_settleable` are both false.
#[test]
fn test_readiness_fields_pre_maturity() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);
    let maturity: u64 = 20_000;
    client.init(
        &admin,
        &String::from_str(&env, "READY_PRE"),
        &sme,
        &TARGET,
        &500i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &TARGET);
    client.fund(&investor, &TARGET);
    env.ledger().with_mut(|l| l.timestamp = maturity - 1);
    assert_readiness_matches_predicates(&env, &client);
}

/// Funded at the exact maturity timestamp (no hold): all fields ready.
#[test]
fn test_readiness_fields_at_maturity() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);
    let maturity: u64 = 20_000;
    client.init(
        &admin,
        &String::from_str(&env, "READY_AT"),
        &sme,
        &TARGET,
        &500i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &TARGET);
    client.fund(&investor, &TARGET);
    env.ledger().with_mut(|l| l.timestamp = maturity);
    assert_readiness_matches_predicates(&env, &client);
}

/// Funded after maturity but with an active legal hold: the hold must
/// override maturity; `is_settleable` / `ready_now` are false.
#[test]
fn test_readiness_fields_after_maturity_with_hold() {
    let env = Env::default();
    env.mock_all_auths();
    let token = install_stellar_asset_token(&env);
    let (contract_id, client) = deploy_with_id(&env);
    let admin = Address::generate(&env);
    let sme = Address::generate(&env);
    let treasury = Address::generate(&env);
    let maturity: u64 = 20_000;
    client.init(
        &admin,
        &String::from_str(&env, "READY_HLD"),
        &sme,
        &TARGET,
        &500i64,
        &maturity,
        &token.id,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );
    let investor = Address::generate(&env);
    token.stellar.mint(&investor, &TARGET);
    client.fund(&investor, &TARGET);
    env.ledger().with_mut(|l| l.timestamp = maturity + 100);
    client.set_legal_hold(&true);
    assert_readiness_matches_predicates(&env, &client);
}

/// Already-settled escrow: terminal status makes `is_settleable` false.
#[test]
fn test_readiness_fields_already_settled() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    fund_to_target(&client, &env);
    client.settle();
    assert_readiness_matches_predicates(&env, &client);
}

/// Explicit zero-maturity case: `has_maturity_lock()` is false and
/// `maturity_reached` is vacuously true.
#[test]
fn test_readiness_fields_zero_maturity_lock_false() {
    let env = Env::default();
    let (client, admin, sme) = setup(&env);
    default_init(&client, &env, &admin, &sme);
    assert!(
        !client.has_maturity_lock(),
        "maturity=0 → has_maturity_lock must be false"
    );
    fund_to_target(&client, &env);
    assert_readiness_matches_predicates(&env, &client);
}

// ──────────────────────────────────────────────────────────────────────────────
// `settle_pool` field in EscrowSettled event (GitHub Issue #639)
// ──────────────────────────────────────────────────────────────────────────────

/// Verify that settle_pool equals principal + coupon for a standard yield rate.
///
/// The sole investor funds the escrow to the exact target so `funded_amount` and
/// `FundingCloseSnapshot.total_principal` both equal `principal`. After settlement,
/// `compute_investor_payout` returns the full `settle_pool` for the sole participant.
#[test]
fn test_settle_pool_principal_plus_coupon() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    let (token, treasury) = free_addresses(&env);

    let principal = 1_000_000_000i128; // 1,000 tokens (assuming 6 decimals)
    let yield_bps = 500i64; // 5%

    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SP001"),
        &sme,
        &principal,
        &yield_bps,
        &0u64,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    // Fund exactly `principal` so funded_amount == funding_target == principal.
    let investor = Address::generate(&env);
    client.fund(&investor, &principal);
    client.settle();

    // Compute expected settle_pool: coupon = 1_000_000_000 × 500 / 10_000 = 50_000_000
    // settle_pool = 1_000_000_000 + 50_000_000 = 1_050_000_000
    let expected_coupon = 50_000_000i128;
    let expected_settle_pool = principal + expected_coupon;

    // Verify settle_pool via compute_investor_payout, which uses the same arithmetic:
    // The sole investor should receive the full settle_pool.
    let payout = client.compute_investor_payout(&investor);
    assert_eq!(
        payout, expected_settle_pool,
        "Single investor payout must equal settle_pool (principal + coupon)"
    );

    // Verify the escrow state post-settlement.
    let escrow = client.get_escrow();
    assert_eq!(escrow.funded_amount, principal);
    assert_eq!(escrow.yield_bps, yield_bps);
    assert_eq!(escrow.status, 2, "Escrow must be in settled state");
}

/// Verify settle_pool equals principal when yield_bps is zero (no coupon).
#[test]
fn test_settle_pool_zero_yield() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    let (token, treasury) = free_addresses(&env);

    let principal = 5_000_000_000i128;
    let yield_bps = 0i64; // 0% yield

    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SP002"),
        &sme,
        &principal,
        &yield_bps,
        &0u64,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    // Fund exactly `principal` so funded_amount == funding_target == principal.
    let investor = Address::generate(&env);
    client.fund(&investor, &principal);
    client.settle();

    // With zero yield, settle_pool should equal principal (no coupon).
    // Expected: settle_pool = 5_000_000_000 + 0 = 5_000_000_000
    let expected_settle_pool = principal;

    // Verify settle_pool via compute_investor_payout: sole investor receives principal.
    let payout = client.compute_investor_payout(&investor);
    assert_eq!(
        payout, expected_settle_pool,
        "Zero yield: payout must equal principal (settle_pool has no coupon)"
    );

    let escrow = client.get_escrow();
    assert_eq!(escrow.funded_amount, principal);
    assert_eq!(escrow.yield_bps, 0);
    assert_eq!(escrow.status, 2, "Escrow must be in settled state");
}

/// Verify settle_pool uses floor division (rounding down) for coupon calculation.
#[test]
fn test_settle_pool_rounding_floor() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    let (token, treasury) = free_addresses(&env);

    // Choose a principal and yield that produces a non-integer coupon to verify floor rounding.
    let principal = 1_000_003i128; // Odd number to force rounding
    let yield_bps = 333i64; // 3.33%

    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SP003"),
        &sme,
        &principal,
        &yield_bps,
        &0u64,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    // Fund exactly `principal` so funded_amount == funding_target == principal.
    let investor = Address::generate(&env);
    client.fund(&investor, &principal);
    client.settle();

    // Compute expected coupon with floor division:
    // coupon = 1_000_003 × 333 / 10_000 = 333_000_999 / 10_000 = 33_300 (floor)
    // settle_pool = 1_000_003 + 33_300 = 1_033_303
    let expected_coupon = 33_300i128;
    let expected_settle_pool = principal + expected_coupon;

    // Verify rounding: the numerator is 333_000_999 and 333_000_999 / 10_000 = 33_300 (floor),
    // not 33_301. Confirm settle_pool via compute_investor_payout on the sole investor.
    let payout = client.compute_investor_payout(&investor);
    assert_eq!(
        payout, expected_settle_pool,
        "Floor rounding: settle_pool must be {expected_settle_pool}, got {payout}"
    );

    let escrow = client.get_escrow();
    assert_eq!(escrow.funded_amount, principal);
    assert_eq!(escrow.yield_bps, yield_bps);
    assert_eq!(escrow.status, 2, "Escrow must be in settled state");
}

/// Verify settle_pool handles large principal amounts without overflow.
#[test]
fn test_settle_pool_large_principal() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    // A real Stellar asset token is required: the principal here exceeds the
    // default mock-token balance, so the investor must be explicitly minted funds
    // to clear the pre-transfer balance guard in `fund`.
    let sac = install_stellar_asset_token(&env);
    let token = sac.id.clone();
    let treasury = Address::generate(&env);

    // Use a large principal near the upper practical limit for i128.
    let principal = 1_000_000_000_000_000_000i128; // 1 quintillion base units
    let yield_bps = 100i64; // 1%

    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SP004"),
        &sme,
        &principal,
        &yield_bps,
        &0u64,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    // Fund exactly `principal` so funded_amount == funding_target == principal.
    let investor = Address::generate(&env);
    sac.stellar.mint(&investor, &principal);
    client.fund(&investor, &principal);
    client.settle();

    // Compute expected settle_pool:
    // coupon = 1_000_000_000_000_000_000 × 100 / 10_000 = 10_000_000_000_000_000
    // settle_pool = 1_000_000_000_000_000_000 + 10_000_000_000_000_000 = 1_010_000_000_000_000_000
    let expected_coupon = 10_000_000_000_000_000i128;
    let expected_settle_pool = principal + expected_coupon;

    // Verify no overflow occurs and settle_pool is correct via compute_investor_payout.
    let payout = client.compute_investor_payout(&investor);
    assert_eq!(
        payout, expected_settle_pool,
        "Large principal: settle_pool must be {expected_settle_pool} without overflow"
    );

    let escrow = client.get_escrow();
    assert_eq!(escrow.funded_amount, principal);
    assert_eq!(escrow.yield_bps, yield_bps);
    assert_eq!(escrow.status, 2, "Escrow must be in settled state");
}

/// Verify settle_pool with maximum yield_bps (10000 = 100%).
#[test]
fn test_settle_pool_max_yield() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    let (token, treasury) = free_addresses(&env);

    let principal = 100_000_000i128;
    let yield_bps = 10_000i64; // 100% yield (max allowed)

    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SP005"),
        &sme,
        &principal,
        &yield_bps,
        &0u64,
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    // Fund exactly `principal` so funded_amount == funding_target == principal.
    let investor = Address::generate(&env);
    client.fund(&investor, &principal);
    client.settle();

    // Compute expected settle_pool:
    // coupon = 100_000_000 × 10_000 / 10_000 = 100_000_000
    // settle_pool = 100_000_000 + 100_000_000 = 200_000_000
    let expected_coupon = 100_000_000i128;
    let expected_settle_pool = principal + expected_coupon;

    // Verify settle_pool at maximum yield via compute_investor_payout.
    let payout = client.compute_investor_payout(&investor);
    assert_eq!(
        payout, expected_settle_pool,
        "Max yield (100%): settle_pool must be double the principal"
    );

    let escrow = client.get_escrow();
    assert_eq!(escrow.funded_amount, principal);
    assert_eq!(escrow.yield_bps, yield_bps);
    assert_eq!(escrow.status, 2, "Escrow must be in settled state");
}

/// Verify settle_pool is computed correctly when maturity is zero (no maturity lock).
#[test]
fn test_settle_pool_no_maturity() {
    let env = Env::default();
    env.mock_all_auths();
    let (client, admin, sme) = setup(&env);
    let (token, treasury) = free_addresses(&env);

    let principal = 2_000_000_000i128;
    let yield_bps = 750i64; // 7.5%

    client.init(
        &admin,
        &soroban_sdk::String::from_str(&env, "SP006"),
        &sme,
        &principal,
        &yield_bps,
        &0u64, // maturity = 0 (no maturity lock)
        &token,
        &None,
        &treasury,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None,
        &None::<i64>,
    );

    // Fund exactly `principal` so funded_amount == funding_target == principal.
    let investor = Address::generate(&env);
    client.fund(&investor, &principal);
    client.settle();

    // Compute expected settle_pool:
    // coupon = 2_000_000_000 × 750 / 10_000 = 150_000_000
    // settle_pool = 2_000_000_000 + 150_000_000 = 2_150_000_000
    let expected_coupon = 150_000_000i128;
    let expected_settle_pool = principal + expected_coupon;

    // Verify settle_pool with no maturity lock via compute_investor_payout.
    let payout = client.compute_investor_payout(&investor);
    assert_eq!(
        payout, expected_settle_pool,
        "No-maturity settle_pool must be {expected_settle_pool}"
    );

    let escrow = client.get_escrow();
    assert_eq!(escrow.funded_amount, principal);
    assert_eq!(escrow.yield_bps, yield_bps);
    assert_eq!(escrow.maturity, 0u64);
    assert_eq!(escrow.status, 2, "Escrow must be in settled state");
}