---
title: "Total Return Swaps"
description: "Leveraged directional exposure on the liability-swap primitive: margin accounting, coverage as the utilization curve, skew-based funding, and progressive deleveraging"
audience: both
type: reference
status: design
lang: en
updated: "2026-09-06"
publish: true
---

# Total Return Swaps

> **Roadmap - not built.** No margin contract is deployed and no leveraged position can be opened on any BTR instance today. What *is* live is the primitive underneath: `swapLiability`, documented in [Liability Swaps](/docs/4-4-liability-swaps), enabled on all 37 Arc 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 are 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

Most leveraged-trading designs need three things the host protocol does not have: a way to express directional exposure, a utilization curve to price the last unit of capacity, and a solvency system. BTR already has the first two.

| Requirement | Where it comes from |
|---|---|
| Directional exposure | `swapLiability`, live ([§2](#2-the-primitive-that-already-exists)) |
| Capacity pricing | The coverage wall $Q(c) = \ln c - c + 1$, live ([§6](#6-coverage-is-the-utilization-curve)) |
| Open-interest ceiling | The wall's hard stop and its coverage floor $c^\*$, live ([§6](#6-coverage-is-the-utilization-curve)) |
| Margin, funding, liquidation | New. The whole of the build ([§4](#4-architecture), [§7](#7-funding), [§8](#8-margin-and-health), [§9](#9-progressive-deleveraging)) |

The consequence is that **no change is made to `Pool`, `Pricing`, 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. This is the property that makes the design worth building: it adds no surface to the audited core.

---

## 2. The primitive that already exists

*Verified against `PoolLiquidity.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:

```solidity
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**, and it is what the app already labels "Debt swap".

The full call pipeline - the two haircuts, the Lemma B mark cap, the depeg breaker, the anti-JIT cooldown, the revert surface - is documented in [Liability Swaps](/docs/4-4-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. The question is whose, and the answer determines the whole 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 is borne by that leg's LPs through the exit haircut. If it falls, they gain.

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

| Step | Trader | Pool |
|---|---|---|
| Open | posts 1000 margin, takes 3000 exposure | target leg `liabilities` +3000-equivalent, reserves unchanged |
| Mark +10% | position worth 3300 | target leg coverage falls further as the mark rises |
| Close | repays 2000, keeps 1300 (**+30% on margin**) | net liabilities +300 against no new reserves |

The trader's 300 of profit is 300 of coverage the LPs no longer have. **The pool pays the trader's profit, and is paid by the trader's loss.** That is not a defect of the design; it is what taking the other side means, and it is the same arrangement every pool-backed perpetual runs on. It is also the single largest risk in this page, and [§11](#11-the-central-risk-lps-are-the-counterparty) treats it as such.

Note what is *not* happening: 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. What there is instead is under-coverage, 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. Because every unit of liability the vault mints is backed by real deposited capital - trader margin plus the pool's own - 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` in any case: slot 2 is documented as carrying 16 free bits, and that budget is reserved for fields the quote path reads.

**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`, max 300 s, see [Flow Guards](/docs/3-3-flow-guards)) does set a floor on close latency, and the deleveraging ladder in [§9](#9-progressive-deleveraging) is sized to tolerate it.

---

## 5. Position lifecycle

| Action | Effect |
|---|---|
| **Open** | Margin is deposited to the pool if not already held as receipts, locked in the vault, and `swapLiability` is called for the full notional. The κ toll and the embedded spread are paid on the way in. |
| **Increase** | A further `swapLiability` for the increment, tolled at the leg's coverage *after* existing open interest - so each increment costs more than the last. |
| **Reduce** | Partial `swapLiability` back toward the collateral leg. `lpAmountIn` is arbitrary, so partial closes need no new machinery. |
| **Close** | Reduce to zero, settle accrued funding, release remaining collateral. |
| **Deleverage** | A reduce initiated by the keeper rather than the trader ([§9](#9-progressive-deleveraging)). |

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

---

## 6. Coverage is the utilization curve

*Verified against `Pricing.sol` as deployed.*

A leveraged venue needs a curve that makes the last unit of capacity expensive. BTR has one already, 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, which is the property the whole capacity argument rests on.

The wall is the coverage potential $Q(c) = \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:

- **A hard ceiling.** A fill whose output would meet or exceed the leg's reserves is tolled its entire output, which blocks it. **Liability cannot be minted past the out-leg's reserves.**
- **A coverage floor.** Trading cannot drive a leg below $c^\* = \kappa/(\kappa + \mathrm{BPS})$. Live Arc $\kappa$ values run 600 bps on stables to 2500 bps on volatiles, which places that floor between roughly 5.7% and 19.8% depending on the leg.

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](#10-open-questions) 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. It carries 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 it is already the quantity the wall prices, so funding and the entry toll read the same signal.

This choice is the primary defence in [§11](#11-the-central-risk-lps-are-the-counterparty), and it is a design commitment rather than a tuning detail. 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](#10-open-questions).

---

## 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 ([Oracles](/docs/3-4-oracles), [Depeg Halt](/docs/3-5-depeg-halt)). A position's health is the ratio of collateral value to the maintenance requirement of its open exposure.

Valuation follows the pool's own conservatism: collateral held as LP receipts on an under-covered leg is marked at its post-haircut value, not its face. An LP claim that would redeem at a haircut cannot be posted at par, for the same reason `swapLiability` re-denominates only the post-haircut face - otherwise a deficit on the collateral leg is laundered into 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.

| Health | Action |
|---|---|
| Below 1.20 | Increases blocked; trader warned |
| Below 1.10 | Reduce by 25% |
| Below 1.05 | Reduce to 50%, then 75% |
| Below 1.00 | Full unwind; penalty to the insurance fund |

Stepwise reduction suits an oracle-priced venue. A cliff liquidation converts a marginal position into a forced full-size fill at the worst moment for the pool's coverage, and the convex toll means that fill is priced at its own worst point on 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 - \Delta)/L$. A liability swap does not move reserves; its true post-trade coverage is $R/(L + \Delta)$. The modelled figure is always the lower of the two, so the toll **overcharges, which is pool-favourable and therefore safe** - but the gap widens sharply with size, which is precisely 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 by construction, and 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 and outranks everything else on this page.**

**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 is the deliberate choice: it keeps the liquidation path free of any indexer dependency, and 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, on the principle that a newly exercised pricing path should not have its first stress test in production.

---

## 11. The central risk: LPs are the counterparty

This deserves stating plainly rather than as a footnote, because it 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:

- **Informed flow.** Traders who are systematically right extract from LPs. This is the same adverse-selection problem the AIMM's spread and toxic-flow work addresses on the swap side ([Toxic Flow Mitigation](/docs/1-1-6-toxic-flow-mitigation)), reappearing on a path where the trader chooses the direction and holds for as long as they like.
- **One-way skew.** In a trending market the book crowds one way, the pool is structurally on the other, and LPs bleed for as long as the trend runs.
- **Entry at the mark.** Exposure is taken at oracle marks rather than discovered through depth. That is the correct behaviour for a liability swap, but under leverage it is also the mechanism that lets a trader size in without moving the price against themselves.

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 load-bearing one: it is the only control that acts continuously on a position rather than once at entry, and it is the only one that makes a crowded book correct itself.

Two things this is explicitly not:

- **It is not yield on idle capital.** Capital is not lent out; no reserve is deployed anywhere by this mechanism. What LPs are paid is 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 - and conflating the two misrepresents the risk.
- **It is not a market-neutral fee business.** LP returns under this design have a directional component that did not exist before it. Any LP-facing surface that offers leveraged-trading revenue must present that component alongside it.

---

## 12. Build scope

| Component | Status |
|---|---|
| `swapLiability` exposure engine | Built, live on 37 Arc legs |
| Coverage wall, ceiling and floor | Built, verified to apply to the LP path |
| Oracle marks, staleness and depeg gates | Built |
| `MarginVault` - ledger, cross-collateral, health, funding, deleverage, position set | Not built |
| Liquidation keeper | Not built |
| SDK position types and quoting | Not built |
| App surface | Not built |

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](#2-the-primitive-that-already-exists) 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](/docs/4-4-liability-swaps): the primitive, its haircuts, mark cap, and revert surface
- [Inventory Management](/docs/1-1-1-inventory-management): the coverage ratio and the withdrawal haircut
- [Spread & Fees](/docs/1-1-4-spread-fees): the spread and the coverage toll
- [Toxic Flow Mitigation](/docs/1-1-6-toxic-flow-mitigation): adverse selection on the swap path
- [Invariants](/docs/1-1-8-invariants): what the pricing engine guarantees, and under which conditions
- [Flow Guards](/docs/3-3-flow-guards): the anti-JIT cooldown
- [Oracles](/docs/3-4-oracles), [Depeg Halt](/docs/3-5-depeg-halt): mark sourcing and the gates on it