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

[Tapanito]

    
Title:        XRP Ledger-native Lending Protocol
Revision:     1 (2024-04-12)

Authors:   
  Vytautas Vito Tumas
  Aanchal Malhotra

Affiliation:
  Ripple

XRP Ledger-native Lending Protocol

Abstract

1. Introduction

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 fixed-term loans, utilizing pooled funds with pre-set terms for interest-accruing loans. The current design bypasses the need for collateral, relying instead on off-chain underwriting, risk management, and a First-Loss Capital protection scheme.

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.

At a glance Liquidity Providers (or lenders) deposit XRP or Fungible Tokens into a Lending Pool to earn interest in the Lending Pool's asset. Loan terms determine the interest earned agreed between the Borrower and the Lending Pool Delegate.

A Pool Delegate may manage one or more Lending Pools. The Pool Delegates' responsibility is to attract capital and provide funding to vetted Borrowers while earning various fees.

A Lending Pool is managed by a single Pool Delegate. The Pool Delegate is responsible for negotiating loan terms with borrowers, performing diligence, and managing the Loan. To evaluate the loan terms, Pool Delegate reviews a Borrower's reputation, expertise, and performance. Once the Borrower and Pool Delegate agree to the interest, Pool Delegate funds the loans from their managed Lending Pool. The current protocol supports multiple-lender-single-borrower Lending Pools for Fixed-Term Loans.

1.1 Modular Protocol Design

The primary objective of these specifications is to introduce an XRP Ledger-native Lending Protocol. The design's guiding principles are flexibility and reusability.

• flexibility: A Lending Protocol is a relatively complex system with multiple mechanisms, such as loans, loan collateral, risk management and incentives, asset pooling, fees, etc. Therefore, it must be upgradeable and extensible while maintaining backward compatibility to facilitate iterative design and development.

• reusability: A Lending Protocol requires a way to Pool a single asset from one or more Liquidity Providers, track balances between multiple accounts, manage loan states, etc, requiring various new ledger entries. However, instead of specific single-use entries, we introduce general objects that are reusable across multiple future protocols.

This work introduces the following three specifications:

1. XLS-64d - Pseudo-Account: Introduces a LedgerEntries field to the AccountRoot object allowing to associate a single pseudo-account with one or more other ledger entries. A pseudo-account is responsible for tracking various balances and issuing tokens on behalf of associated objects.
2. XLS-65d - Single Asset Tokenized Pool: Introduces a new Pool ledger entry representing a single tokenized asset pool. The specification introduces a minimal, extendable ledger entry and flexible transactions to interact with the object.
3. [XLS-66d] - A native XRP Ledger Lending Protocol: This specification introduces a Lending Protocol for the XRP Ledger. It leverages XLS-65d to manage Liquidity Provider assets. The protocol uses off-chain underwriting, on-chain agreements, and loan management.

1.1.1 Modular Design

The figure below illustrates the modular design of this proposal. From the left, the pseudo-account tracks various balances and issues tokens associated with the Pool ledger entry. The Pool ledger entry defines a minimal interface and transactions to pool liquidity from one or more LPs. The Liquidity Providers' share of the Pool is represented as LPTokens, issued by the pseudo-account. Finally, multiple protocols can use the Pool ledger entry and the pseudo-account for their needs. In this proposal, we will use it for the Lending Protocol specification.

1.1.2 Pseudo-Account

The term pseudo-account identifies an account created as part of some protocol. No user can control, send funds, or sign transactions on behalf of the pseudo-account. ONLY protocols can alter the state of the pseudo-account. When writing this specification, there are three applications for pseudo-accounts: AMM, Single Asset Tokenized Vault, and Lending Protocol.

The figure below outlines the architecture of a pseudo-account. A single account can be associated with multiple objects in the same protocol.

1.2 Terminology

1.2.1 Actors

• Pool Delegate: An entity responsible for issuing and managing Loans.

• Borrower: An entity seeking to borrow Fungible Tokens from a Lending Pool. Borrowers make loan payments composed of principal and interest, which accumulate in the lending pool.

• Liquidity Provider: Entities that deposit a single asset in the Lending Pool in return for pool shares in the form of LPTokens. The Lending Pool Delegate can lend the assets to a potential Borrower.

1.2.2 Entities

• Lending Pool: A construct that locks user-deposited assets in a shared yield-bearing pool. The Lending Pool accrues interest payments made by the borrowers.

• Loan: A construct that captures the terms of a Loan on-chain. It also maintains information essential for day-to-day Loan book-keeping. A Borrower and a Pool Delegate create a Loan using a multi-signature transaction.

• LPTokens: An asset representing the Liquidity Provider's share of the Lending Pool instance. The Lending Pool [pseudo-account] issues LPTokens upon depositing liquidity. The LPTokens are destroyed upon liquidity removal.

1.2.3 Concepts

• Principal: The Loan principal is the initial amount of Fungible Tokens borrowed or lent in a Loan Agreement, excluding any interest or fees that may accrue over time. It represents the core amount of capital that the Lender and Borrower exchanged at the Loan's inception, and it serves as the basis for calculating interest payments and determining the overall repayment obligation.

• Interest: Interest is the additional amount of Fungible Tokens charged by a lender for using borrowed funds, expressed as a percentage of the Loan principal. It represents the cost of borrowing and compensates the Liquidity Provider for the risk incurred and the opportunity cost of lending out funds.

• Fees: Fees are additional charges incurred by the Borrower beyond the interest rate. The Pool Delegate is the primary receiver of the fees.

1.3 Overview of the Lending Pool features

1.3.1 Lending Pool Representation

A Lending Pool is a specific implementation of the Pool specification. PoolCreate, PoolUpdate and PoolDelete transactions are used to manage the state of the ledger entry.

1.3.2 Liquidity Management

Liquidity Providers may use Deposit, Withdraw, or Redeem transactions to provision and remove liquidity and any accrued interest from the Pool. They may only withdraw assets from the Pool that are not lent. In this version, we only support a first-come-first-serve withdrawal strategy.

1.3.3 Issuing a Loan

_
A new Loan ledger entry represents a Loan. The Pool Delegate is responsible for finding borrowers and underwriting Loans. Loan underwriting is an off-chain process between the Borrower and the Lender, potentially facilitated by the Pool Delegate. However, the Loan terms are saved on-chain. A Borrower and Lender can create a new Loan with a multi-signature transaction, LoanCreate. The multi-signature transaction ensures that both parties agree on the Loan terms before making the Loan. This version only supports a single Borrower Fixed-Term Loan. However, the design allows for new Loan types.

FixedTermLoan:

Fixed-term Loans have a predefined maturity date, such as 180 days, established at the time of creation. These Loans offer certainty for lenders and borrowers, ensuring a clear timeframe for financial planning.

1.3.4 Managing a Loan

• Borrower:

  • The Borrower interacts with the Loan object with two transactions, LoanPayment and Drawdown. The LoanPayment transaction is used to make a Loan payment, including any interest, close the Loan early or return borrowed funds. The Drawdown transaction is used to withdraw the lent funds.

• Pool Delegate:

  • Under certain conditions, the Pool Delegate may submit UpdateLoan or DeleteLoan transactions. The Update transaction is used only to default to a Loan after a late payment grace period. The Delete transaction is used to Delete the Loan object once the Loan has matured or defaulted.
  • Every Loan has a defined payment interval that determines when the Borrower is expected to make a payment. If the Borrower does not make a payment before the expected due date, there is a grace period during which they can make a late payment. After the grace period passes, the Loan is considered in default, and the Pool Delegate can repossess the Loan.

1.3.5 Risk Management

In this version, we propose only using Pool Delegate Cover as a mechanism to manage the risk of a Loan default. The Pool Delegate Cover is a first-loss capital deposited by the Pool Delegate. In case of a Loan default, the Pool Delegate Cover covers some of the lost assets. The Pool Delegate may add and remove deposits with CoverDeposit and CoverWithdraw transactions.

1.3.6 Loan Fees

The fees are separated into three categories:

• Origination Fee: The origination fee only applies to fixed-term Loans. It is paid by the Borrower during the Loan funding and reduced from their drawable principal balance.
• Service Fee: A fee the Borrower pays during a Loan payment is added to the gross interest.
• Management Fee: Fees taken as a portion of gross interest paid by the Borrower when a payment is made.

1.3.7 Origination Fee

Origination Fee is paid during Loan funding and refinance operations of a Fixed-Term Loan. The Origination Fee is calculated in the following way:

• delegateOriginationFee is a term specified during Loan instantiation as a nominal amount.

1.3.8 Service Fee

Service fees are paid during Loan payments and added to gross interest. They are calculated in the following way:

• delegateServiceFee is a Loan term specified as a nominal amount, e.g., 10XRP. The Borrower and the Pool Delegate agree on the fee.

1.3.9 Management Fee

Management fees are paid during Loan payments. The fees are deducted from the gross interest paid by the Borrower using the following formula:

$$managementFee = grossInterest \times managementFeeRate$$

The managementFee goes to the PoolDelegate, and the remaining $grossInterest - managementFee$ goes to the Liquidity Providers.

2. A Lending Pool Instance

2.1 On-Ledger Objects

The Lending Pool Protocol implements the Single Asset Tokenized Pool specification. An AccountRoot and a Pool object represents a LendingPool instance. Both objects are created using the PoolCreate transaction. The LendingPool state can be updated using the PoolUpdate transaction. Finally, an empty Lending Pool can be deleted using the PoolDelete transaction. A Lending Pool is considered empty when there are no outstanding Loans, assets, or LPTokens in the underlying Pool object.

2.1.1 Lending Pool pseudo-account

In addition to standard the pseudo-account parameters, the Lending Pool AccountRoot must have the following set:

• asfRequireAuth enabled to ensure that only authorized entities can hold LPTokens.
• lsfDefaultRipple disabled to ensure that LPToken holders cannot transfer LPTokens among themselves.

2.1.2 LendingPool LPTokens

The Lending Pool Liquidity Provider Tokens LPTokens are a type of Pool LPTokens. Their balance is tracked via an Authorized Trust Line.

Only the Lenders, i.e. accounts that have deposited assets into the Lending Pool, are authorized to hold LPTokens.

TBD
Some users of the Lending Protocol may want to allow the transfer of LPTokens between different users. Perhaps it is wise to make the transferability of LPTokens configurable.

2.1.3 Lending Pool Access Control

The Pool Delegate can control who may provide liquidity and withdraw funds from the Lending Pool via a Lending Pool's Permissions field, which contains `Allowlists of accounts that can provide liquidity or borrow funds from the Lending Pool.

2.1.4 LendingPool Accounting

Total Pool Value (TotalValue)

The TotalValue variable represents the total Lending Pool value. The current proposal is for a single-borrower Lending Pool. Therefore, the totalValue of a Lending Pool is calculated as follows:

$$ totalValue = availableLiquidity + (outstandingPrincipal_{Loan} + outstandingInterest_{Loan}) $$

where:

• $outstandingPrincipal_{Loan}$ is the remaining funds the Borrower still owes.

• $outstandingInterest_{Loan}$ is the remaining amount of interest the Borrower still owes. It is represented as a fixed amount owed at a given date.

The total Loan interest is calculated as follows:

$$ interestDue = principalRequested \times interestRate \times \frac{paymentInterval}{365} $$

For example, the total interest for a Loan of 1,000,000$ with 15% interest and a 30-day payment interval would be:

$$1e6 \times 0.15 \times \frac{30}{365} \approx 12328.77$$

At any given time, we can calculate the outstanding interest of a Loan as follows:

$$outstandingInterest_{Loan}(t) = interestDue \times \frac{t - timeSinceLastPayment}{paymentInterval}$$

Continuing the above example, given that the Borrower made a payment in time on the 30th day, the interest due on the 31st day would be:

$$ outstandingInterest_{Loan}(31) = 12328.77 \times \frac{31 - 30}{30} \approx 410.96 $$

The above computation would be costly in a multi-loan system, where a single Lending Pool can have an unbounded number of associated Loans. Therefore, a more efficient solution will be needed for such a system.

2.1.5 Pool Delegate Cover

Pool Delegate Cover is a first-loss capital deposited by the Pool Delegate for a given Lending Pool. First-loss capital protects the Liquidity Providers in case of a Loan default.

Pool Delegate Cover is NOT enforced. For example, a Pool Delegate may create a Lending Pool with zero Pool Delegate Cover. However, a Liquidity Provider (Lender) may be reluctant to deposit assets in an uncovered Lending Pool.

Two variables control the Pool Delegate Cover:

• MinCoverPercentage is the percentage of TotalValue that must be covered by the Liquidity Pool Delegate.
• MaxCoverLiquidationPercentage is the percentage of the Pool Delegate Cover covering the Pools loss.

If the available Pool Cover falls below the MinCoverPercentage, two consequences occur:

1. The Pool Delegate cannot fund a new Loan.
2. The Pool Delegate cannot receive fees. Instead, the fees are routed to the Lending Pool.

Examples

Example 1:

MinCoverPercentage            = 0.1
MaxCoverLiquidationPercentage = 0.1

TotalValue     = 1,000,000 Tokens
CoverDeposited = 10,000 Tokens

DefaultAmount = 1,000 Tokens

CoverLiquidated = min(10,000 * 0.1, 1,000) = 1,000 Tokens
DefaultRemaining = 1,000 - 1,000 = 0 Tokens

TotalValue     = 1,000,000 - 0 = 1,000,000 Tokens
CoverRemaining = 10,000 - 1,000 = 9,000 Tokens

Example 2:

MinCoverPercentage            = 0.1
MaxCoverLiquidationPercentage = 0.1

TotalValue     = 1,000,000 Tokens
CoverDeposited = 10,000 Tokens

DefaultAmount = 2,000 Tokens

CoverLiquidated  = min(10,000 * 0.1, 2,000) = 1,000 Tokens
DefaultRemaining = 2,000 - 1,000 = 1,000 Tokens

TotalValue     = 1,000,000 - 1,000 = 999,000 Tokens
CoverRemaining = 10,000 - 1,000 = 9,000 Tokens

2.1.6 LendingPool Withdrawal

A Liquidity Provider (Lender) can make a Withdraw request anytime. Currently, the Lending Protocol ONLY supports a FirstComeFirstServe based withdrawal.

The requests are served on a first-come-first-serve basis. Multiple withdrawal requests occurring in the same ledger will execute in a non-deterministic order due to the Canonical Transaction Execution Order. In case of insufficient liquidity, only a portion of the LPTokens from the withdrawal request will be redeemed.

2.1.7 LendingPool fields

The LendingPool is a specialized instance of the Pool ledger entry. It adds the following fields to the Details field of a Pool:

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
Permissions	Yes	Yes	Object	STObject	A permissions object that controls which accounts can access the Lending Pool.

The Permissions field contains two members:

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
Lenders	Yes	Yes	Object	STObject	An object that controls which accounts have permission to deposit/withdraw assets from the Pool.
Borrowers	Yes	Yes	Object	STObject	An object that controls which accounts have permission to borrow assets from the Pool.

A single STObject object contains two members:

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
IsPublic	Yes	Yes	bool	bool	Indicates whether the object is public. In case it is public, the Accounts MUST BE ignored. The default value is false.
Accounts	Yes	Yes	array	Vector256	An AccountID list of accounts that have access. By default, this value is empty.

---

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
Withdraw	Yes	No	Object	STObject	An object containing the LendingPool's withdrawal strategy configuration.

Note:

Withdraw is purposefully an object to have the flexibility to introduce new fields configuring withdrawal parameters without affecting the base object.

The Withdraw object contains the following member:

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
Type	Yes	No	String	UINT16	The type of withdrawal strategy supported by the LendingPool.

---

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
LiquidityCap	No	Yes	String or Object	AMOUNT	The maximum amount of assets that can be deposited in the Pool. If no LiquidityCap exists, the default maximum value is $2^{256} - 1$.

---

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
Fees	Yes	No	Object	STObject	Object containing fee configs.

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
ManagementFeeRate	Yes	No	Number	UINT16	Specifies the basis point fee to be charged by the Pool Delegate. Valid values for this field are between 0 and 10000 inclusive. A value of 1 is equivalent to 1/10 bps or 0.001%, allowing trading fees between 0% and 10%.

---

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
PoolDelegateCover	Yes	No	Object	STObject	The object configuring the PoolDelegate Cover.

The PoolDelegateCover configures aspects of the first-loss capital posted by the PoolDelegate for a given Pool.

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
MinCoverPercentage	Yes	No	Number	UINT16	The percentage of the Pool's capital that the Pool Delegate must cover with first-loss capital.
MaxCoverLiquidationPercentage	Yes	No	Number	UINT16	The percentage of the Pool Delegates cover that goes towards reducing losses during a default.
CoverDeposited	Yes	No	String or Object	AMOUNT	The amount of PoolDelegateCover asset that was deposited into the Liquidity Pool.

---

2.2 CUD LendingPool transactions

The Lending Pool creates an instance of a Pool ledger entry. It implements the Pool interface. The CUD transactions of the Pool object take additional fields and behaviour.

2.2.1 PoolCreate transaction

The PoolCreate transaction creates new Pool and pseudo-account (AccountRoot) objects.

Notes:

• PoolCreate is not allowed with LPTokens.

Fields

Pool Instance Specific Fields

---

Field Name	Required?	JSON Type	Internal Type	Description
Type	Yes	String	UINT16	Type specifies the concrete type of the Pool. The value for a Lending Pool is 1.

---

Field Name	Required?	JSON Type	Internal Type
Details	Yes	Object	STObject

Details specifies the protocol-specific values for the Pool.

Lending Pool Specific Fields

Field Name	Required?	JSON Type	Internal Type	Description
Permissions	No	Object	STObject	A permissions object that controls which accounts are allowed to access the Lending Pool.

This configures the borrowers and lenders who are allowed to interact with the Pool. When the Permissions field is NOT specified, the Pool is private. For example, IsPublic in the Lenders and Borrowers objects is set to false, and the Accounts field is empty.

The Permissions field contains two members:

Field Name	Required?	JSON Type	Internal Type	Description
Lenders	Yes	Object	STObject	An object that controls which accounts have permission to deposit/withdraw assets from the Pool.
Borrowers	Yes	Object	STObject	An object that controls which accounts have permission to borrow assets from the Pool.

Each object contains two members:

Field Name	Required?	JSON Type	Internal Type	Description
IsPublic	Yes	bool	bool	Indicates whether the object is public. In case it is public, the Accounts MUST BE ignored. The default value is false.
Accounts	Yes	array	Vector256	An AccountID list of accounts that have access. By default, this value is empty.

---

Field Name	Required?	JSON Type	Internal Type	Description
Withdraw	Yes	Object	STObject	An object containing the LendingPool's withdrawal strategy configuration.

The Withdraw object contains the following member:

Field Name	Required?	JSON Type	Internal Type	Description
Type	Yes	String	UINT16	The type of withdrawal strategy supported by the LendingPool.

Currently, only FirstComeFirstServe withdrawal is supported. The uint16 value is 1.

---

Field Name	Required?	JSON Type	Internal Type	Description
LiquidityCap	No	String or Object	AMOUNT	The maximum amount of assets that can be deposited in the Pool. If no LiquidityCap exists, the default maximum value is $2^{256} - 1$.

---

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
Fees	Yes	No	Object	STObject	Object containing fee configs.

Field Name	Required?	Modifiable?	JSON Type	Internal Type	Description
ManagementFeeRate	Yes	No	Number	UINT16	Specifies the basis point fee to be charged by the Pool Delegate. Valid values for this field are between 0 and 10000 inclusive. A value of 1 is equivalent to 1/10 bps or 0.001%, allowing trading fees between 0% and 10%.

---

Field Name	Required?	JSON Type	Internal Type	Description
PoolDelegateCover	Yes	Object	STObject	The object configuring the PoolDelegate Cover.

Field Name	Required?	JSON Type	Internal Type	Description
MinCoverPercentage	Yes	Number	UINT16	The percentage of the Pool's capital that the Pool Delegate must cover with first-loss capital.

Field Name	Required?	JSON Type	Internal Type	Description
MaxCoverLiquidationPercentage	Yes	Number	UINT16	The percentage of the Pool Delegates cover that goes towards reducing losses during a default.

---

Failure Conditions

In addition to the default failure conditions, the PoolCreate transaction MUST fail when:

• An unfunded address exists in the Accounts field for the Borrowers or Lenders objects.

State Changes

If the transaction is successful:

• Three new ledger entries [Pool, AccountRoot, DirectoryNode] are created.
• An Authorized Trust Line is created to track LPTokens.
• A Trust Line is created to track PoolDelegateCover.
• A Trust Line is created between the issuer of the Pools Fungible Token and the Pool Delegate's account. This trustline is later used to transfer fees to the Pool Delegate.

2.2.2 PoolUpdate transaction

Fields

In addition to mandatory Pool fields, the following information may be provided.

---

Field Name	Required?	JSON Type	Internal Type
Details	Yes	struct	BLOB

Modifiable Fields

Field Name	Required?	JSON Type	Internal Type	Description
Permissions	No	Object	STObject	A permissions object that controls which accounts can access the Lending Pool.

Configures the borrowers and lenders that are allowed to interact with the Pool. The new Permissions value WILL OVERWRITE the existing Permissions value.

If a Liquidity Provider access is removed, they WILL NOT be able to Deposit new assets. However, they WILL be able to Redeem/Withdraw assets from the Lending Pool.
If a Borrower's access is removed, they WILL NOT be able to request a new Loan. However, this DOES NOT affect existing Loans.

---

Field Name	Required?	JSON Type	Internal Type	Description
LiquidityCap	No	String or Object	AMOUNT	The maximum amount of assets that can be deposited in the Pool. If no LiquidityCap exists, the default maximum value is $2^{256} - 1$.

Configures the maximum Liquidity Cap of a Lending Pool.

---

Details is a struct with the modifiable Lending Pool fields.

Failure Conditions

The transaction MUST fail when:

• The AccountID of the transaction DOES NOT equal PoolDelegateID.
• The transaction attempts to modify an immutable field.
• The transaction provides an invalid value to a field.

State Changes

• MUST update ONLY the mutable fields of the Details structure.

2.2.3 PoolDelete transaction

Fields

The transaction MUST provide mandatory Pool fields to identify the instance.

Failure Conditions

• The transaction MUST fail if the AccountID of the transaction DOES NOT equal PoolDelegateID.
• The transaction MUST fail if the LPTokenBalance of the Pool is NOT zero.
• The transaction MUST fail if any outstanding Loan objects are associated with the Lending Pool.
• The transaction MUST fail if the PoolDelegateCover Trust Line is not empty. I.e. the Pool Delegate still needs to withdraw their cover.

State Changes

• Delete the Pool ledger entry.
• Delete the AccountRoot object.
• Delete the DirectoryNode object.
• Delete all associated Trust Lines.
• Release Owner Reserve.

2.3 Liquidity Provider Transaction

2.3.1 Deposit transaction

The Liquidity Providers use the Deposit transaction to add liquidity to the Lending Pool in exchange for the Lending Pool LPTokens.

Fields

There are no additional fields.

Failure Conditions

In addition to Pool specification failures, the transaction MUST fail when:

• The Lending Pool is NOT public, AND the account depositing assets is NOT authorized.
• Adding the assets to the Lending Pool would exceed LiquidityCap.

State Changes

There are no additional state changes.

2.3.2 Withdraw transaction

Withdraw request for a Lending Pool is currently disabled.

2.3.3 Redeem transaction

TBD
The Redeem transaction requires further thought. Please see Appendix A.

The Redeem transaction burns Liquidity Providers LPTokens in exchange for assets from the Lending Pool. The Liquidity Provider may only redeem the Pool's AvailableLiquidity. Any lent assets are not redeemable. The maximum asset amount that a Liquidity Provider can withdraw at a given time is based on the proportion of LPTokens the Provider owns. For example, assuming a Liquidity Provider owns 50% of all LPTokens, they may redeem up to 50% of the available liquidity.

Redeem Limits

The following formula computes the maximum amount of LPTokens a Liquidity Provider can redeem at the current time:

$$ MaxRedeem(LP) = \frac{LiquidityShare(LP) \times LPTokenBalance}{TotalValue} $$

where:

$$ LiquidityShare(LP) = AvailableLiquidity \times \frac{LPTokens(LP)}{LPTokenBalance} $$

Example Calculation

Example 1:

Alice = 1,000 LPTokens
Bob   = 9,000 LPTokens

LPTokenBalance        = 10,000 LPTokens
TotalValue           = 11,000 Tokens
AvailableLiquidity    = 1,000 Tokens

LiquidityShare_Alice = 1,000 * (1,000 / 10,000) = 100 Tokens
LiquidityShare_Bob   = 1,000 * (9,000 / 10,000) = 900 Tokens

MaxRedeem_Alice = (100 * 10,000) / 11,000 = 90.91 LPTokens
MaxRedeem_Bob   = (900 * 10,000) / 11,000 = 818.18 LPTokens

Fields

There are no additional fields.

Failure Conditions

TBD
Exact failure conditions depend on the redemption mechanism in place. Once the redemption mechanism is finalized, the exact failure conditions will be described.

State Changes

TBD
Exact state changes depend on the redeem mechanism. Once the logic is finalized, the exact state changes will be described.

2.4 Pool Delegate Cover transactions

2.4.1 CoverDeposit Transaction

A PoolDelegate can submit a CoverDeposit transaction to add Pool Delegate Cover into a single Lending Pool Instance.

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	✔️	String	UINT16

TransactionType specifies the new transaction type. The integer value is 61.

---

Field Name	Required?	JSON Type	Internal Type
Account	✔️	String	AccountID

Indicates the account that initiated the transaction.

---

Field Name	Required?	JSON Type	Internal Type
Fee	✔️	String	AMOUNT

Fee specifies the integer amount of XRP, in drops, to be destroyed as a cost of depositing assets to the Pool.

---

Field Name	Required?	JSON Type	Internal Type
Amount	✔️	String or Object	AMOUNT

Amount specifies the amount of the pool asset to deposit. Amount is a String when the Pool asset is XRP. Otherwise, it is an AMOUNT Object.

---

Field Name	Required?	JSON Type	Internal Type
PoolSequence	✔️	number	UINT32

Sequence number of the Pool instance.

---

Field Name	Required?	JSON Type	Internal Type
PoolDelegateID	✔️	String	AccountID

The PoolDelegateID of the Pool.

---

Failure Conditions

The transaction MUST fail when:

• The ID of the account submitting the transaction is not equal to the PoolDelegateID.
• The Asset deposited is NOT equal to the asset of the Lending Pool.
• The depositing account has insufficient funds.

State Changes

• If the deposited asset is XRP, it is transferred from the account initiating the transaction to the AccountRoot of the Pool, updating the Balance field of both accounts.
• If the deposited asset is a Token, the balance between the Pool instance account and the issuer account is adjusted.
• Increase the CoverDeposited of the Pool.

2.4.2 CoverWithdraw Transaction

A Pool Delegate can submit a CoverWithdraw transaction to remove the Pool Delegate Cover. However, the cover amount can never be removed below the MinCoverPercentage threshold.

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	✔️	String	UINT16

TransactionType specifies the new transaction type. The integer value is 62.

---

Field Name	Required?	JSON Type	Internal Type
Account	✔️	String	AccountID

Indicates the account that initiated the transaction.

---

Field Name	Required?	JSON Type	Internal Type
Fee	✔️	String	AMOUNT

Fee specifies the integer amount of XRP, in drops, to be destroyed as a cost of withdrawing assets from the Pool.

---

Field Name	Required?	JSON Type	Internal Type
Amount	✔️	String or Object	AMOUNT

Amount specifies the amount of the pool asset to withdraw. Amount is a String when the pool asset is XRP. Otherwise, it is an AMOUNT Object.

---

Field Name	Required?	JSON Type	Internal Type
PoolSequence	✔️	number	UINT32

Sequence number of the Pool instance.

---

Field Name	Required?	JSON Type	Internal Type
PoolDelegateID	✔️	String	AccountID

The PoolDelegateID of the Pool.

---

Failure Conditions

The transaction MUST fail when:

• The ID of the account submitting the transaction is not equal to the PoolDelegateID.
• The Asset withdrawn is NOT equal to the asset of the Lending Pool.
• The remaining CoverDeposited amount would be less than $MinCoverPercentage \times TotalValue$.

State Changes

• If the withdrawn asset is XRP, it is transferred from the Pool instance account to the account initiating the transaction, updating each account's Balance field.
• If the withdrawn asset is a token, the balance between the Pool instance account and the issuer account is adjusted.
• Decrease the CoverDeposited of the Pool.

3. Loan Instance

The Borrower and the Pool Delegate agree on the Loan terms off-chain and save these terms on-chain. We track a Loan agreement between the Borrower and a lender through a new Loan object. A Loan object is used to:

• Perform Loan financing.
• Withdraw the funded amount.
• Computation of payment quantities and timetables. Managing both amortized and interest-only payment formats.
• Conduct repossession of leftover amounts in the event of loan default.
• Managing Loan interest and principal payments.
• The Loan object supports upgradability via the Type field. Currently, only FixedTermLoanV1 is supported.

The Loan object uses the AccountRoot entry of the associated Lending Pool to track XRP or Fungible Token balances.

3.1 Creating a Loan

The Borrower and a Lending Pool Delegate can create a new Loan by submitting a Multi-Signature transaction LoanCreate. The transaction contains the Loan terms and the signatures of the Borrower and the Lending Pool Delegate. We chose a multi-signature approach to ensure that no one party could create a Loan object.

3.1.1 Loan Creation Pre-Requisites

• The address of the Borrower account must be present in the Permissions.Borrowers field of the Lending Pool.
• The Lending Pool must contain enough liquidity to meet the requested Loan principal.

3.2 Fixed-Term-Loan

A fixed-term Loan has a fixed, agreed-upon due date set at the Loan creation.

3.2.1 Asset Definitions

A Fixed Term Loan manages two assets:

• FundsAsset: This represents XRP or the Fungible Token that is funded, drawn down and paid during the Loan lifecycle.

3.2.2 Loan Accounting

The following variables are used to track the amount of a given asset in the Loan:

DrawableFunds

Represents the amount of FundsAsset that can be drawn from the Loan by the Borrower.

The value is incremented ONLY when:

• During initial Loan funding.
• A borrower makes a payment and sends too much FundsAsset. The excess is added to the DrawableFunds.
• A Loan is closed early, sending too much FundsAsset. The excess is added to the DrawableFunds.
• A Borrower returns funds, adding FundsAsset back into the Loan to reduce the outstanding principal.

The value is decremented ONLY when:

• The Borrower draws down on the Loan.
• The Pool Delegate repossesses the Loan (set to zero).

3.3 Default

3.3.1 Overview

A Loan has a defined payment interval, which determines when the Borrower is expected to make payments. If the Borrower does not make a payment before the expected due date, there is a grace period during which they can make a late payment. After the grace period passes, the Loan is considered in default, and the pool delegate can repossess it by defaulting on it.

3.3.2 Fund Recovery

When a Loan defaults, capital is recovered through the mechanics of delegate pool cover. The Pool Delegate does not recover any fees owed during a Loan default.

3.3.3 First-Loss Capital

Each Pool maintains a reserved amount of liquidity whose primary purpose is to serve as first-loss capital in case a Loan defaults. This capital is provided by the Pool Delegate and is used to make up for the losses after a Loan Default. This mechanism is in place to align incentives between the Pool Delegate and Liquidity Providers. The MaxCoverLiquidationPercentage is set at the Lending Pool level, which defines the percentage of Pool cover used when covering for losses.

First-loss capital is liquidated atomically. The losses owed to the Pool are calculated, and the Pool Delegate cover is liquidated to the MaxCoverLiquidationPercentage. The remaining losses are represented to the Liquidity Providers as a decrease in TotalValue.

3.4 On-Ledger Objects

3.4.1 Loan ID

We propose to use a similar technique to generate a Loan ID as is used to create an Offer Object ID:

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

3.4.2 Loan States

A Loan may be in one of the three states:

• Active: Once a Loan is created, it is considered active. The Borrower may draw down funds and make payments according to the terms of a Loan Agreement.
• Mature: Once the Borrower pays the principal and interest, the Loan is considered Mature. It is an end-of-life state, at which point the Loan object can be deleted, given that all assets related to the Loan have been settled.
• Default: If the Borrower fails to pay in time, the Pool Delegate may mark the Loan as defaulted. A Pool Delegate can claim all assets of a defaulted Loan.

3.4.3 Loan Fields

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
Type	Yes	No	String	UINT8	The type of the Loan.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
LoanSequence	Yes	No	Number	UINT32	Sequence number of the Loan instance. It is used to generate a Loan ID.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
Borrower	Yes	No	String	AccountID	The address of the Borrower's account. It is used to generate a Loan ID.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
Lender	Yes	No	String	AccountID	The address of the Pool Delegate account. It is used to generate a Loan ID.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
PoolID	Yes	No	String	UINT256	The object ID of the Lending Pool with which the Loan is associated.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
FundsAsset	Yes	No	String or Object	ISSUE	This represents XRP or Fungible Token that is funded, drawn down, and paid during the Loan lifecycle.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
State	Yes	No	String	UINT8	This represents the current state of the Loan, one of Active, Mature, and Default.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
Fees	Yes	No	Object	STObject	A structure containing Loan-specific fees.

The Fees object is composed of the following fields:

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
DelegateOriginationFee	Yes	Yes	Number	UINT16	A nominal amount of funds paid to the Pool Delegate when the Loan is created. It must be between 0% and up to 2.5% of the principal amount.
DelegateServiceFee	Yes	Yes	Number	UINT16	A nominal amount of funds assets that are paid to the Pool Delegate on every Loan payment.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
Rates	Yes	No	Object	STObject	A structure containing Loan-specific Loan rates.

The Rates object is composed of the following fields:

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
InterestRate	Yes	Yes	Number	UINT16	Annualized interest rate in basis points.
ClosingFeeRate	Yes	Yes	Number	UINT16	Loan Closing interest rate in basis points.
LateFeeRate	Yes	Yes	Number	UINT16	A nominal fee rate applied to the principal amount on late payments.
LateInterestRate	Yes	Yes	Number	UINT16	A premium added to the interest rate for late payments in basis points.

---

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
Details	Yes	No	Object	STObject	A structure containing Loan-specific details. I.e. different Loan types may have different fields describing the state of the Loan.

The Details object is composed of the following fields:

Field Name	Required?	Loan Term?	JSON Type	Internal Type	Description
GracePeriod	Yes	Yes	Number	UINT16	The number of seconds that the Pool Delegate must wait before triggering a default on a late Loan. It MUST be greater than 12 hours.
PaymentInterval	Yes	Yes	Number	UINT16	The number of seconds between each Loan payment. It MUST be greater than 0.
LoanStartDate	Yes	No	Number	UINT32	The timestamp of when the Loan was created in Ripple Epoch.
NextPaymentDueDate	Yes	No	Number	UINT32	The timestamp of when the next payment is due in Ripple Epoch.
LastPaymentDate	Yes	No	Number	UINT32	The timestamp of when the last payment was made in Ripple Epoch.
TotalPayments	Yes	No	Number	UINT16	The total number of payments to be made in the Loan term. It MUST be greater than 0.
PaymentsRemaining	Yes	No	Number	UINT16	The number of payments remaining on the Loan.

| PrincipalRequested | Yes | Yes | String or Object | AMOUNT | The nominal amount of principal asset. |
| EndingPrincipal | Yes | Yes | String or Object | AMOUNT | The expected principal amount to be paid at the end of the Loan term. |
| DrawableFunds | Yes | No | String or Object | AMOUNT | The amount of FundsAsset available to the Borrower. |

---

3.5 Loan CUD Transactions

3.5.1 LoanCreate transaction

The LoanCreate transaction creates a new instance of the Loan object. It is a multi-signature transaction signed by the Borrower and the Pool Delegate.

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	Yes	String	UINT16

TransactionType specifies the new transaction type. The integer value is 61.

---

Field Name	Required?	JSON Type	Internal Type
Type	Yes	String	UINT8

---

Field Name	Required?	JSON Type	Internal Type
Borrower	Yes	String	AccountID

---

Field Name	Required?	JSON Type	Internal Type
Lender	Yes	String	AccountID

---

Field Name	Required?	JSON Type	Internal Type
PoolID	Yes	String	UINT256

---

Field Name	Required?	JSON Type	Internal Type
FundsAsset	Yes	String or Object	ISSUE

---

Field Name	Required?	JSON Type	Internal Type
Fees	Yes	Object	STObject

The Fees object is composed of the following fields:

Field Name	Required?	JSON Type	Internal Type	Description
DelegateOriginationFee	Yes	Yes	Number	UINT16
DelegateServiceFee	Yes	Yes	Number	UINT16

---

Field Name	Required?	JSON Type	Internal Type
Rates	Yes	Object	STObject

The Rates object is composed of the following fields:

Field Name	Required?	JSON Type	Internal Type
InterestRate	Yes	Number	UINT16
ClosingFeeRate	Yes	Number	UINT16
LateFeeRate	Yes	Number	UINT16
LateInterestRate	Yes	Number	UINT16

---

Field Name	Required?	JSON Type	Internal Type
Details	Yes	Object	STObject

The Details object is composed of the following fields:

Field Name	Required?	JSON Type	Internal Type
PaymentInterval	Yes	Number	UINT16
TotalPayments	Yes	Number	UINT16
PrincipalRequested	Yes	String or Object	AMOUNT
EndingPrincipal	Yes	String or Object	AMOUNT

---

Multi-Signature Specific Fields

Field Name	Required?	JSON Type	Internal Type
Signers	Yes	Object	STArray

The Signers field contains a multi-signature from exactly two key pairs. For further details on the field content, see Signers Field.

One of the key pairs MUST belong to the Pool Delegate of the Lending Pool.

The second key:

• In case the Lending Pool is public, I.e. Permissions.Borrower.IsPublic == True the key can belong to any other account.
• Otherwise, the Account of the key must be a member of the Permissions.Borrower.Accounts array.

Failure Conditions

The LoanCreate transaction MUST fail when:

• The CoverDeposited is less than $MinCoverPercentage \times TotalValue$.
• The PoolDelegateID is NOT one of the signers, OR the Borrower is NOT one of the signers.
• The Lending Pool is private, and the Borrower is not on the Permissions.Borrower.Accounts list.
• The AvailableLiquidity is less than PrincipalRequested.
• The FundsAsset does not match the asset of the Lending Pool.
• The Type is not a supported Loan type.
• Invalid values are passed on to the Loan terms.

Loan Object Initial Values

The following attributes must have the following initial values:

• State: The initial value is Active.
• Details.NextPaymentDueDate: The initial value is: $TimeOfCreation + PaymentInterval$.
• Details.DrawableFunds: The initial value is equal to $PrincipleRequested - DelegateOriginationFee$.

State Changes

If the transaction is successful:

• Two new ledger entries [Loan, DirectoryNode] are created.

• The LoanID is added to the LedgerEntries field of Lending Pool's AccountRoot.

• AvailableLiquidity of the Lending Pool is decremented by PrincipalRequested.

• IF the fundsAsset is XRP:

  • The Balance field of the Lending Pool's AccountRoot is decremented by DelegateOriginationFee.
  • The Balance field of the Pool Delegates AccountRoot is incremented by DelegateOriginationFee.

• IF the fundsAsset is a Fungible Token:

  • The balance of the Trust Line between the Lending Pool's AccountRoot and the issuer account is decremented by DelegateOriginationFee.
  • The balance of the Trust Line between the Pool Delegates AccountRoot and the issuer account is incremented by DelegateOriginationFee.

3.5.2 LoanUpdate transaction

The LoanUpdate transaction updates the Loan state. Currently, only defaulting on the Loan is supported.

Defaulting a Loan

The Pool Delegate may default a Loan only when: Details.NextPaymentDueDate + Details.GracePeriod is greater than the close_time of the latest validated ledger.

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	Yes	String	UINT16

TransactionType specifies the new transaction type. The integer value is 62.

---

Field Name	Required?	JSON Type	Internal Type
LoanSequence	Yes	Number	UINT32

---

Field Name	Required?	JSON Type	Internal Type
Borrower	Yes	String	AccountID

---

Field Name	Required?	JSON Type	Internal Type
Account	Yes	String	AccountID

The ID of the account submitting the transaction. It MUST be equal to Lender.

---

Field Name	Required?	JSON Type	Internal Type
State	Yes	String	UINT8

Note:

• Currently, ONLY the Default state is supported.

Failure Conditions

The transaction MUST fail when:

• Details.NextPaymentDueDate + Details.GracePeriod is less than the close_time of the latest validated ledger.
• The current state of the Loan is Mature.

State Changes

Upon defaulting on the Loan, the following state changes occur:

TBD

3.5.3 LoanDelete transaction

The LoanDelete transaction deletes a Loan that has reached maturity or has defaulted. All balances associated with the Loan must be settled.

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	Yes	String	UINT16

TransactionType specifies the new transaction type. The integer value is 63.

---

Field Name	Required?	JSON Type	Internal Type
LoanSequence	Yes	Number	UINT32

---

Field Name	Required?	JSON Type	Internal Type
Borrower	Yes	String	AccountID

---

Field Name	Required?	JSON Type	Internal Type
Account	Yes	String	AccountID

The ID of the account submitting the transaction MUST be equal to Lender.

---

Failure Conditions

The transaction MUST fail when:

• The State of the Loan is NOT Mature or Default.

State Changes

• Remove the LoanID entry from the AccountRoot of the Lending Pool.
• Delete the Loan ledger entry.
• Delete the DirectoryNode object.
• TODO: what other state changes need to happen?

3.5.4 LoanPayment transaction

The LoanPayment transaction is used to make a payment against a Loan. The transaction can take one of the following types:

• Close: A payment to close the Loan early.
• ReturnFunds: A payment to return fundsAsset to the Loan.
• Payment: A standard Loan repayment.

The transaction type is controlled via the Flags transaction parameter.

Flag Name	Hex Value	Description
tfClose	TBD	A transaction to close the Loan early.
tfReturnFunds	TBD	A transaction to return principal borrowed.
tfPayment	TBD	A transaction to make a payment against the Loan.

Payments

A Borrower can make a Payment on their Loand by sending a LoanPayment transaction with type Payment.

Amortization

On Loan instantiation, the following Loan attributes are set. These attributes affect the payment calculation of a Loan:

• PrincipalRequested: Total principal amount owed on the Loan.
• EndingPrinciple: Principal balance remaining at the end of the Loan. This amount is zero if the Loan is fully amortized. The Loan is interest-only if this amount equals PrincipalRequested and partially amortized if it is anything in between.
• InterestRate: The annualized interest rate used throughout the Loan.
• PaymentInterval: Time between payments in seconds.
• PaymentsRemaining: Total number of payments made throughout the Loan.

The payment schedule is calculated with a standard amortization formula.

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

$$raisedRate = (1 + periodicRate)^{paymentsRemaining}$$

$$ totalPayment = \frac{(principal \times raisedRate - endingPrincipal) \times periodicRate}{raisedRate - 1} $$

$$interestPortion = principal \times periodicRate$$

$$principalPortion = totalPayment - interestPortion$$

Late Payments

When a Borrower makes a payment after the nextPaymentDueDate timestamp, it is considered late. There are two rate attributes used to calculate late fees:

• LateInterestPremiumRate: Additional Premium charged for late payments. For example, if the premium is 5% and the interest rate is 10%, the Borrower must pay 15% interest.
• LateFeeRate: Fee charged as a percentage of the outstanding principal at the time of payment.

A total late payment is calculated as follows:

$$ totalLatePayment = totalPayment + (principal \times lateFeeRate) + defaultInterest $$

where defaultInterest is:

$$ defaultInterest = \frac{principal \times (interestRate + LateInterestPremiumRate) \times daysDate \times secondsInDay}{365 \times secondsInDay} $$

where secondsInDay is the number of seconds in 24 hours. I.e. 86400.

Closing a Loan

A Borrower can close a Loan early by sending a LoanPayment transaction with the type Close. Allowing the Borrower to pay back the whole principal and interest in a single transaction. There is one rate attribute used to calculate the total amount due:

• ClosingRate: Fee charged as a percentage of the outstanding principal at the time of payment.

The total due is calculated as follows:

$$ total = principal \times closingRate $$

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	Yes	String	UINT16

TransactionType specifies the new transaction type. The integer value is 64.

---

Field Name	Required?	JSON Type	Internal Type
LoanSequence	Yes	Number	UINT32

---

Field Name	Required?	JSON Type	Internal Type
Lender	Yes	String	AccountID

---

Field Name	Required?	JSON Type	Internal Type
Account	Yes	String	AccountID

The ID of the account submitting the transaction MUST equal the Borrower field of the Loan.

---

Field Name	Required?	JSON Type	Internal Type
Amount	Yes	String or Object	STAmount

---

Failure Conditions

The transaction MUST fail when:

• The Loan state is Mature or Default.
• The user has fewer funds than what is specified in the Amount field.

Close payment
Payment payment
ReturnFunds payment

State Changes

• IF the fundsAsset is XRP:

  • Update the Balance field of all affected AccountRoot objects. In other words, transfer the funds from the Borrower to the pseudo-account of the Lending Pool.

• IF the fundsAsset is a Fungible Token:

  • Update the balance of the Trust Lines between all affected AccountRoot objects. In other words, transfer the funds from the Borrower to the pseudo-account of the Lending Pool.

Close transaction type

• Loan state changes

  • Set PaymentsRemaining to zero.
  • Update NextPaymentDueDate to LoanStartDate + PaymentInterval * TotalPayments.
  • Update LastPaymentDate to the current timestamp.
  • Set State to Mature.

• LendingPool state changes

  • Increment AvailableLiquidity of the Lending Pool.

Payment transaction type

• The Payment Amount comprises principal + interest, the total is calculated using the amortization function.

• Decrement the PaymentsRemaining field.

• Update NextPaymentDueDate to NextPaymentDueDate + PaymentInterval.

• Update LastPaymentDate to the current timestamp.

• IF PaymentsRemaining is zero:

  • Set State to Mature.

• LendingPool state changes

  • Increment AvailableLiquidity of the Lending Pool.

Fee management for Payment and Close transactions

• Service Fees:

  • Service Fees are charged against DrawableFunds of the Loan.
    TBD

• Management Fees:

  • Management Fees are charged against the gross interest of the Loan.
    TBD

ReturnFunds transaction type

• IF the fundsAsset is XRP:

  • The Balance field of the Lending Pool's AccountRoot is incremented by Amount.
  • The Balance field of the Borrower's AccountRoot is decremented by Amount.

• IF the fundsAsset is a Fungible Token:

  • The balance of the Trust Line between the Lending Pool's AccountRoot and the issuer account is incremented by Amount.
  • The balance of the Trust Line between the Borrowers AccountRoot and the issuer account is decremented by Amount.

• DrawableFunds of the Loan Object is incremented by Amount.

3.5.6 Drawdown transaction

The Drawdown transaction withdraws the principal lent to the Borrower.

Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	Yes	String	UINT16

TransactionType specifies the new transaction type. The integer value is 65.

---

Field Name	Required?	JSON Type	Internal Type
LoanSequence	Yes	Number	UINT32

---

Field Name	Required?	JSON Type	Internal Type
Lender	Yes	String	AccountID

---

Field Name	Required?	JSON Type	Internal Type
Account	Yes	String	AccountID

The ID of the account submitting the transaction MUST equal the Borrower field of the Loan.

---

Field Name	Required?	JSON Type	Internal Type
Amount	Yes	String or Object	STAmount

The Amount of funds to drawdown from the Loan.

---

Failure Conditions

The transaction MUST fail when:

• The specified Amount is greater than the DrawableFunds of the Loan.
• The Loan State is Default.

State Changes

• IF the fundsAsset is XRP:

  • The Balance field of the pseudo-account of the Lending Pool is decremented by Amount.
  • The Balance field of the Borrowers AccountRoot is incremented by Amount.

• IF the fundsAsset is a Fungible Token:

  • The balance of the Trust Line between the pseudo-account of the Lending Pool and the issuer account is decremented by Amount.
  • The balance of the Trust Line between the Borrowers AccountRoot and the issuer account is incremented by Amount.

• Decrement DrawableFunds of the Loan object by Amount.

Appendix A - Outstanding decision points

A-1 Redeeming LPTokens

The strategy to redeem LPTokens must balance implementation complexity and usability. The First-Come-First-Serve approach is NOT fair. It provides Liquidity Providers with inside knowledge an advantage. For example, a Liquidity Provider with advanced knowledge of an impending Default to minimize losses may try to quickly redeem as many LPTokens before a Loan default.

Therefore, we propose additional ideas on how redeeming could be done.

A-1.1 End-of-life redeeming

Once a Loan is created, Liquidity Providers may not add or remove funds from the Lending Pool, effectively freezing the Pool until the Loan reaches end-of-life. Once the Loan finishes, Liquidity Providers may withdraw lent funds plus any accrued interest.

Pros:

• Simple implementation.
• Prevents a situation where a Liquidity Provider might minimize losses by attempting to Redeem as many assets as possible before a Loan Default. In other words, with this mechanism, either everyone or no one wins.

Cons:

• The Liquidity Provider's interest is locked until the Loan ends. Due to price volatility, their assets may be worth less than before investment.
• Forces Liquidity Providers behaviour.

A-1.2 Queue-based redeeming

Liquidity Providers submit Redeem requests to a Lending Pool, where these requests are Queued. Periodically, at fixed intervals, each Redeem request is processed. A Liquidity Provider may have zero or one pending Redeem request at any time. In addition, to prevent greedy Liqudity Providers, at any given time, a Liqudity Provider may withdraw NO MORE than their portion of the accumulated funds. For example, if a Liquidity Provider provides 50% of total liquidity, they can redeem only up to 50% of funds at any stage.

Pros:

• Gives every Liquidity Provider a fair opportunity to withdraw funds.

Cons:

• This approach promotes early withdrawal. Any Liquidity Provider that delays withdrawal till the end of the Loan may have to bear the cost of the Loan default.
• A mechanism is required to queue the redeem requests and execute them at time-based intervals. However, this could be triggered by the LoanPayment.

A-1.3 Immediate payout

Instead of accumulating yield and principal in the Lending Pool, the funds are distributed at the time of payment. The Loan object maintains the portion of funds each Liquidity Provider contributed. For example, if Alice and Bob deposited 10,000 and 90,000 into the Lending Pool, And the Loan is for 10,000, then the Loan object will maintain a constant value stating that Alice owns 10% of any funds from this Loan and Bob owns 90% of any funds from this Loan. Thus, every time the Borrower makes a payment, 10% goes to Alice and 90% to Bob.

Pros:

• Every Liquidity Provider gets their fair share of principal + interest.

Cons:

• Forces Liquidity Providers into a particular behaviour.

A-2 Liquidity Provider Voting

Currently, only a Pool Delegate may default a Loan. However, in doing so, they would lose the Pool Delegate Cover. Therefore, there is no on-chain intrinsic incentive for a Pool Delegate to default a Loan. There might be off-chain incentives about which we cannot make any assumptions.

To address this issue, Liquidity Providers may vote to Default a Loan (once Default conditions are met). The weight of each vote is proportional to the LPTokens the Liquidity Provider holds.

[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.