0066 XLS - 66d: XRP Ledger-native Lending Protocol

[Tapanito]

    
Title:        Lending Protocol
Revision:     1 (2024-09-30)

Authors:    
  Vytautas Vito Tumas
  Aanchal Malhotra

Affiliation:
  Ripple

Lending Protocol

Abstract

Decentralized Finance (DeFi) lending represents a transformative force within the blockchain ecosystem. It revolutionizes traditional financial services by offering a peer-to-peer alternative without intermediaries like banks or financial institutions. At its core, DeFi lending platforms empower users to borrow and lend digital assets directly, fostering financial inclusion, transparency, and efficiency.

This proposal introduces fundamental primitives for an XRP Ledger-native Lending Protocol. The protocol offers straightforward on-chain uncollateralized fixed-term loans, utilizing pooled funds with pre-set terms for interest-accruing loans. The design relies on off-chain underwriting and risk management to assess the creditworthiness of the borrowers. However, the First-Loss Capital protection scheme absorbs some losses in case of a Loan Default.

This version intentionally skips the complex mechanisms of automated on-chain collateral and liquidation management. Instead, it focuses on the primitives and the essential components for on-chain credit origination. Therefore, the primary design principle is flexibility and reusability to enable the introduction of additional complex features in the future.

1. Introduction

1.1 Overview

The Lending Protocol uses the Vault on-chain object to provision assets from one or more depositors. A Loan Broker is responsible for managing the Lending Protocol and the associated Vault. The Vault Owner and Loan Broker must be on the same account, but this may change in the future.

The specification introduces two new ledger entries: LoanBroker and Loan. The LoanBroker object captures the Lending Protocol-specific details, such as fees and First-Loss Capital cover. Furthermore, it tracks the funds taken from the Vault. The Loan object captures the Loan agreement between the Loan Broker and the Borrower.

The specification introduces the following transactions:

• LoanBrokerSet: A transaction to create a new LoanBroker object.
• LoanBrokerDelete: A transaction to delete an existing LoanBroker object.
• LoanBrokerCollateralDeposit: A transaction to deposit First-Loss Capital.
• LoanBrokerCollateralWithdraw: A transaction to withdraw First-Loss Capital.
• LoanSet: A transaction to create a new Loan object.
• LoanDelete: A transaction to delete an existing Loan object.
• LoanManage: A transaction to manage an existing Loan.
• LoanDraw: A transaction to drawdown Loan funds.
• LoanPay: A transaction to make a Loan payment.

The flow of the lending protocol is as follows:

1. The Loan Broker creates a Vault ledger entry.
2. The Loan Broker creates a LoanBroker ledger entry with a LoanBrokerSet transaction.
3. The Depositors deposit assets into the Vault.
4. Optionally, the Loan Broker deposits First-Loss Capital into the LoanBroker with the LoanBrokerCollateralDeposit transaction.
5. The Loan Broker and Borrower create a Loan object with a LoanSet transaction.
6. The Borrower can draw funds with the LoanDraw transaction and make payments with the LoanPay.
7. If the Borrower fails to pay the Loan, the Loan Broker can default the Loan using the LoanManage transaction.
8. Once the Loan has matured (or defaulted), the Borrower or the Loan Broker can delete it using a LoanDelete transaction.
9. Optionally, the Loan Broker can withdraw the First-Loss Capital using the LoanBrokerCollateralWithdraw transaction.
10. When all Loan objects are deleted, the Loan Broker can delete the LoanBroker object with a LoanBrokerDelete transaction.
11. When all LoanBroker objects are deleted, the Loan Broker can delete the Vault object.

1.2 Compliance Features

1.2.1 Clawback

Clawback is a mechanism by which an asset Issuer (IOU or MPT, not XRP) claws back the funds. It can be performed on the Vault, not the Lending Protocol.

1.2.2 Freeze

Freeze is a mechanism by which an asset Issuer (IOUT or MPT, not XRP) freezes an Account, preventing that account from sending or receiving the Asset. Furthermore, an Issuer may enact a global freeze, which prevents everyone from sending or receiving the Asset. Note that in both single-account and global freezes, the Asset can be sent to the Issuer.

If the Issuer freezes a Borrower's account, the Borrower cannot make loan payments or draw down funds. A frozen account does not lift the obligation to repay a Loan.
If a Loan Broker's account is frozen, the Broker will not receive any Loan fees. They will be able to create new loans, and existing loans will not be affected. However, the Loan Broker cannot deposit or withdraw First-Loss Capital.

Finally, the exact behaviour has yet to be defined in a global freeze. TBD

1.3 Risk Management

Risk management involves mechanisms that mitigate the risks associated with lending. To protect investors' assets, we have introduced an optional first-loss capital protection scheme. This scheme requires the Loan Broker to deposit a fund that can be partially liquidated to cover losses in the event of a loan default. The amount of first-loss capital required is a percentage of the total debt owed to the Vault. In case of a default, a portion of the first-loss capital will be liquidated based on the minimum required cover. The liquidated capital is placed back into the Vault to cover some of the loss.

1.4 Interest Rates

There are three basic 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.

1.5 Fees

The lending protocol charges a number of fees that the Loan Broker can configure. The protocol will not charge the fees if the Loan Broker has not deposited enough First-Loss Capital.

• Management Fee: This is a percentage of interest charged by the Loan Broker. Intuitively, the Vault depositors pay this fee.
• Loan Origination Fee: A nominal fee paid to the Loan Broker taken from the principal lent.
• Loan Service Fee: A nominal fee paid on top of each loan payment.
• Late Payment Fee: A nominal fee paid on top of a late payment.
• Early Payment Fee: A nominal fee paid on top of an early payment.

1.6 Terminology

1.6.1 Terms

• Fixed-Term Loan: A type of Loan with a known end date and a constant periodic payment schedule.
• Principal: The original sum of money borrowed that must be repaid, excluding interest or other fees.
• Interest: The cost of borrowing the Asset, calculated as a percentage of the loan principal, which the Borrower pays to the Lender over time.
• Drawdown: The process where a borrower accesses part or all of the loan funds after the Loan has been created.
• Default: The failure by the Borrower to meet the obligations of a loan, such as missing payments.
• First-Loss Capital: The portion of capital that absorbs initial losses in case of a Default, protecting the Vault from loss.
• Term: The period over which a Borrower must repay the Loan.
• Amortization: The gradual repayment of a loan through scheduled payments that cover both interest and principal over time.
• Repayment Schedule: A detailed plan that outlines when and how much a borrower must pay to repay the Loan fLoan.
• Grace Period: A set period after the Loan's due date after which the Loan Broker can default the Loan
• Origination Fee: A nominal one-time fee the loan broker charges for processing a new loan application.
• Service Fee: A recurring nominal charge the Borrower pays during Loan payment.
• Management Fee: A percentage fee charged by the Borrower on the loan interest before returning the interest to the Vault.
• Late Payment Fee: A penalty charged to the Borrower for failing to make a payment on or before its due date.
• Interest Rate: The percentage charged by the loan broker on the loan principal, representing the cost of borrowing.
• Late Interest Rate: A higher interest rate applied to overdue loan payments as a penalty for late repayment.
• Closing Interest Rate: The final interest rate charged when the Loan is closed or fully repaid.

1.6.2 Actors

• LoanBroker: The entity issuing the Loan.
• Borrower: The account that is borrowing funds.

1.7 System Diagram

+-----------------+                          +-----------------+                       +-----------------+
|    Depositor    |                          |    LoanBroker   |                       |     Borrower    |
|   AccountRoot   |                          |   AccountRoot   |                       |   AccountRoot   |
|-----------------|                          |-----------------|                       |-----------------|
| Owner Directory |                          | Owner Directory |                       | Owner Directory |
+-----------------+                          +-----------------+                       +-----------------+
      ^         |                                     |                                         |
      |       Reserve                  ____________Reserve____________                       Reserve
   Account      |                     |                               |                         |
      |         V                     V                               V                         V
+-----------------+          +-----------------+          +-----------------+          +-----------------+
|                 |          |                 |1        N|                 |1        N|                 |
|     MPToken     |          |      Vault      |--------->|   LoanBroker    |--------->|       Loan      |
|                 |          |                 |          |-----------------|          |                 |
+-----------------+          +-----------------+          | Owner Directory |          +-----------------+
         |                            ^                  +-----------------+                    ^
      Issuance                        | ___________       ____________^  |_________Link_________|
         |                            |            Account            |
         V                            ^               |               ^
+-----------------+                   |      +-----------------+      |
|      Share      |                   |      |  Pseudo-Account |      |
| MPTokenIssuance |<------Issuer------| -----|   AccountRoot   |      |
|                 |                   |_Link_|-----------------|_Link_|
+-----------------+                          | Owner Directory |
                                             +-----------------+

2. Ledger Entries

2.1. LoanBroker Ledger Entry

The LoanBroker object captures attributes of the Lending Protocol.

2.1.1 Object Identifier

The key of the LoanBroker object is the result of SHA512-Half of the following values concatenated in order:

• The LoanBroker space key 0x006C (Lower-case l).
• The AccountID(https://xrpl.org/docs/references/protocol/binary-format/#accountid-fields) of the account submitting the LoanBrokerSet transaction, i.e. Lender.
• The transaction Sequence number. If the transaction used a Ticket, use the TicketSequence value.

2.1.2 Fields

The LoanBroker object has the following fields:

Field Name	Modifiable?	Required?	JSON Type	Internal Type	Default Value	Description
LedgerEntryType	N/A	✔️	string	UINT16	TODO	Ledger object type.
LedgerIndex	N/A	✔️	string	UINT16	N/A	Ledger object identifier.
Flags	Yes	✔️	string	UINT32	0	Ledger object flags.
PreviousTxnID	N/A	✔️	string	HASH256	N/A	The ID of the transaction that last modified this object.
PreviousTxnLgrSeq	N/A	✔️	number	UINT32	N/A	The sequence of the ledger containing the transaction that last modified this object.
Sequence	N/A	✔️	number	UINT32	N/A	The transaction sequence number that created the LoanBroker.
OwnerNode	N/A	✔️	number	UINT64	N/A	Identifies the page where this item is referenced in the owner's directory.
VaultID	No	✔️	string	HASH256	N/A	The ID of the Vault associated with this Lending Protocol Instance.
Owner	No	✔️	string	AccountID	N/A	The address of the account that is the vault owner.
Data	Yes		string	BLOB	None	Arbitrary metadata about the Vault. Limited to 256 bytes.
ManagementFeeRate	No		number	UINT16	0	The 1/10th basis point fee charged by the Lending Protocol. Valid values are between 0 and 10000 inclusive. A value of 1 is equivalent to 1/10 bps or 0.001%
OwnerCount	N/A	✔️	number	UINT32	0	The number of active Loans issued by the LoanBroker.
DebtTotal	N/A	✔️	number	NUMBER	0	The total asset amount the protocol owes the Vault, including interest.
DebtMaximum	Yes	✔️	number	NUMBER	0	The maximum amount the protocol can owe the Vault. The default value of 0 means there is no limit to the debt.
CoverAvailable	N/A	✔️	number	NUMBER	0	The total amount of first-loss capital deposited into the Lending Protocol.
CoverRateMinimum	No	✔️	number	UINT16	0	The 1/10th basis point of the DebtTotal that the first loss capital must cover. Valid values are between 0 and 100000 inclusive. A value of 1 is equivalent to 1/10 bps or 0.001%.
CoverRateLiquidation	No	✔️	number	UINT16	0	The 1/10th basis point of minimum required first loss capital that is liquidated to cover a Loan default. Valid values are between 0 and 100000 inclusive. A value of 1 is equivalent to 1/10 bps or 0.001%.

2.1.3 Lending Protocol _pseudo-account_

The Lending Protocol uses the _pseudo-account_ of the associated Vaultobject to hold the First-Loss Capital.

2.1.4 Ownership

The lending protocol object is stored in the ledger and tracked in an Owner Directory owned by the account submitting the LoanBrokerSet transaction. Furthermore, the object is also tracked in the OwnerDirectory of the pseudo-account.

The LoanBroker requires tracking associated Loan objects to prevent the LoanBroker object from being deleted while loans are active as well as future RPC endpoints. Therefore, the LoanBroker has an associated Owner Directory object.

The RootIndex of the DirectoryNode object is the result of SHA512-Half of the following values concatenated in order:

• The OwnerDirectory space key 0x004F
• The LoanBrokerID

2.1.5 Reserves

The LoanBroker object costs one owner reserve for the account creating it.

2.1.6 Accounting

The Lending Protocol tracks the funds owed to the associated Vault in the DebtTotal attribute. It captures the principal amount taken from the Vault and the interest due, excluding all fees. The DebtMaximum attribute controls the maximum debt a Lending Protocol may incur. Whenever the Lender issues a Loan, DebtTotal is incremented by the Loan principal and interest, excluding fees. When $DebtTotal \geq DebtMaximum$, the Lender cannot issue new loans until some of the debt is cleared. Furthermore, the Lender may not issue a loan that would cause the DebtTotal to exceed DebtMaximum.

Example

Example 1: # Issuing a Loan #

** Initial States **

-- Vault --
AssetsTotal         = 100,000 Tokens
AssetsAvailable     = 100,000 Tokens
SharesTotal         = 100,000 Shares

-- Lending Protocol --
DebtTotal           = 0
# The fee charged by the Lending Protocol against any interest.
ManagementFeeRate   = 0.1 (10%)


# The Lender issues the following Loan
-- Loan --
LoanPrincipal       = 1,000 Tokens
LoanInterestRate    = 0.1 (10%)

# SIMPLIFIED
LoanInterest        = LoanPrincipal x LoanInterestRate
                    = 100 Tokens

** State Changes **

-- Vault --
# Increase the potential value of the Vault
AssetsTotal     = AssetsTotal + ((LoanInterest - (LoanInterest x ManagementFeeRate)))
                = 100,000 + (100 - (100 x 0.1)) = 100,000 + 90
                = 100,090 Tokens

# Decrease Assets Available in the Vault
AssetsAvailable = AssetsAvailable - LoanPrincipal
                = 100,000 - 1,000
                = 99,000 Tokens

SharesTotal     = (UNCHANGED)

-- Lending Protocol --
# Increase Lending Protocol Debt
DebtTotal   = DebtTotal + LoanPrincipal + (LoanInterest - (LoanInterest x ManagementFeeRate))
            = 0 + 1,000 + (100 - (100 x 0.1)) = 1,000 + 90
            = 1,090 Tokens


---------------------------------------------------------------------------------------------------

Example 2: # Loan Payment #

** Initial States **

-- Vault --
AssetsTotal         = 100,090 Tokens
AssetsAvailable     = 99,000 Tokens
SharesTotal         = 100,000 Shares

-- Lending Protocol --
DebtTotal           = 1,090 Tokens
# The fee charged by the Lending Protocol against any interest.
ManagementFeeRate   = 0.1 (10%)

-- Loan --
LoanPrincipal       = 1,000 Tokens
LoanInterestRate    = 0.1 (10%)
# SIMPLIFIED
LoanPayments        = 2

# SIMPLIFIED
LoanInterest        = LoanPrincipal x LoanInterestRate
                    = 100 Tokens


# The Borrower makes a single payment

PaymentAmount           = 550 Tokens
PaymentPrincipalPortion = 500 Tokens
PaymentInterestPortion  = 50 Tokens


** State Changes **

-- Vault --
AssetsTotal     = (UNCHANGED)

# Increase Assets Available in the Vault
AssetsAvailable = AssetsAvailable + PaymentPrincipalPortion + (PaymentInterestPortion - (PaymentInterestPortion x ManagementFeeRate)
                = 99,000 + 500 + (50 - (50 x 0.1))
                = 99,545 Tokens

SharesTotal     = (UNCHANGED)

-- Lending Protocol --

# Decrease Lending Protocol Debt
DebtTotal   = DebtTotal - PaymentPrincipalAmount - (PaymentInterestPortion - (PaymentInterestPortion x ManagementFeeRate)
            = 1,090 - 500 - (50 - (50 x 0.1))
            = 545 Tokens

2.1.7 First-Loss Capital

The First-Loss Capital is an optional mechanism to protect the Vault depositors from incurring a loss in case of a Loan default. The first loss of capital absorbs some of the loss. The following parameters control the First-Loss Capital:

• CoverAvailable - the total amount of cover deposited by the Lending Protocol Owner.
• CoverRateMinimum - the percentage of DebtTotal that must be covered by the CoverAvailable.
• CoverRateLiquidation - the maximum percentage of the minimum required cover ($DebtTotal \times CoverRateMinimum$) that will be liquidated to cover a Loan Default.

Whenever the available cover falls below the minimum cover required, two consequences occur:

• The Lender cannot issue new Loans.
• The Lender cannot receive fees. Borrower fees are ignored (i.e. the Borrower does not have to pay a Loan payment fee), and the Management Fee is instead deposited into a Vault.

Examples

Example 1: 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 --
DefaultAmount = 1,090 Tokens


# First-Loss Capital liquidation maths

# 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, 1,090)
                    = 10.9 Tokens

DefaultRemaining    = DefaultAmount - DefaultCovered
                    = 1,090 - 10.9
                    = 1,079.1 Tokens

** State Changes **

-- Vault --
AssetsTotal     = AssetsTotal - DefaultRemaining
                = 100,090 - 1,079.1
                = 99,010.9 Tokens

AssetsAvailable = AssetsAvailable + DefaultCovered
                = 99,000 + 10.9
                = 99,010.9 Tokens

SharesTotal = (UNCHANGED)

-- Lending Protocol --
DebtTotal       = DebtTotal - DefaultAmount
                = 1,090 - 1,090
                = 0 Tokens

CoverAvailable  = CoverAvailable - DefaultCovered
                = 1,000 - 10.9
                = 989.1 Tokens

2.2. Loan Ledger Entry

A Loan ledger entry captures various Loan terms on-chain. It is an agreement between the Borrower and the loan issuer.

2.2.1 Object Identifier

The LoanID is calculated as follows:

• Calculate SHA512-Half of the following values:
  • The Loan space key 0x004C (capital L)
  • The AccountID of the Borrower account.
  • The LoanBrokerID of the associated LoanBrokerobject.
  • The Sequence number of the LoanSet transaction. If the transaction used a Ticket, use the TicketSequence value.

2.2.2 Fields

Field Name	Modifiable?	Required?	JSON Type	Internal Type	Default Value	Description
LedgerEntryType	N/A	✔️	string	UINT16	TODO	Ledger object type.
LedgerIndex	N/A	✔️	string	UINT16	N/A	Ledger object identifier.
Flags	Yes		string	UINT32	0	Ledger object flags.
PreviousTxnID	N/A	✔️	string	HASH256	N/A	The ID of the transaction that last modified this object.
PreviousTxnLgrSeq	N/A	✔️	number	UINT32	N/A	The ledger sequence containing the transaction that last modified this object.
Sequence	N/A	✔️	number	UINT32	N/A	The transaction sequence number that created the loan.
OwnerNode	N/A	✔️	number	UINT64	N/A	Identifies the page where this item is referenced in the owner's directory.
LoanBrokerID	No	✔️	string	HASH256	N/A	The ID of the LoanBroker associated with this Loan Instance.
Borrower	No	✔️	string	AccountID	N/A	The address of the account that is the borrower.
LoanOriginationFee	No	✔️	number	NUMBER	N/A	A nominal funds amount paid to the LoanBroker.Owner when the Loan is created.
LoanServiceFee	No	✔️	number	NUMBER	N/A	A nominal funds amount paid to the LoanBroker.Owner with every Loan payment.
LatePaymentFee	No	✔️	number	NUMBER	N/A	A nominal funds amount paid to the LoanBroker.Owner when a payment is late.
FullPaymentFee	No	✔️	number	NUMBER	N/A	A nominal funds amount paid to the LoanBroker.Owner when a payment full payment is made.
InterestRate	No	✔️	number	UINT16	N/A	Annualized interest rate of the Loan in 1/10th basis points.
LateInterestRate	No	✔️	number	UINT16	N/A	A premium is added to the interest rate for late payments in 1/10th basis points. Valid values are between 0 and 100000 inclusive. (0 - 100%)
ClosingInterestRate	No	✔️	number	UINT16	N/A	An interest rate charged for repaying the Loan early in 1/10th basis points. Valid values are between 0 and 100000 inclusive. (0 - 100%)
PrincipalRequested	No	✔️	number	NUMBER	N/A	The principal amount requested by the Borrower.
StartDate	No	✔️	number	UINT32	N/A	The timestamp of when the Loan starts Ripple Epoch.
PaymentsTotal	No	✔️	number	UINT32	N/A	The total number of payments against the Loan.
PaymentInterval	No	✔️	number	UINT32	N/A	Number of seconds between Loan payments.
GracePeriod	No	✔️	number	UINT32	N/A	The number of seconds after the Payment Due Date that the Loan can be Defaulted.
NextPaymentDueDate	N/A	✔️	number	UINT32	N/A	The timestamp of when the next payment is due in Ripple Epoch.
PaymentsRemaining	N/A	✔️	number	UINT32	PaymentsTotal	The number of payments remaining on the Loan.
AssetsAvailable	N/A	✔️	number	NUMBER	PrincipalRequested	The asset amount that is available in the Loan.

2.2.2.1 Flags

The Loan object supports the following flags:

Flag Name	Flag Value	Modifiable?	Description
lsfDefault	0x0001	No	If set, indicates that the Loan is defaulted.
lsfImpaired	0x0002	Yes	If set, indicates that the Loan is impaired.

2.2.3 Ownership

The Loan objects are stored in the ledger and tracked in an Owner Directory owned by the Borrower.

Furthermore, to facilitate the Loan object lookup from the LoanBroker, the object is also tracked in the OwnerDirectory associated with the LoanBroker object.

2.2.4 Reserves

The Loan object costs one owner reserve for the Borrower.

3. Transactions

3.1. LoanBroker Transactions

In this section we specify the transactions associated with the LoanBroker ledger entry.

3.1.1 LoanBrokerSet

The transaction creates a new LoanBroker object or updates an existing one.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
VaultID	✔️	string	HASH256	N/A	The Vault ID that the Lending Protocol will use to access liquidity.
LoanBrokerID		string	HASH256	N/A	The Loan Broker ID that the transaction is modifying.
Flags		string	UINT32	0	Specifies the flags for the Lending Protocol.
Data		string	BLOB	None	Arbitrary metadata in hex format. The field is limited to 256 bytes.
ManagementFeeRate		number	UINT16	0	The 1/10th basis point fee charged by the Lending Protocol Owner. Valid values are between 0 and 10000 inclusive.
DebtMaximum		number	NUMBER	0	The maximum amount the protocol can owe the Vault. The default value of 0 means there is no limit to the debt.
CoverRateMinimum		number	UINT16	0	The 1/10th basis point DebtTotal that the first loss capital must cover. Valid values are between 0 and 100000 inclusive.
CoverRateLiquidation		number	UINT16	0	The 1/10th basis point of minimum required first loss capital liquidated to cover a Loan default. Valid values are between 0 and 100000 inclusive.

3.1.1.1 Failure Conditions

• The Vault with VaultID does not exist.
• The submitter is NOT the Owner of the associated Vault object.
• Any of the fields are invalid.
• A LoanBroker object with the specified ID does not exist.
• The submitter is attempting to modify fixed fields.

3.1.1.2 State Changes

• IF transaction creates a new object:

  • Add LoanBrokerID to the OwnerDirectory of the submitting account.
  • Add LoanBrokerID to the OwnerDirectory of the Vault's _pseudo-account_.

• IF transaction updates an existing object:

  • Update appropriate fields.

3.1.1.3 Invariants

TBD

3.1.2 LoanBrokerDelete

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
LoanBrokerID		string	HASH256	N/A	The Loan Broker ID that the transaction is deleting.

3.1.2.1 Failure Conditions

• A LoanBroker object with the specified ID does not exist.
• The submitter is NOT the Owner of the LoanBroker.
• The OwnerCount field is greater than zero.
• CoverAvailable is greater than zero.

3.1.2.2 State Changes

• Delete LoanBrokerID from the OwnerDirectory of the submitting account.
• Delete LoanBrokerID from the OwnerDirectory of the Vault's _pseudo-account_.
• Delete the OwnerDirectory associated with the LoanBroker object.

3.1.2.3 Invariants

TBD

3.1.3 LoanBrokerCollateralDeposit

The transaction creates a new LoanBroker object or updates an existing one.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
LoanBrokerID	✔️	string	HASH256	N/A	The Loan Broker ID to deposit First-Loss Capital.
Amount	✔️	object	STAmount	0	The Fist-Loss Capital amount to deposit.

3.1.3.1 Failure Conditions

• The LoanBroker object with LoanBrokerID does not exist.
• The submitter is NOT the Owner of the associated LoanBroker object.
• The submitter attempts to deposit an Asset that does not match the Asset of the Vault.
• The submitter does not have sufficient funds available.
• The Issuer of the Asset has placed a global freeze, or the LoanBroker.Owner account is frozen.

3.1.3.2 State Changes

• IF Amount is XRP:

  • Decrement the Balance field of the submitter's AccountRoot by Amount.
  • Increment the Balance field of the Vault's _pseudo-account_.

• IF Amount is IOU:

  • Decrement the TrustLine between the Issuer and submitters AccountRoot by Amount.
  • Increment the TrustLine the Issuer and the Vault's _pseudo-account_.

• IF Amount is MPT:

  • Decrement the MPToken of the submitter Account by Amount.
  • Increment the MPToken of the Vault's _pseudo-account_ by Amount.

• Increment LoanBroker.CoverAvailable by Amount.

3.1.3.3 Invariants

TBD

3.1.4 LoanBrokerCollateralWithdraw

The LoanBrokerCollateralWithdraw transaction withdraws the First-Loss Capital from the LoanBroker.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	Transaction type.
LoanBrokerID	✔️	string	HASH256	N/A	The Loan Broker ID from which to withdraw First-Loss Capital.
Amount	✔️	object	STAmount	0	The amount of Vault asset to withdraw.

3.2.2.1 Failure conditions

• The LoanBroker object with LoanBrokerID does not exist.
• The submitter is NOT the Owner of the associated LoanBroker object.
• The submitter is attempting to withdraw an Asset that does not match the Asset of the Vault.
• The LoanBroker.CoverAvailable is less than the Amount.
• The Issuer of the Asset has placed a global freeze, or the LoanBroker.Owner account is frozen.

3.2.2.2 State Changes

• IF Amount is XRP:

  • Decrement the Balance field of the Vault's _pseudo-account_.
  • Increment the Balance field of the submitter's or AccountRoot by Amount.

• IF Amount is IOU:

  • Increment the TrustLine between the Issuer and submitters AccountRoot by Amount.
  • Decrement the TrustLine the Issuer and the Vault's _pseudo-account_.

• IF Amount is MPT:

  • Increment the MPToken of the submitter Account by Amount.
  • Decrement the MPToken of the Vault's _pseudo-account_ by Amount.

• Decrement LoanBroker.CoverAvailable by Amount.

3.2. Loan Transactions

In this section we specify transactions associated with the Loan ledger entry.

3.2.1 LoanSet Transaction

The transaction creates a new Loan object.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
LoanBrokerID	✔️	string	HASH256	N/A	The Loan Broker ID associated with the loan.
Flags		string	UINT32	0	Specifies the flags for the Loan.
Data		string	BLOB	None	Arbitrary metadata in hex format. The field is limited to 256 bytes.
Borrower	✔️	string	AccountID	N/A	The address of the account that is the borrower.
LoanOriginationFee		number	NUMBER	0	A nominal funds amount paid to the LoanBroker.Owner when the Loan is created.
LoanServiceFee		number	NUMBER	0	A nominal amount paid to the LoanBroker.Owner with every Loan payment.
LatePaymentFee		number	NUMBER	0	A nominal funds amount paid to the LoanBroker.Owner when a payment is late.
FullPaymentFee		number	NUMBER	0	A nominal funds amount paid to the LoanBroker.Owner when an early full repayment is made.
InterestRate		number	UINT16	0	Annualized interest rate of the Loan in basis points.
LateInterestRate		number	UINT16	0	A premium added to the interest rate for late payments in basis points. Valid values are between 0 and 10000 inclusive. (0 - 100%)
ClosingInterestRate		number	UINT16	0	A Fee Rate charged for repaying the Loan early in 1/10th basis points. Valid values are between 0 and 100000 inclusive. (0 - 100%)
PrincipalRequested	✔️	number	NUMBER	N/A	The principal amount requested by the Borrower.
StartDate	✔️	number	UINT32	N/A	The timestamp of when the Loan starts Ripple Epoch.
PaymentsTotal		number	UINT32	1	The total number of payments to be made against the Loan.
PaymentInterval		number	UINT32	60	Number of seconds between Loan payments.
GracePeriod		number	UINT32	60	The number of seconds after the Loan's Payment Due Date can be Defaulted.
Lender	✔️	object	STObject	N/A	An inner object that contains the signature of the Lender over the transaction.

3.2.1.1 Lender

An inner object that contains the signature of the Lender over the transaction. The fields contained in this object are:

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
SigningPubKey	✔️	string	STBlob	N/A	The Public Key to be used to verify the validity of the signature.
Signature	✔️	string	STBlob	N/A	The signature of over all signing fields, including the Signature of the Borrower.
Signers	✔️	list	STArray	N/A	An array of transaction signatures from the LoanBroker.Owner signers to indicate their approval of this transaction.

The final transaction must include Signature or Signers.

If the Signers field is necessary, then the total fee for the transaction will be increased due to the extra signatures that need to be processed, similar to the additional fees for multisigning. The minimum fee will be $(|signatures| + 1) \times base_fee$

The total fee calculation for signatures will now be $(1 + |tx.Signers| + |tx.Lender.Signers|) \times base_fee$.

This field is not a signing field (it will not be included in transaction signatures, though the Signature or Signers field will be included in the stored transaction).

3.2.1.2 Multi-Signing

The LoanSet transaction is a mutual agreement between the Borrower and the LoanBroke.Owner to create a Loan. Therefore, the LoanSet transaction must be signed by both parties. The multi-signature flow is as follows:

1. The Borrower creates a new transaction with the pre-agreed terms of the Loan and signs the transaction.
2. The Lender signs over all signing fields, including the signature of the Borrower.

3.2.1.3 Failure Conditions

• The LoanBroker object associated with LoanBrokerIDdoes not exist.

• The Account submitting the transaction is not the LoanBroker.Owner.

• The Issuer account of the Asset is frozen (Global Freeze). No changes can be made to a Loan for a globally frozen asset.

• Lender. Signature is invalid.

• Either of the tfDefault, tfImpair or tfUnimpair flags are set.

• The Borrower account does not exist.

• The Trustline or MPToken between the Borrower and the Issuer is frozen.

• The Borrower is not Authorized to hold the Loan asset.

• PaymentInterval is less than 60 seconds.

• GracePeriod is greater than the PaymentInterval.

• The Loan Start Date is in the past: StartDate < CurrentTime.

• Insufficient assets in the Vault:

  • Vault(LoanBroker(LoanBrokerID).VaultID).AssetsAvailable < Loan.PrincipalRequested.

• Exceeds maximum Debt of the LoanBroker:

  • LoanBroker(LoanBrokerID).DebtMaximum < LoanBroker(LoanBrokerID).DebtTotal + Loan.PrincipalRequested

• Insufficient First-Loss Capital:

  • LoanBroker(LoanBrokerID).CoverAvailable < (LoanBroker(LoanBrokerID).DebtTotal + Loan.PrincipalRequested) x LoanBroker(LoanBrokerID).CoverRateMinimum

3.2.1.4 State Changes

• If the Loan Asset is an IOU:

  • Create a Trustline between the Issuer and the Borrower if one does not exist.

• If the Loan Asset is an MPT:

  • Create an MPToken object for the Borrower if one does not exist.

• Vault(LoanBroker(LoanBrokerID).VaultID) object state changes:

  • Decrease Assets Available in the Vault:

    • Vault.AssetsAvailable -= Loan.PrincipalRequested.

  • Increase the Total Value of the Vault:

    • Vault.AssetsTotal += LoanInterest - (LoanInterest x LoanBroker.ManagementFeeRate) where LoanInterest is the Loan's total interest.

• LoanBroker(LoanBrokerID) object changes:

  • LoanBroker.DebtTotal +=

    • Loan.PrincipalRequested +
    • (LoanInterest - (LoanInterest x LoanBroker.ManagementFeeRate)

  • Increase the number of active Loans:

    • LoanBroker.OwnerCount += 1

  • If the DirectoryNode for the LoanBroker does not exist, create one.

    • Add LoanID to DirectoryNode.Indexes.

3.2.1.4 Invariants

TBD

3.2.2 LoanDelete Transaction

The transaction deletes an existing Loan object.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
LoanID	✔️	string	HASH256	N/A	The ID of the Loan object to be deleted.

3.2.2.1 Failure Conditions

• A Loan object with the specified LoanID does not exist.
• The Account submitting the LoanDelete is not the LoanBroker.Owner or the Loan.Borrower.
• The Loan is active:
  • Loan.PaymentsRemaining > 0

3.2.2.2 State Changes

• Remove LoanID from the Owner Directory associated with the LoanBroker.
• Decrement LoanBroker.OwnerCount by 1.
• Delete the Loan object.
• Release reserve funds back to the Borrower.

3.2.3 LoanManage Transaction

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
LoanID	✔️	string	HASH256	N/A	The ID of the Loan object to be updated.
Flags		string	UINT32	0	Specifies the flags for the Loan.

3.2.3.1 Flags

Flag Name	Flag Value	Description
tfDefault	0x0001	Indicates that the Loan should be defaulted.
tfImpair	0x0002	Indicates that the Loan should be impaired.
tfUnimpair	0x0003	Indicates that the Loan should be un-impaired.

3.2.3.1 Failure Conditions

• A Loan object with the specified LoanID does not exist.

• The Account submitting the transaction is not the LoanBroker.Owner.

• The lsfDefault flag is set on the Loan object. Once a Loan is defaulted, it cannot be modified.

• The Loan has been repaid:

  • Loan.PaymentsRemaining == 0.

• The tfDefault flag is specified AND:

  • The Late Payment Grace period has not passed:
    • CurrentTime < Loan.NextPaymentDueDate + Loan.GracePeriod.

3.2.3.2 State Changes

• If the tfDefault flag is specified:

  • Calculate the amount of the Default that First-Loss Capital covers:

    • The default Amount equals the outstanding principal and interest, excluding any funds unclaimed by the Borrower.
      • DefaultAmount = (Loan.PrincipalOutstanding + Loan.InterestOutstanding) - Loan.AssetsAvailable.
    • Apply the First-Loss Capital to the Default Amount
      • DefaultCovered = min((LoanBroker(Loan.LoanBrokerID).DebtTotal x LoanBroker(Loan.LoanBrokerID).CoverRateMinimum) x LoanBroker(Loan.LoanBrokerID).CoverRateLiquidation, DefaultAmount)
    • DefaultAmount -= DefaultCovered

  • Update the Vault:

    • Decrease the Total Value of the Vault:
      • Vault(LoanBroker(LoanBrokerID).VaultID).AssetsTotal -= DefaultAmount.
    • Increase the Assets Available of the Vault by liquidated First-Loss Capital and any unclaimed funds amount:
      • Vault(LoanBroker(LoanBrokerID).VaultID).AssetsAvailable += DefaultCovered + Loan.AssetsAvailable.

• Update the LoanBroker:

  • Decrease the Debt of the LoanBroker:
    • LoanBroker(LoanBrokerID).DebtTotal -=
    • Loan.PrincipalOutstanding + Loan.InterestOutstanding + Loan.AssetsAvailable
  • Decrease the First-Loss Capital Cover Available:
    • LoanBroker(LoanBrokerID).CoverAvailable -= DefaultCovered.
  • Decrease the number of active Loans:
    • LoanBroker(LoanBrokerID).OwnerCount -= 1

• Update the Loan:

  • Loan(LoanID).Flags = lsfDefault.
  • Loan(LoanID).PaymentsRemaining = 0.
  • Loan(LoanID).AssetsAvailable = 0.

3.2.3.3 Invariants

TBD

3.2.4 LoanDraw Transaction

The Borrower submits a LoanDraw transaction to draw funds from the Loan.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
LoanID	✔️	string	HASH256	N/A	The ID of the Loan object to be drawn from.
Amount	✔️	number	NUMBER	N/A	The amount of funds to drawdown.

3.2.4.1 Failure Conditions

• The Loan has not started: StartDate > CurrentTime.
• A Loan object with the specified LoanID does not exist.
• The account submitting the transaction is not equal to Loan. Borrower.
• There are insufficient assets in the Loan Loan.AssetsAvailable < Amount.
• The Loan has either lsfImpaired or lsfDefault flags.
• The Issuer of the Vault's Asset enacted a Global Freeze or a freeze on the Borrower account.
• The Borrower missed a payment: the current ledger time is greater than Loan.NextPaymentDueDate.

3.2.4.2 State Changes

• IF Loan asset is XRP:

  • Decrease the Balance field of the Vault's _pseudo-account_ AccountRoot by amount.
  • Increase the Balance field of the Borrower's AccountRoot by amount.

• IF Loan asset is IOU:

  • Decrease the Trustline between the Vault's _pseudo-account_ and the Issuer by Amount.
  • Increase the Trustline between the Borrower and the Issuer by Amount.

• IF Loan asset is MPT:

  • Decrease the MPToken of the Vault's _pseudo-account_ by Amount.
  • Increase the MPToken of the Borrower by Amount.

• Decrease Loan.AssetsAvailable by Amount.

3.2.4.3 Invariants

TBD

3.2.5 LoanPay Transaction

The Borrower submits a LoanPayment transaction to make a Payment on the Loan.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	The transaction type.
LoanID	✔️	string	HASH256	N/A	The ID of the Loan object to be drawn from.
Amount	✔️	number	NUMBER	N/A	The amount of funds to pay.

3.2.5.1 Payment Types

A Loan payment can fall into one of the three categories:

• Regular payment is made on time, where the payment size and schedule are calculated with a standard amortization formula.

• A late payment, when a Borrower makes a payment after netxPaymentDueDate. Late payments include a LatePaymentFee and LateInterestRate.

• An early full payment is when a Borrower pays the outstanding principal. A ClosingInterestRate is charged on the outstanding principal.

The payment amount and timing determine the type of payment. A payment made before the Loan.NextPaymentDueDate is a regular payment and follows the standard amortization calculation. Any payment made after this date is considered a late payment.

Each payment comprises three parts, principal, interest and fee. The principal is an amount paid against the principal of the Loan, interest is the interest portion of the Loan, and fee is the fee part paid by the Borrower on top of principal and interest.

Payments below the minimum amount are automatically rejected. The minimum amount is determined by the payment's timeliness. Any funds exceeding the minimum payment are applied to the Loan principal. If the Borrower submits the entire amount, the Loan is paid off. No additional funds are charged.

  Rejected        Overpayment          Returned
------------|-----------------------|------------
    Minimum Amount           Full Payment

                Payment Amount

Late payments take priority over full payments. A Borrower cannot make a full payment when their payment is late. The Borrower must make the late payment and only then make a full payment.

3.2.5.1.1 Regular Payment

A single payment is calculated using the amortization payment formula:

$$ totalDue = periodicPayment + loanServiceFee $$

$$ periodicPayment = principalOutstanding \times \frac{periodicRate \times (1 + periodicRate)^{PaymentsRemaining}}{(1 + periodicRate)^{PaymentsRemaining} - 1} $$

where the periodic interest rate is the interest rate charged per payment period:

$$ periodicRate = \frac{interestRate \times paymentInterval}{365 \times 24 \times 60 \times 60} $$

The principal and interest portions can be derived as follows:

$$ interest = principalOutstanding \times periodicRate $$

$$ principal = periodicPayment - interest $$

3.2.5.1.2 Early Full Repayment

A Borrower can close a Loan early by submitting the total amount needed to do so. This amount is the sum of the remaining balance, any accrued interest, a prepayment penalty, and a prepayment fee.

$$ totalDue = principalOutstanding + accruedInterest + prepaymentPenalty + fullPaymentFee $$

Accrued interest up to the point of early closure is calculated as follows:

$$ accruedInterest = principalOutstanding \times periodicRate \times \frac{secondsSinceLastPayment}{paymentInterval} $$

Finally, the Lender may charge a prepayment penalty for paying a loan early, which is calculated as follows:

$$ prepaymentPenalty = principalOutstanding \times closingInterestRate $$

An early payment pays less interest than calculated when increasing the Vault value in the LoanSet transaction. Therefore, the Vault value (captured by Vault.AssetsTotal) must be recalculated after an early payment. Assume a function CurrentValue() that returns principalOutstanding and interestOutstanding of the Loan. Furthermore, assume a function FullPayment() that implements the Full Payment calculation. The function returns the total full payment due split into principal and interest.

The value change for an early full repayment is calculated as follows:

$$ valueChange = (prepaymentPenalty) - (interestOutstanding - accruedInterest) $$

Note that valueChange <= 0 as an early repayment reduces the total value of the Loan.

3.2.5.1.3 Late Payment

When a Borrower makes a payment after NextPaymentDueDate, they must pay a nominal late payment fee and an additional interest rate charged on the overdue amount for the unpaid period. The formula is as follows:

$$ totalDue = periodicPayment + latePaymentFee + latePaymentInterest $$

A special, late payment interest rate is applied for the over-due period:

$$ latePaymentInterest = principalOutstanding \times \frac{lateInterestRate \times secondsSinceLastPayment}{365 \times 24 \times 60 \times 60} $$

A late payment pays more interest than calculated when increasing the Vault value in the LoanSet transaction. Therefore, the total Vault value captured by Vault.AssetsTotal must be recalculated.
Assume the function PeriodicPayment() returns the expected periodic payment, split into principalPeriodic and interestPeriodic. Furthermore, assume the function LatePayment() that implements the Late Payment formula. The function returns the late payment split into principalLate and interestLate, where interestLate is calculated using the formula above. Note that principalPeriodic == principalLate and interestLate > interestPeriodic are used only when the payment is late. Otherwise, interestLate == interestPeriodic.

$$ valueChange = interestLate - interestPeriodic $$

Note that valueChange >= 0.

3.2.5.1.4 Management Fee Calculations

The LoanBroker Management fee is charged against the interest portion of the Loan and subtracted from the total Loan value at Loan creation. However, the fee is charged only during Loan payments. Early and Late payments change the total value of the Loan by decreasing or increasing the value of total interest. Therefore, when an early or late payment is made, the management fee must be updated.

To update the management fee, we need to compute the new total management fee based on the new total interest after executing the early or late payment. Therefore, we need to capture the Loan value before the payment is made and the new value after the payment is made.

For the calculation, assume the following variables:

• Let $\mathcal{P}$ and $\mathcal{p}$ represent the total and outstanding Loan principal.
• Let $\mathcal{I}$ and $\mathcal{i}$ represent the total and outstanding Loan interest computed from $\mathcal{P}$ and $\mathcal{p}$ respectively.
• Let $\mathcal{V}$ and $\mathcal{v}$ represent the total and outstanding value of the Loan. $\mathcal{V} = \mathcal{P} + \mathcal{I}$ and $\mathcal{v} = \mathcal{p} + \mathcal{i}$.
• Finally, let $\mathcal{m}$ represent the management fee rate of the Loan Broker.

Assume $f(\mathcal{v})$ is a Loan payment, $f(\mathcal{v}) = \mathcal{v'}$, the new outstanding loan value is equal to the application of the payment transaction to the current outstanding value. Furthermore, assume $\mathcal{V} \xrightarrow{f(\mathcal{v})} \mathcal{V'}$, is the change in the Loan total value as the result of applying $f(\mathcal{v})$.

we say that $\mathcal{V'} = \mathcal{P'} + \mathcal{I'}$. It's important to note that a payment transaction must never change the total principal. I.e. $\mathcal{P} = \mathcal{P'}$, the change in total value is caused by the change in total principal only.

$\Delta_{\mathcal{V}} = \mathcal{I'} - \mathcal{I}$ is the total value change of the Loan. When $\Delta_{\mathcal{V}} &gt; 0$ the total value of the Loan increased, when $\Delta_{\mathcal{V}} &lt; 0$ the total value decreased, and if $\Delta_{\mathcal{V}} = 0$ the value remained the same.

The total management fee is calculated as follows:

$$ managementFeeTotal = \mathcal{I} \times \mathcal{m} $$

We compute the management fee paid so far as follows:

$$ managementFeePaid = (\mathcal{I} - \mathcal{i}) \times \mathcal{m} $$

$$ managementFeeDue = managementFeeTotal - managementFeePaid $$

Finally, we compute the change in management fee as follows:

$$ managementFeeChange = \mathcal{i'} \times \mathcal{m} - managementFeeDue $$

The above calculation can be simplified to:

$$ managementFeeChange = \Delta_{\mathcal{V}} \times \mathcal{m} $$

When the management fee change is negative, the Loan's value decreases, and thus, the Loan Broker's debt decreases.
Intuitively, a negative fee change suggests that the fee must be returned, increasing the loan broker's debt.

In contrast, if the management fee change is positive, the Loan's value increases, and a further fee must be deducted from the debt.
Intuitively, a positive fee change suggests that an additional fee must be paid due to the increase in the interest paid.

The LoanBroker debt is then updated as:

$$ LoanBroker.DebtTotal = LoanBroker.DebtTotal - managementFeeChange $$

3.2.5.2 Failure Conditions

• A Loan object with specified LoanID does not exist.

• The Loan has not started yet: Loan.StartDate > CurrentTime.

• The account making a payment is NOT the Loan.Borrower.

• Loan.PaymentsRemaining or Loan.PrincipalOutstanding is 0.

• The _pseudo-account_ of the Vault(LoanBroker(Loan.LoanBrokerID).VaultID) is frozen.

• The Borrower Trustline or the MPToken is frozen.

• The Issuer of the Vault's Asset enacted a global freeze.

• If the payment is late: CurrentTime > Loan.NextPaymentDueDate AND:

  • The Amount < LatePaymentAmount()

• If the payment is on time: CurrentTime <= Loan.NextPaymentDueDate AND:

  • The Amount < PeriodicPaymentAmount()

3.2.5.3 State Changes

Assume the payment is split into principal, interest and fee, and totalDue = principal + interest + fee.

• If the loan payment is late, use CurrentTime > Loan.NextPaymentDueDate:

  • Compute principal, interest and fee using the Late Payment formula.

• If the Loan payment is on time:

  • Compute principal, interest and fee using Periodic Payment formula.

• If the Amount paid is greater or equal to Full Payment Amount:

  • Compute principal, interest and fee using the Full Payment formula.

• Compute overflow = Amount - totalDue.

• Compute totalPaid = totalDue.

• Loan object state changes:

  • Decrement Loan.PaymentsRemaining by 1.
  • Decrement Loan.PrincipalOutstanding by principal.
  • If the Payment is periodic AND overflow > 0:
  • If Loan.PaymentsRemaining > 0 and LoanLoanncipalOutstanding > 0:
    • Set the next payment date: LoanLoantPaymentDueDate += Loan.PaymentInterval.

• LoanBroker(Loan.LoanBrokerID) object state changes:

  • Compute the management fee:

    • feeManagement = interest x LoanBroker.ManagementFeeRate

  • If there is not enough first-loss capital: LoanBroker.CoverAvailable < LoanBroker.DebtTotal x LoanBroker.CoverRateMinimum:

    • If the management fee was not charged, add it to the total debt:
      • LoanBroker.DebtTotal += feeManagement

  • If there is enough first-loss capital: LoanBroker.CoverAvailable >= LoanBroker.DebtTotal x LoanBroker.CoverRateMinimum:

  • Decrement the management fee from totalPaid amount:

    • totalPaid = totalPaid - feeManagement

  • Decrement LoanBroker Debt by the amount paid:

    • LoanBroker.DebtTotal -= totalPaid

  • Update the LoanBroker Debt by the Loan value change:

    • LoanBroker.DebtTotal += valueChange

  • Update the LoanBroker Debt by the change in the management fee:

    • LoanBroker.DebtTotal -= (valueChange x LoanBroker.ManagementFeeRate)

  • If the loanLoanpaid off: LoanLoanmentsRemaining == 0 and LoanLoanncipalOutstanding == 0:

    • Decrement active loans: LoanBroker.OwnerCount = LoanBroker.OwnerCount - 1

• Vault(LoanBroker(Loan.LoanBrokerID).VaultID) state changes:

  • Increment available assets in the Vault by the amount paid:

    • Vault.AssetsAvailable = Vault.AssetsAvailable + totalPaid

  • Update the Vault total value by the change in the Loan total value:

    • Vault.AssetsTotal = Vault.AssetsTotal + valueChange

  • Update the Vault total value by the change in the management fee:

    • Vault.AssetsTotal = Vault.AssetsTotal - (vaultChange x LoanBroker.managementFeeRate)

  • If there is not enough first-loss capital: LoanBroker.CoverAvailable < LoanBroker.DebtTotal x LoanBroker.CoverRateMinimum:

    • The management fee was not charged; increment Vault TotalValue:
      • Loan.AssetsTotal = Loan.AssetsTotal + feeManagement

3.2.5.4 Invariants

TBD

Appendix

[dangell7]

Personally I would have designed all of this to abide by the current security laws in the US but thats just me.

As these proposals sit, one could invest into a pool, then the managers of that pool could make investment decisions that they don't agree with. This is why we have the current laws set up the way we do in the US. I.E. A prospectus is created, an N-1 is filed, then citizens can invest into the Fund and know exactly what they are investing in. Maybe you could view this more as a third party money manager, however a 3PMM still defines clearly what investments the Fund may invest in.

These proposals, imo, add complex risk and will likely violate current securities laws but don't let that stop you, I still like the ideas.

[mvadari]

I think this is why many of us shared concern early about DID.

Where were those concerns expressed? I don't see any in the spec discussion, and I don't recall any voiced elsewhere.

The spec implements the industry-standard W3C DID spec, to avoid reinventing the wheel and having too many standards in the industry.

The problem with storing that sort of KYC/financial data directly on-ledger is due to privacy - you want the verified credential (VC) data to be stored off-chain because you only want that data for certain use-cases, not for everyone to see on a public blockchain.

Those licensed professionals that you mention could still issue VCs for those details, and the pool manager could verify those details off-chain before approving the deposit auth. If you want it on-chain in some form, it could be encrypted in a memo so the pool manager doesn't need to communicate off-chain with the prospective loan participants. Then you don't need a list of "approved FINRA-licensed addresses" that you somehow have to store on-chain and always keep updated.

[dangell7]

Here is where we realized you had done it backwards to what we were thinking and would have done. More concerns were voiced internally or on other channels like twitter.

I never said anything about storing data on the ledger, you just store the attestation.

[Tapanito]

Great ideas @dangell7 !

If it were me, I would force depositAuth, with DID, verifying that the user has accreditation status. I would also force that the managers have a financial advisor status thought DID. Without them being licensed, them choosing investments for clients is absolutely a violation.

To echo @mvadari it might be quite tricky to add any credential verification logic to the blockchain. The nature of XRPL is that protocols are part of the "core" implementation. Verifying credentials would require coupling rippled with some verifiable credential issuer. Though, I like the depositAuth idea. Currently, it can be achieved via the Permissions field, where a Pool Delegate can explicitly authorise Liquidity Providers and Borrower. (Assuming the Pool Delegate vets the Liqudity Provider and the Borrower off-chain). Do I understand correctly, that you're proposing to enforce that these accounts (Liquidity Providers, Borrower, Pool Delegate) all have associated DIDs with them?

A lot of this might be off chain stuff, however I would attempt to move as much of this on chain as I can. Or at least make the attempts. I would also move away from renaming things. I would lean more into the current financial instruments than out. For example, the "Pool" is actually what most of us would refer to as a "Fund". Changing the name isn't going to help you in a legal preceding, we obviously know what it is.

Variable naming is hard :) . We chose Pool (though perhaps Vault might be an even better name) as it indicates a construct that holds a single asset deposited by one or more accounts. It is not necessarily yield-bearing. For example, Pool could be used for a multi-party escrow. Lending Protocol is just one application that requires a way to "pool" an asset from multiple accounts.

[dangell7]

I think it comes down to who your target market is. If your target market is "crypto" (2 trillion) than Pool works well. However if your target market is Hedge Funds, Financial Advisors and Institutional Finance (23 trillion) than changing the name of something that already exist is just confusing. Also fyi, a multiparty escrow is still called an escrow fund in finance.

Honestly, it really doesn't matter. We're already actively trying to obfuscate the "crypto nomenclature" for everyday users so in this case we would do the same and present them to clients and customers as funds. In the eyes of the law they are funds. Call them whatever you'd like in the backend.

I take back what I said, I would let the creator of the Pool handle the DID/DepositAuth and requirements of their jurisdictional law and not force anything.

[jazzi-cooper]

Great points, @dangell7. I agree that we need to broaden our target market beyond just crypto natives. These users will likely use front-end applications that can rename "pools" to better fit their audience. The main audience for this specification is crypto-familiar developers, so I think its reasonable to use established blockchain terminology. For what its worth, we are shifting from the traditional finance model, which is somewhat exclusive and opaque,to a more open, transparent crowd-sourced approach. I think term "pool" aligns well with this new structure.

[rothexD]

I feel like a pool should have the option to have some type of uri/data field that it can use to link to external resources, you could put a bunch of usefull stuff behind that like a contacts page of the fund management, page informing about registration (i think lending will almost likely lead to it needing to be registered with the gov in some form) etc

[jazzi-cooper]

Yes great catch, this was meant to be included. It is in the pool spec. We will update this spec to reference it.

[rothexD]

mb the uri is in pool and this extends pool

i have now read through everything and maybe i missed it but i was looking for something like:

either the pool or this should also have a transfer ownership functionality

pool management may go bust or be bought/sold to others and they will want to ensure all access to mangement gets moved to them

[Tapanito]

@rothexD, thank you for your feedback. Indeed, a PoolDelegateURI is part of the Pool specification. Would an additional field specific to the Pool itself be beneficial?

[rothexD]

@rothexD, thank you for your feedback. Indeed, a PoolDelegateURI is part of the Pool specification. Would an additional field specific to the Pool itself be beneficial?

I was not expecting it to be in Pool as in my mind a Pool should be designed so that it can be something generic decentralized with no direct owner.

For example a decentralized tokenized Pool of xrp that can be used for flash-loans or similar in the future.

I don't see a need to have an additional uri field

[Tapanito]

@rothexD a similar issue about pool transferabiliy was raised in the Pool spec (#192 (comment)) .

Is decoupling a Pool owner and Delegate and giving them different permissions (including transferring the owner) a similar feature you had in mind?

[dangell7]

I like how you included Failure Conditions and State Changes.

This makes it very clear what the results of each transaction are.

[Tapanito]

Thank you @dangell7 !

[tequdev]

It seems to me that a malicious account could take away a user's funds by controlling both the delegator and the borrower, is that correct?
(if Borrowing Amount > Cover Funds)

Users have to fully evaluate the delegator.

[Tapanito]

Yes, @tequdev, that is correct. This version of the Protocol heavily relies on off-chain processes to prevent your scenario from happening. Liquidity Providers will have to evaluate the Pool Delegates; Pool Delegates will have to assess the Liquidity Providers and the Borrowers. Although assets are issued and repaid on-chain, contractual agreements between all parties will have to be made to enforce the correct behaviour from all parties.
The first version of the Protocol is based on creditworthiness. However, future iterations will introduce more sophisticated mechanisms to provide economic incentives to behave correctly. Before we do that, it's essential to get the fundamentals right, which this spec aims to do.

[outrum]

I'm particularly interested in how we're planning to tackle potential fraud or manipulation by borrowers or pool delegates. Given the off-chain underwriting and the significant responsibilities pool delegates hold, how are we making sure everything stays above board?

[jazzi-cooper]

On other chains, a lot of this happens off-chain between the Application ("marketplace") and the pool delegate. They often have legal contracts in place to ensure pool delegate accountability.

Over time, we would like to bring more of this on-chain, but this is just a v1.

[ShaneSCalder]

Are we also thinking of flash loans, leverage or settlement loans? How will this integrate with escrow as some of the basic functionality for lending could be applied or borrowed. Cheers

[jazzi-cooper]

Flash loans aren't possible on XRPL today because it doesn't support the necessary atomic transactions. However, upcoming features like XLS-56d (atomic/batch tx's) could potentially change this. As for the use cases you mentioned, they require collateral support, which we haven't included in the first version of our proposal. There is definitely a lot of value to unlock there so we will aim to include in a future version.

[gregtatcam]

Details field is used in multiple places as an inner object (SField), but it includes different fields. It must have a unique field name in each case, otherwise you are not going to be able to define the content of these inner objects in InnerObjectFormats.cpp.

[dangell7]

Is the outstanding principal the principal amount - drawable amount? This might create issues on a term loan if you allow multiple draw down events.

Doing an "Open Ended" Loan Pool makes things much more complex. Iterating through both Contributors and Composition is alot of work.
I would limit the number of contributors in a pool.

If the composition is submitted as part of the transactor, is it possible that the loan provider can choose whoever they want? Is this a legal issue? Could that loan/borrower always choose 100% of UserA assets thereby avoiding interest to specific liquidity providers in the pool?

Updating every contributor is a lot for every deposit/loan/withdraw transaction. Not a big deal if the number is limited but at 1000 contributors thats not going to work well. Even more so, allowing withdraw/deposit of amounts "pledged" during a loan will make things very complex.

You can calculate the withdraw amount in the transactor if you have the total outstanding loans on an object but this means that the user couldn't withdraw any amount "pledged" until the loan is closed. This is how I would structure it. Allowing the User to withdraw after each payment is adding complexity that I really dont believe is needed.

Ex. You and I deposit 100 each. A loan is made for 100. Thats 50% you and 50% me. I can withdraw 50 now and 50 + interest when the loan closes (or if the loan defaults then less). By allowing rolling withdraws you also open the door for users to each month pull the interest + principal they pledged.

Max Cover doesnt make any sense. In general the pool delegate doesn't make sense to me.
The cover or collateral should come from the borrower or a third party on behalf of the borrower which can be different for each loan.
The account that gives the collateral is not the account that receives interest. The composition is who receives interest or the pool liquidity providers. Each loan should have a collateral provider based on the PoolCollateral.min. That collateral is return at the end or taken in the event of default. Maybe I misunderstand the pool delegate.

GracePeriod & PaymentInterval are UINT32.

Some additional notes:

Loans take awhile to underwrite so by the time the loan is finalized, there may not be liquidity in the pool. Underwriters would need to manage this. You could solve this by having another transaction for LoanProposal to "lock" funds so that its clear when underwriting how much funds are available. The idea you have is that more liquidity could be deposited, which would require asking the pool or others to deposit more liquidity.

This makes sense in theory but imo its backwards. In practice you would write a loan application, then seek liquidity or underwrite the loan and that would then receive approval from the liquidity providers.

1. Application
2. Underwriting
3. Approval

I would do this.

LoanPropose - This is an agnostic object on the ledger the owner is the borrower. Its not created with a poolID. There is no lender, or pool delegate.
ApproveLoan - This is a voting mechanism of a pool. The votes come from the pool managers. When approved the pool id is added to the LoanObject.
VotePoolManager - Vote to add or remove pool managers (handles the governance structure of the pool)

• You have PoolDelegate but imo the pool liquidity providers should be the ones who vote managers in and out of the pool delegate role. In your example the PoolDelegate is whoever created the pool.

Imo this makes it much more peer to peer. The borrower can create their application and submit that to the ledger for any pool to approve of.

[Tapanito]

Closing the discussion as the specification is in a good spot. For further feedback please refer to the pull request #240

[Briandavidbrown1983]

Suggested Clarification:

Management Fee: This is a fee charged by the Loan Broker, calculated as a percentage of the interest earned on loans. It's deducted from the interest that would otherwise go to the Vault depositors. Essentially, borrowers pay the full interest, but before that interest reaches depositors, the Loan Broker takes their cut.

This explanation makes it clear:

That the fee is part of the interest income.

It's taken before distribution to depositors, thus affecting the yield they receive from the loans.

[Tapanito]

That's a great clarification, thank you. I'll update the spec. Though the discussion is closed, let's move this conversation to the PR 🙇

[Briandavidbrown1983]

You're welcome! And my apologies. Only my second time commenting on Github; still learning. Thanks! Here to help!