♾️3.3 Market Orders

Notation

• $A$ : the exact amount of credit to be sold

• $r$: absolute rate (not the APR) obtained by applying debtPosition.dueDate to the buyer yield curve

• $\Delta T$ : the remaining time to maturity i.e. deltaT = debtPosition.dueDate - block.timestamp

• $f$ : Conditional Fragmentation Fee, can be zero or non-zero depending on specific conditions

• $f^{\star}$ : Actual Fragmentation Fee, equal to fragmentationFee in the protocol

• $k$ : Swap Fee defined as APR (so needs to be multiplied by a time to become an absolute rate)

• $V$ : the amount of cash swapped

• $A_{max}$ : the maximum amount of credit that can be traded which is equivalent to creditPosition.credit the amount the credit is entitled to

3.3.1 Sell Credit Market Order (borrowing market order)

The FROB Borrowing Market Order can be used for different purposes.

The mechanism is always the same:

• the borrower specifies, in addition to MEV-protection parameters:

  • a lender

  • a tenor

  • an creditPositionId to sell

  • an amount to borrow

  • exactAmountIn whether the amount parameter means credit or cash

• for the lender's limit order, the related rate is computed by applying the specified tenor to the limit order yield curve so $r(t_{tenor})$

• as a result of this, given the amount and the rate, the future value of the loan related to that specific limit order is computed by applying the linear interest rate model

If the borrower wants to take multiple loans, from N different lenders, they may do so with a multicall by submitting N borrowing market orders.

Observation: thanks to its robust API, both existing and new credit may be sold through the SellCreditMarket function. By passing type(uint256).max as the creditPositionId, the system first creates a DebtPosition/CreditPosition pair assigned to the sender, in a "mint credit" internal operation, and then sells that CreditPosition to the lender. If an existing credit position is being sold, the tenor parameter is ignored, as it can be automatically computed from the related debt position.

3.3.1.1 To take a new fixed-rate loan

This is the primary purpose of the Sell Credit Market Order; to take a new fixed-rate loan, a borrower fills a lending limit order, and a DebtPosition, CreditPosition pair is created as a result.

3.3.1.2 To exit a loan you own

Lenders can "exit" their lending position before the due date by selling their credit to other lenders

This is possible because the FROB as an order book without any further adaptation serves 2 purposes

• to price the borrowing requests and

• to price the credit aka future cashflow

3.3.1.3 Technical specification

• In this case, the amountIn is credit

• With exactAmountIn=true

  • Formula

    • $V = \frac{A}{(1+r)} (1 - k \Delta T) - f$

  • Preconditions

    • $A \le A_{max}$ since it is not possible to sell more credit than the creditPosition.credit

    • $0 \le k \Delta T < 1$ since of course, we need to avoid the swap fee to eat the full or even exceed it, even though that's more of a theoretical issue since

      • the break-even is at $\Delta T = \frac{1}{k}$

      • the order of magnitude of the fee we are considering is 0.5% APR so the break-even would be for a credit whose remaining lifetime is 200 years.

  • Fragmentation Fee

    • if $A = A_{max}$ then $f = 0$ since there is no fragmentation as the full credit is swapped

    • if $A < A_{max}$ then $f = f^{\star}$

  • Explanation

    • The $\frac{A}{1+r}$ is the amount of cash the credit buyer values the amount of credit he is buying, before fees

    • Then fees are applied and

      • $k \Delta T$ is charged since the swap fee is a function of the remaining lifetime of the loan and is applied to the cash side of the trade

        • The higher $k$ or $\Delta T$ and the lower the cash returned to the credit seller

      • $f$ is charged to cover the gas costs related to credit fragmentation

        • The higher $f$ and the lower the cash returned to the credit seller

• With exactAmountIn=false

  • Formula

    • $A = \frac{(V + f) (1+r)}{(1 - k \Delta T)}$

  • Preconditions

    • Recalling the formula for exactAmountIn=true let's compute

      • $V_{max, max} = \frac{A_{max}}{(1+r)} (1 - k \Delta T)$

        • which is the maximum amount of cash possible, obtained by selling the full credit and therefore assuming no fragmentation fee

      • Let's define $K = \frac{1+r}{1 - k \Delta T}$ so we see immediately that

        • $V_{max,max} = \frac{A_{max}}{K}$ and that plugging it into the formula here we obtain that by submitting $V_{max,max}$ we sell $A_{max}$ and therefore there is no fragmentation and it is correct not to charge the fragmentation fee

      • Now we see in general $A = VK + fK$ so what happens if $V = V_{max,max} - \epsilon$ i.e. the seller wants to get slightly less than the max possible?

      • It happens that charging the fragmentation fee would make $A > A_{max}$ and therefore make the trading impossible

      • The turning point is for $A_{max} = VK + fK$ meaning

      • $V_{max, min} = \frac{A_{max}}{(1+r)} (1 - k \Delta T) - f^{\star}$

      • for which the trader can still sell the full amount, but the amount of cash it gets is less than the previous case since $V_{max,min} < V_{max,max}$ but still both require selling the entire $A_{max}$ amount

    • This is to say that the preconditions are

      • $V = V_{max,max}$ or $V < V_{max,min}$

  • Fragmentation Fee

    • Starting from $V$ they are

      • If $V = V_{max,max}$ then $f = 0$

      • If $V < V_{max,min}$ then $f = f^{\star}$

    • Equivalently starting from $A$ simply they are

      • if $A = A_{max}$ then $f = 0$ since there is no fragmentation as the full credit is swapped

      • if $A < A_{max}$ then $f = f^{\star}$

  • Explanation

    • The $\frac{A}{1+r}$ is the amount of cash the credit buyer values the amount of credit he is buying, before fees

    • Then fees are applied and

      • $k \Delta T$ is charged since the swap fee is a function of the remaining lifetime of the loan and is applied to the cash side of the trade

        • The higher $k$ and $\Delta T$ and the higher the amount $A$ to be sold to get the desired amount out

      • $f$ is charged to cover the gas costs related to credit fragmentation

        • The higher $f$ and the higher the amount $A$ to be sold to get the desired amount out

3.3.2 Buy Credit Market Order (lending market order)

There is also a FROB for borrowing bids.

The mechanism is similar to that of selling credit:

• the lender specifies, in addition to MEV-protection parameters:

  • a borrower

  • a tenor

  • an creditPositionId to sell

  • an amount to lend

  • exactAmountIn whether the amount parameter means cash or credit

Observation: thanks to its robust API, here too, both existing and new credit may be bought through the BuyCreditMarket function. By passing type(uint256).max as the creditPositionId, the system first creates a DebtPosition/CreditPosition pair assigned to the borrower, in a "mint credit" internal operation, and then buys that CreditPosition to the sender. If an existing credit position is being bought, both the tenor and borrower parameters are ignored, as these can be automatically computed from the related debt and credit positions.

The main use case has been envisioned for that is to allow borrowers to exit their positions before the due date, without forfeiting the full-term interest.

It is also possible for lenders to fill limit orders on the borrowing offer book. However, this is likely to be a less frequent arbitrage event, i.e. when borrow bids are priced higher than the market lending rate.

3.3.2.1 Technical specification

• In this case, the amountIn is cash

• with exactAmountIn=false

  • Formula

    • $V = \frac{A}{(1+r)} + f$

    • We can see that

      • the amount of cash to send in is equal to the credit desired (exact amount out) converted into cash discounting by the rate and increased by the fragmentation fee and then

  • Preconditions

    • $A \le A_{max}$ since it is not possible to buy more than the full credit amount

  • Fragmentation Fee

    • if $A = A_{max}$ then $f=0$

    • if $A < A_{max}$ then $f = f^{\star}$

• with exactAmountIn=true

  • Formula

    • $A = (V-f)(1+r)$

    • We can see that,

      • the amount of credit that is obtained is equal to the amount of cash sent in (exact amount in) first subtracted by the fragmentation fee and then converted into credit using the rate

  • Preconditions

    • $A \le A_{max}$

    • We need to compute the $V_{max, max}$ and $V_{max,min}$ as previously explained in the SellCreditMarket case, but this time we use the BuyCreditMarket formula so

      • $V_{max, max} = \frac{A_{max}}{(1+r)} (1 + k \Delta T)$

      • $V_{max, min} = \frac{A_{max}}{(1+r)} (1 + k \Delta T) - f^{\star}$

    • So the conditions for the swap to happen are

      • $V = V_{max,max}$ or $V < V_{max,min}$

  • Fragmentation Fee

    • Starting from $V$ they are

      • If $V = V_{max,max}$ then $f = 0$

      • If $V < V_{max,min}$ then $f = f^{\star}$

    • Equivalently starting from $A$ they are

      • if $A = A_{max}$ then $f = 0$ since there is no fragmentation as the full credit is swapped

      • if $A < A_{max}$ then $f = f^{\star}$

In the case of BuyCreditMarket, there is no swap fee in the formula since it is not paid by the credit buyer (even though he is on the active side of the trade), but by the credit seller. So the. amount of cash received by the credit seller is netCash = cash * (1 - k * \Delta T).