feat: emergency withdrawal — admin force-returns user tokens from a frozen market

[abayomicornelius]

Summary

If a market is paused due to a critical bug or oracle failure, LP and trader funds can be permanently stuck. An emergency withdrawal mechanism lets the admin return tokens to their rightful owners without executing normal protocol logic.

Proposed Design

Add emergency_withdraw(market: Address, recipient: Address, token: Address, amount: u128) to exchange_router, gated behind a special EMERGENCY_ADMIN role (separate from normal admin to require higher multi-sig threshold).

• Only callable when the market's pause flag is set
• Bypasses all valuation and fee logic
• Transfers tokens directly from market pool to recipient
• Emits EmergencyWithdrawal { market, token, amount, recipient, authorized_by }

Security Requirements

• EMERGENCY_ADMIN must be a multi-sig with at least 3-of-5 threshold
• Each emergency withdrawal requires a separate auth call (no batch emergency drain)
• After use, emit an on-chain explanation event with a reason string

Acceptance Criteria

• Callable only when market is paused
• Requires EMERGENCY_ADMIN role
• Emits structured event with full audit trail
• Integration test: pause market, emergency withdraw, assert recipient received tokens
• Non-emergency-admin call reverts

Affected Contracts

exchange_router, role_store

[Hassanmovic98]

I'll add emergency_withdraw to the exchange router, gated behind a separate EMERGENCY_ADMIN role with 3-of-5 multi-sig threshold. Only works when the market is paused, bypasses all valuation logic, transfers tokens directly to the recipient.
Emits EmergencyWithdrawal with market, token, amount, and who authorized it. No batch drains — each withdrawal requires a separate auth call so there's a clear audit trail.
Integration tests verify: pause the market, emergency withdraw, recipient gets tokens. Non-admin calls revert.

[tobiadewola41-eng]

@tobiadewola41-eng has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would like to work on this issue because

ℹ️ Repo Maintainers: To accept this application, review their application or assign @tobiadewola41-eng to this issue.