Credit and looping

The credit facility lends a market’s collateral token against locked issuance tokens (CreditFacility_v1). Each loan is a position in the market’s ReserveManager_v1, and the lent collateral comes from the market’s reserve. The facility values locked tokens at the reference price, not at the buy price. When the buy price is close to the reference price, a borrow against newly bought tokens returns most of the collateral the buy spent, and that collateral can buy again. Repeated in one transaction, the same new collateral buys more supply than a single buy.

Parts of a loan

The origination fee is the fee charged on each amount lent. The code calls it the borrowing fee (setBorrowingFeeRate, getBorrowingFeeRate). LTV (loan-to-value) is the share of the locked tokens’ value at the reference price that can be lent, in basis points. A loan closes when its loan amount and locked tokens both reach zero through repayment, or when it is merged into another loan.

Borrowing

A borrower names the amount of collateral to borrow. The facility computes the issuance tokens that must be locked for that amount at the current reference price and LTV, and pulls them from the borrower. The ReserveManager_v1 opens a position, records the full amount as loan amount, and draws that amount from the market’s reserve. The facility sends the origination fee to the fee treasury and the rest to the borrower. $$q = \left\lceil \frac{L \cdot 10\,000}{\text{LTV} \cdot P_{\text{ref}}} \right\rceil, \qquad \text{fee}_o = \left\lceil L \cdot \frac{f_o}{10\,000} \right\rceil, \qquad \text{paid} = L - \text{fee}_o$$ where:

• $L$ is the amount borrowed, in collateral (requestedLoanAmount_). The loan amount starts at $L$
• $q$ is the number of issuance tokens locked
• $\text{LTV}$ is the loan-to-value ratio in basis points (getLoanToValueRatio)
• $P_{\text{ref}}$ is the reference price, in collateral per token, 18 decimals (getReferencePrice)
• $f_o$ is the origination fee in basis points (getBorrowingFeeRate)

Both $q$ and the fee are rounded up. Read the other way, locked tokens $q$ support a loan of at most $q \cdot P_{\text{ref}} \cdot \text{LTV} / 10\,000$. Example. The reference price is 2.00, LTV is 8,000 bps (80%), and the origination fee is 200 bps (2%). A borrower borrows 1,600 collateral.

Repaying

A borrower repays any part of the loan amount. The facility pulls the collateral, and the ReserveManager_v1 returns it to the market’s reserve. Locked tokens are released in proportion to the share of the loan amount repaid. No fee is charged on a repayment. $$c = \min(a, \; D), \qquad u = \left\lfloor q \cdot \frac{c}{D} \right\rfloor$$ where:

• $a$ is the amount the borrower offers (repaymentAmount_)
• $D$ is the loan amount before the repayment
• $c$ is the amount repaid. An amount above the loan amount repays the loan amount in full
• $q$ is the locked tokens before the repayment
• $u$ is the tokens released to the borrower, rounded down

When a repayment brings both the loan amount and the locked tokens to zero, the facility closes the position and removes the loan. Example. Continuing from the loan above (1,000 tokens locked, loan amount 1,600), the borrower repays 400, then the rest.

Other loan functions

• Repay for another address. repayFor takes collateral from the caller and releases tokens to the loan’s borrower. It reverts for a loan whose borrower reports the IPresaleClaimObligations_v1 interface (a loan held by the early-access escrow).
• Transfer. transferLoan moves a loan to a new borrower. The locked tokens and the loan amount do not change. The new borrower cannot be the current borrower or the zero address.
• Merge. consolidateLoans merges two or more of the caller’s loans into one new loan. The ReserveManager_v1 adds up the locked tokens and the loan amounts, closes the old positions, and opens one position with a new ID.

Rebalancing a loan

When the reference price increases, the same locked tokens support a larger loan. rebalanceLoan lends the difference between that larger amount and the current loan amount, against the tokens already locked. The origination fee applies to the new amount, and the loan amount increases by the full new amount. $$B = \left\lfloor q \cdot P_{\text{ref}} \cdot \frac{\text{LTV}}{10\,000} \right\rfloor, \qquad \Delta = B - D$$ where:

• $B$ is the amount the locked tokens support at the current reference price and LTV
• $D$ is the current loan amount
• $\Delta$ is the new amount lent. The call reverts if $D$ is at or above $B$

The calculation uses the current loan amount, so a loan that has been partly repaid can be rebalanced up to $B$ again. Example. The loan from the borrowing example has 1,000 tokens locked and loan amount 1,600. The reference price increases from 2.00 to 2.50.

Looping

Looping is buying issuance tokens and borrowing against them, repeated in one transaction. Each repeat is a round: the facility buys on the curve with the collateral it holds, locks the tokens that buy minted, and borrows against them. The amount paid out by the borrow is the collateral for the next round. buyAndBorrow runs between 1 and the maximum rounds per transaction (getMaxLoops). In each round:

1. The facility buys on the market’s curve with all the collateral it holds for the call. The market takes the buy fee (Markets and curves).
2. The facility borrows the most the minted tokens support: $n \cdot P_{\text{ref}} \cdot \text{LTV} / 10\,000$, rounded down. The tokens are locked in a new loan for the borrower.
3. The origination fee goes to the fee treasury. The rest stays on the facility for the next round.

After the last round, the facility returns the collateral it still holds to the caller. All tokens bought in the call stay locked, apart from any remainder from rounding, which goes to the borrower. With consolidate_ set, the facility merges the call’s loans into one. $$c_{i+1} = r \cdot c_i, \qquad r = \Big(1 - \frac{f_b}{10\,000}\Big) \cdot \frac{P_{\text{ref}}}{p} \cdot \frac{\text{LTV}}{10\,000} \cdot \Big(1 - \frac{f_o}{10\,000}\Big), \qquad N_k = n_1 \cdot \frac{1 - r^k}{1 - r}$$ where:

• $c_i$ is the collateral spent in round $i$; $c_1$ is the new collateral (amount_)
• $f_b$ is the market’s buy fee in basis points (getBuyFee)
• $p$ is the average price paid per token in the round. The formula holds when every round pays the same price, for example when all buys fall in one step
• $r$ is the share of each round’s collateral that carries into the next round
• $n_1$ is the tokens minted in round 1, and $N_k$ is the tokens minted over $k$ rounds

$P_{\text{ref}} / p$ is the only term that depends on the curve. It is 1 when the buy price equals the reference price and falls as the premium, the distance of the buy price above the reference price, grows. Example. The reference price is 1.00, the buy fee is 100 bps (1%), LTV is 8,000 bps (80%), and the origination fee is 200 bps (2%). A borrower loops 1,000 new collateral for 3 rounds. In the first case the buy price is 1.10 (a 10% premium); in the second it is 2.20 (a 120% premium). In both cases every buy falls within one step. Values are rounded to two decimals; the contract works in 18-decimal units. Buy price 1.10, $r = 0.99 \times (1.00 / 1.10) \times 0.80 \times 0.98 = 0.7056$: Buy price 2.20, $r = 0.99 \times (1.00 / 2.20) \times 0.80 \times 0.98 = 0.3528$: The same 1,000 new collateral buys 1,983.12 tokens at a 10% premium and 664.77 tokens at a 120% premium. On a real curve each buy raises the buy price, so later rounds pay more per token than these single-step cases.

Where the lent collateral comes from

The facility does not hold a pool of its own. Each loan draws collateral from the market’s reserve through the ReserveManager_v1, which is the only contract the curve accepts draws from. drawReserves and restoreReserves move collateral out of and back into the reserve, the curve’s collateral balance. They do not change the curve’s virtual collateral supply (Markets and curves), and locking does not change the issuance token’s supply. Borrowing and repaying therefore do not move the curve’s price. After each openPosition, draw, repay and mergePositions, the ReserveManager_v1 checks that the position’s loan amount is at or below its locked tokens × the reference price, rounded down. The call reverts otherwise. This check uses the full reference value; the facility applies LTV on top of it. Example. For the 1,600 loan above, the reserve falls by 1,600 and the virtual collateral supply stays the same. The ReserveManager_v1 records 1,000 tokens locked and 1,600 loan amount, and its check compares 1,600 with 1,000 × 2.00 = 2,000.

Parameters

The launch route grants no role on the three setters, so only the holder of DEFAULT_ADMIN_ROLE passes their permission check. The facility sends origination fees to the market’s fee treasury (Fees and routing).

Who can call what at launch

repay, transferLoan and rebalanceLoan also require the caller to own the loan. Authority lists every role.

Scenarios

Example: borrowing for liquidity elsewhere. An address locks 1,000 tokens at a reference price of 2.00, with LTV at 80% and the origination fee at 2%, and borrows 1,600. The borrower receives 1,568.00 collateral, as in the borrowing example, and deposits it in a pool outside the market. The market’s curve, reserve and loan record do not change after the deposit. On a connected market, the borrowed token is the issuance token of the base market.

Edge cases

• Zero inputs. A borrow amount, repayment amount or round count of 0 reverts.
• Too many rounds. A round count above the maximum rounds per transaction reverts.
• Minimum loan. When the origination fee is above 0, a loan below 10,000 ÷ fee bps base units, rounded up, reverts.
• Slippage on a loop. buyAndBorrow takes a minimum for the total tokens minted across all rounds, including locked tokens. Below it, the whole call reverts.
• Rounding remainder. Locked tokens per round are rounded up from the loan, and the loan is rounded down from the tokens. Tokens left over from a round go to the borrower at the end of the call.
• Repayment release rounds down. A small repayment can release 0 tokens.
• Loan ownership. repay, transferLoan and rebalanceLoan revert for a loan the caller does not own. consolidateLoans reverts if any loan is not the caller’s, or if fewer than two loans are given.
• Frozen market. The curve’s drawReserves and restoreReserves revert while the market is frozen, so borrowing, looping, rebalancing and repaying revert.
• Endowed markets. On a market with an endowment controller, draws revert while endowment setup is open or before activation. Each draw also reverts unless total loan amount plus endowment draws plus the new amount is at or below the reference price × the lower of supply and the reference segment’s size. See Endowed reference segment.

Code

_{Source: house-markets/contracts at 0ebbc89a (branch integration/v12-post-qa).}