> For the complete documentation index, see [llms.txt](https://docs.efficientdex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.efficientdex.com/how-pools-work/credit-and-collateral.md). # Credit and collateral How an Efficient pool that borrows caps its borrowing with the LTV pin and the credit check, and how it posts, tops up and protects its collateral. **An Efficient pool that borrows caps its borrowing at its LTV pin.** The cap holds whatever its hooks quote. After every sell, the credit check bounds the pool's net debt by the pin. Each borrow posts enough collateral at its lending market to keep that loan within the pin when it's drawn. Lending markets are optional, and only pools that borrow hold collateral. A pool with borrowing switched off posts none when it sells. A pool with no lending market has nowhere to post any. Debt left from before a pool's borrowing went off keeps its collateral posted until that debt is repaid. [Just-in-time financing](/how-pools-work/just-in-time-financing.md) covers how a pool borrows. This page covers how much. Values given for the first Everlong vault are examples from its configuration. That vault runs cbBTC against USDC on Base, financed through Morpho Blue. ## The LTV pin and collateral **The LTV pin is the pool's own loan-to-value ceiling, one value for the whole pool.** It bounds the credit check. It also sets how much collateral the pool posts at each venue. A venue is the pool's position at one lending market. Before each borrow, the financing router posts enough pool asset at the venue to keep its debt within the pin. The new borrow counts towards that debt: $$ C\_v \ge \frac{D\_v}{\ell,P\_i} $$ Here $$\ell$$ is the LTV pin, and $$C\_v$$ is the pool asset posted at venue $$v$$. The venue's debt is $$D\_v$$, in units of its loan asset $$i$$. A loan asset is a token the pool can borrow, such as the other token in its pair. In the first Everlong vault, it's USDC. The feed price $$P\_i$$ is units of loan asset $$i$$ per unit of pool asset. It comes from the pool's [price feed](/how-pools-work/price-feeds-and-oracles.md). The router posts from any pool asset the pool holds unposted, including a trader's incoming sale. A proportional deposit posts its share at each venue. It posts more at a venue that interest or a price fall has left past the pin. If the deposit's own pool asset falls short of that, it draws on the pool's unposted pool asset. Buys, exits, pokes and recentres post nothing. Nor does a sell paid from the loan asset's execution buffer, or any sell while that loan asset's borrowing is switched off. After a buy, the pool releases collateral above what the pin requires. It does so once that excess reaches 10% of what it has posted. **The pool asset held unposted is the pool asset's execution buffer.** It pays buys before any lending-market call. `setPoolAssetReserve(venueId, reserve)` sets a reserve for this buffer. A buy's collateral release refills the buffer to the reserve once the buffer falls a tenth or more short. The rest stays posted. The reserve isn't a cap. A sell or a deposit can lift the buffer above it, until a `maintain` top-up posts the excess. The pool operator can set a reserve only by naming a lending market whose collateral earns. Morpho Blue is the only venue type the code supports, and its collateral earns nothing. So no pool can set a reserve today. The keeper, the pool operator or a controller hook can also post or release collateral with `maintain`. They can do this while feature bit 4, `FEATURE_MAINTENANCE`, is on. ### Moving the dials **The credit setting** $$\varphi$$ **is the pool's second dial.** It's the share of a sell's incoming pool asset that counts towards the sell's room. It sits above zero and at most 1. The keeper or the pool operator moves both dials with `setDials(phiWad, ltvWad)`, and the router's pin follows. Each move must pass six rules: 1. Each dial stays inside its envelope, and the pin's maximum is under 1. 2. A rise in the LTV pin is no more than a set step. 3. One cooldown separates moves of either dial. A lower pin with no rise in $$\varphi$$ skips the cooldown while a lending market's lowered liquidation LTV sits under the pin plus the safety gap. 4. A move that doesn't lower the pin keeps the pin plus the safety gap at or under $$\mathrm{LLTV}$$. That's the lowest liquidation LTV among venues that can borrow or carry debt. With no such venue, only a lower pin passes. 5. A move that doesn't lower the pin also keeps the distance to liquidation, $$1 - \ell/\mathrm{LLTV}$$, at or above a set minimum. 6. A move that loosens either dial goes through only if the book already fits the new bound. A lower pin skips the step and rules 4 and 5, so the pool can follow a lending market's lower liquidation LTV in one move. The envelopes, the step, the cooldown, the safety gap and the minimum distance are all fixed at creation. The first Everlong vault starts at a pin of 0.55, inside an envelope of 0.10 to 0.70. Its credit setting starts at 1. Its market's liquidation LTV is 0.86. Against that, its safety gap of 0.02 and minimum distance of 15% allow a pin of up to about 0.73. ## The credit check **The credit check bounds a pool's net debt by the pool asset it owns.** It uses the feed price. It converts each loan asset's net debt into the pool asset, then adds up the positive amounts: $$ n\_i = \frac{D\_i - S\_i - L\_i}{P\_i}, \qquad U = \sum\_i \max(0,,n\_i), \qquad U \le \ell,A $$ Here $$D\_i$$ and $$S\_i$$ are the debt and the supplied balance in loan asset $$i$$ across its venues. The loan asset's execution buffer, held on hand, is $$L\_i$$. The term $$A$$ is the pool's gross holding: the pool asset held plus posted. The term $$U$$ is its net debt. Net debt rounds up, and a surplus rounds down. Only positive amounts count. So a surplus in one loan asset never makes room in another. ### A sell's room **A sell's room is the largest payout that keeps the credit check true.** The room counts the pool asset the sell brings in. Sells pay out only the first loan asset, numbered 0. A payout of $$x$$ adds $$x/P\_0$$ to net debt. It also brings in about $$x/P\_0$$ of pool asset, counted at $$\varphi$$: $$ U + \frac{x}{P\_0} ;\le; \ell\left(A + \varphi,\frac{x}{P\_0}\right) \quad\Longrightarrow\quad x ;\le; \frac{\ell A - U}{1 - \ell\varphi},P\_0 $$ The pool adds any surplus it holds in loan asset 0. It then takes off a margin $$\varepsilon$$, fixed at creation under 10%: $$ R\_0 = (1 - \varepsilon),\frac{\max(0,\ \ell A - U) + \max(0,,-n\_0)}{1 - \ell\varphi},P\_0 $$ Take the example book on [The pool and its book](/how-pools-work/the-pool-and-its-book.md). It has a gross holding of 100 cbBTC, $2,000,000 of debt and a feed price of $100,000 per cbBTC. Its net debt is 20 cbBTC. At a pin of 0.55, its bound is 55 cbBTC. With a credit setting of 1, the room is 35 over 0.45. That's about 77.8 cbBTC, or $7.8m. ### Limits on a sell **A sell fills only up to its ceiling.** That's the smaller of $$R\_0$$ and the loan asset's per-swap cap. The pool's invariant hook fits its fill under that ceiling. The trader keeps any input the smaller fill doesn't use. The first Everlong vault sets its per-swap cap at 1,000,000 USDC. If loan asset 0's borrowing is switched off, its cash replaces $$R\_0$$. That cash is its execution buffer plus what the pool has supplied. While debt from before the switch went off remains, $$R\_0$$ still caps such a sell too. A sell with no room reverts with `RoomExhausted`. After a sell settles, the pool checks $$U \le \ell A$$ again. If that fails, the sell reverts with `LedgerBoundBreached`. These checks apply on any curve the invariant hook fills on, including the Everlong hook's leverage curve. A sell the lending markets can't fund reverts whole. See [Just-in-time financing](/how-pools-work/just-in-time-financing.md#funding-orders). [Trade](/use-efficient/trade.md#the-preview) covers sizing an order from `previewSwap`. ### Deposits, buys and exits **Deposits and buys that would end over the bound take a ratio test instead.** The test has two conditions. No loan asset's net debt divided by $$A$$ may rise by more than one part in a billion. No loan asset without net debt may end with some. The price cancels out of the ratio. So a buy that raises no ratio clears the test, even on a book already over the bound. Every exit takes the ratio test, whatever the bound shows. An exit that fails it reverts with `ExitWorsensLedger`. Loan-to-loan swaps take the bound itself, as sells do. ## Limits on new borrowing **Every borrow at a venue must also clear that venue's bounds:** * the venue's and the loan asset's borrow switches, and the drawn set * the oracle band * the venue's liquidation LTV, which must still clear the LTV pin plus the safety gap * the lending market's free cash: on Morpho Blue, total supply minus total borrow * the venue's debt cap, and the loan asset's debt cap across its venues * the LTV pin, counting the collateral the venue holds and what the pool can post there * the rate ceiling. For a sell or a loan-to-loan swap, the router sizes each borrow to the tightest of them. When one venue has no room left, the router moves to the next in the borrow order. [Just-in-time financing](/how-pools-work/just-in-time-financing.md) covers that order. A proportional deposit's borrow isn't sized. It must fit every bound at each venue, or the whole deposit reverts. ### The rate ceiling and caps **A venue's rate ceiling stops new borrowing from pushing its market's borrow rate past a set level.** The router projects the rate after the borrow. It borrows the largest amount that keeps the rate at or under the ceiling, erring low. If the rate is already over, that venue lends nothing. The ceiling doesn't cap interest on debt already drawn. The lending market sets that interest. The parameter is `maxBorrowRateWad`, a per-second rate in WAD, as Morpho Blue's rate models report it. Debt and supply caps apply to each venue, and to each loan asset across its venues. A cap of zero means no cap. The pool operator sets them with `setVenueCaps(id, debtCap, supplyCap, maxBorrowRateWad)` and `setLoanCaps(idx, debtCap, supplyCap, borrowEnabled)`. The guardian can only tighten either. The first Everlong vault's venue has a ceiling of 7,386,586,395, about 23% a year before compounding. It caps debt at 1,500,000 USDC and supply at 2,000,000 USDC. ### The oracle band **The oracle band allows borrowing only where a market's oracle agrees with the feed price.** That's because lending markets liquidate at their own oracle's price. The router passes a venue only inside the band: $$ \left|,p\_{\mathrm{venue}} - P\_i,\right| ;\le; b,P\_i $$ Here $$b$$ is the band, and $$p\_{\mathrm{venue}}$$ is the lending market's oracle price, in the same units as $$P\_i$$. The band gates venue admission, every borrow, collateral release above the pin and refinancing. It never gates repaying or withdrawing supply. The pool operator sets the band with `setOracleBand(bandWad)`, up to 20% and with no delay. The guardian can only switch it on or narrow it. A band of zero switches the check off and leaves the lending market's own checks. The first Everlong vault runs a band of 10%. ### The fund re-check **By default, the router re-checks each borrow of a sell or loan-to-loan swap just before it executes.** It checks four limits again: * the liquidation LTV against the pin plus the gap * the debt cap * the rate ceiling * the pin. It skips free cash, which the lending market enforces. The re-check runs after the plan's withdrawals and that borrow's collateral post. The pool operator can switch the re-check off with `setFundRecheck(false)` to save gas. The plan's checks still apply. A deposit's borrow and a refinance keep their own checks. The guardian can only switch the re-check back on. ## Limits and their reference prices **Each limit reads the pool's feed price, the lending market's oracle or no price.** That decides what a gap between the two prices can move. | Check | What it stops | Measured on | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | The credit check, $$U \le \ell A$$ | Sells and loan-to-loan swaps that would end over it | The pool's feed price | | The ratio test | Deposits and buys that would end over the bound and worsen a loan asset's ratio | The feed price for the bound, no price for the ratio | | The ratio test on exits | Exits that worsen a loan asset's ratio | No price | | The per-swap cap | Sells and buys past it, which fill only up to it | No price | | The loan asset's cash, when its borrowing is off | Sells past it, which fill only up to it | No price | | The LTV pin at each venue | Borrowing past the pin on the collateral posted there | The pool's feed price | | Free cash, debt caps, the rate ceiling, the drawn set and the borrow switches | New borrowing | No price | | Liquidation LTV against the pin plus the safety gap | Borrowing at that venue, admitting it with borrowing on, switching its borrowing on, and dial moves that don't lower the pin | No price | | The oracle band | Borrowing, collateral release above the pin, refinancing and admission | Both prices, compared | | The lending market's liquidation LTV | Collateral withdrawals that would leave the loan past it | The lending market's oracle | A pool's hooks can add limits of their own. The Everlong hook does this on its leverage curve. See [The Everlong strategy](https://docs.foreverlong.io/everlong/everlong-strategy). ## Liquidation LTV and health factor **A lending market decides liquidation by its own test, not the credit check.** Each Morpho Blue market has a fixed liquidation LTV. The health factor compares it with the loan's current LTV: $$ \mathrm{LTV}*v = \frac{D\_v}{C\_v,p*{\mathrm{venue}}}, \qquad \mathrm{HF}\_v = \frac{\mathrm{LLTV}\_v}{\mathrm{LTV}\_v} $$ Here $$\mathrm{LLTV}\_v$$ is the market's liquidation LTV. The health factor $$\mathrm{HF}\_v$$ reaches 1 at the liquidation line. It counts gross debt at one market, at that market's oracle price. The credit check instead nets each loan asset across the pool, at the feed price. The pool reads each venue's health at its feed price: $$ h\_v = \frac{C\_v,P\_i,\mathrm{LLTV}\_v}{D\_v} $$ So $$\mathrm{HF}*v$$ equals $$h\_v$$ times $$p*{\mathrm{venue}}/P\_i$$. Each borrow posts what the pin requires. So right after a borrow, $$h\_v$$ is at least $$\mathrm{LLTV}\_v/\ell$$. [Maintaining 1:1 exposure](https://docs.foreverlong.io/everlong/maintaining-btc-exposure) works through the first Everlong vault's numbers. Two rules apply once a venue is past its liquidation LTV. A buy that needs its collateral fills only if the buy's repayment brings the venue back under the line. An exit there goes through only if it clears the venue's whole debt. [Risks and safeguards](/use-efficient/risks-and-safeguards.md) covers liquidation risk. ## Collateral top-ups **Anyone can top up a pool's collateral at a venue once that venue falls due.** The call is `maintainCollateral()`. No pause or feature switch stops it. A venue falls due once its LTV has used a fifth of the room from the pin to its market's liquidation LTV. For a venue carrying debt, that's when: $$ \frac{D\_v}{C\_v,\hat{P}\_v} > \ell + 0.2,(\mathrm{LLTV}\_v - \ell) $$ Here $$C\_v$$ counts only collateral the pool posted itself. So collateral a third party adds there neither stops a top-up nor shrinks it. The price $$\hat{P}\_v$$ is the feed price $$P\_i$$, with one exception. While the oracle band is on, it's the lending market's oracle price wherever that's lower. The lower oracle price applies only while the venue's collateral plus the pool's unposted pool asset could still bring it under its liquidation LTV. The first Everlong vault has a pin of 0.55 and a liquidation LTV of 0.86. There, a venue falls due at an LTV of about 0.61. If a lending market's liquidation LTV falls under the pin plus the safety gap, the top-up's target there changes. The new target is that liquidation LTV less the gap. The venue then falls due a fifth of the gap past that target. That holds only while its collateral plus the pool's unposted pool asset could still bring it under its liquidation LTV. Otherwise the pin stays the target. A liquidation LTV at or under the pin then leaves no room, so the venue falls due at the pin itself. Morpho Blue liquidation LTVs never move, so neither case arises at the first Everlong vault's market. `maintainCollateral()` picks the due venue with the lowest health. It posts unposted pool asset there, back to what the venue's target requires. It posts no more than the pool holds unposted or the venue still accepts. It passes over a due venue that accepts none, and emits `CollateralMaintained`. With no top-up due, it reverts with `NothingToMaintain`. It needs a checked feed price for every venue carrying debt. Swaps, deposits and exits never call it. But a sell that borrows restores the pin where it borrows. A proportional deposit does too, drawing on the pool's unposted pool asset where its own falls short. So a pool carrying debt needs a regular caller as prices fall. [Operate a pool](/run-a-pool/operate-a-pool.md) covers this. ## Emergency calls **The pool operator and the guardian share four emergency calls, each acting on one venue.** All four use `emergency(kind, id, assets)`. It goes straight to the pool's account at that lending market. So no pause stops it, including the router's. | Kind | What it does | Condition | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `Repay` | Accrues interest, then repays debt from the loan asset's execution buffer first. The caller pays any shortfall. What the debt doesn't absorb stays in the pool | None | | `TopUp` | Posts the pool's unposted pool asset as collateral | The venue carries debt and isn't retired | | `WithdrawSupplied` | Accrues interest, then returns supplied loan asset to the pool | None | | `WithdrawCollateral` | Returns posted collateral to the pool | The venue carries no debt | None of these calls can send assets anywhere but the pool or the pool's account at the lending market. If a market's rate model can't be read, only the top-up works. A Morpho Blue market is admitted only with the reviewed adaptive curve rate model. That model answers every read. [Roles and governance](/run-a-pool/roles-and-governance.md) lists every role's financing calls and the notice each change gets.