Total Return Swaps

Roadmap - not built. No margin contract is deployed and no leveraged position can be opened on any BTR instance today. The primitive underneath is live: swapLiability, documented in Liability Swaps, enabled per leg (see deployed instances for which legs). That call already delivers an unlevered total return swap; this page specifies what is added on top to make it a levered one. Sections 2 and 6 are verified against deployed code and marked as such. Every parameter presented as a threshold or a ladder step is a proposal, not a measured or committed value. Section 10 lists what must be settled before any of it ships.

A total return swap gives one party the full economic return of an asset - price change plus carry - without that party holding the asset. On BTR the pool is the other side. A trader posts margin, takes exposure to a listed leg, and settles the difference between the mark at open and the mark at close. Nothing is borrowed in the token sense and nothing leaves the pool.

1. Why this is a small addition and not a new protocol

Leverage needs three parts: directional exposure, a utilization curve pricing the last unit of capacity, and a solvency system. Only the third is new.

No change is made to Pool, PricingLib, or the oracle. The margin system is a satellite contract that holds LP receipts and calls the same public entry point any LP can call. It adds no surface to the audited core.

2. The primitive that already exists

Verified against PoolLiquidityLib.sol as deployed.

swapLiability(tokenIn, tokenOut, lpAmountIn, minLpAmountOut, deadline) burns an LP receipt on one leg and mints one on another. It moves the two liabilities counters and touches no reserves: the function carries that as an explicit invariant, and the ledger step is the whole of its balance-sheet effect:

assetIn.liabilities  -= uint128(liabIn);
assetOut.liabilities += uint128(liabOut);

An LP holding USDC-leg receipts who converts them to WBTC-leg receipts now carries BTC price exposure funded entirely by their own deposit. Their profit or loss on closing is the mark differential. That is a total return swap at 1×, available today; the app labels it “Debt swap”.

The full call pipeline - the pool rate it converts at, the Lemma B mark cap, the depeg breaker, the anti-JIT cooldown, the revert surface - is documented in Liability Swaps and is unchanged by anything on this page.

3. What leverage actually requires

At 1× the trader’s own capital backs the position. Above 1× someone else’s does. Whose capital backs it determines the design.

The pool’s LPs take the other side. When a trader opens a levered long on a leg, that leg’s liabilities rise while its reserves do not, so its coverage $c=R/L$ falls: the pool now owes more of that asset than it holds. If the mark rises, the shortfall lands in the pool rate $C$ and every LP in the pool bears it pro-rata. If it falls, they gain.

Worked through, on a 3× long with 1000 of margin against a 3000 position, the mark rising 10%:

The trader’s 300 of profit is 300 of coverage the LPs no longer have. The pool pays the trader’s profit and receives the trader’s loss. Every pool-backed perpetual runs on this arrangement. It is the largest risk on this page; §11 covers it.

No tokens are lent and no reserves leave. There is no utilization crunch in the lending sense, no state in which an LP cannot exit because capital is out on loan. There is under-coverage instead, which the protocol already measures, prices and absorbs.

4. Architecture

One new contract, MarginVault, plus one new keeper.

Trader ──► MarginVault ──► Pool.swapLiability   (existing, unmodified)
              │                  │
              │                  └── κ coverage toll charged at entry, per fill
              ├── per-user ledger: collateral, exposure, debt, funding index
              ├── cross-collateral valuation at oracle marks
              └── enumerable set of open positions ──► Liquidation keeper

The vault holds every position’s LP receipts centrally and keeps a per-user ledger internally. To Pool, the vault is one large LP doing ordinary liability swaps. Every unit of liability the vault mints is backed by real deposited capital, trader margin plus the pool’s own, so the pool’s accounting sees nothing it does not already see from ordinary LPs.

Funding accrual lives in the vault, not in Pool. There is no spare storage for it in IPool.Asset: the slots are packed for the quote path, which reads two of them per leg.

The anti-JIT cooldown is not an obstacle at vault scale. LPToken._beforeTokenTransfer freezes the minted amount rather than the account, so a vault carrying a large aggregate balance clears the balanceOf ≥ amount + frozen test. The 15 s default (DEFAULT_FLOW_COOLDOWN_SECS, max 300 s, see Flow Guards) does set a floor on close latency, and the deleveraging ladder in §9 is sized to tolerate it.

5. Position lifecycle

Existing LP receipts can be posted directly as margin without a round trip through withdraw-and-redeposit, the same efficiency argument that motivates swapLiability itself.

6. Coverage is the utilization curve

Verified against PricingLib.sol as deployed.

A leveraged venue needs a curve that makes the last unit of capacity expensive. BTR has one, and the LP path goes through it: anchorPathQuoteLp → getAnchorPathQuote → _quotePath → _settleQuote, where the coverage toll is applied to every fill. Liability swaps are tolled on the same wall market swaps cross. There is no bypass; the capacity argument rests on that.

The wall is the coverage potential $Q\left(c\right)=\ln c-c+1$, convex and diverging as $c\to 0$, scaled per leg by $\kappa$. Two consequences bound open interest without any new code:

Because the toll is convex, a 3× position pays disproportionately more than three 1× positions. Capacity is priced, not rationed by a hand-set cap, though §10 records why a hand-set cap is still wanted on top for the first release.

7. Funding

The κ toll is charged at entry. It prices the pool’s assumption of directional risk at the moment the risk is taken, and it is charge-only: no time value, so a position held for months pays it once. Funding covers the rest.

Funding is skew-based, not a flat borrow rate: the net-long side of a leg pays the net-short side, with the rate a function of the leg’s coverage and the imbalance of open interest on it. Coverage is the natural input because the wall already prices it, so funding and the entry toll read the same signal.

This is the primary defence in §11. A flat rate leaves a one-way book with no mechanism to correct itself; a skew-based rate makes a crowded side progressively expensive to hold and pays traders to take the other side of it. No rate curve is proposed here. Fitting one is part of the sizing study in §10.

8. Margin and health

Collateral is cross-margined across legs and valued at oracle marks, using the same feeds and the same staleness and depeg gates that price swaps (Mark Relayer, Flow Guards). A position’s health is the ratio of collateral value to the maintenance requirement of its open exposure.

Valuation follows the pool’s own rule: collateral held as LP receipts is marked at face · C, the value the pool settles it at, not at face. A claim worth less than face cannot be posted at par, for the same reason swapLiability re-denominates only face · C; otherwise a pool deficit becomes margin credit.

9. Progressive deleveraging

Positions are reduced in steps rather than closed at a cliff. Because swapLiability accepts an arbitrary lpAmountIn, partial reduction is native to the primitive and needs no auction, no external liquidator incentive, and no settlement machinery of its own.

The ladder below is illustrative; the thresholds are proposals pending the sizing study.

Stepwise reduction suits an oracle-priced venue. A cliff liquidation converts a marginal position into a forced full-size fill when the pool’s coverage is lowest, and the convex toll prices that fill at the steepest point of the wall. Reducing early and in pieces keeps each fill on a cheaper part of the curve. Bad debt is socialised only if a position gaps through the whole ladder.

10. Open questions

Three items are unresolved. They are engineering gates, not tuning.

The toll models a mechanism this path does not use. _covToll derives the post-trade coverage as a reserve drain, $c_1=(R-\mathrm{\Delta })/L$. A liability swap does not move reserves; its true post-trade coverage is $R/(L+\mathrm{\Delta })$. The modelled figure is always the lower of the two, so the toll overcharges, which is pool-favourable and therefore safe. The gap widens sharply with size, which is the leverage regime. Whether the overcharge prices leverage out of viability before it prices it correctly is the sizing study, and it gates the maximum leverage the vault will offer.

Round-trip neutrality is not established for this path. The wall’s neutrality property is scoped, in the source, to closed loops at constant liabilities, with only a small fee residual noted as pool-favourable. A liability swap changes liabilities; a levered book changes them repeatedly and by large increments. The residual must be shown to remain pool-favourable at leverage scale. If it can turn trader-favourable, that is a toll-negative loop and a drain. This is the first item in the audit round.

Position enumeration has no precedent in the stack. No component discovers an account roster; the existing keepers work from hand-listed rosters in their manifests, which does not extend to an open set of leveraged users. The vault therefore maintains an on-chain enumerable set of open positions, paged by the keeper through multicall. That costs gas on open and close, and it keeps the liquidation path free of any indexer dependency: solvency should not rest on an off-chain service being live.

Beyond these, the first release is expected to carry a hand-set open-interest cap per leg in addition to the wall’s own ceiling, because a newly exercised pricing path should not be stress-tested first in production.

11. The central risk: LPs are the counterparty

This changes what an LP position is. Today an LP earns fees and carries inventory risk. Under this design they also carry a short book against the protocol’s own traders. The known failure modes of pool-backed leveraged venues all follow from that:

The controls are the entry toll, the wall’s ceiling and floor, skew-based funding, per-leg open-interest caps, and a bounded maximum leverage. Funding is the main one: it is the only control that acts continuously on a position rather than once at entry, and the only one that makes a crowded book correct itself.

This is not yield on idle capital. Capital is not lent out and no reserve is deployed anywhere by this mechanism. LPs are paid a risk premium for taking the other side of a directional trade. Deploying genuinely idle reserves to external venues is a separate, already-built facility, the yield hooks (rehypothecation); conflating the two misrepresents the risk.

It is not a market-neutral fee business either. LP returns under this design have a directional component that did not exist before it, and any LP-facing surface that offers leveraged-trading revenue must present that component alongside it.

12. Build scope

The keeper reuses the existing keeper framework: RPC failover, the executor’s nonce handling and stuck-nonce recovery, the shared run loop, gas budgeting, arming gates and per-role key segregation, and the alerting pager. New to it are the health-factor math, the vault ABI, the roster page, and the deleveraging action plan.

An unlevered release is possible ahead of the levered one, since §2 is already live: position tracking and the app surface can be proven against a path that works today, before any margin contract exists.

13. Related documentation

• Liability Swaps: the primitive, its rate, mark cap, and revert surface
• Inventory Management: the coverage ratio and the pool rate
• Spread & Fees: the spread and the coverage toll
• Toxic Flow Mitigation: adverse selection on the swap path
• Invariants: what the pricing engine guarantees, and under which conditions
• Flow Guards: the anti-JIT cooldown
• Mark Relayer, Flow Guards: mark sourcing and the gates on it