Lending Protocol

docs/_snippets/common-links.md

@@ -1,11 +1,13 @@
 [ACCOUNT_ZERO]: https://xrpl.org/docs/concepts/accounts/addresses#special-addresses
+[AccountID]: https://xrpl.org/docs/references/protocol/binary-format/#accountid-fields
 [AccountDelete]: https://xrpl.org/docs/references/protocol/transactions/types/accountdelete
 [Address]: https://xrpl.org/docs/references/protocol/data-types/basic-data-types#addresses
 [amendment]: https://xrpl.org/docs/concepts/networks-and-servers/amendments
 [common fields]: https://xrpl.org/docs/references/protocol/transactions/common-fields/
 [common ledger entry fields]: https://xrpl.org/docs/references/protocol/ledger-data/common-fields/
 [credentials]: https://xrpl.org/docs/concepts/decentralized-storage/credentials
 [EscrowFinish]: https://xrpl.org/docs/references/protocol/transactions/types/escrowfinish
+[`flags` field]: https://xrpl.org/docs/references/protocol/transactions/common-fields#flags-field
 [Hash]: https://xrpl.org/docs/references/protocol/data-types/basic-data-types#hashes
 [Internal Type]: https://xrpl.org/docs/references/protocol/binary-format/
 [ledger entry ID]: https://xrpl.org/docs/references/protocol/ledger-data/common-fields/
@@ -14,19 +16,18 @@
 [ledger index]: https://xrpl.org/docs/references/protocol/data-types/basic-data-types/#ledger-index
 [PaymentChannelClaim]: https://xrpl.org/docs/references/protocol/transactions/types/paymentchannelclaim
 [Payment]: https://xrpl.org/docs/references/protocol/transactions/types/payment
+[PermissionedDomain entry]: /docs/xls-80d-permissioned-domains/permissioneddomain.md
+[PermissionedDomainSet transaction]: /docs/xls-80d-permissioned-domains/permissioneddomainset.md
+[PermissionedDomainDelete transaction]: /docs/xls-80d-permissioned-domains/permissioneddomaindelete.md
 [reserve requirement]: https://xrpl.org/docs/concepts/accounts/reserves
 [seconds since the Ripple Epoch]: https://xrpl.org/docs/references/protocol/data-types/basic-data-types#specifying-time
 [SHA-512Half]: https://xrpl.org/docs/references/protocol/data-types/basic-data-types#hashes
 [Specifying Ledgers]: https://xrpl.org/docs/references/protocol/data-types/basic-data-types/#specifying-ledgers
 [standard format]: https://xrpl.org/docs/references/http-websocket-apis/api-conventions/response-formatting/
 [transaction result codes]: https://xrpl.org/docs/references/protocol/transactions/transaction-results
 [universal error types]: https://xrpl.org/docs/references/http-websocket-apis/api-conventions/error-formatting#universal-errors
-
-[PermissionedDomain entry]: /docs/xls-80d-permissioned-domains/permissioneddomain.md
-[PermissionedDomainSet transaction]: /docs/xls-80d-permissioned-domains/permissioneddomainset.md
-[PermissionedDomainDelete transaction]: /docs/xls-80d-permissioned-domains/permissioneddomaindelete.md
 <!-- TODO: replace with link to roadmap page when that's ready -->
-[PermissionedDomains amendment]: /docs/xls-80d-permissioned-domains/index.page.tsx
-[Single Asset Vault amendment]: https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0065d-single-asset-vault
-
+[Lending Protocol amendment]: https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0066d-lending-protocol
 [PermissionedDEX amendment]: /docs/xls-81d-permissioned-dexes/index.page.tsx
+[PermissionedDomains amendment]: /docs/xls-80d-permissioned-domains/index.page.tsx
+[Single Asset Vault amendment]: https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0065-single-asset-vault

docs/xls-66d-lending-protocol/concepts/lending-protocol.md

@@ -0,0 +1,164 @@
+---
+seo:
+    description: The XRPL Lending Protocol enables on-chain, uncollateralized fixed-term loans.
+labels:
+  - Decentralized Finance
+  - Lending Protocol
+---
+# Lending Protocol
+
+The Lending Protocol is an XRP Ledger DeFi primitive that enables on-chain, fixed-term, uncollateralized loans using pooled funds from a [Single Asset Vault](https://opensource.ripple.com/docs/xls-65d-single-asset-vault). The implementation relies on off-chain underwriting and risk management to assess the creditworthiness of borrowers, but offers peer-to-peer loans without intermediaries like banks or financial institutions. First-loss capital protection is used to help offset losses from loan defaults.
+
+The current implementation of the lending protocol doesn't include automated on-chain collateral and liquidation management, instead focusing on on-chain credit origination.
+
+To ensure compliance needs are met, asset issuers can [claw back](https://xrpl.org/docs/references/protocol/transactions/types/clawback) funds from the vault associated with the lending protocol. Issuers can also [freeze](https://xrpl.org/docs/concepts/tokens/fungible-tokens/freezes) individual accounts or issue a global freeze.
+
+## Protocol Flow
+
+There are three parties involved in the process of creating a loan.
+
+- **Loan Brokers**: Create asset vaults and manage associated loans.
+- **Depositors**: Add assets to vaults.
+- **Borrowers**: Receive loans, making repayments as defined by their loan terms.
+
+[{% inline-svg file="./lending-protocol.svg" /%}](./lending-protocol.svg "Diagram: The lifecycle of a loan.")
+
+The lifecycle of a loan is as follows:
+
+1. A loan broker creates a vault.
+2. Depositors add assets to the vault.
+3. (Optional) The loan broker deposits first-loss capital.
+4. A loan broker and borrower create a loan, defining the terms of the loan, and the requested principal (excluding fees) is transferred to the borrower.
+5. If payments are missed, the loan enters a grace period. Once the grace period expires, the loan broker has the option to default the loan.
+6. The loan is deleted when matured or defaulted.
+7. (Optional) The loan broker can withdraw first-loss capital.
+8. After all loans are paid, the loan broker can delete the `LoanBroker` ledger entry, and then the corresponding `Vault` ledger entry.
+
+
+## Accounting
+
+### Risk Management
+
+#### First-Loss Capital
+
+First-Loss Capital is an optional mechanism to mitigate the risks associated with lending. To protect investors' assets, a loan broker can deposit assets as first-loss capital, which acts as a buffer and are liquidated in the event of loan defaults. The liquidated capital is placed into the vault to cover some of the losses from missed payments. 
+
+Three parameters control the First-Loss Capital:
+
+- `CoverAvailable`: The total amount of cover deposited by the lending protocol owner.
+- `CoverRateMinimum`: The percentage of debt that must be covered by `CoverAvailable`.
+- `CoverRateLiquiditation`: The maximum percentage of the minimum required cover _(DebtTotal x CoverRateMinimum)_ that will be liquidated to cover a loan default.
+
+Whenever the available cover falls below the minimum required:
+
+- The lender can't issue new loans.
+- The lender can't receive lender fees. All fees are added to the First-Loss Capital to cover the deficit.
+
+Below is an example of how first-loss capital is liquidated to cover a loan default:
+
+```
+** Initial States **
+
+-- Vault --
+AssetsTotal             = 100,090 Tokens
+AssetsAvailable         = 99,000 Tokens
+SharesTotal             = 100,000 Tokens
+
+-- Lending Protocol --
+DebtTotal               = 1,090 Tokens
+CoverRateMinimum        = 0.1 (10%)
+CoverRateLiquidation    = 0.1 (10%)
+CoverAvailable          = 1,000 Tokens
+
+-- Loan --
+AssetsAvailable       = 500 Tokens
+PrincipleOutstanding  = 1,000 Tokens
+InterestOutstanding   = 90 Tokens
+
+
+# First-Loss Capital liquidation maths
+
+DefaultAmount = PrincipleOutstanding + InterestOutstanding - AssetsAvailable
+              = 1,000 + 90 - 500
+              = 590
+
+# The amount of the default that the first-loss capital scheme will cover
+DefaultCovered      = min((DebtTotal x CoverRateMinimum) x CoverRateLiquidation, DefaultAmount)
+                    = min((1,090 * 0.1) * 0.1, 1,090) = min(10.9, 590)
+                    = 10.9 Tokens
+
+Loss                = DefaultAmount - DefaultCovered
+                    = 590 - 10.9
+                    = 579.1 Tokens
+
+FundsReturned       = DefaultCovered + AssetsAvailable
+                    = 10.9 + 500
+                    = 510.9
+
+# Note: Loss + FundsReturned MUST be equal to PrincipleOutstanding + InterestOutstanding
+
+** State Changes **
+
+-- Vault --
+AssetsTotal     = AssetsTotal - Loss
+                = 100,090 - 579.1
+                = 99,510.9 Tokens
+
+AssetsAvailable = AssetsAvailable + FundsReturned
+                = 99,000 + 510.9
+                = 99,510.9 Tokens
+
+SharesTotal = (UNCHANGED)
+
+-- Lending Protocol --
+DebtTotal       = DebtTotal - PrincipleOutstanding + InterestOutstanding
+                = 1,090 - (1,000 + 90)
+                = 0 Tokens
+
+CoverAvailable  = CoverAvailable - DefaultCovered
+                = 1,000 - 10.9
+                = 989.1 Tokens
+```
+
+#### Impairment
+
+If the loan broker discovers a borrower can't make an upcoming payment, impairment allows the loan broker to register a "paper loss" with the vault. The impairment mechanism moves the due date of the next payment to the time the loan is impaired, allowing the loan to default more quickly. However, if the borrower makes a payment before that date, the impairment status is automatically cleared.
+
+
+### Compliance
+
+#### Clawback
+
+Issuers (IOU or MPT, not XRP) can claw back funds from First-Loss Capital. To ensure there is always a minimum amount of capital available to protect depositors, issuers can't claw back the entire available amount. Instead, they can claw back up to a minimum amount of First-Loss Capital that the loan broker must maintain for the lending protocol; the minimum amount is calculated as `LoanBroker.DebtTotal * LoanBroker.CoverRateMinimum`.
+
+#### Freeze
+
+Freezing is a mechanism by which an asset issuer (IOU or MPT, not XRP) prevents an account from sending their issued asset. _Deep freeze_ takes this a step further by preventing an account from sending _and_ receiving issued assets. Issuers can also enact a _global freeze_, which prevents everyone from sending or receiving their issued asset.
+
+{% admonition type="info" name="Note" %}
+In all freeze scenarios, assets can be sent back to the issuer.
+{% /admonition %}
+
+If a borrower has their account frozen or deep frozen, they can't make loan payments. This doesn't absolve a borrower of their repayment obligations, and they will eventually default on their loan.
+
+Freezing a borrower's account won't affect a loan broker's functions, but it will prevent them from receiving any lending protocol fees. However, issuers can freeze a loan broker's _pseudo-account_ and prevent the loan broker from creating new loans; existing loans won't be affected. A deep freeze on a loan broker's _pseudo-account_ also prevents loans from being repaid.
+
+
+### Interest Rates
+
+There are three interest rates associated with a loan:
+
+- **Interest Rate**: The regular interest rate based on the principal amount. It is the cost of borrowing funds.
+- **Late Interest Rate**: A higher interest rate charged for a late payment.
+- **Full Payment Rate**: An interest rate charged for repaying the total loan early.
+
+
+### Fees
+
+The lending protocol charges a number of fees that the loan broker can configure. The protocol won't charge these fees if the loan broker hasn't deposited enough first-loss capital.
+
+- **Management Fee**: This is a percentage of interest charged by the loan broker. Vault depositors pay this fee.
+- **Loan Origination Fee**: A fee paid to the loan broker, taken from the principal amount loaned out.
+- **Loan Service Fee**: A fee charged on top of each loan payment.
+- **Late Payment Fee**: A fee paid on top of a late payment.
+- **Early Payment Fee**: A fee paid on top of an early payment.