[toluwalasedaniel459-cmyk]

Closes #970

Stacked on #1092 (#969). This branch builds on feat/constrained-fee-recipients, so the diff against main includes #1092's commits. The new commits here are 46054f5 (the feature) and 92e9e1c (merge of #1092's main sync). Please review and merge #1092 first.

⚠️ Merging this PR restores the codebase #1090 deleted. #1090 (280f268) removed 765 files from main, and #1083, #1089 and #1084 were merged on top of that tree. To make these PRs mergeable, main was merged into #1092's branch (and from there into this one), keeping the full tree. This PR therefore re-adds every file #1090 deleted (about 1.17M lines, identical to main at 5436392) and keeps the 6 files main added since:
libs/clob_settlement_core/src/lib.rs, contracts/reader/src/clob_reads.rs, tests/reentrancy_token.rs, docs/REENTRANCY_ANALYSIS.md, docs/clob-read-api-specification.md and docs/market-data-streaming.md. None of these 6 are compiled yet: there is no Cargo.toml, mod declaration or test registration for them.

To review only this PR's own changes, diff against 5436392, the last main commit before #1090.

CI: main's .github/workflows were also deleted by #1090, so no checks run on this PR upstream. They were run on the fork instead (see Verification).

Summary

Several markets can accrue protocol fees in the same token (e.g. every */USDC market). This PR keeps fees market-scoped for both custody and ledger, and adds token-level reads and withdrawals that aggregate those per-market entries without double counting.

Topology:

• Custody: each market's fees sit in that market's own market_token pool. Markets never share a custody balance.
• Ledger: fees accrue to claimable_fee_amount(market, token) and are backed by pool_amount(market, token). Both keys include the market, so two markets sharing a quote token write different entries and cannot overwrite each other.
• No token-level ledger: there is no separate token-level fee ledger, so the same custody tokens are never recorded twice.

New fee_handler entrypoints:

Entrypoint	Auth	Behaviour
claimable_fees_by_token(token, markets)	view	Returns TokenFeeAttribution { token, total, markets: [MarketFeeAmount { market, amount }] }
claim_token_fees(keeper, token, markets)	FEE_KEEPER	See below

claim_token_fees claims each market exactly as claim_fees does: from that market's own pool, against its own pool_amount, to its own trusted recipient (#969), with its own FeeClaimed event. It then emits tkfee_clm TokenFeesClaimed { token, total, market_count }. The call is atomic: one failing market reverts every transfer.

Guards (both calls):

• DuplicateMarket (#10 — Add upgrade entrypoint to order_handler #10): a market listed twice is rejected, so it cannot be counted twice.
• TooManyMarkets (#9 — Add upgrade entrypoint to withdrawal_handler #9): at most MAX_TOKEN_FEE_MARKETS = 20 markets. This bounds iteration, including the pairwise duplicate check.
• FeeOverflow (#11 — Add upgrade entrypoint to liquidation_handler #11): totals use checked u128 addition.

Reader fix: reader::get_protocol_stats now rejects duplicate markets (DuplicateMarket, #6). Before, listing a market twice counted its fees, pool value and open interest twice.

Refactor: claim_fees now shares the internal per-market claim path. Its behaviour and resource cost are unchanged: every existing benchmark scenario is identical.

Topology assumption: #970 says to implement the topology selected in #11/#19. I couldn't find that decision recorded in the repo, so this PR implements the existing market-scoped model. Please confirm that's the selected topology.

Tests

• fee_handler unit tests:
  • Two markets sharing a token keep separate ledgers.
  • The token view attributes each share.
  • Claiming one market leaves the other's ledger, pool_amount and custody untouched.
  • claim_token_fees pays each market to its own recipient, with the exact event sequence.
  • Duplicate markets are rejected and nothing moves.
  • The 20-market bound holds, and both the exact limit and an empty list are accepted.
  • A non-keeper is rejected.
  • The sweep reverts atomically when one market's ledger isn't backed by its own pool.
  • Overflowing totals are rejected.
• reader: duplicate markets are rejected in get_protocol_stats.
• tests/shared_quote_token_fees.rs (e2e):
  • Two ETH/USD markets settle shorts with the same quote-token collateral, and each accrues exactly its own fee.
  • A later settlement in market B leaves A's ledger unchanged.
  • The token-level sweep pays the treasury and a market override, each from its own pool, and decrements each pool_amount by its own fee.
  • Listing a market twice cannot double count.
• tests/resource_bench.rs: new scenario fees/claim_token_fees. MAX_TOKEN_FEE_MARKETS is added to the baseline's bounded constants.

Verification (local, Windows host with soroban-sdk 25.3.1)

Check	Result
cargo fmt --all -- --check	✅
clippy --all-targets -D warnings (fee-handler, reader, integration tests)	✅
fee-handler tests	✅ 41 passed (7 new)
reader protocol_stats tests	✅ 6 passed (1 new)
shared_quote_token_fees, fee_receiver_routing, resource_bench	✅
Bench compare	✅ gate passed; all existing scenarios byte-for-byte identical to the CI-recorded baseline
WASM build (fee-handler, reader, fee-batch-sweeper)	✅
Auth audit regenerated	✅ claim_token_fees auth-bearing, PASS

Not run: the full workspace cargo test. It stops at the pre-existing tests/funding_rate.rs failures described in #1092.

After the merge with main (92e9e1c, fork CI runs 39450574755 and 39450581857): rustfmt, clippy, the WASM build and Resource Benchmarks pass. cargo test fails only on the 6 known funding_rate tests.

Docs and types

• docs/security.md documents shared-quote-token attribution, the new entrypoints and the new errors.
• docs/auth-audit.md is regenerated.
• bindings/fee-handler is regenerated.
• bindings/reader is left stale, as are the other bindings already stale since feat: typed error model, market lifecycle states, and versioned event schema #1085. Regenerating it would pull in about 600 lines of unrelated gmx-types additions.

🤖 Generated with Claude Code

[drips-wave]

@toluwalasedaniel459-cmyk Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits