BSIP: 70
Title: Peer-to-Peer Leveraged Trading (Variant B)
Authors: George Harrap, Michel Santos, Peter Conrad
Status: Draft
Type: Protocol
Created: 2019-06-17
Discussion: https://github.com/bitshares/bsips/issues/170

Abstract

This BSIP defines a protocol upgrade in order to support peer-to-peer lending, borrowing and margin trading markets on the BitShares DEX. Lending is defined as any user of the BitShares DEX having the ability to post an offer to lend any BitShares asset they own to a market where a borrower may take that offer (by posting collateral) and pay the lender a lender-defined amount of interest over a time period.

The Borrower may choose to take the offer or post their preferred borrowing interest rate as a Bid and when taken, execute an exchange transaction with that token for another specified by the lender. The borrower will pay the lender interest in the asset type that was borrowed. Should the value of their margin position fall by a specified amount, the borrowers' balance will be margin called and sold on the market to payback the debt to the lender. The borrower risks losing their collateral in the case of a margin call and the lender risks the orderbook depth being insufficient to pay back their loan in the specified market.

Motivation

BitShares is the longest running decentralised cryptocurrency exchange and one of the pioneers of collateralised stablecoins. While the BitShares DEX makes it easy to trade in an environment where users have custody of their own keys, there are opportunities to be made to improve liquidity, onboard new users and affect great trading activity on the BitShares DEX.

The highest volume and most liquid exchanges in the world to date like Bitmex and Bitfinex who rose to dominance due to their usage of leverage in catalysing greater liquidity for their customers.

With this in mind, some of the key inhibitors to growth right now for the BitShares DEX include:

Incentive for Smartcoin creation / holding: The growth in liquidity of Smartcoins like bitUSD, BitCNY, BitEUR and others depends on users locking up BTS collateral to create these assets. For users engaged in creating these assets they must often manage exposure to a highly volatile collateral asset and are not paid for taking on the risk which could reduce potential new issuance.

Smartcoin Liquidity: The most liquid BitShares markets are often the smart coin markets, however the liquidity of Smartcoins in circulation on the orderbook is not yet comparable to larger teir centralised exchanges thereby reducing potential usage of the BitShares DEX.

Counterparty risk of crypto lending: Currently one of the only ways with market traction to earn passive income on cryptocurrency holdings is to trust a centralised counterparty and give up ownership of your money to another entity. This is highly risky with users no longer in control of their funds and at risk of hacking or confiscation.

BTS Price growth: The Bitshares token (BTS) is the underlying collateral required for committee issued assets and therefore a higher Bitshares price incentivises greater Smartcoin creation. Growing demand for BitShares assets promotes higher collateralisation of BTS which requires more BTS being removed from circulation which over time reduces supply and can increase positive price pressure.

The motivation behind this BSIP is to address these concerns and increase user demand, liquidity and passive income opportunities for users of the BitShares DEX.

Rationale

This BSIP seeks to address the inhibitors to growth in the BitShares DEX by introducing P2P Lending, Borrowing and Margin trading markets on the BitShares DEX. This new functionality would address the above concerns as follows:

Passive risk adjusted income: Any user may choose to lend any BitShares asset for a user defined rate of return over a specified time period. This not only provides an added incentive to hold an asset that can return a yield but also ensures existing liquidity of BitShares assets is deployed to the trading orderbook.

On-chain lending and borrowing reduces risk: Users seeking a return would not need to trust third party intermediaries with their funds and can engage in lending and borrowing contracts on the BitShares DEX. This reduces risk compared to competing centralised non-custodial competitors.

Increased DEX liquidity: With the ability for users to lend new or existing liquidity directly to the orderbooks, it provides greater order book depth than exists currently. This reduces risk for margin traders who rely on ample orderbook depth to ensure their positions can be adequately executed at a desired price or in the case of margin calls greater depth reduces collateral losses.

Long / Short any asset on the DEX: A user could borrow or lend any asset on the DEX adding new opportunities to make money from market movements especially in bear markets. This also enables smartcoin issuers to hedge their BTS (or other) exposure which could assist these users maintain adequate MCR ratios thereby reducing global settlement risk.

Added volume and usage of BTS: Every operation on the BitShares DEX requires a fee to be paid which returns BTS to the reserve pool. Greater usage of the BitShares DEX increases fees paid, reduces supply which can result in a positive price pressure on BTS. Additionally new smartcoin issuance for committee assets and some private assets requires BTS as collateral and therefore increased issuance also requires the purchase and lock up of BTS, increasing demand of BTS.

The BitShares DAC is well situated to capture a market opportunity in this space with the core intent of this BSIP to increase the viability of the BitShares DEX as a high volume, non-custodial, transparent and liquid trading exchange.

Specifications

The process flow for margin trading is depicted below. The process consists of seven stages with some stages containing parallel processes.

Process Flow

Stage 1a: Prior to any loan being offered or matched, the asset issuer must authorize the loan asset for lending for margin trading against sets of tradable assets.
Stage 1b: Prior to any loan being offered or matched, it must be possible to look up a valid reference price between the tradable asset and the the loan asset on the internal DEX market.
Stage 2: Lenders and potential Borrowers can place offers on the Lending Order Book. The offers by lenders ("loan offers") and the offers by borrowers ("borrow offers") shall remain on the books until they either expire or are matched by counter-offers.
Stage 3: Compatible offers are matched to create a loan.
Stage 4a: A borrower/ may hold the borrowed asset and/or trade against the agreed-upon tradable asset for the duration of the loan. Stage 4b: The smart contract will transfer interest payments from the borrower's loan portfolio to the lender on a daily basis. Stage 4c The smart contract shall appraise the loan to check whether sufficient collateral backs the loan. Stage 4d: A borrower may update the amount of collateral in their loan.
Stage 5a: A borrower may initiate a loan closure any time prior to the loan expiry. Stage 5b: The smart contract may initiate a margin call when the loan expires. Stage 5c: The smart contract may initiate a loan closure if it is unable to pay the daily interest on behalf of the borrower. Stage 5d: The smart contract may initiate a loan closure by margin call if it appraises the loan's collateral as being too low.
Stage 6: During a margin call process the smart contract attempts to liquidate a loan portfolio to obtain a sufficient balance of the borrowed asset to repay the lender. This might require selling the balance of the tradable asset on the market.
Stage 7a: During a loan closure, the lender is repaid what is owed and any balance of assets that remain in the loan portfolio are transferred to the borrower's regular set of balances. Stage 7b: Alternatively, if a margin call is initiated that does not complete within a certain amount of time, the entire loan portfolio shall be confiscated from the borrower and transferred to the lender as a substitute payment for what is owed.

Stage 1a: Authorized Leveraged Trading Pairs

The asset issuer of the loan asset must authorize the loan asset to be used for lending for margin trading ("leveraged trading") against a set of tradable assets. This set of authorized tradable asset may be updated by the asset issuer at any time. These restrictions shall affect the creation of new loan and borrow offers.

Stage 1b: Reference Price

Knowledge of the exchange rate between the loan asset and the tradable asset is essential for the smart contract to automatically appraise a portfolio during the loan appraissal and to evaluate the need for a possible margin call. This price shall be determined by the smart contract from data on the decentralized exchange and not from any external price feeds. The reference price shall be validated under specific rules, and prohibitions shall be imposed while the reference price is invalid.

Determination of Reference Price

The reference price for the tradable asset that is denominated in terms of the loan asset shall be updated every block that has any activity (new orders, canceled orders, and matched orders) in that market pair's trading book. The reference price of the tradable asset shall be calculated according to the following rules.

Asset	Reference Price	Validity of Reference Price
Tradable asset is a bitAsset that is not in global settlement	The highest offer price for the tradable asset. If there are no offers, the last traded price.	Valid if (a) there any offers for the tradable asset, and (b) if there has ever been any trade activity.
Tradable asset is a bitAsset that is in global settlement	Global settlement price	Always valid
All other assets	The highest offer price for the tradable asset. If there are no offers, the last traded price.	Valid if (a) there any offers for the tradable asset, and (b) if there has ever been any trade activity.

If the validity conditions are not satisfied for the asset pair, the reference price shall be considered invalid and certain activities shall be prohibited.

Prohibited Activity under Invalid Reference Price

A valid reference price permits the tradable asset components of the portfolio (T_liquid and T_orders) to be appraised in terms of the loan asset. This allows the entire loan portfolio to be appraised which further allows a check of the minimum collateral requirements for an existing loan.

Therefore with a valid reference price

loan offers may be made,
loan offers may be matched,
assets within a loan portfolio may be traded,
a borrower may deposit additional borrowed asset,
a borrower may withdraw the tradable asset subject to collateral requirements,
loan portfloios may be closed by the borrower,
loan portfolios may be closed by the smart contract due to the expiration, and
loan portfolios may be margin called subject to collateral requirements.

However an invalid reference price prevents a portfolio appraisal (except for the trivial case where the portfolio only consists of the borrowed asset components (B_liquid and B_orders). Without the ability to appraise the tradable asset portion of the portfolio, collateral requirements cannot be evaluated. Therefore,

loan offers shall not be matched to prevent the creation of new loans,
a borrower shall not be able to sell more of the borrowed asset if the new liquid balance (B_liquid^after) shall become less than the minimum collateral value. This constraint can be expressed as MCV ≤ B_liquid^after.
- The new limit order (B_trade^new) is constrained such that 0 < B_trade^new ≤ B_liquid^before - MCV
a borrower shall not be able to sell more of the tradable asset if the new liquid balance (B_liquid^after) shall become less than the minimum collateral value. This constraint can be expressed as MCV ≤ B_liquid^after
- The new limit order with a minimum to receive of the borrowed asset (B_trade^receive) is constrained such that 0 < B_trade^receive ≤ B_liquid^before - MCV
a borrower shall not be permitted to withdraw the tradable asset unless the liquid balance of the borrowed asset (B_liquid) is greater than the maintenance collateral value (MCV). This constraint can be expressed as MCV ≤ B_liquid
margin calls shall not be initiated because the collateral ratio (CR) of the loan portfolio cannot be calculated.

Stage 2: Offers to Lend and Borrow

Both potential lenders and potential borrowers can place offers on the Loan Order Book. Potential lenders place "loan offers" and potential borrowers place "borrow offers". Loan offers contain the following parameters:

Lending Offer Parameter	Description
Asset type to lend	The asset type that the lender is offering to lend
Minimum amount to lend	The minimum amount of the loan asset type that will be lent into a matched loan.
Maximum amount to lend	The maximum amount of the loan asset type that the lender is offering. This amount is deducted from the lender's balances when the offer is created.
Asset type of collateral	The asset type that the borrower must provide as collateral. For this initial version of margin trading, this shall be the same asset type as the asset type to lend.
Maintenance collateral ratio (MCR)	The minimum collateral ratio that the lender is expecting at the beginning of a loan. MCR ≥ MCCR ≥ 1
Margin call collateral ratio (MCCR)	The minimum collateral ratio below which a margin call of the loan is initiated. MCR ≥ MCCR ≥ 1
Maximum duration of margin call	The maximum duration of a margin call, if one is necessary, after which a portfolio confiscation will be triggered.
Asset type to trade against (Tradable asset)	The asset type that the lender permits the borrower to trade against. This restriction protects the lender from exit scam trading.
Minimum duration of loan	The minimum duration of the loan that the lender is willing to accept
Maximum duration of loan	The maximum duration of the loan that the lender is willing to accept
Minimum interest rate	The minimum daily interest rate that the lender is willing to accept
Expiration date	Expiration date of the offer

Borrow offers contain the following parameters:

Borrowing Offer Parameter	Description
Asset type to borrow	The asset type that the borrower is seeking
Minimum amount to borrow	The minimum amount of the loan asset type that will be borrowed into a matched loan.
Maximum amount to borrow	The maximum amount of the loan asset type that the borrower is willing to borrow.
Asset type as collateral	The asset type that the borrower must provide for collateral. For this initial version of margin trading, this shall be the same asset type as the asset type to lend.
Amount of collateral	The amount of collateral the borrower has put into the offer. This amount is deducted from the borrower's balances when the offer is created.
Maintenance collateral ratio (MCR)	The maximum collateral ratio that the borrower is willing to offer at the beginning of a loan. MCR ≥ MCCR ≥ 1
Margin call collateral ratio (MCCR)	The maximum collateral ratio below which a margin call of the loan is initiated. MCR ≥ MCCR ≥ 1
Minimum duration of margin call protection	The minimum duration of a margin call, if one is necessary, after which a portfolio confiscation will be triggered.
Asset type to trade against (Tradable asset)	The asset type that the borrower can trade against.
Minimum duration of loan	The minimum duration of the loan that the borrower is willing to accept
Maximum duration of loan	The maximum duration of the loan that the borrower is willing to accept
Maximum interest rate	The maximum daily interest rate that the borrower is willing to accept
Expiration date	Expiration date of the offer

After an offer is created, all users shall be able to identify:

which unmatched offers are on the Lending Order Book, and
which offers are matched.

Users shall have the ability to filter offers either by type (loan offer or borrow offer), asset type to loan, tradable asset type, amounts, interest rate, loan duration, maintenance collateral ratio, and margin call collateral ratio. This capability shall either be done at the Core RPC-API node and/or at the user interface. Offers to lend and offers to borrow shall have unique identifiers which can be referenced for loan matching.

The creation of offers, their partial and complete matches, their expiration, and their closures, shall be recorded as part of the account history of the lender and the borrower.

Offers to lend and borrow shall remain on the Loan Order Book until they either are canceled by the offeror, expire, or are completely matched and filled.

Stage 3: Loan Offer Matching

New offers shall be automatically compared to existing counter-offers on the book. This matchmaking investigation shall:

identify compatible offers
match compatible offers
create a loan from the matched offers

Compatibility Filtering

This matchmaking process shall only match a loan offer (L) with a borrow offer (B) if those offers have the following compatible conditions.

Offer Parameter	Compatibility Conditions
Loan amount (P)	L_P^min ≤ B_P^max and B_P^min ≤ L_P^max
Loan duration (D)	L_D^min ≤ B_D^max and B_D^min ≤ L_D^max
Interest rate (I)	L_I ≤ B_I
Minimum collateral ratio (MCR)	L_MCR ≤ B_MCR
Margin call collateral ratio (MCCR)	L_MCCR ≤ B_MCCR
Margin call duration (MCD)	B_MCD ≤ L_MCD

Therefore when a new loan offer or borrow offer is received, it shall be checked against the existing offers. This new offer will become the "taker" to the existing "maker" offers. The outcome of this investigation may identify multiple "maker" offers to be compatible with the new "taker" offer.

If no compatible offers are found for the new offer, the new offer shall be added to the offer order book and retained until it is canceled, expires, or is completely matched and filled.

Offer Matching

When multiple loan offers (L) are found to be compatible with multiple borrow offers (B), they shall be prioritized in a deterministic manner to identify which of the compatible offers will be matched to each other.

As the definition of most offer parameters are not exact values (e.g. a lender might offer a loan for exactly 6 months) but are rather bounded values (e.g. a lender might offer a loan for a duration between 3 months and 12 months), and the compatibility conditions permit a range of overlap between a loan offer and a borrow offer, there may mathematically be an infinite number of loan definitions that could be created from even a single loan offer and borrow offer. (Technically the number of loan offers are finite because they will only be characterized by finite-precision integer parameters.) Matches shall be made to favor the existing offers on the loan offer books (the "makers").

If the new offer (the "taker") is a borrow offer, the compatible loan offers shall be sorted in favor of the lenders (the "makers"). These compatible offers shall be sorted in favor of the lender offers as described in the following table.

Loan Parameter	Loan Parameter Selection	Loan Parameter Value	Prioritization Order
Interest rate (I)	Highest compatible interest rate	B_I	1
Loan duration (D)	Longest compatible loan duration	min(L_D^max, B_D^max)	2
Loan amount (P)	Largest compatible amount	min(L_P^max, B_P^max)	3
Margin call collateral ratio (MCCR)	Highest compatible MCCR	B_MCCR	4
Minimum collateral ratio (MCR)	Highest compatible MCR	B_MCR	5
Margin call duration (MCD)	Shortest MCD	B_MCD	6

If the new offer (the "taker") is a loan offer, the compatible offers shall be sorted in favor of the borrowers (the "makers"). These compatible offers shall be prioritized favor of the borrower offers as described in the following table.

Loan Parameter	Loan Parameter Selection	Loan Parameter Value	Prioritization Order
Interest rate (I)	Lowest compatible interest rate	L_I	1
Loan amount (P)	Largest compatible amount	min(L_P^max, B_P^max)	2
Loan duration (D)	Longest compatible loan duration	min(L_D^max, B_D^max)	3
Margin call collateral ratio (MCCR)	Lowest compatible MCCR	L_MCCR	4
Minimum collateral ratio (MCR)	Lowest compatible MCR	L_MCR	5
Margin call duration (MCD)	Longest MCD	L_MCD	6

The highest prioritized maker offer shall be paired to the new offer and a new loan shall be created in accordance with the loan parameter values in the corresponding table.

Loan Creation

The matching of a loan offer with a borrow offer shall result in the creation of a loan.

This new loan portfolio shall receive the loan amount (P) from the lending offer and an amount of collateral asset (K) from the borrowing offer equal to

K = (MCR - 1) × P

A loan shall be created from a single lending offer and a single borrowing offer.

This loan portfolio shall then become available for margin trading by the borrower.

Effective Dates of the Loan

The start date of the loan shall be when the loan is matched. The end date of the loan shall be calculated by adding the loan duration to the start date. The loan may be closed:

by the borrower before the end date,
by the smart contract when the end date arrives, or
by the smart contract before the end date if the loan portfolio is undervalued.

Filling of Loan Offer

The matching of a loan offer with a borrow offer will result in one or both of the offers being completely consumed. If an offer is not completely filled, the offer shall be "partially filled" by having the loan amount (P) deducted from the offer's "available balance".

Effects of Partial Fills on a Loan Offer

The reduction to a loan offer reduces the amount that has been offered by the prospective lender.

(B_P^max)^new = (B_P^max)^old - P

If this remainder exceeds the loan offer's minimum amount (B_P^min), the loan offer shall be retained on the offer books. Otherwise the offer shall be cancelled by the smart contract.

Effects of Partial Fills on a Borrow Offer

The reduction to a borrow offer reduces the amount of collateral (K) that is being offered by the prospective borrower.

K^new = K^old - P

This effectively reduces the maximum loan amount of the borrow offer.

(L_P^max)^new = K^new ÷ (MCR - 1) = (K^old - P) ÷ (MCR - 1)

If this remainder exceeds the borrow offer's minimum amount (L_P^min), the loan offer shall be retained on the offer books. Otherwise the offer shall be cancelled by the smart contract.

Re-evaluation of a New Offer

If the partially-filled offer is retained and if the partially filled offer is the new offer, it shall be re-evaluated for loan matching against the remaining counter-offers.

Stage 4a: Margin Trading within Loan Portfolio

Assets that are borrowed shall be placed into the borrower's margin trading "loan portfolio". This portfolio shall only be used for trading on the decentralized exchange in the market pair consisting of the "Asset type to lend/borrow" and the "Asset type to trade against". It shall not be possible to transfer funds to any account, nor use any of the assets as collateral to create another pegged asset on BitShares.

Any assets obtained from trading shall by placed into the loan portfolio and shall also be restricted to trading between the pair of asset types defined in the loan agreement. Conditional withdrawals of the tradable asset by the borrower shall be permitted. Deposit of the lent asset by the borrower shall also be permitted.

Trading Limits

A borrower shall be able to use the borrowed asset type in the loan portfolio to trade against the tradable asset on the order book of the market pair. The amount of the borrowed asset type (B) that may be used for placing new orders shall be limited to ensure that the loan portfolio's balance of the borrowed asset exceeds the minimum collateral (K). Before a trade the liquid balance of the asset type is B_liquid^before. The liquid balance of the asset type after a new order (B_trade^new) can be calculated as

B_liquid^after = B_liquid^before - B_trade^new

The new liquid balance must satisfy the following condition and definition for collateral

B_liquid^after ≥ K = (MCR - 1) × B₀

which can be re-arranged as

B_trade^new ≤ B_liquid^before - (MCR - 1) × B₀

This expresses a maximum amount for any new limit orders where the borrowed asset is offered to trade. If this amount is negative, no new trades shall be permitted.

Multiple Loan Portfolios

A borrower may have multiple outstanding loans each with their own distinct loan portfolio. Trading of assets from each loan portfolio shall be independent of other loan portfolios that are controlled by the borrower. Trade orders shall only draw from assets within a single loan portfolio.

The distinction of loan portfolios from each other are intended to segregate the risk of each loan which can have separate loan durations, margin collateral ratios, and tradable assets. This segregation should better secure the lenders than a single co-mingled loan portfolio.

User interfaces that facilitate trading for a borrower may optionally aggregate multiple loan portfolios into a single "margin trading wallet" to disguise the fact that multiple loan portfolios are being tracked.

Stage 4b: Daily Interest Payment

The daily interest due (I_daily) on the prinicipal (B₀) shall be calculated as

I_daily = B₀ × R_daily

where R_daily is daily interest rate. This daily interest shall be calculated in terms of the lent asset type.

The daily interest that is due shall be deducted from the borrower's balance of the borrowed asset type in the loan portfolio and deposited into the lender's account. If the borrower's loan portfolio holds insufficient balance of the lent asset type to pay the daily interest then a margin call shall be initiated.

When a loan is closed the interest for that last day shall be paid at that time. If a margin call requires multiple days to complete in accordance with the agreed duration of the margin call's loan, no additional interest shall be owed by the lender beyond payment for the last day of interest.

Stage 4c: Appraisal of Loan Portfolio

Debt Owed

The debt owed by a borrower for a particular loan is the amount lent by the lender. Interest is due on a daily basis.

Portfolio Appraisal

A borrower may have many outstanding loans which are owed to different borrowers. Each loan portfolio will initially consist of the principal that is lent by the lender plus the initial collateral that is provided by the borrower. The borrowed asset and the collateral asset shall initially be the same asset type (B).

After the loan is initiated, the borrower may use that asset type to trade against the tradable asset type (T) that is permitted by the loan, and/or may hold the borrowed asset. Therefore this loan-related portfolio may consist of balances of two asset types: the borrowed asset type, and the tradable asset type.

PA = B + T

Portfolio Components

While a loan is outstanding the balance of the borrowed asset and tradable asset may consist as either liquid balances in the loan portfolio or as open orders on the order book. Therefore the entire loan portfolio may be decomposed into four parts:

a balance of borrowed asset that is liquid (B_liquid)
a balance of tradable asset that is liquid (T_liquid)
a balance of borrowed asset that is in open order (B_orders)
a balance of tradable asset that is in open order (T_orders)

PA = B_liquid + T_liquid + B_orders + T_liquid

The valuation of the portfolio shall also be denominated in terms of the borrowed asset type for purposes of appraisal by the smart contract. The valuation of the borrower's loan-related portfolio shall consist of the valuation of the two assets in the portfolio at the time of interest.

The valuation of the liquid balance and order balance of the borrowed asset shall simply be their sum.
The valuation of the liquid balance and order of the tradable asset shall be denominated in the borrowed asset type by the smart contract with the use of reference price.

Example of Portfolio Appraisal

Bob borrowed 70 bitUSD 203.3 days ago while supplying by supplying 30.03 bitUSD as collateral. Bob has been margin trading with this loan portfolio against bitBTC and currently has a balance of 45 bitUSD and 0.025 bitBTC. The current reference price indicates that bitBTC is priced at 5000 bitUSD per bitBTC. This loan portfolio will be appraised (PA) at:

PA = (45 bitUSD) + (0.025 bitBTC × 5000 bitUSD ÷ bitBTC)

... = (45 bitUSD) + (125 bitUSD)

... = 170 bitUSD

Collateral Ratio

After the calculation of a portfolio appraisal (PA) and the debt owed (B₀), the collateral ratio (CR) shall be calculated as

CR = PA ÷ B₀

At the beginning of the loan, the collateral ratio will satisfy the following conditions.

CR ≥ MCR ≥ MCCR ≥ 1

Derived Valuations

The maintenance collateral valuation (MCV) of the loan portfolio is denominated in the borrowed asset and equals

MCV = MCR × B₀

where B₀ is the debt owed.

Similarly, the margin call collateral valuation (MCCV) of the loan portfolio is denominated in the lent asset and equals

MCCV = MCCR × B₀

It is desired for the appraised valuation of the portfolio (PA) to be greater than or equal this value

PA ≥ MCV ≥ MCCV ≥ B₀

but it is possible for this valuation to fall below the MCV. If

PA < MCCV

a margin call shall be initiated.

Triggering of Appraisal

Portfolio appraisals shall be triggered at multiple times. A portfolio appraisal shall be triggered:

before any new portfolio trade is executed to calculate the current trading limit,
after a loan portfolio is updated by the borrower,
after a margin trade order is filled, and
after interest is paid.

Stage 4d: Loan Portfolio Updates

Status of Loan Portfolio

The "recent" appraisal value, debt owed, collateral ratio, and derived valuations, and of the portfolio shall be able to be queried by the lender and borrower at any time.

Deposits

A borrower shall be able to deposit additional amounts of the borrowed asset into the loan portfolio. A borrower may choose to deposit additional collateral to avoid having the loan be margin called.

Withdrawals

A borrower shall be able to withdraw only the tradable asset as long as the market valuation of the portfolio (PA) after the withdrawal is greater than or equal to the maintenance collateral valuation. The withdrawal limit (W_limit) is defined as

W_limit = PA - MCV

where MCV is maintenance collateral valuation and PA is portfolio appraisal.

Example of Withdrawal

Bob borrowed 70 bitUSD 203 days ago at a daily interest rate of 0.0261% while supplying by supplying 30.03 bitUSD as collateral to satisfy the offer's 142.9% maintainance collateral ratio.

The debt owed is still 70 bitUSD. The maintenance collateral valuation (MCV) of the portfolio is

MCV = MCR × B₀

... = 1.429 × 73.8276 bitUSD

... = 105.4996 bitUSD

During this time Bob has been margin trading with this loan portfolio against bitBTC and currently has a balance of 45 bitUSD and 0.025 bitBTC. The current reference price indicate that bitBTC is priced at 5000 bitUSD per bitBTC. This loan portfolio will be appraised at:

PA = (45 bitUSD) + (0.025 bitBTC × 5000 bitUSD ÷ bitBTC)

... = (45 bitUSD) + (125 bitUSD)

... = 170 bitUSD

The borrower may withdraw up to the equivalent (W_limit) of

W_limit = PA - MCV

... = 170 bitUSD equivalent - 105.4996 bitUSD equivalent

... = 64.5004 bitUSD equivalent

The withdrawal limit denominated in bitBTC is

W_limit = (64.5004 bitUSD ÷ (5000 bitUSD ÷ bitBTC))

... = 0.01291 bitBTC

Bob may withdraw bitBTC up to this limit because the balance of bitBTC, 0.025, exceeds this amount. If the balance of the tradable asset were, for example, only 0.1 bitBTC then Bob would only be able to withdraw 0.1 bitBTC.

Stage 5a: Initiation of Loan Closure by Borrower

A borrower may close an outstanding loan position by having a sufficient balance of the borrowed asset type in the loan portfolio and then initiating a loan closure with the appropriate parameters.

Initiation of Loan Closure Parameter	Description
Lending Offer ID	Identifier of an existing and open loan offer

The initiation of a loan closure shall close any and all open trade orders that are related to this loan. If the balance of the borrowed asset type is insufficient to repay what is owed then the initiation of the loan closure shall be rejected. It is the responsibility of the borrower to ensure a sufficient balance in the borrowed asset type to repay the loan.

Stage 5b: Expiration of Loan

The smart contract shall initiate a margin call if an outstanding loan expires.

A future BSIP may consider opening a new loan from any existing offers on the Loan Order Book.

Stage 5c: Initiation of Loan Closure because of Insufficient Funds

A loan portfolio may categorized as consisting of four components of balances of which one is the balance of borrowed asset that is liquid (B_liquid). This balance is drawn from to pay the daily interest. If this balance is insufficient to pay the interest then a loan closure shall be initiated.

Stage 5d: Initiation of Loan Closure by Margin Call

If the collateral ratio ever drops below the margin call collateral ratio,

CR < MCCR

the smart contract shall initiate a margin call.

Stage 6: Margin Call

Restriction of Loan Portfolio

When a margin call is initiated on a specific loan portfolio, no new market orders may be initiated that make use of any balance in the loan portfolio. Any other loan portfolios that the borrower might have shall not be affected by margin calls on other loans.

Any open market orders that are related to that specific loan portfolio shall be cancelled.

After all open orders are cancelled, the portfolio will consist of some amount in the borrowed asset type and some amount in the tradable asset type.

PA = B_liquid + T_liquid

Liquidation Plan

The smart contract shall determine whether the balance of the borrowed asset (B_liquid) is sufficient to pay the necessary balance (B_closure). The difference between the two is the excess borrowed asset (B_excess)

B_excess = B_liquid - B_closure

If the balance is sufficient (B_excess > 0), the process shall transition to a conventional loan closure.

If the balance is insufficient (B_excess < 0), the smart contract shall create a limit order that offers the entire balance of the tradable asset (T) while asking for the difference between what is owed and the liquid balance(-B_excess). This limit order shall have a limited lifetime defined by the maximum margin call duration that was agreed to in the original loan terms.

If the margin call's limit order is filled, then by definition of the limit order there shall be sufficient balance of the borrowed asset type to transition to a conventional loan closure.

Portfolio Confiscation

If the margin call's limit order expires without being completely filled, a portfolio confiscation shall be automatically initiated to permit the prompt completion of the margin call. The smart contract shall confiscate the entire loan portfolio from the borrower for ultimate transfer to the lender.

Monitoring of Liquidation Plan

It shall be possible to monitor the status of the liquidation plan associated with any margin call. An inquiry into the status of the liquidation plan shall return:

how much of the tradable asset was originally being liquidated,
how much of the tradable asset has been sold, and
how much of the borrowed asset has been obtained as a result of the liquidation.

Stage 7a: Conventional Loan Closure

A standard loan closure is possible if and only if the loan portfolio's balance of the borrowed asset type (B_liquid) is sufficient to repay the principal plus interest for the last day of the loan.

B_closure = B₀ + I_daily

If that condition is satisfied, a standard loan closure can be:

initiated by the borrower
initiated by expiration of the loan
initiated by the full completion of a margin call

Any balances that remain in the loan portfolio after repaying the lender shall be transferred to the borrower's regular set of balances and shall no longer be encumbered by any restrictions.

A future BSIP may consider re-lending a lenders balance by automatically creating a new offer on the Loan Order Book on behalf of the lender.

The loan shall be closed.

Stage 7b: Unconventional Loan Closure

If a margin call's liquidation plan expires without obtaining a sufficient balance of the borrowed asset to repay the lender, the confiscated loan portfolio shall be transferred to the lender as a substitute payment for the debt.

The loan shall be closed.

Definable Loan Constraints

The BitShares Committee shall be able to define parameters that can constrain new loans; changes to these values shall not affect loans that were offered before the change:

Term	Description
Maximum loan durations	The maximum duration for a new loan offer
Minimum MCR	The minimum maintenance collateral ratio (MCR) that may be agreed upon
Minimum MCCR	The minimum margin call collateral ratio (MCCR) that may be agreed upon
Maximum interest rates	The maximum interest rate that may be agreed upon
Maximum duration of margin call	The duration during which a borrower's loan portfolio shall be protected from confiscation.

Fees

Fees shall be defined for each of the operations:

creation of a lend offer
creation of a borrow offer
canceling an open offer
depositing additional collateral
withdrawing assets from a loan portfolio
closing a loan
placing trade orders from the loan portfolio
- Placing orders from the margin account incurs a computational burden on the nodes because of the need to ensure adequate collateralization of each loan portfolio. This expense should be reflected in some fee related to loan portfolio operations. A natural fit is to charge a higher fee for placing fees from a margin account.

The standard fee for canceling a trade order shall apply.

Voting Stake

Voting stake shall be calculated per account as before this proposal and with the following additions to account for any core tokens (BTS) that are associated with lending.

Any balance of BTS in a lending offer shall be staked to the owner of the offer.
Any balance of BTS in a borrowing offer shall be staked to the owner of the offer.
If BTS is the tradable asset in a loan portfolio, the liquid balance (T_liquid) and the balance in open orders (T_orders) shall be staked to the borrower.
If BTS is the borrowed asset in a loan portfolio, the liquid balance (B_liquid) and the balance in open orders (B_orders) shall be staked to the lender up to the principal amount that is lent (B₀). Any balance in excess of the principal shall be staked to the borrower.
- The motivation for this segregation of voting stake is to prevent the renting of voting stake through this lending mechanism.

Software Specifications

Note 1: Interest is paid every 24 hours, regardless of local calendar. E. g. Daylight Savings Time is ignored.

Note 2: Percentage-based calculations (interest, CR) are always rounded up to the next possible value (aka "satoshi").

Note 3: MCR and MCCR are expressed in the same way as in the existing price feed logic, i. e. only the part above 100%, and as a scaled percentage value. E. g. a value of 4200 would mean 142%.

Note 4: "Implementation hints" are not to be considered part of the formal specification, but merely as a possible implementation.

Database Objects

`lending_offer_object` (new)

Fields:

lending_offer_id_type id - The object ID
account_id_type owner - The lending account ID
asset_id_type loan_asset - The asset type that the lender is offering to lend
share_type min_amount - The minimum amount of the asset type that the borrower must borrow
share_type max_amount - The maximum amount of the asset type that the lender is offering
unsigned_int mcr - The minimum collateral ratio that the lender is expecting at the beginning of a loan, as a scaled percentage
unsigned_int mccr - The collateral ratio below which a margin call of the loan is initiated, as a scaled percentage
unsigned_int max_call_duration - The maximum duration of a margin call in seconds, if one is necessary, after which a portfolio confiscation will be triggered
asset_id_type tradable_asset - The asset type that the lender permits the borrower to trade against
unsigned_int min_duration - The minimum duration of the loan that the lender is willing to accept, in days
unsigned_int max_duration - The maximum duration of the loan that the lender is willing to accept, in days
unsigned_int min_interest_rate - The minimum daily interest rate that the lender is willing to accept, as a scaled percentage
time_point_sec expiration - Expiration date of the offer
extension_type ext - reserved for future extensions

Implementation hints:

Indexed by_owner, by_asset, by_expiration
Secondary index for tracking core per account

`borrowing_offer_object` (new)

Fields:

borrowing_offer_id_type id - The object ID
account_id_type owner - The borrowing account ID
asset_id_type loan_asset - The asset type that the borrower is offering to borrow
share_type min_amount - The minimum amount of the asset type that the lender must lend
share_type max_amount - The maximum amount of the asset type that the borrower wants to borrow
share_type available_collateral - The amount of collateral the borrower has put into the offer
unsigned_int mcr - The maximum collateral ratio that the borrower is willing to provide at the beginning of the loan, as a scaled percentage
unsigned_int mccr - The maximum collateral ratio the borrower will accept, below which a margin call of the loan is initiated, as a scaled percentage
unsigned_int min_call_duration - The minimum duration of a margin call in seconds, if one is necessary, after which a portfolio confiscation will be triggered
asset_id_type tradable_asset - The asset type that the borrower wants to trade against
unsigned_int min_duration - The minimum duration of the loan that the borrower is willing to accept, in days
unsigned_int max_duration - The maximum duration of the loan that the borrower is willing to accept, in days
unsigned_int max_interest_rate - The maximum daily interest rate that the borrower is willing to accept, as a scaled percentage
time_point_sec expiration - Expiration date of the offer
extension_type ext - reserved for future extensions

Implementation hints:

Indexed by_owner, by_asset, by_expiration
Secondary index for tracking core per account

`loan_portfolio_object` (new)

Fields:

account_id_type owner - The borrowing account ID
account_id_type lender - The lending account ID
asset_id_type principal_asset - The ID of the borrowed asset
share_type principal_borrowed - The amount that was originally borrowed
share_type minimum_collateral - The minimum amount of collateral that must be maintained
share_type principal_balance - The amount of the borrowed asset currently held in the portfolio
share_type principal_in_orders - The amount of the borrowed asset currently held in market orders
asset_id_type trade_asset - The ID of the asset that can be traded against
share_type trade_balance - The amount of the tradable asset currently held in the portfolio
share_type trade_in_orders - The amount of the tradable asset currently held in market orders
share_type mccv - The portfolio value below which a margin call of the loan is initiated, in terms of principal_asset
unsigned_int call_duration - The duration of a margin call in seconds, if one is necessary, after which a portfolio confiscation will be triggered
optional<time_point_sec> confiscation_time - After a margin call has been initiated, this contains the time when the portfolio will be confiscated
share_type daily_interest - The daily interest amount to be paid
time_point_sec interest_due_at - Date at which the next interest payment is due
share_type cumulative_interest - The cumulative interest paid for this loan so far
time_point_sec earliest_end - Date after which the portfolio can be closed by the borrower
time_point_sec latest_end - Date after which the portfolio will be closed automatically
optional<price> call_price - If present, contains the price (in terms of principal/trade) below which the portfolio is margin called

Implementation hints:

Indexed by_owner, by_lender, by_interest_due, by_expiration (i. e. latest_end)
Secondary index for tracking core per account

Chain parameters

The chain_parameters (configurable by committee) will receive a new extension field margin_lending with these members:

unsigned_int max_duration - maximum allowed loan duration in days
unsigned_int minimum_mcr - minimum allowed mcr for loans, as a scaled percentage
unsigned_int minimum_mccr - minimum allowed mccr for loans, as a scaled percentage
unsigned_int max_interest - maximum allowed daily interest rate, as a scaled percentage
unsigned_int max_call_duration - maximum allowed call duration in seconds

This extension must not be present in proposals before the hardfork time.

Miscellaneous

limit_order_object receives a new field optional<loan_portfolio_id_type> loan

Implementation hints:

Secondary index on limit_order_object for tracking by_loan

Operations

All new operations have a simple flat fee. New operations must not be allowed before the hardfork time, neither in proposals nor directly. New fees must not be allowed in chain parameter update proposals before the hardfork.

`lending_offer_create_operation` (new)

Fields:

account_id_type lender - The lending account ID
asset_id_type asset_to_lend - The asset type that the lender is offering to lend
share_type min_to_lend - The minimum amount of the asset type that the borrower must borrow
share_type max_to_lend - The maximum amount of the asset type that the lender is offering
unsigned_int mcr - The minimum collateral ratio that the lender is expecting at the beginning of a loan, as a scaled percentage
unsigned_int mccr - The collateral ratio below which a margin call of the loan is initiated, as a scaled percentage
unsigned_int max_call_duration - The maximum duration of a margin call in seconds, if one is necessary, after which a portfolio confiscation will be triggered
asset_id_type tradable_asset - The asset type that the lender permits the borrower to trade against
unsigned_int min_duration - The minimum duration of the loan that the lender is willing to accept, in days
unsigned_int max_duration - The maximum duration of the loan that the lender is willing to accept, in days
unsigned_int min_interest_rate - The minimum daily interest rate that the lender is willing to accept, as a scaled percentage
time_point_sec expiration - Expiration date of the offer
extension_type ext - reserved for future extensions

Validation checks:

lender must be a valid account ID, must exist, must authorize the operation, must pay fee
asset_to_lend and tradable_asset must be valid asset IDs, must not be equal, and both assets must exist
min_to_lend > 0
max_to_lend >= min_to_lend
mcr >= mccr
max_duration >= min_duration
expiration > head_block_time
min_duration <= chain_parameters.max_duration
mcr >= chain_parameters.min_mcr
mccr >= chain_parameters.min_mccr
min_interest_rate <= chain_parameters.max_interest_rate
max_call_duration <= chain_parameters.max_call_duration
lender must have at least max_to_lend of asset_to_lend in his balance
asset_to_lend must be authorized for margin lending against tradable_asset
asset_to_lend and the tradable_asset must not be transfer restricted
lender must be whitelisted or must not be blacklisted for the asset_to_lend and the tradable_asset due to transfer restrictions

Evaluation:

Deduct max_to_lend of asset_to_lend from lender balance
Create new lending_offer_object and populate object fields from operation fields
Operation result is new object id
Trigger automatic matching

`borrowing_offer_create_operation` (new)

Fields:

account_id_type borrower - The borrowing account ID
asset_id_type asset_to_borrow - The asset type that the borrower is offering to borrow
share_type min_to_borrow - The minimum amount of the asset type that the lender must lend
share_type max_to_borrow - The maximum amount of the asset type that the borrower wants to borrow
unsigned_int mcr - The maximum collateral ratio that the borrower is willing to provide at the beginning of the loan, as a scaled percentage
unsigned_int mccr - The maximum collateral ratio the borrower will accept, below which a margin call of the loan is initiated, as a scaled percentage
unsigned_int min_call_duration - The minimum duration of a margin call in seconds, if one is necessary, after which a portfolio confiscation will be triggered
asset_id_type tradable_asset - The asset type that the borrower wants to trade against
unsigned_int min_duration - The minimum duration of the loan that the borrower is willing to accept, in days
unsigned_int max_duration - The maximum duration of the loan that the borrower is willing to accept, in days
unsigned_int max_interest_rate - The maximum daily interest rate that the borrower is willing to accept, as a scaled percentage
time_point_sec expiration - Expiration date of the offer
extension_type ext - reserved for future extensions

Validation checks:

borrower must be a valid account ID, must exist, must authorize the operation, must pay fee
asset_to_borrow and tradable_asset must be valid asset IDs, must not be equal, and both assets must exist
min_to_borrow > 0
max_to_borrow >= min_to_borrow
mcr >= mccr
max_duration >= min_duration
expiration > head_block_time
min_duration <= chain_parameters.max_duration
mcr >= chain_parameters.min_mcr
mccr >= chain_parameters.min_mccr
min_interest_rate <= chain_parameters.max_interest_rate
min_call_duration <= chain_parameters.max_call_duration
borrower must have at least max_to_borrow * mcr of asset_to_borrow in his balance
asset_to_borrow must be authorized for margin lending against tradable_asset
asset_to_borrow and the tradable_asset must not be transfer restricted
borrower must be whitelisted or must not be blacklisted for the asset_to_lend and the tradable_asset due to transfer restrictions

Evaluation:

Deduct max_to_borrow * mcr of asset_to_borrow from borrower balance
Create new borrowing_offer_object and populate object fields from operation fields
Operation result is new object id
Trigger automatic matching

`lending_cancel_operation` (new)

This operation can be used to cancel lending and borrowing offers.

Fields:

account_id_type owner - Creator of the operation (fee paying account), must equal owner of the offer
offer_id_type offer - Either a lending_offer_id_type or a borrowing_offer_id_type
extension_type ext - reserved for future extensions

Validation checks:

owner must be a valid account ID, must exist, must authorize the operation, must pay fee
offer must be a valid lending offer ID or borrowing offer ID and must exist
offer.owner == owner

Evaluation:

If offer is a lending offer:
- Add offer.max_amount of offer.loan_asset to owner balance
If offer is a borrowing offer:
- Add offer.available_collateral of offer.loan_asset to owner balance
Delete offer from database
Operation result is amount paid back to owner

`lending_accepted_operation` (new, virtual)

Fields:

account_id_type offerer - must equal owner of the offer
offer_id_type offer - id of the accepted offer, lending_offer_id_type or a borrowing_offer_id_type
loan_portfolio_id_type loan - id of the resulting loan portfolio

`loan_interest_operation` (new, virtual)

Fields:

account_id_type lender - the lender's account id
account_id_type borrower - the borrower's account id
loan_id_type loan - ID of the loan portfolio to adjust
asset interest_amount - Amount of interest paid to loan.lender

`loan_closed_operation` (new, virtual)

Fields:

account_id_type lender - the lender's account id
account_id_type borrower - the borrower's account id
loan_id_type loan - ID of the loan portfolio to adjust
asset principal_paid_back - Amount of principal paid back to lender
asset trade_confiscated - Amount of trade asset paid to lender
asset principal_turned_out - Amount of principal paid out to borrower
asset trade_turned_out - Amount of trade asset paid out to borrower

`loan_close_operation` (new)

Fields:

account_id_type borrower - the borrower's account id
loan_id_type loan - ID of the loan portfolio to adjust

Validation checks:

borrower must be a valid account ID, must exist, must authorize the operation, must pay fee
loan must be a valid loan portfolio ID and must exist
loan.owner == borrower
head_block_time >= loan.earliest_end
loan.principal_in_orders == 0 && loan.trade_in_orders == 0
loan.principal_balance >= loan.principal_borrowed + loan.daily_interest

Evaluation:

Trigger interest payment (see below)
Pay loan.principal_borrowed of loan.principal_asset to loan.lender
Pay loan.principal_balance - loan.principal_borrowed of loan.principal_asset to loan.borrower
Pay loan.trade_balance of loan.trade_asset to loan.borrower
Create a virtual loan_closed_operation
Delete loan

`loan_update_operation` (new)

Fields:

account_id_type owner - Creator of the operation (fee paying account), must equal owner of the loan portfolio
loan_id_type loan - ID of the loan portfolio to adjust
asset principal_delta - Amount of principal asset to add / withdraw
asset trade_delta - Amount of trade asset to add / withdraw
extension_type ext - reserved for future extensions

Validation checks:

owner must be a valid account ID, must exist, must authorize the operation, must pay fee
loan must be a valid loan portfolio ID and must exist
loan.owner == owner
principal_delta != 0 || trade_delta != 0
principal_delta >= 0
!confiscation_time.valid || trade_delta >= 0
If principal_delta > 0 or trade_delta > 0, owner must have sufficient balance
If trade_delta < 0
- loan.trade_balance >= -trade_delta
- Let mcv = loan.principal_borrowed + loan.minimum_collateral
- if is_reference_price_valid
  - If loan.principal_balance + loan.principal_in_orders < mcv
    - Let min_trade = reference_price * (mcv - loan.principal_balance - loan.principal_in_orders)
    - loan.trade_balance + loan.trade_in_orders + trade_delta >= min_trade
- Otherwise (!is_reference_price_valid)
  - mcv <= loan.principal_balance

Evaluation:

If principal_delta > 0:
- Deduct principal_delta from loan.owner's balance
- Add principal_delta.amount to loan.principal_balance
If trade_delta != 0:
- Deduct trade_delta from loan.owner's balance
- Add trade_delta.amount to loan.trade_balance
- Re-appraise portfolio and throw if margin call is triggered

Loan trading

Note: trading from a loan portfolio happens on the same markets as trading from an account. Trading is therefore not implemented separately, but through modifications to the existing trade mechanisms.

Fields:

The existing limit_order_create_operation and fill_order_operation receive one optional extension field:

loan_id_type loan - ID of the loan portfolio from which the trade is executed

The loan field is not allowed before the hardfork time, neither directly nor in proposals.

Validation checks:

If the loan extension is present in a limit_order_create_operation, the following checks replace the existing checks against the seller's account balance:

loan is valid and refers to an existing loan_portfolio_object
seller == loan.owner
!loan.confiscation_time.valid (no trades after margin call)
amount_to_sell.asset_id == loan.principal_asset || amount_to_sell.asset_id == loan.trade_asset
If amount_to_sell.asset_id == loan.principal_asset:
- loan.principal_balance - amount_to_sell.amount >= loan.minimum_collateral
- min_to_receive.asset_id == loan.trade_asset
- if !is_reference_price_valid
  - 0 < amount_to_sell.amount <= loan.principal_balance - mcv
If amount_to_sell.asset_id == loan.trade_asset:
- loan.trade_balance >= amount_to_sell.amount
- min_to_receive.asset_id == loan.principal_asset
- if !is_reference_price_valid
  - 0 < min_to_receive.amount <= loan.principal_balance - mcv

Evaluation:

The loan extension will be recorded in the new limit_order_object
If loan field is present,
- amount_to_sell will be deducted from the loan balance and recorded in loan's ..._in_order fields, not the account's
- fill_order will be modified to pay trade proceeds into loan portfolio and adjust loan's ..._in_order fields
- fill_order must re-appraise the portfolio
- cancel_order will be modified to return funds into loan portfolio and adjust loan's ..._in_order fields

Database API Calls

The following methods will be added to the database_api:

vector<lending_offer_object> get_lending_offers_by_asset <loan-asset> <trade-asset> <optional limit> <optional start>
vector<borrowing_offer_object> get_borrowing_offers_by_asset <loan-asset> <trade-asset> <optional limit> <optional start>
vector<lending_offer_object> get_lending_offers_by_account <account> <optional limit> <optional start>
vector<borrowing_offer_object> get_borrowing_offers_by_account <account> <optional limit> <optional start>
vector<loan_portfolio_object> get_loans_by_lender <account> <optional limit> <optional start>
vector<loan_portfolio_object> get_loans_by_borrower <account> <optional limit> <optional start>
vector<limit_order_object> get_orders_by_loan <loan-id> <optional limit> <optional start>

All result lists are ordered by ascending object id. Server-side limits are configurable.

Processing Logic Changes

Automatic Matching of Offers

Similar to database::apply_order(). Triggered when a new offer is evaluated.

Let taker_offer = new_offer
If new_offer is loan offer
- Let prioritization_policy = Favor Borrowers policy
- counter_offers = existing borrow offers
Otherwise (new offer is borrow offer)
- Let prioritization_policy = Favor Lenders policy
- counter_offers = existing loan offers
while true
- Let compatible_offers = find_compatible_offers(new_offer, counter_offers, prioritization_policy)
- if no compatible_offers
  - return false
- otherwise
  - Let maker_offer = highest-prioritized counter offer
  - [loan_object_id, taker_offer_filled] = create_loan(taker_offer, maker_offer, prioritization_policy)
  - If taker_offer_filled
    - return true

Margin calls

Set loan.confiscation_time = head_block_time + loan.call_duration
Cancel open market orders of this loan, as usual
If loan.principal_balance >= loan.principal_borrowed + loan.daily_interest: close loan as described above
Otherwise:
- Let gap = loan.principal_borrowed + loan.daily_interest - loan.principal_balance
- Create and execute a virtual limit_order_create for loan with amount_to_sell = loan.trade_balance and min_to_receive = gap
- If the order has been (partially) filled, restart margin call process (meaning gap is smaller or perhaps closed)

Notes:

The new limit order will "walk the book" until the available trade balance has been spent (or there are no more orders in the book with a matching price). It is possible that this process buys up much more principal than required to close the gap, possibly at a price far away from the usual market price. Thus, the borrower should avoid being margin called.
Due to rounding, edge cases may exist where the limit order has been partially filled and then cancelled without buying sufficient principal to close the gap. It may then be impossible to create a new order for the remaining gap, because that would be considered "dust". The consequence would be that the loan stays in margin call state until it is confiscated. For practical purposes this shouldn't make much of a difference because rounding issues are a few "satoshis" only.

Interest payments

Similar to database::clear_expired_proposals, in each block

Check all loan_portfolio_object.interest_due_at against head_block_time
If passed and if !loan_portfolio_object.confiscation_time.valid,
- If loan.daily_interest > loan.principal_balance: initiate margin_call
- Otherwise,
  - Deduct loan.daily_interest from loan.principal_balance
  - Add loan.daily_interest of loan.principal_asset to loan.lender's balance
  - Add loan.daily_interest to loan.cumulative_interest
  - Create a virtual loan_interest_operation
  - Add 86400 to loan.interest_due_at
  - Re-appraise portfolio

Expire open offers

Similar to database::clear_expired_orders, in each block

Check lending_offer_object.expiration and borrowing_offer_object.expiration against head_block_time
If expired, create a virtual lending_cancel_operation and execute as describe above

Expire open loans

Similar to database::clear_expired_orders, in each block

Check loan_portfolio_object.latest_end against head_block_time
If expired:
- Cancel open orders of this portfolio with virtual limit_order_cancel operations
- If loan.principal_balance < loan.principal_borrowed + loan.daily_interest: initiate margin call
- Otherwise: close loan as described above

Handle margin calls

In each block, for each loan that is in margin call state,

If loan.principal_balance >= loan.principal_borrowed + loan.daily_interest
- Cancel open order, if any
- Close loan as described above

Confiscate expired margin calls

Similar to database::clear_expired_orders, in each block

Check valid loan_portfolio_object.confiscation_time against head_block_time
If expired,
- Cancel open order, if any
- Add loan.principal_balance of loan.principal_asset to loan.lender's balance
- Add loan.trade_balance of loan.trade_asset to loan.lender's balance
- Create appropriate virtual loan_closed_operation
- Delete loan

Vote tallying

vote_tally_helper computes voting_stake per account as before, plus core in
- lending_offers
- borrowing_offers
- If core is the trade_asset in a loan_portfolio
  - Let lender_stake = 0
  - Let borrower_stake = trade_balance
- If core is the principal_asset in a loan_portfolio
  - Let lender_stake = min(principal_balance, principal_borrowed)
  - Let borrower_stake = principal_balance - lender_stake

Calculate reference price

If tradable asset is a bitAsset
- If tradable asset is in global settlement
  - is_reference_price_valid = true and reference_price = global_settlement_price
Otherwise
- if tradeable asset-borrowed asset market has any offers for the tradable asset
  - is_reference_price_valid = true and reference_price = highest_offer
- else if tradeable asset-borrowed asset market has ever had any matched exchange
  - is_reference_price_valid = true and reference_price = last_exchange_price
- otherwise
  - is_reference_price_valid = false

Portfolio appraisal

Let principal = loan.principal_balance + loan.principal_in_orders
If principal >= loan.mccv, clear loan.call_price
Otherwise
- if (loan.trade_balance + loan.trade_in_orders) > 0
  - set loan.call_price = (loan.mccv - principal) / (loan.trade_balance + loan.trade_in_orders)
  - if reference_price is valid and reference_price < loan.call_price: trigger margin call
- else
  - Trigger margin call

Changes to `cli_wallet`

The following commands will be added to cli_wallet:

list_lending_offers <account>
list_borrowing_offers <account>
get_lending_offers <loan-asset> <trade-asset>
get_borrowing_offers <loan-asset> <trade-asset>
lending_offer_create with operation parameters
borrowing_offer_create with operation parameters
lending_offer_cancel <id>
lending_offer_accept <id> <amount> <duration>
loan_update <id> <delta-principal> <delta-trade>
get_loan_valuation <id>
get_loan_call_price <id>
loan_close <id>
The sell_asset command will receive an additional optional parameter, the loan portfolio id

Discussion

Risks

Financial: Price of a market pair on the DEX

A stagnant, nascent, or illiquid order book on the DEX for a particular market pair might not reflect the valuation of the collateral according to external market pairs. That will affect the appraisal value of the loan collateral which then affects margin calculations. Margin calculations affect both future loan offers on the books and matched loans.

Potential lenders and borrowers should carefully review any internal market pair and compare it with the external market pair to determine (a) whether internal market reflects a reasonable exchange ratio/price, and (b) whether the internal market could be easily manipulated to either overvalue or undervalue collateral.

Financial: Margin Calls at Market Price

If a margin call is initiated and if a liquidation plan requires selling the tradable asset to repay the lender in lent asset type, borrowers should be aware that it will be sold as an effective market order. The resulting sale on the DEX order book may return much less than if the offer were made on an external market.

Financial: Repayment of a Margin Called Loan

Loans that are margin called might require a liquidation plan that involves placing an limit order to buy enough of the lent asset to repay the loan.

If the market order remains unfilled on the DEX order book in excess of maximum margin call duration, the borrower's entire loan portfolio shall be confiscated thereby leaving the borrower with nothing after the loan closure.

Financial: Avalanche effect of Margin Calls

A margin call on a loan portfolio will immediately try to buy large amounts of the borrowed asset from the market. This can lead to a sudden spike in the trade price. This in turn can affect the reference price, which could lead to additional margin calls in other portfolios.

Powers of Asset Issuers

Asset issuers have extensive control over how their asset is used on BitShares including the ability to whitelist the trading of an asset against other assets), to restrict the transfers of an asset, and to seize any issued asset from an account if the asset is defined with the appropriate flags. These interaction of these powers with lending for margin trading are described.

Market Restrictions

The power to whitelist and blacklist trading pairs for an issuer's asset, which has the appropriate flags enabled, shall be unaffected by this proposal. This lending proposal makes use of the existing trading mechanisms therefore all rules shall continue to apply.

For example, if an issuer's asset is blacklisted from trading against any other asset, no trading of the Asset will be possible either from an account's regular set of balances or from their loan portfolio.

Alternatively, an issuer's asset (X) might initially be whitelisted to trade against any other asset, which permits the creation of a loan portfolio to trade against another asset (Y). Trading by the borrower ensues and the borrower obtains some quantity of Asset Y in their portfolio. If the asset issuer then blacklists trading between X and Y, the borrower shall no longer be able to trade the asset from anywhere including their loan portfolio. Another effect will be that margin calls shall no longer be able to be liquidated by means of buying back the borrowed asset on the DEX. Consequently if a margin call is initiated after a blacklisting and the loan portfolio's balance of the borrowed asset was insufficient to repay the lender, the margin call shall eventually result in an unconventional loan closure.

Transfer Restrictions

The existing power to restrict the direct transfer of an issuer's asset, which has the appropriate flags enabled, from one account to another shall be unaffected by this proposal.

Interest payment involves the transfer of the [borrowed asset-type](#borrow-asset] from the borrower to the lender. Therefore the creation of loan and borrow offers, and the matching of offers shall only be permitted if (a) if the borrow asset is not transfer restricted, and (b) if both the lender and the borrower are whitelisted or are not blacklisted for the borrow asset.

An unconventional loan closure transfers all balances of the borrow asset type and the tradable asset type to the lender. Therefore the creation of loan and borrow offers, and the matching of offers shall only be permitted if (a) if the tradable asset is not transfer restricted, and (b) both the lender and the borrower are whitelisted or are not blacklisted for the tradable asset.

Asset Seizure

The power to seize an issuer's asset, which has the appropriate flags enabled, shall remain possible if the asset is held in the account's regular set of balances. This power does not currently extend to assets held in open orders. Similarly, it shall not be possible to seize an asset that is held inside of a loan offer, borrow offer, or loan portfolio. An asset issuer may instead first impose a transfer restriction on the account, and then wait for the loan to be closed with appropriate balances being distributed to the regular balances of the borrower and lender at which time the conventional asset seizure may be invoked.

Summary for Shareholders

This BSIP defines a protocol upgrade to support peer-to-peer lending, borrowing and margin trading markets on the BitShares DEX. The motivation behind this BSIP is to increase the user demand for smartcoins on BitShares by offering on-chain peer-to-peer lending and borrowing to augment the existing trading. The multiple stage process between borrowers and lenders is supported with software specifications and a discussion of risks to lenders, borrowers, and asset holders, and asset issuers.

Copyright

This document is placed in the public domain.

bitshares / bsips

Lending for Margin Trading (Variant B) #184

Abstract

Motivation

Rationale

Specifications

Stage 1a: Authorized Leveraged Trading Pairs

Stage 1b: Reference Price

Determination of Reference Price

Prohibited Activity under Invalid Reference Price

Stage 2: Offers to Lend and Borrow

Stage 3: Loan Offer Matching

Compatibility Filtering

Offer Matching

Loan Creation

Effective Dates of the Loan

Filling of Loan Offer

Effects of Partial Fills on a Loan Offer

Effects of Partial Fills on a Borrow Offer

Re-evaluation of a New Offer

Stage 4a: Margin Trading within Loan Portfolio

Trading Limits

Multiple Loan Portfolios

Stage 4b: Daily Interest Payment

Stage 4c: Appraisal of Loan Portfolio

Debt Owed

Portfolio Appraisal

Portfolio Components

Collateral Ratio

Derived Valuations

Triggering of Appraisal

Stage 4d: Loan Portfolio Updates

Status of Loan Portfolio

Deposits

Withdrawals

Stage 5a: Initiation of Loan Closure by Borrower

Stage 5b: Expiration of Loan

Stage 5c: Initiation of Loan Closure because of Insufficient Funds

Stage 5d: Initiation of Loan Closure by Margin Call

Stage 6: Margin Call

Restriction of Loan Portfolio

Liquidation Plan

Portfolio Confiscation

Monitoring of Liquidation Plan

Stage 7a: Conventional Loan Closure

Stage 7b: Unconventional Loan Closure

Definable Loan Constraints

Fees

Voting Stake

Software Specifications

Database Objects

lending_offer_object (new)

borrowing_offer_object (new)

loan_portfolio_object (new)

Chain parameters

Miscellaneous

Operations

lending_offer_create_operation (new)

borrowing_offer_create_operation (new)

lending_cancel_operation (new)

lending_accepted_operation (new, virtual)

loan_interest_operation (new, virtual)

loan_closed_operation (new, virtual)

loan_close_operation (new)

loan_update_operation (new)

Loan trading

Database API Calls

Processing Logic Changes

Automatic Matching of Offers

Margin calls

Interest payments

Expire open offers

Expire open loans

Handle margin calls

Confiscate expired margin calls

Vote tallying

Calculate reference price

Portfolio appraisal

Changes to cli_wallet

Discussion

`lending_offer_object` (new)

`borrowing_offer_object` (new)

`loan_portfolio_object` (new)

`lending_offer_create_operation` (new)

`borrowing_offer_create_operation` (new)

`lending_cancel_operation` (new)

`lending_accepted_operation` (new, virtual)

`loan_interest_operation` (new, virtual)

`loan_closed_operation` (new, virtual)

`loan_close_operation` (new)

`loan_update_operation` (new)

Changes to `cli_wallet`