Percolator wrapper · Invariant INV-077

Bounding the refresh work of liened claims at trade admission

One admission check, one hard cap: a trade may not push a portfolio's lien-refresh work past liened_claims + 6 × active_legs ≤ 72. Below: the problem, the upstream fix, a working calculator that runs the exact check, and the evidence from our own port to a diverged engine build.

Upstream · aeyakovenko/percolator-prog PR #465 · merged 2026-11-14 Ported to our diverged engine build Proven in our LiteSVM harness Deployment prep — not deployed to mainnet
Imperial
01 · The problem
§1

Unbounded refresh work at admission

When the Percolator wrapper admits a trade, it refreshes the loss state of the liened claims attached to the portfolios involved — and before the fix, the cost of that refresh grew with the number of liened claims times the portfolio's active legs, with nothing capping it. Anyone could stuff a portfolio with liened claims and legs until admitting a single trade against it cost more compute than a transaction can carry, freezing those portfolios out of trading. That is a griefing / denial-of-service surface sitting directly in the wrapper's admission path: cheap to construct, expensive for everyone else, and it blocks the honest trades the refresh exists to protect.

02 · The fix
§2

The INV-077 bound

Source: upstream — aeyakovenko/percolator-prog PR #465

work(portfolio) = liened_claims + 6 × active_legs ≤ 72   // zero when the portfolio carries no liened claims
  • Constants: WRAPPER_SOURCE_LIEN_REFRESH_LEG_WEIGHT = 6, WRAPPER_MAX_SOURCE_LIEN_REFRESH_WORK = 72.
  • Checked before and after the trade, on both portfolios (source and counterparty), on the single-trade and the batch paths alike.
  • Refusal is total: a trade that would raise a portfolio's work past 72 aborts admission with PercolatorError::InvalidInstruction and the transaction rolls back in full — no partial state. A trade that lowers the work, or leaves it unchanged, is never refused by this bound.
  • Lien-free portfolios are untouched: with no liened claims the refresh work is zero, and the pre-existing 14-leg portfolio cap (WRAPPER_MAX_PORTFOLIO_ASSETS = 14) remains the binding limit.
03 · Working example
§3

Run the admission check

Drag the sliders. The calculator implements the check exactly as written in the wrapper — work = liened_claims + 6 × active_legs (zero when there are no liened claims) against the cap of 72.

work = 1 + 6 × 11 = 67
cap 72
ADMITTED
work 67 ≤ 72 — the admission check passes.

Cases A and B are the exact portfolios exercised in our LiteSVM harness (§4): the 11-leg portfolio is admitted, and adding the 12th leg is refused with a full rollback.

04 · Our evidence
§4

The port, proven in our harness

Source: our LiteSVM test harness — ported build, 2026-11-14

  • Exposure confirmed, then ported: our wrapper is a diverged sibling of the upstream codebase (engine pin 35ddd692… vs upstream's measured 427dc5fc at PR #465) and carried the same unbounded admission path. The INV-077 port — constants, both refresh-work views, both trade paths — was applied at source level with the same shape as upstream; the bound is a count check, not a CU budget, so its shape is engine-independent.
  • Constants test passes: the ported constants match the upstream table (leg weight 6, max work 72).
  • Behavioral test passes: a portfolio with 1 liened claim and 11 active legs (work 67 ≤ 72) is admitted; adding the 12th leg (work 73 > 72) is refused with PercolatorError::InvalidInstruction and the state verified rolled back in full.
  • No regressions: the full v16_cu suite on the ported tree runs 132 passed / 22 failed — every failure is the pre-existing missing-matcher-sibling class, none touch INV-077.
  • Artifact provenance: our pre-port build reproduces byte-exactly, so the size delta of the ported artifact below is exactly the port and nothing else.
Ported wrapper artifact
1,545,816 bytes
Delta vs pre-port
+1,112 bytes
Pre-port artifact
1,544,704 bytes · reproduced byte-exact

ported wrapper sha256  6ef81d774011967e2f0fe15ac854361fc085a2714b931e844c8da150e59d9a00
pre-port wrapper sha256   310c2de8596a6e9a34c1aacefe0622b83929e78019214a6e15e9ebfd278873a1

Status, stated plainly: this is our Percolator deployment preparation. The ported artifact is not deployed to mainnet; a devnet rehearsal of these exact artifacts is in progress. Nothing on this page is a trading or investment claim.

05 · The wider stack
§5

The wider stack

The wrapper is the on-chain half of this system. The client side — market aggregation, routing, and SDK access to Percolator markets — lives in the Solizardking/percolator repository, the perp-aggregator tree. It consumes the wrapper's markets, and the INV-077 bound is one of the program-side guarantees that client builds on.

06 · Links
§6

Sources