[CIP-87] Expose penalty cap on /trades API

[fleupold]

Description

Quasilabs complained that the penalty cap is not readable from the API. Since - like protocol fees - they can change from auction to auction, this PR adds them on the same endpoint where executed fee policies can be found, namely the /trades endpoint.

Changes

• DB function to fetch penalties for a given order, auction id
• Inject penalty information like protocol fees on the trades struct
• Update openapi

How to test

Made API check part of the e2e test

[github-actions]

Reminder: Please consider backward compatibility when modifying the API specification.
If breaking changes are unavoidable, ensure:

• You explicitly pointed out breaking changes.
• You communicate the changes to affected teams (at least Frontend team and SAFE team).
• You provide proper versioning and migration mechanisms.

---

Caused by:

• crates/orderbook/openapi.yml

[claude]

Claude finished @fleupold's task in 2m 57s —— View job

---

Review: [CIP-87] Expose penalty cap on /trades API

• Read changed files and gather context
• Analyze DB query changes
• Analyze model/API changes
• Post summary

This looks solid and ready to merge. The implementation mirrors the existing executed_protocol_fees batching pattern closely, so it's consistent with the codebase.

What I checked:

• ✅ The SQL is correct and defensive: penalty_caps_native[array_position(order_uids, order_uid)] returns NULL both when penalties were disabled (penalty_caps_native IS NULL) and when the position/index isn't found, which filter_map then correctly drops → None. Matches the documented "absent" semantics.
• ✅ Keying on (auction_id, order_uid) is the right join key and matches how the trade attributes itself to the settling auction.
• ✅ Batched single query (no N+1), guarded by the existing u16::MAX early-return.
• ✅ HexOrDecimalU256 serializes as a decimal string, consistent with the BigUint OpenAPI ref; the allOf + nullable: true shape matches other nullable fields in the spec.
• ✅ Model test + e2e coverage (asserting the trade cap is non-zero and matches a persisted DB cap) are good.

Minor, non-blocking observations (no change required):

• The auction_order_uids.len() >= u16::MAX guard's comment says "sqlx only allows u16::MAX arguments," but both this new query and the existing fee_policies::fetch_all bind 2 parameters per key, so the real bind limit is u16::MAX / 2. This is pre-existing behavior (not introduced here) and only matters at ~32k+ trades for a single owner/order filter, so it's effectively unreachable — just noting it.
• Small stylistic inconsistency: executed_protocol_fees wraps its own timer inside the method, whereas the penalty_caps timer is inlined at each call site (duplicated across trades and trades_paginated). Not worth changing unless you want symmetry.

Nice touch making the API assertion part of the e2e test.
· branch trades-penalty-cap

[MartinquaXD]

Logic looks sound but wouldn't it make more sense on the /solver_competition endpoint? Quasilabs even said they would use the native prices from the competition endpoint to convert the native price to some unit they care about.

I'm okay to merge this as is because it's arguably also a property on the specific trade but for the purpose of reasoning about the performance of the solver having this data in the solver competition endpoint seems more practical.

[fleupold]

Logic looks sound but wouldn't it make more sense on the /solver_competition endpoint?

Yes, I think that would make sense to. The reason I added it here is that, conceptually, I find it closest to the fee policies, which are also only exposed here. If we want to expose more things about the order on the solver_competition endpoint, I think we would need to redesign that schema a bit. If many solution settle the same order, we probably don't want to repeat a ton of information which is the same for the same order.