feat: smart collateral liquidation & BNB provider for fixed-term markets

[ricklista]

Summary

Add smart collateral liquidation support to BrokerLiquidator for fixed-term broker markets, and extend MarketFactory to auto-configure BNBProvider for WBNB-based fixed-term markets and route smart provider whitelisting to brokerLiquidator (vs liquidator/publicLiquidator for common markets).

Change type

• New contract
• Upgrade (existing proxy)
• Bug fix
• Gas optimization
• Configuration change
• Migration / deploy script
• Test
• Dependency update

Contracts changed

Contract	File	Type
BrokerLiquidator	src/liquidator/BrokerLiquidator.sol	modified
IBrokerLiquidator	src/liquidator/IBrokerLiquidator.sol	modified
MarketFactory	src/moolah/MarketFactory.sol	modified
IBroker	src/broker/interfaces/IBroker.sol	modified
DeployBrokerLiquidator	script/broker/deploy_brokerLiquidator.s.sol	modified
LendingBrokerTest	test/broker/LendingBroker.t.sol	modified
MarketFactoryTest	test/moolah/MarketFactoryTest.sol	modified

Interface changes

IBrokerLiquidator — new functions:

• withdrawETH(uint256 amount) external
• liquidateSmartCollateral(bytes32, address, address, uint256, uint256, bytes) external returns (uint256, uint256)
• flashLiquidateSmartCollateral(bytes32, address, address, uint256, address, address, bytes, bytes, bytes) external returns (uint256, uint256)
• smartProviders(address) external view returns (bool)
• batchSetSmartProviders(address[], bool) external

BrokerLiquidator — new functions/features:

• receive() external payable — accept native BNB
• withdrawETH(uint256) — MANAGER role
• liquidateSmartCollateral(...) — BOT role, seize + redeem LP via SmartProvider
• flashLiquidateSmartCollateral(...) — BOT role, flash liquidation with LP redemption + token swaps in callback
• redeemSmartCollateral(...) — BOT role, standalone LP redemption
• batchSetSmartProviders(...) — MANAGER role
• New events: SmartProvidersChanged, SmartLiquidation

IBrokerLiquidator.MoolahLiquidateData struct — new fields appended:

• swapSmartCollateral, smartProvider, minToken0Amt, minToken1Amt, token0Pair, token1Pair, swapToken0Data, swapToken1Data

IBroker — new function:

• ORACLE() external view returns (IOracle)

MarketFactory — signature changes:

• createFixedTermMarket(FixedTermMarketParams, bool) — added liquidatorSmartProvider param
• batchCreateFixedTermMarkets(FixedTermMarketParams[], bool[]) — added liquidatorSmartProviders param

Storage layout

BrokerLiquidator (upgrade): Two new state variables appended after existing storage:

• mapping(address => bool) public smartProviders (slot after brokerToMarketId)
• uint256 internal _lastRepaidAssets (next slot)

No variables reordered or removed. No __gap in this contract. New variables are strictly appended — no storage collision risk.

MarketFactory: No new state variables. All new dependencies (brokerLiquidator, BNBProvider, etc.) are immutable (set in constructor, stored in bytecode). No storage impact.

Access control

BrokerLiquidator:

• New BOT-gated functions: liquidateSmartCollateral, flashLiquidateSmartCollateral, redeemSmartCollateral
• New MANAGER-gated functions: withdrawETH, batchSetSmartProviders
• Existing access patterns unchanged

MarketFactory: Unchanged — createFixedTermMarket and batchCreateFixedTermMarkets remain OPERATOR-gated.

Risk assessment

Area	Risk	Note
Storage collision	🟢 None	New BrokerLiquidator vars appended at end; MarketFactory has no new state vars
Fund safety	🟡 Low	receive() + withdrawETH added — MANAGER-gated withdrawal mitigates risk. onMoolahLiquidate callback handles smart collateral swaps with external calls to whitelisted pairs. _lastRepaidAssets used as transient state across callback boundary
Access control	🟢 None	All new functions use existing role gates (BOT, MANAGER). No new roles introduced
External call safety	🟡 Low	flashLiquidateSmartCollateral callback makes external calls to token0Pair/token1Pair with user-supplied calldata — mitigated by pairWhitelist check. Native BNB sent via call{value} to whitelisted pairs

Deployment

• Chain: BSC mainnet
• Deploy script: script/broker/deploy_brokerLiquidator.s.sol (updated for payable cast)
• Upgrade path: Deploy new BrokerLiquidator implementation, upgrade proxy via timelock. Deploy new MarketFactory implementation (constructor args include brokerLiquidator address), upgrade proxy via timelock.

Test plan

• forge test passes (9/9 MarketFactoryTest)
• testCreateFixedTermMarketWithBNBLoan — BNBProvider auto-set for WBNB loan markets
• testCreateFixedTermMarketWithBNBCollateral — BNBProvider auto-set for WBNB collateral markets
• testCreateFixedTermMarketWithSmartProvider — smart provider config routes to brokerLiquidator
• testBatchCreateFixedTermMarkets — batch creation with mixed BNB + smart provider markets