Repository navigation
[SDK] Add the composition constraint engine #1199
Description
Summary
Add a pure constraint validator that enforces allocation and aggregate-exposure limits on a composition at init and after every rebalance.
Motivation
The engine bounds risk per strategy and per trade only: leverage is limited to 1 to 20 in packages/strategies/src/sizing.ts:11-16, and slippage is bounded in the slippage model. Nothing constrains a composition, where the same asset can be reached through several members at once. A user could hold the same asset through three members without seeing the combined exposure, because no single member shows it. Composition is exactly where that hidden concentration appears, so it needs an explicit check.
Proposed Solution
- Add a
CompositionConstraintstype covering a maximum weight per member, a maximum aggregate exposure per asset, a maximum member count, and a required cash buffer. - Add a pure
validateComposition(constraints, composition, portfolioView)that returns typed violations. It computes aggregate exposure across members rather than per member. - Support two policies: reject (throw a typed error) or clamp (reduce the offending order before it is applied). Default to reject, and keep the mode explicit in config.
- The composition applies the decision when merging member orders; members never mutate one another's orders.
Scope
| Field | Value |
|---|---|
| Area | SDK |
| Protocol affected | None |
| Network | testnet |
| Breaking change? | No |
Alternatives Considered
- Fold the limits into each member's own config. Rejected, because the whole point is the aggregate view, which no single member can see.
- Validate only in the UI. Rejected, because the engine must reject an invalid composition regardless of caller.
Acceptance Criteria
- A composition that breaches a constraint is rejected, or clamped per the configured mode, with a typed error naming the constraint.
- Aggregate per-asset exposure is computed across members, not per member.
- Constraints are validated at init and after each rebalance.
- Tests cover each constraint and both modes.
-
pnpm --filter @meridian/strategies testandnpx tsc --noEmitpass.
Additional Context
Depends on the composition interface, #1197, and the capital allocation, #1198. Part of the Meridian Strategies initiative.
Star the repo
Please star this repository before picking up this issue. It is a small ask that meaningfully helps the project reach more people.
Activity
CodlithLab commentedon Oct 19, 2026
@CodlithLab has applied to work on this issue as part of the Stellar Wave Program's 10th wave.
ℹ️ Repo Maintainers: To accept this application, review their application or assign @CodlithLab to this issue.
liutingqiu commentedon Oct 20, 2026
@liutingqiu has applied to work on this issue as part of the Stellar Wave Program's 10th wave.
ℹ️ Repo Maintainers: To accept this application, review their application or assign @liutingqiu to this issue.
Shalombonet commentedon Oct 20, 2026
@Shalombonet has applied to work on this issue as part of the Stellar Wave Program's 10th wave.
ℹ️ Repo Maintainers: To accept this application, review their application or assign @Shalombonet to this issue.
drips-wave commentedon Oct 20, 2026
Congratulations, @CodlithLab! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on October 22, 2026.
🧑💻 @CodlithLab: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.
Warning
When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.
🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.
🌊 Happy Wave 🌊