[toluwalasedaniel459-cmyk]

Closes #971

Stacked on #1093 (#970) → #1092 (#969). This branch builds on feat/per-market-fee-attribution, so its diff against main includes those PRs' commits. The new commits here are 7670d11, 97129dd, 11afb6a and 094fe9f, plus 2834081 (merge of the main sync from #1092/#1093). Please merge #1092 and #1093 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 #1093's and 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

Adds a global per-token fee ledger, total_claimable_fee_amount(token), kept equal to the sum of the per-market sub-ledgers claimable_fee_amount(market, token). Also adds read APIs for treasury reconciliation.

The total always equals the sum of the sub-ledgers:

• Accrual: all three settlement paths (increase position, decrease position, swap) accrue through one helper, gmx_market_utils::apply_delta_to_claimable_fee_amount. It moves the per-market entry and the global total in the same call. fee_handler::record_fee_accrual does the same.
• Claims: claim_fees and claim_token_fees release the transferred amount from the global total in the same call as the per-market entry. A claim the global ledger does not cover reverts with FeeLedgerMismatch (#12 — Add upgrade entrypoint to adl_handler #12).

Aggregate withdrawal cannot exceed summed accrued balances:

• Each per-market claim is bounded by its own ledger.
• claim_token_fees also checks its total against the listed markets' summed accrued balances and against the global total, reverting with ExceedsAccruedFees (#13 — Add upgrade entrypoint to fee_handler #13).

Read APIs (fee_handler):

Entrypoint	Auth	Returns
total_claimable_fees(token)	view	The global total
reconcile_token_fees(token, markets)	view	FeeReconciliation (see below)

FeeReconciliation has the fields token, ledger_total, markets_total, reconciled and markets. Each markets entry is a MarketFeeReconciliation { market, claimable, pool_amount, custody, backed }.

• backed means claimable <= pool_amount and claimable <= custody.
• reconciled means every market is backed and markets_total == ledger_total.
• A market missing from the list shows up as ledger_total > markets_total.

Upgrade migration:

• backfill_fee_total(token, markets) (admin only) adds pre-upgrade per-market ledgers into the global total, at most once per (market, token), and emits FeeTotalBackfilled.
• docs/deployment.md gives the order:
  1. Upgrade fee_handler.
  2. Backfill.
  3. Upgrade order_handler and liquidation_handler. adl_handler is not upgradeable and must be redeployed.
  4. Check reconcile_token_fees reports reconciled: true.
• Until backfill runs, claims of pre-upgrade fees revert. That is fail-safe: nothing can be over-withdrawn.

All new calls reject duplicate markets and are bounded by MAX_TOKEN_FEE_MARKETS = 20.

Tests

• fee_handler unit tests:
  • The global total reconciles with the sub-ledgers through accrual, claim_fees and claim_token_fees.
  • A missing market is reported as unreconciled.
  • A ledger the global total does not cover cannot be claimed, and nothing moves.
  • The backfill adds each ledger once, with exact events, and requires admin auth.
  • An unbacked market is flagged.
  • record_fee_accrual moves the total.
  • Bounds and duplicate rejection hold.
• Test fixtures: fixtures that seed fee ledgers directly now also seed the global total, as real accrual does. This applies to fee_handler, fee_batch_sweeper and resource_bench.
• tests/shared_quote_token_fees.rs (e2e): two markets settle shorts in a shared quote token. The global total equals the per-market sum, reconciliation passes, omitting a market shows the shortfall, and after the token-level sweep both totals are 0.

Verification

Check	Result
CI (fork, workflow_dispatch): rustfmt, clippy --all-targets -D warnings, WASM build	✅
CI cargo test	❌ only the pre-existing tests/funding_rate.rs failures (see #1092)
fee_handler unit tests (CI)	✅ 48 passed
Full integration suite, locally, --no-fail-fast	✅ every test file passes except funding_rate, including the binaries CI never reaches
Resource benchmarks (CI run 39361305731)	✅ gate passes

Benchmark changes: only fees/claim_fees and fees/claim_token_fees changed, by +1 read and +1 write each for the global total. fees/reconcile_token_fees is a new scenario. No lifecycle scenario changed.

After the merge with main (2834081, fork CI runs 39450588863 and 39450596402): 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: reconciliation model, errors and entrypoints.
• docs/deployment.md: upgrade ordering.
• docs/auth-audit.md: regenerated. backfill_fee_total is auth-bearing (PASS).
• bindings/fee-handler: regenerated.

🤖 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